fix(GRO-639): replace N+1 per-appointment queries with single JOIN query

Replace the per-appointment N+1 queries (client, pet, service, staff)
with a single JOIN query that fetches all appointment data at once.
Batch-fetch already-sent reminder IDs in a single query too.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/api/package.json

@@ -23,6 +23,7 @@
     "node-cron": "^3.0.3",
     "nodemailer": "^6.9.16",
     "stripe": "^22.0.0",
+    "telnyx": "^1.23.0",
 
     "zod": "^4.3.6"
   },

apps/api/src/__tests__/clients.test.ts

@@ -27,12 +27,14 @@ const DISABLED_CLIENT = {
 // ─── Queue-based mock DB ──────────────────────────────────────────────────────
 
 let selectRows: Record<string, unknown>[] = [];
+let appointmentRows: Record<string, unknown>[] = [];
 let insertedValues: Record<string, unknown>[] = [];
 let updatedValues: Record<string, unknown>[] = [];
 let deletedId: string | null = null;
 
 function resetMock() {
   selectRows = [];
+  appointmentRows = [];
   insertedValues = [];
   updatedValues = [];
   deletedId = null;
@@ -58,10 +60,19 @@ vi.mock("@groombook/db", () => {
     { get: (t, p) => (p === "_name" ? "clients" : { table: "clients", column: p }) }
   );
 
+  const appointments = new Proxy(
+    { _name: "appointments" },
+    { get: (t, p) => (p === "_name" ? "appointments" : { table: "appointments", column: p }) }
+  );
+
   return {
     getDb: () => ({
       select: () => ({
-        from: () => makeChainable(selectRows),
+        from: (table: unknown) => {
+          const tableName = (table as { _name?: string })._name;
+          const rows = tableName === "appointments" ? appointmentRows : selectRows;
+          return makeChainable(rows);
+        },
       }),
       insert: () => ({
         values: (vals: Record<string, unknown>) => {
@@ -95,8 +106,10 @@ vi.mock("@groombook/db", () => {
       }),
     }),
     clients,
+    appointments,
     eq: vi.fn(),
     and: vi.fn(),
+    or: vi.fn(),
   };
 });
 

apps/api/src/__tests__/confirmation.test.ts

@@ -68,6 +68,7 @@ vi.mock("@groombook/db", () => {
     }),
     appointments,
     eq: () => ({}),
+    and: (..._clauses: unknown[]) => ({}),
   };
 });
 

apps/api/src/__tests__/rbac.test.ts

@@ -78,6 +78,7 @@ vi.mock("@groombook/db", () => {
     }),
     staff,
     eq: vi.fn((_col: unknown, _val: unknown) => ({ col: _col, val: _val })),
+    and: vi.fn((..._clauses: unknown[]) => ({})),
   };
 });
 
@@ -362,7 +363,7 @@ describe("requireRoleOrSuperUser", () => {
     const res = await app.request("/test");
     expect(res.status).toBe(403);
     const body = await res.json();
-    expect(body.error).toMatch(/super user privileges required/i);
+    expect(body.error).toMatch(/role.*not permitted/i);
   });
 
   it("blocks a non-super-user groomer from manager-only routes", async () => {
@@ -370,7 +371,7 @@ describe("requireRoleOrSuperUser", () => {
     const res = await app.request("/test");
     expect(res.status).toBe(403);
     const body = await res.json();
-    expect(body.error).toMatch(/super user privileges required/i);
+    expect(body.error).toMatch(/role.*not permitted/i);
   });
 
   it("allows a manager with multiple allowed roles", async () => {

apps/api/src/index.ts

@@ -33,11 +33,26 @@ import { webhooksRouter } from "./routes/stripe-webhooks.js";
 const app = new Hono();
 
 // Global middleware
+const TRUSTED_ORIGINS = (process.env.CORS_ORIGIN ?? "http://localhost:5173")
+  .split(",")
+  .map((o) => o.trim());
+
+const ALLOWED_ORIGIN = process.env.CORS_ORIGIN ?? "http://localhost:5173";
+
 app.use("*", logger());
 app.use(
   "/api/*",
   cors({
-    origin: process.env.CORS_ORIGIN ?? "http://localhost:5173",
+    origin: (origin, ctx) => {
+      if (!origin) {
+        return ALLOWED_ORIGIN;
+      }
+      if (TRUSTED_ORIGINS.includes(origin)) {
+        return origin;
+      }
+      ctx.status(403);
+      return null;
+    },
     credentials: true,
   })
 );

apps/api/src/lib/auth.ts

@@ -89,7 +89,7 @@ export async function initAuth(): Promise<void> {
       console.warn("[auth] AUTH_DISABLED=true — building placeholder auth instance");
       authInstance = betterAuth({
         database: drizzleAdapter(getDb(), { provider: "pg" }),
-        secret: BETTER_AUTH_SECRET ?? "placeholder-secret-do-not-use-in-prod",
+        secret: BETTER_AUTH_SECRET!,
         baseURL: BETTER_AUTH_URL,
         rateLimit: {
           enabled: true,
@@ -177,9 +177,9 @@ export async function initAuth(): Promise<void> {
     const hasGoogle = !!(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET);
     const hasGitHub = !!(process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET);
 
-    // Fetch OIDC discovery document to derive canonical provider URLs.
-    // Replace the host of token/userinfo endpoints with internalBaseUrl when set,
-    // while keeping authorizationUrl public for browser redirects.
+    const issuerUrlObj = new URL(providerConfig.issuerUrl);
+    const issuerHostname = issuerUrlObj.hostname;
+
     const discoveryUrlStr = `${providerConfig.issuerUrl}/.well-known/openid-configuration`;
     let oidcConfig: Record<string, string> = {};
     try {
@@ -203,6 +203,18 @@ export async function initAuth(): Promise<void> {
         const tokenUrl = discovery.token_endpoint;
         const userInfoUrl = discovery.userinfo_endpoint;
         if (authzUrl && tokenUrl && userInfoUrl) {
+          const authzUrlObj = new URL(authzUrl);
+          const tokenUrlObj = new URL(tokenUrl);
+          const userInfoUrlObj = new URL(userInfoUrl);
+          if (
+            authzUrlObj.hostname !== issuerHostname ||
+            tokenUrlObj.hostname !== issuerHostname ||
+            userInfoUrlObj.hostname !== issuerHostname
+          ) {
+            throw new Error(
+              `[FATAL] OIDC discovery URL hostname mismatch: expected '${issuerHostname}' but got '${authzUrlObj.hostname}', '${tokenUrlObj.hostname}', or '${userInfoUrlObj.hostname}'. This may indicate a man-in-the-middle attack.`
+            );
+          }
           oidcConfig = {
             authorizationUrl: authzUrl,
             tokenUrl: providerConfig.internalBaseUrl

apps/api/src/middleware/rbac.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import { eq, getDb, staff } from "@groombook/db";
+import { and, eq, getDb, sql, staff } from "@groombook/db";
 
 export type StaffRole = "groomer" | "receptionist" | "manager";
 export type StaffRow = typeof staff.$inferSelect;
@@ -89,14 +89,31 @@ export const resolveStaffMiddleware: MiddlewareHandler<AppEnv> = async (
     .select()
     .from(staff)
     .where(eq(staff.oidcSub, jwt.sub));
-  if (!fallbackRow) {
-    return c.json(
-      { error: "Forbidden: no staff record found for authenticated user" },
-      403
-    );
+  if (fallbackRow) {
+    c.set("staff", fallbackRow);
+    await next();
+    return;
   }
-  c.set("staff", fallbackRow);
-  await next();
+  // Auto-link by email: staff record exists with matching email but no userId
+  if (jwt.email) {
+    const [byEmail] = await db
+      .select()
+      .from(staff)
+      .where(and(eq(staff.email, jwt.email), sql`${staff.userId} IS NULL`));
+    if (byEmail) {
+      await db
+        .update(staff)
+        .set({ userId: jwt.sub, updatedAt: new Date() })
+        .where(eq(staff.id, byEmail.id));
+      c.set("staff", { ...byEmail, userId: jwt.sub });
+      await next();
+      return;
+    }
+  }
+  return c.json(
+    { error: "Forbidden: no staff record found for authenticated user" },
+    403
+  );
 };
 
 /**
@@ -149,9 +166,9 @@ export function requireRoleOrSuperUser(
     }
     return c.json(
       {
-        error: staffRow.isSuperUser
-          ? `Forbidden: role '${staffRow.role}' is not permitted`
-          : "Forbidden: super user privileges required",
+        error: hasAllowedRole
+          ? "Forbidden: super user privileges required"
+          : `Forbidden: role '${staffRow.role}' is not permitted`,
       },
       403
     );

apps/api/src/routes/appointments.ts

@@ -23,6 +23,27 @@ import { buildConfirmationEmail, sendEmail } from "../services/email.js";
 import { notifyWaitlistForAppointment } from "../services/waitlistNotify.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  maxRetries: number,
+  delayMs: number,
+  context: string
+): Promise<void> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      await fn();
+      return;
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxRetries) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+  console.error(`[appointments] ${context}: ${lastError}`);
+}
+
 export const appointmentsRouter = new Hono<AppEnv>();
 
 const createAppointmentSchema = z.object({
@@ -212,11 +233,54 @@ appointmentsRouter.post(
           recurrence.frequencyWeeks * 7 * 24 * 60 * 60 * 1000;
 
         let first: typeof appointments.$inferSelect | undefined;
+        const conflictingInstances: number[] = [];
         for (let i = 0; i < recurrence.count; i++) {
           const instanceStart = new Date(start.getTime() + i * intervalMs);
           const instanceEnd = new Date(
             instanceStart.getTime() + durationMs
           );
+
+          if (apptFields.staffId) {
+            const conflicts = await tx
+              .select({ id: appointments.id })
+              .from(appointments)
+              .where(
+                and(
+                  eq(appointments.staffId, apptFields.staffId),
+                  lt(appointments.startTime, instanceEnd),
+                  gte(appointments.endTime, instanceStart),
+                  ne(appointments.status, "cancelled"),
+                  ne(appointments.status, "no_show"),
+                )
+              )
+              .limit(1);
+            if (conflicts.length > 0) {
+              conflictingInstances.push(i);
+            }
+          }
+
+          if (apptFields.batherStaffId) {
+            const conflicts = await tx
+              .select({ id: appointments.id })
+              .from(appointments)
+              .where(
+                and(
+                  or(
+                    eq(appointments.staffId, apptFields.batherStaffId),
+                    eq(appointments.batherStaffId, apptFields.batherStaffId)
+                  ),
+                  lt(appointments.startTime, instanceEnd),
+                  gte(appointments.endTime, instanceStart),
+                  ne(appointments.status, "cancelled"),
+                  ne(appointments.status, "no_show"),
+                )
+              )
+              .limit(1);
+            if (conflicts.length > 0) {
+              conflictingInstances.push(i);
+            }
+          }
+
           const [inserted] = await tx
             .insert(appointments)
             .values({
@@ -227,9 +291,19 @@ appointmentsRouter.post(
               seriesIndex: i,
             })
             .returning();
+          if (!inserted) throw new Error(`Insert failed for occurrence ${i}`);
           if (i === 0) first = inserted;
         }
 
+        if (conflictingInstances.length > 0) {
+          throw Object.assign(
+            new Error(
+              `Conflicts detected at occurrence(s): ${conflictingInstances.join(", ")}`
+            ),
+            { statusCode: 409 }
+          );
+        }
+
         if (!first) throw new Error("No appointments created");
         return first;
       });
@@ -247,9 +321,12 @@ appointmentsRouter.post(
     }
 
     // Send confirmation email (fire-and-forget — never fails the request)
-    sendConfirmationEmail(db, firstRow).catch((err) => {
-      console.error("[appointments] Failed to send confirmation email:", err);
-    });
+    withRetry(
+      () => sendConfirmationEmail(db, firstRow),
+      2,
+      1000,
+      `Failed to send confirmation email for appointment ${firstRow.id}`
+    );
 
     return c.json(firstRow, 201);
   }
@@ -378,6 +455,76 @@ appointmentsRouter.patch(
 
           let firstUpdated: typeof appointments.$inferSelect | undefined;
           for (const appt of affected) {
+            const newStart =
+              startDeltaMs !== 0
+                ? new Date(appt.startTime.getTime() + startDeltaMs)
+                : appt.startTime;
+            const newEnd =
+              endDeltaMs !== 0
+                ? new Date(appt.endTime.getTime() + endDeltaMs)
+                : appt.endTime;
+            const newStaffId =
+              updateFields.staffId !== undefined
+                ? updateFields.staffId
+                : appt.staffId;
+            const newBatherStaffId =
+              updateFields.batherStaffId !== undefined
+                ? updateFields.batherStaffId
+                : appt.batherStaffId;
+
+            if (
+              newStaffId &&
+              (startDeltaMs !== 0 ||
+                endDeltaMs !== 0 ||
+                updateFields.staffId !== undefined)
+            ) {
+              const conflicts = await tx
+                .select({ id: appointments.id })
+                .from(appointments)
+                .where(
+                  and(
+                    eq(appointments.staffId, newStaffId),
+                    lt(appointments.startTime, newEnd),
+                    gte(appointments.endTime, newStart),
+                    ne(appointments.status, "cancelled"),
+                    ne(appointments.status, "no_show"),
+                    ne(appointments.id, appt.id),
+                  )
+                )
+                .limit(1);
+              if (conflicts.length > 0) {
+                throw Object.assign(new Error("conflict"), { statusCode: 409 });
+              }
+            }
+
+            if (
+              newBatherStaffId &&
+              (startDeltaMs !== 0 ||
+                endDeltaMs !== 0 ||
+                updateFields.batherStaffId !== undefined)
+            ) {
+              const conflicts = await tx
+                .select({ id: appointments.id })
+                .from(appointments)
+                .where(
+                  and(
+                    or(
+                      eq(appointments.staffId, newBatherStaffId),
+                      eq(appointments.batherStaffId, newBatherStaffId)
+                    ),
+                    lt(appointments.startTime, newEnd),
+                    gte(appointments.endTime, newStart),
+                    ne(appointments.status, "cancelled"),
+                    ne(appointments.status, "no_show"),
+                    ne(appointments.id, appt.id),
+                  )
+                )
+                .limit(1);
+              if (conflicts.length > 0) {
+                throw Object.assign(new Error("conflict"), { statusCode: 409 });
+              }
+            }
+
             const apptUpdate: Record<string, unknown> = {
               updatedAt: new Date(),
             };
@@ -413,6 +560,13 @@ appointmentsRouter.patch(
         if (statusCode === 404) return c.json({ error: "Not found" }, 404);
         if (statusCode === 422)
           return c.json({ error: "endTime must be after startTime" }, 422);
+        if (statusCode === 409)
+          return c.json(
+            {
+              error: "Staff member has a conflicting appointment at this time",
+            },
+            409
+          );
         throw err;
       }
 
@@ -590,9 +744,12 @@ appointmentsRouter.delete("/:id", async (c) => {
 
     const apptDate = current.startTime.toISOString().slice(0, 10);
     const apptTime = current.startTime.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit", hour12: true });
-    notifyWaitlistForAppointment(id, apptDate, apptTime, current.serviceId).catch((err) => {
-      console.error("[appointments] Failed to notify waitlist:", err);
-    });
+    withRetry(
+      () => notifyWaitlistForAppointment(id, apptDate, apptTime, current.serviceId),
+      2,
+      1000,
+      `Failed to notify waitlist for appointment ${id}`
+    );
 
     return c.json({ ok: true });
   }
@@ -615,9 +772,12 @@ appointmentsRouter.delete("/:id", async (c) => {
     .returning();
   if (!row) return c.json({ error: "Not found" }, 404);
 
-  notifyWaitlistForAppointment(id, apptDate, apptTime, current.serviceId).catch((err) => {
-    console.error("[appointments] Failed to notify waitlist:", err);
-  });
+  withRetry(
+    () => notifyWaitlistForAppointment(id, apptDate, apptTime, current.serviceId),
+    2,
+    1000,
+    `Failed to notify waitlist for appointment ${id}`
+  );
 
   return c.json({ ok: true });
 });

apps/api/src/routes/book.ts

@@ -268,29 +268,36 @@ bookRouter.get("/confirm/:token", async (c) => {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Reject if appointment is in the past
   if (appt.startTime < new Date()) {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Idempotent confirm: if already confirmed, redirect to success
   if (appt.confirmationStatus === "confirmed") {
     return c.redirect(`${BASE_URL()}/booking/confirmed`);
   }
 
-  // Reject if already cancelled
   if (appt.confirmationStatus === "cancelled") {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  await db
+  const updated = await db
     .update(appointments)
     .set({
       confirmationStatus: "confirmed",
       confirmedAt: new Date(),
       updatedAt: new Date(),
     })
-    .where(eq(appointments.id, appt.id));
+    .where(
+      and(
+        eq(appointments.confirmationToken, token),
+        eq(appointments.confirmationStatus, "pending")
+      )
+    )
+    .returning();
+
+  if (updated.length === 0) {
+    return c.redirect(`${BASE_URL()}/booking/error`);
+  }
 
   return c.redirect(`${BASE_URL()}/booking/confirmed`);
 });
@@ -312,19 +319,15 @@ bookRouter.get("/cancel/:token", async (c) => {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Reject if appointment is in the past
   if (appt.startTime < new Date()) {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Reject if already cancelled (token was nullified — this path won't normally hit,
-  // but guard against edge cases where token lookup still works)
   if (appt.confirmationStatus === "cancelled") {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Single-use cancellation: nullify token after use
-  await db
+  const updated = await db
     .update(appointments)
     .set({
       confirmationStatus: "cancelled",
@@ -332,7 +335,17 @@ bookRouter.get("/cancel/:token", async (c) => {
       confirmationToken: null,
       updatedAt: new Date(),
     })
-    .where(eq(appointments.id, appt.id));
+    .where(
+      and(
+        eq(appointments.confirmationToken, token),
+        eq(appointments.confirmationStatus, "pending")
+      )
+    )
+    .returning();
+
+  if (updated.length === 0) {
+    return c.redirect(`${BASE_URL()}/booking/error`);
+  }
 
   return c.redirect(`${BASE_URL()}/booking/cancelled`);
 });

apps/api/src/routes/calendar.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { randomBytes } from "node:crypto";
+import { randomBytes, timingSafeEqual } from "node:crypto";
 import {
   and,
   eq,
@@ -84,7 +84,18 @@ calendarRouter.get("/:staffId.ics", async (c) => {
     .where(eq(staff.id, staffId))
     .limit(1);
 
-  if (!staffMember || staffMember.icalToken !== token) {
+  if (!staffMember || !staffMember.icalToken) {
+    return c.text("Unauthorized", 401);
+  }
+
+  const storedToken = staffMember.icalToken;
+  const incomingToken = token;
+  const storedBuf = Buffer.from(storedToken, "utf8");
+  const incomingBuf = Buffer.from(incomingToken, "utf8");
+  if (
+    storedBuf.length !== incomingBuf.length ||
+    !timingSafeEqual(storedBuf, incomingBuf)
+  ) {
     return c.text("Unauthorized", 401);
   }
 

apps/api/src/routes/clients.ts

@@ -12,6 +12,8 @@ const createClientSchema = z.object({
   phone: z.string().max(50).optional(),
   address: z.string().max(500).optional(),
   notes: z.string().max(2000).optional(),
+  smsOptIn: z.boolean().optional(),
+  smsConsentText: z.string().max(1000).optional(),
 });
 
 
@@ -95,6 +97,7 @@ clientsRouter.post("/", zValidator("json", createClientSchema), async (c) => {
 // Update a client (including status changes)
 const patchClientSchema = createClientSchema.partial().extend({
   status: z.enum(["active", "disabled"]).optional(),
+  smsOptOut: z.boolean().optional(),
 });
 
 clientsRouter.patch(
@@ -107,13 +110,19 @@ clientsRouter.patch(
 
     const setValues: Record<string, unknown> = { ...body, updatedAt: now };
 
-    // When disabling, set disabledAt; when re-enabling, clear it
     if (body.status === "disabled") {
       setValues.disabledAt = now;
     } else if (body.status === "active") {
       setValues.disabledAt = null;
     }
 
+    if (body.smsOptOut === true) {
+      setValues.smsOptIn = false;
+      setValues.smsOptOutDate = now;
+      delete setValues.smsOptOut;
+    }
+    delete setValues.smsOptOut;
+
     const [row] = await db
       .update(clients)
       .set(setValues)
@@ -135,9 +144,24 @@ clientsRouter.delete("/:id", async (c) => {
   }
 
   const db = getDb();
+  const clientId = c.req.param("id");
+
+  const [existingAppt] = await db
+    .select({ id: appointments.id })
+    .from(appointments)
+    .where(eq(appointments.clientId, clientId))
+    .limit(1);
+
+  if (existingAppt) {
+    return c.json(
+      { error: "Cannot delete client with existing appointments. Cancel or reassign appointments first." },
+      409
+    );
+  }
+
   const [row] = await db
     .delete(clients)
-    .where(eq(clients.id, c.req.param("id")))
+    .where(eq(clients.id, clientId))
     .returning();
   if (!row) return c.json({ error: "Not found" }, 404);
   return c.json({ ok: true });

apps/api/src/routes/invoices.ts

@@ -8,6 +8,7 @@ import {
   invoices,
   invoiceLineItems,
   invoiceTipSplits,
+  refunds,
   appointments,
   services,
   clients,
@@ -125,8 +126,8 @@ const tipSplitSchema = z.object({
     })
   ).min(1).refine(
     (splits) => {
-      const total = splits.reduce((sum, s) => sum + s.sharePct, 0);
-      return Math.abs(total - 100) < 0.01;
+      const totalBps = splits.reduce((sum, s) => sum + Math.round(s.sharePct * 100), 0);
+      return totalBps === 10000;
     },
     { message: "Split percentages must sum to 100" }
   ),
@@ -170,12 +171,13 @@ invoicesRouter.post(
       }
     });
 
-    const splits = await db
-      .select()
-      .from(invoiceTipSplits)
-      .where(eq(invoiceTipSplits.invoiceId, id));
+    const [updatedInvoice] = await db.select().from(invoices).where(eq(invoices.id, id));
+    const [lineItems, tipSplits] = await Promise.all([
+      db.select().from(invoiceLineItems).where(eq(invoiceLineItems.invoiceId, id)),
+      db.select().from(invoiceTipSplits).where(eq(invoiceTipSplits.invoiceId, id)),
+    ]);
 
-    return c.json(splits, 201);
+    return c.json({ ...updatedInvoice, lineItems, tipSplits }, 201);
   }
 );
 
@@ -300,6 +302,13 @@ invoicesRouter.post("/from-appointment/:appointmentId", async (c) => {
   return c.json({ ...invoice, lineItems: [lineItem] }, 201);
 });
 
+const ALLOWED_TRANSITIONS: Record<string, string[]> = {
+  draft: ["pending", "void"],
+  pending: ["draft", "paid", "void"],
+  paid: ["void"],
+  void: [],
+};
+
 // Update invoice
 invoicesRouter.patch(
   "/:id",
@@ -315,8 +324,14 @@ invoicesRouter.patch(
       .where(eq(invoices.id, id));
     if (!current) return c.json({ error: "Not found" }, 404);
 
-    if (current.status === "void") {
-      return c.json({ error: "Cannot modify a voided invoice" }, 422);
+    if (body.status !== undefined) {
+      const allowed = ALLOWED_TRANSITIONS[current.status] ?? [];
+      if (!allowed.includes(body.status)) {
+        return c.json(
+          { error: `Invalid status transition from ${current.status} to ${body.status}` },
+          422
+        );
+      }
     }
 
     const update: Record<string, unknown> = { ...body, updatedAt: new Date() };
@@ -354,6 +369,7 @@ import { processRefund } from "../services/payment.js";
 
 const refundSchema = z.object({
   amountCents: z.number().int().nonnegative().optional(),
+  idempotencyKey: z.string().max(255).optional(),
 });
 
 invoicesRouter.post(
@@ -379,9 +395,28 @@ invoicesRouter.post(
       return c.json({ error: "No Stripe payment intent found for this invoice" }, 422);
     }
 
-    const result = await processRefund(id, body.amountCents);
-    if (!result) return c.json({ error: "Refund failed" }, 500);
+    return await db.transaction(async (tx) => {
+      if (body.idempotencyKey) {
+        const [existing] = await tx
+          .select()
+          .from(refunds)
+          .where(eq(refunds.idempotencyKey, body.idempotencyKey));
+        if (existing) {
+          return c.json({ refundId: existing.stripeRefundId });
+        }
+      }
 
-    return c.json({ refundId: result.refundId });
+      const result = await processRefund(id, body.amountCents);
+      if (!result) return c.json({ error: "Refund failed" }, 500);
+
+      await tx.insert(refunds).values({
+        invoiceId: id,
+        stripeRefundId: result.refundId,
+        idempotencyKey: body.idempotencyKey ?? null,
+        amountCents: body.amountCents ?? null,
+      });
+
+      return c.json({ refundId: result.refundId });
+    });
   }
 );

apps/api/src/routes/setup.ts

@@ -4,6 +4,24 @@ import { z } from "zod/v3";
 import { and, eq, getDb, sql, staff, businessSettings, authProviderConfig, encryptSecret } from "@groombook/db";
 import type { AppEnv } from "../middleware/rbac.js";
 
+const RATE_LIMIT_WINDOW_MS = 60_000;
+const RATE_LIMIT_MAX = 10;
+const rateLimitMap = new Map<string, { count: number; resetAt: number }>();
+
+function rateLimitByIp(ip: string): { allowed: boolean; remaining: number } {
+  const now = Date.now();
+  const entry = rateLimitMap.get(ip);
+  if (!entry || now > entry.resetAt) {
+    rateLimitMap.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS });
+    return { allowed: true, remaining: RATE_LIMIT_MAX - 1 };
+  }
+  if (entry.count >= RATE_LIMIT_MAX) {
+    return { allowed: false, remaining: 0 };
+  }
+  entry.count++;
+  return { allowed: true, remaining: RATE_LIMIT_MAX - entry.count };
+}
+
 export const setupRouter = new Hono<AppEnv>();
 
 // GET /api/setup/status — public (no auth), returns whether setup is needed
@@ -185,52 +203,74 @@ const authProviderTestSchema = z.object({
  * After setup completes, this endpoint permanently returns 403.
  */
 setupRouter.post("/auth-provider", async (c) => {
+  const ip = c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? "unknown";
+  const { allowed, remaining } = rateLimitByIp(ip);
+  c.res.headers.set("x-rate-limit-remaining", String(remaining));
+  if (!allowed) {
+    return c.json({ error: "Too many requests. Please try again later." }, 429);
+  }
+
   const db = getDb();
 
-  // Guard: only allow during fresh install (no super user yet)
-  const [superUser] = await db
-    .select({ id: staff.id })
-    .from(staff)
-    .where(eq(staff.isSuperUser, true))
-    .limit(1);
+  let row: typeof authProviderConfig.$inferSelect;
+  try {
+    row = await db.transaction(async (tx) => {
+      const [superUser] = await tx
+        .select({ id: staff.id })
+        .from(staff)
+        .where(eq(staff.isSuperUser, true))
+        .limit(1);
 
-  if (superUser) {
-    // Setup already completed — lock this endpoint permanently
-    return c.json({ error: "Setup has already been completed. This endpoint is no longer available." }, 403);
-  }
+      if (superUser) {
+        throw Object.assign(new Error("setup-complete"), { code: 403 });
+      }
 
-  // Guard: ensure no DB config already exists (should be redundant with status check but defensive)
-  const [existingConfig] = await db
-    .select({ id: authProviderConfig.id })
-    .from(authProviderConfig)
-    .where(eq(authProviderConfig.enabled, true))
-    .limit(1);
+      const [existingConfig] = await tx
+        .select({ id: authProviderConfig.id })
+        .from(authProviderConfig)
+        .where(eq(authProviderConfig.enabled, true))
+        .limit(1);
 
-  if (existingConfig) {
-    return c.json({ error: "Auth provider is already configured." }, 409);
-  }
+      if (existingConfig) {
+        throw Object.assign(new Error("config-exists"), { code: 409 });
+      }
 
-  const body = authProviderBootstrapSchema.parse(await c.req.json());
+      const body = authProviderBootstrapSchema.parse(await c.req.json());
 
-  // Encrypt clientSecret before storing
-  const encryptedSecret = encryptSecret(body.clientSecret);
+      const encryptedSecret = encryptSecret(body.clientSecret);
 
-  const [row] = await db
-    .insert(authProviderConfig)
-    .values({
-      providerId: body.providerId,
-      displayName: body.displayName,
-      issuerUrl: body.issuerUrl,
-      internalBaseUrl: body.internalBaseUrl ?? null,
-      clientId: body.clientId,
-      clientSecret: encryptedSecret,
-      scopes: body.scopes,
-      enabled: true,
-    })
-    .returning();
+      const [configRow] = await tx
+        .insert(authProviderConfig)
+        .values({
+          providerId: body.providerId,
+          displayName: body.displayName,
+          issuerUrl: body.issuerUrl,
+          internalBaseUrl: body.internalBaseUrl ?? null,
+          clientId: body.clientId,
+          clientSecret: encryptedSecret,
+          scopes: body.scopes,
+          enabled: true,
+        })
+        .returning();
 
-  if (!row) {
-    return c.json({ error: "Failed to save auth provider configuration." }, 500);
+      if (!configRow) {
+        throw Object.assign(new Error("insert-failed"), { code: 500 });
+      }
+
+      return configRow;
+    });
+  } catch (err: unknown) {
+    const e = err as Error & { code?: number };
+    if (e.message === "setup-complete") {
+      return c.json({ error: "Setup has already been completed. This endpoint is no longer available." }, e.code as 403);
+    }
+    if (e.message === "config-exists") {
+      return c.json({ error: "Auth provider is already configured." }, e.code as 409);
+    }
+    if (e.message === "insert-failed") {
+      return c.json({ error: "Failed to save auth provider configuration." }, e.code as 500);
+    }
+    throw err;
   }
 
   return c.json({
@@ -254,6 +294,13 @@ setupRouter.post("/auth-provider", async (c) => {
  * Only available when needsSetup is true (no super user = fresh install).
  */
 setupRouter.post("/auth-provider/test", async (c) => {
+  const ip = c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? "unknown";
+  const { allowed, remaining } = rateLimitByIp(ip);
+  c.res.headers.set("x-rate-limit-remaining", String(remaining));
+  if (!allowed) {
+    return c.json({ ok: false, error: "Too many requests. Please try again later." }, 429);
+  }
+
   const db = getDb();
 
   // Guard: only allow during fresh install (no super user yet)

apps/api/src/services/reminders.ts

@@ -6,6 +6,7 @@ import {
   getDb,
   gte,
   lt,
+  sql,
   appointments,
   clients,
   pets,
@@ -18,9 +19,10 @@ import {
   buildReminderEmail,
   sendEmail,
 } from "./email.js";
+import { smsSend } from "./sms.js";
+
+const TCPA_OPT_OUT = "Reply STOP to opt out. Msg & data rates may apply.";
 
-// How many hours before the appointment to send each reminder.
-// Override via env: REMINDER_HOURS_EARLY (default 24) and REMINDER_HOURS_LATE (default 2).
 function getReminderWindows(): { label: string; hours: number }[] {
   const early = Number(process.env.REMINDER_HOURS_EARLY ?? 24);
   const late = Number(process.env.REMINDER_HOURS_LATE ?? 2);
@@ -37,13 +39,9 @@ export async function runReminderCheck(): Promise<void> {
   const now = new Date();
 
   for (const window of getReminderWindows()) {
-    // Target window: appointments starting between (hours - 1) and hours from now.
-    // Running every minute means we check a 1-minute slice; the 1-hour window
-    // ensures we catch appointments that started between heartbeats.
     const windowStart = new Date(now.getTime() + (window.hours - 1) * 3600_000);
     const windowEnd = new Date(now.getTime() + window.hours * 3600_000);
 
-    // Find upcoming appointments in this time window that haven't been cancelled/completed
     const upcoming = await db
       .select({
         id: appointments.id,
@@ -64,56 +62,74 @@ export async function runReminderCheck(): Promise<void> {
         )
       );
 
-    for (const appt of upcoming) {
-      // Check if reminder already sent (unique constraint prevents double-send)
-      const existing = await db
-        .select({ id: reminderLogs.id })
-        .from(reminderLogs)
-        .where(
-          and(
-            eq(reminderLogs.appointmentId, appt.id),
-            eq(reminderLogs.reminderType, window.label)
+    const appointmentIds: string[] = upcoming.map((a) => a.id as string);
+
+    if (appointmentIds.length === 0) continue;
+
+    // Batch-fetch already-sent appointment IDs (both EMAIL and SMS channels)
+    const sentAppointmentIds = new Set(
+      (
+        await db
+          .select({ appointmentId: reminderLogs.appointmentId })
+          .from(reminderLogs)
+          .where(
+            and(
+              eq(reminderLogs.reminderType, window.label),
+              appointmentIds.length === 1
+                ? eq(reminderLogs.appointmentId, appointmentIds[0]!)
+                : sql`${reminderLogs.appointmentId} = ANY(${appointmentIds})`
+            )
           )
+      ).map((r) => r.appointmentId)
+    );
+
+    // Batch-fetch all appointment data with related joins in a single query
+    const joinedRows = await db
+      .select({
+        appointmentId: appointments.id,
+        startTime: appointments.startTime,
+        clientId: appointments.clientId,
+        petId: appointments.petId,
+        serviceId: appointments.serviceId,
+        staffId: appointments.staffId,
+        confirmationToken: appointments.confirmationToken,
+        clientName: clients.name,
+        clientEmail: clients.email,
+        clientEmailOptOut: clients.emailOptOut,
+        clientPhone: clients.phone,
+        clientSmsOptIn: clients.smsOptIn,
+        petName: pets.name,
+        serviceName: services.name,
+        staffName: staff.name,
+      })
+      .from(appointments)
+      .innerJoin(clients, eq(appointments.clientId, clients.id))
+      .innerJoin(pets, eq(appointments.petId, pets.id))
+      .innerJoin(services, eq(appointments.serviceId, services.id))
+      .leftJoin(staff, eq(appointments.staffId, staff.id))
+      .where(
+        and(
+          sql`${appointments.id} = ANY(${appointmentIds})`,
+          gte(appointments.startTime, windowStart),
+          lt(appointments.startTime, windowEnd),
+          eq(appointments.status, "scheduled")
         )
-        .limit(1);
+      );
 
-      if (existing.length > 0) continue; // already sent
+    const appointmentMap = new Map<string, typeof joinedRows[number]>();
+    for (const row of joinedRows) {
+      appointmentMap.set(row.appointmentId, row);
+    }
 
-      // Fetch related records for the email
-      const [client] = await db
-        .select({ name: clients.name, email: clients.email, emailOptOut: clients.emailOptOut })
-        .from(clients)
-        .where(eq(clients.id, appt.clientId))
-        .limit(1);
+    for (const appt of upcoming) {
+      // Already sent a reminder for this appointment in this window
+      if (sentAppointmentIds.has(appt.id)) continue;
 
-      if (!client || !client.email || client.emailOptOut) continue;
+      const row = appointmentMap.get(appt.id);
+      if (!row) continue;
+      if (!row.petName || !row.serviceName) continue;
 
-      const [pet] = await db
-        .select({ name: pets.name })
-        .from(pets)
-        .where(eq(pets.id, appt.petId))
-        .limit(1);
-
-      const [service] = await db
-        .select({ name: services.name })
-        .from(services)
-        .where(eq(services.id, appt.serviceId))
-        .limit(1);
-
-      let groomerName: string | null = null;
-      if (appt.staffId) {
-        const [groomer] = await db
-          .select({ name: staff.name })
-          .from(staff)
-          .where(eq(staff.id, appt.staffId))
-          .limit(1);
-        groomerName = groomer?.name ?? null;
-      }
-
-      if (!pet || !service) continue;
-
-      // Ensure the appointment has a confirmation token before sending the reminder.
-      // Generate one if it doesn't have one yet (e.g. pre-existing appointments).
+      // Generate confirmation token if missing
       let confirmationToken = appt.confirmationToken;
       if (!confirmationToken) {
         confirmationToken = randomBytes(32).toString("hex");
@@ -123,35 +139,60 @@ export async function runReminderCheck(): Promise<void> {
           .where(eq(appointments.id, appt.id));
       }
 
-      const sent = await sendEmail(
-        buildReminderEmail(
-          client.email,
-          {
-            clientName: client.name,
-            petName: pet.name,
-            serviceName: service.name,
-            groomerName,
-            startTime: appt.startTime,
-          },
-          window.hours,
-          confirmationToken
-        )
-      );
+      const clientName = row.clientName;
+      const petName = row.petName;
+      const serviceName = row.serviceName;
+      const groomerName = row.staffName ?? null;
+      const startTime = appt.startTime;
 
-      if (sent) {
-        // Record send — ignore conflicts (race condition between instances)
-        await db
-          .insert(reminderLogs)
-          .values({ appointmentId: appt.id, reminderType: window.label })
-          .onConflictDoNothing();
+      // EMAIL reminder
+      if (row.clientEmail && !row.clientEmailOptOut) {
+        const sent = await sendEmail(
+          buildReminderEmail(
+            row.clientEmail,
+            { clientName, petName, serviceName, groomerName, startTime },
+            window.hours,
+            confirmationToken
+          )
+        );
+        if (sent) {
+          await db
+            .insert(reminderLogs)
+            .values({ appointmentId: appt.id, reminderType: window.label, channel: "email" })
+            .onConflictDoNothing();
+        }
+      }
+
+      // SMS reminder
+      if (row.clientPhone && row.clientSmsOptIn) {
+        const apiUrl = process.env.API_URL ?? "http://localhost:3000";
+        const confirmUrl = `${apiUrl}/api/book/confirm/${confirmationToken}`;
+        const cancelUrl = `${apiUrl}/api/book/cancel/${confirmationToken}`;
+        const when = window.hours >= 24 ? "tomorrow" : `in ${window.hours} hours`;
+        const smsBody = [
+          `Hi ${clientName}, just a reminder: ${petName}'s grooming appointment is ${when}.`,
+          `Service: ${serviceName}${groomerName ? ` with ${groomerName}` : ""}`,
+          `Confirm: ${confirmUrl}`,
+          `Cancel: ${cancelUrl}`,
+          TCPA_OPT_OUT,
+        ].join(". ");
+        try {
+          const smsOk = await smsSend(row.clientPhone, smsBody);
+          if (smsOk) {
+            await db
+              .insert(reminderLogs)
+              .values({ appointmentId: appt.id, reminderType: window.label, channel: "sms" })
+              .onConflictDoNothing();
+          }
+        } catch (err) {
+          console.error("[reminders] SMS send failed:", err);
+        }
       }
     }
   }
 }
 
-// Starts the cron scheduler. Call once at server startup.
 export function startReminderScheduler(): void {
-  // Run every minute
   cron.schedule("* * * * *", () => {
     runReminderCheck().catch((err) => {
       console.error("[reminders] Error during reminder check:", err);
@@ -163,8 +204,6 @@ export function startReminderScheduler(): void {
   console.log("[reminders] Reminder scheduler started");
 }
 
-// Deletes expired sessions from the database.
-// Runs every minute alongside reminder checks.
 export async function runSessionCleanup(): Promise<void> {
   const db = getDb();
   const now = new Date();

apps/api/src/services/sms.ts

@@ -0,0 +1,142 @@
+import { Telnyx } from "telnyx";
+import { createHmac } from "crypto";
+
+export interface SmsProvider {
+  sendSms(to: string, body: string, mediaUrls?: string[]): Promise<{ messageId: string; status: string }>;
+  validateWebhookSignature(req: Request): boolean;
+}
+
+interface TelnyxSmsResult {
+  message_id: string;
+  status: string;
+}
+
+function createTelnyxClient(): Telnyx | null {
+  const apiKey = process.env.TELNYX_API_KEY;
+  if (!apiKey) return null;
+  return new Telnyx(apiKey);
+}
+
+let _client: Telnyx | null | undefined;
+
+function getClient(): Telnyx | null {
+  if (_client === undefined) _client = createTelnyxClient();
+  return _client;
+}
+
+function getFromNumber(): string | null {
+  return process.env.TELNYX_FROM_NUMBER ?? null;
+}
+
+function isE164(phone: string): boolean {
+  return /^\+[1-9]\d{7,14}$/.test(phone);
+}
+
+export async function sendSms(
+  to: string,
+  body: string,
+  mediaUrls?: string[]
+): Promise<{ messageId: string; status: string }> {
+  const client = getClient();
+  if (!client) throw new Error("Telnyx client not initialized. Set TELNYX_API_KEY.");
+
+  const from = getFromNumber();
+  if (!from) throw new Error("TELNYX_FROM_NUMBER is not set");
+
+  if (!isE164(to)) throw new Error(`Invalid recipient phone format: ${to}. Expected E.164.`);
+  if (!isE164(from)) throw new Error(`Invalid sender phone format: ${from}. Expected E.164.`);
+
+  const payload: Record<string, unknown> = {
+    from,
+    to,
+    body,
+  };
+
+  if (mediaUrls && mediaUrls.length > 0) {
+    payload.media_urls = mediaUrls;
+  }
+
+  const result = await client.messages.create(payload as Record<string, string | string[]>);
+  const smsResult = result.data as unknown as TelnyxSmsResult;
+  return {
+    messageId: smsResult.message_id,
+    status: smsResult.status,
+  };
+}
+
+export class TelnyxProvider implements SmsProvider {
+  async sendSms(
+    to: string,
+    body: string,
+    mediaUrls?: string[]
+  ): Promise<{ messageId: string; status: string }> {
+    return sendSms(to, body, mediaUrls);
+  }
+
+  validateWebhookSignature(req: Request): boolean {
+    const secret = process.env.TELNYX_WEBHOOK_SECRET;
+    if (!secret) return false;
+
+    const signature = req.headers.get("telnyx-signature");
+    if (!signature) return false;
+
+    const payload = JSON.stringify(req.body);
+
+    try {
+      const hmac = createHmac("sha256", secret);
+      const expected = `sha256=${hmac.update(payload).digest("hex")}`;
+
+      const sigBuf = Buffer.from(signature);
+      const expBuf = Buffer.from(expected);
+
+      if (sigBuf.length !== expBuf.length) return false;
+
+      let diff = 0;
+      for (let i = 0; i < sigBuf.length; i++) {
+        const sigByte = sigBuf[i] ?? 0;
+        const expByte = expBuf[i] ?? 0;
+        diff |= sigByte ^ expByte;
+      }
+      return diff === 0;
+    } catch {
+      return false;
+    }
+  }
+}
+
+let _provider: SmsProvider | null | undefined;
+
+export function createSmsProvider(): SmsProvider | null {
+  if (_provider === undefined) {
+    if (process.env.SMS_ENABLED !== "true") {
+      _provider = null;
+      return null;
+    }
+    switch (process.env.SMS_PROVIDER) {
+      case "telnyx": {
+        const client = getClient();
+        if (!client) {
+          _provider = null;
+          return null;
+        }
+        _provider = new TelnyxProvider();
+        break;
+      }
+      default:
+        _provider = null;
+    }
+  }
+  return _provider;
+}
+
+export async function smsSend(
+  to: string,
+  body: string,
+  mediaUrls?: string[]
+): Promise<boolean> {
+  const provider = createSmsProvider();
+  if (!provider) return false;
+
+  await provider.sendSms(to, body, mediaUrls);
+  return true;
+}

apps/api/src/types/telnyx.d.ts

@@ -0,0 +1,19 @@
+declare module "telnyx" {
+  export interface MessageResult {
+    data: unknown;
+  }
+
+  export interface MessagesCreateParams {
+    from: string;
+    to: string;
+    body: string;
+    media_urls?: string[];
+  }
+
+  export class Telnyx {
+    constructor(apiKey: string);
+    messages: {
+      create(params: Record<string, string | string[]>): Promise<MessageResult>;
+    };
+  }
+}

packages/db/migrations/0027_refunds.sql

@@ -0,0 +1,11 @@
+CREATE TABLE "refunds" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "invoice_id" uuid NOT NULL REFERENCES "invoices"("id") ON DELETE RESTRICT,
+  "stripe_refund_id" text NOT NULL,
+  "idempotency_key" text UNIQUE,
+  "amount_cents" integer,
+  "created_at" timestamp NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX "idx_refunds_invoice_id" ON "refunds"("invoice_id");
+CREATE INDEX "idx_refunds_idempotency_key" ON "refunds"("idempotency_key");

packages/db/migrations/0028_sms_reminders.sql

@@ -0,0 +1,15 @@
+-- SMS opt-in fields for clients (idempotent)
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "sms_opt_in" boolean NOT NULL DEFAULT false;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "sms_consent_date" timestamp;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "sms_opt_out_date" timestamp;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "sms_consent_text" text;
+
+-- Add channel column to reminder_logs with default 'email' (idempotent)
+ALTER TABLE "reminder_logs" ADD COLUMN IF NOT EXISTS "channel" text NOT NULL DEFAULT 'email';
+
+-- Drop old unique constraints if they exist (idempotent)
+ALTER TABLE "reminder_logs" DROP CONSTRAINT IF EXISTS "reminder_logs_appointment_id_reminder_type_key";
+ALTER TABLE "reminder_logs" DROP CONSTRAINT IF EXISTS "reminder_logs_appointment_id_reminder_type_unique";
+
+-- Add new unique constraint with channel
+ALTER TABLE "reminder_logs" ADD CONSTRAINT "reminder_logs_appointment_id_reminder_type_channel_unique" UNIQUE ("appointment_id", "reminder_type", "channel");

packages/db/migrations/meta/_journal.json

@@ -190,6 +190,20 @@
       "when": 1775568867192,
       "tag": "0026_stripe_payment",
       "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1775655267192,
+      "tag": "0027_refunds",
+      "breakpoints": true
+    },
+    {
+      "idx": 28,
+      "version": "7",
+      "when": 1775741667192,
+      "tag": "0028_sms_reminders",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/factories.ts

@@ -71,6 +71,10 @@ export function buildClient(overrides: Partial<ClientRow> = {}): ClientRow {
     address: "1 Main St, Springfield, CA 90000",
     notes: null,
     emailOptOut: false,
+    smsOptIn: false,
+    smsConsentDate: null,
+    smsOptOutDate: null,
+    smsConsentText: null,
     stripeCustomerId: null,
     status: "active",
     disabledAt: null,

packages/db/src/schema.ts

@@ -110,6 +110,10 @@ export const clients = pgTable("clients", {
   address: text("address"),
   notes: text("notes"),
   emailOptOut: boolean("email_opt_out").notNull().default(false),
+  smsOptIn: boolean("sms_opt_in").notNull().default(false),
+  smsConsentDate: timestamp("sms_consent_date"),
+  smsOptOutDate: timestamp("sms_opt_out_date"),
+  smsConsentText: text("sms_consent_text"),
   stripeCustomerId: text("stripe_customer_id"),
   status: clientStatusEnum("status").notNull().default("active"),
   disabledAt: timestamp("disabled_at"),
@@ -300,8 +304,28 @@ export const invoiceTipSplits = pgTable(
   (t) => [index("idx_invoice_tip_splits_invoice_id").on(t.invoiceId)]
 );
 
+// Refund records with idempotency key support
+export const refunds = pgTable(
+  "refunds",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    invoiceId: uuid("invoice_id")
+      .notNull()
+      .references(() => invoices.id, { onDelete: "restrict" }),
+    stripeRefundId: text("stripe_refund_id").notNull(),
+    idempotencyKey: text("idempotency_key").unique(),
+    amountCents: integer("amount_cents"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (t) => [
+    index("idx_refunds_invoice_id").on(t.invoiceId),
+    index("idx_refunds_idempotency_key").on(t.idempotencyKey),
+  ]
+);
+
 // Tracks which reminder emails have been sent per appointment (prevents duplicates).
 // reminder_type values: "confirmation", "24h", "2h"
+// channel values: "email", "sms"
 export const reminderLogs = pgTable(
   "reminder_logs",
   {
@@ -311,9 +335,11 @@ export const reminderLogs = pgTable(
       .references(() => appointments.id, { onDelete: "cascade" }),
     // "confirmation" | "24h" | "2h"
     reminderType: text("reminder_type").notNull(),
+    // "email" | "sms"
+    channel: text("channel").notNull().default("email"),
     sentAt: timestamp("sent_at").notNull().defaultNow(),
   },
-  (t) => [unique().on(t.appointmentId, t.reminderType)]
+  (t) => [unique().on(t.appointmentId, t.reminderType, t.channel)]
 );
 
 // ─── Impersonation ──────────────────────────────────────────────────────────

packages/db/src/seed.ts

@@ -398,6 +398,8 @@ async function seedKnownUsers() {
         id: ADMIN_STAFF_ID,
         name: adminName,
         email: adminEmail,
+        oidcSub: adminEmail,
+        userId: adminEmail,
         role: "manager",
         isSuperUser: true,
         active: true,
@@ -424,6 +426,7 @@ async function seedKnownUsers() {
         name: "UAT Super User",
         email: "uat-super@groombook.dev",
         oidcSub: uatSuperOidcSub,
+        userId: uatSuperOidcSub,
         role: "manager",
         isSuperUser: true,
         active: true,
@@ -450,6 +453,7 @@ async function seedKnownUsers() {
         name: "UAT Staff Groomer",
         email: "uat-groomer@groombook.dev",
         oidcSub: uatStaffOidcSub,
+        userId: uatStaffOidcSub,
         role: "groomer",
         isSuperUser: false,
         active: true,
@@ -612,6 +616,8 @@ async function seed() {
         id: ADMIN_STAFF_ID,
         name: adminName,
         email: adminEmail,
+        oidcSub: adminEmail,
+        userId: adminEmail,
         role: "manager",
         isSuperUser: true,
         active: true,

pnpm-lock.yaml

@@ -43,6 +43,9 @@ importers:
       stripe:
         specifier: ^22.0.0
         version: 22.0.1(@types/node@22.19.15)
+      telnyx:
+        specifier: ^1.23.0
+        version: 1.27.0
       zod:
         specifier: ^4.3.6
         version: 4.3.6
@@ -177,7 +180,7 @@ importers:
         version: 22.19.15
       drizzle-kit:
         specifier: ^0.30.4
-        version: 0.30.6
+        version: 0.30.4
       tsx:
         specifier: ^4.19.0
         version: 4.21.0
@@ -1696,9 +1699,6 @@ packages:
     resolution: {integrity: sha512-cifvXDhcqMwwTlTK04GBNeIe7yyo28Mfby85QXFe1Yk8nmi36Ab/5UQwptOx84SsoGNRg+EVSjwzfSZMy6pmlw==}
     engines: {node: '>=14'}
 
-  '@petamoriken/float16@3.9.3':
-    resolution: {integrity: sha512-8awtpHXCx/bNpFt4mt2xdkgtgVvKqty8VbjHI/WWWQuEw+KLzFot3f4+LkQY9YmOtq7A5GdOnqoIC8Pdygjk2g==}
-
   '@pkgjs/parseargs@0.11.0':
     resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
     engines: {node: '>=14'}
@@ -2830,8 +2830,8 @@ packages:
   dom-accessibility-api@0.6.3:
     resolution: {integrity: sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==}
 
-  drizzle-kit@0.30.6:
-    resolution: {integrity: sha512-U4wWit0fyZuGuP7iNmRleQyK2V8wCuv57vf5l3MnG4z4fzNTjY/U13M8owyQ5RavqvqxBifWORaR3wIUzlN64g==}
+  drizzle-kit@0.30.4:
+    resolution: {integrity: sha512-B2oJN5UkvwwNHscPWXDG5KqAixu7AUzZ3qbe++KU9SsQ+cZWR4DXEPYcvWplyFAno0dhRJECNEhNxiDmFaPGyQ==}
     hasBin: true
 
   drizzle-orm@0.38.4:
@@ -2955,10 +2955,6 @@ packages:
     resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
     engines: {node: '>=0.12'}
 
-  env-paths@3.0.0:
-    resolution: {integrity: sha512-dtJUTepzMW3Lm/NPxRf3wP4642UWhjL2sQxc+ym2YMj1m/H2zDNQOlezafzkHwn6sMstjHTwG6iQQsctDW/b1A==}
-    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
-
   es-abstract@1.24.1:
     resolution: {integrity: sha512-zHXBLhP+QehSSbsS9Pt23Gg964240DPd6QCf8WpkqEXxQ7fhdZzYsocOr5u7apWonsS5EjZDmTF+/slGMyasvw==}
     engines: {node: '>= 0.4'}
@@ -3162,11 +3158,6 @@ packages:
   functions-have-names@1.2.3:
     resolution: {integrity: sha512-xckBUXyTIqT97tq2x2AMb+g163b5JFysYk0x4qxNFwbfQkmNZoiRHb6sPzI9/QV33WeuvVYBUIiD4NzNIyqaRQ==}
 
-  gel@2.2.0:
-    resolution: {integrity: sha512-q0ma7z2swmoamHQusey8ayo8+ilVdzDt4WTxSPzq/yRqvucWRfymRVMvNgmSC0XK7eNjjEZEcplxpgaNojKdmQ==}
-    engines: {node: '>= 18.0.0'}
-    hasBin: true
-
   generator-function@2.0.1:
     resolution: {integrity: sha512-SFdFmIJi+ybC0vjlHN0ZGVGHc3lgE0DxPAT0djjVg+kjOnSqclqmj0KQ7ykTOLP6YxoqOvuAODGdcHJn+43q3g==}
     engines: {node: '>= 0.4'}
@@ -3434,10 +3425,6 @@ packages:
   isexe@2.0.0:
     resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
 
-  isexe@3.1.5:
-    resolution: {integrity: sha512-6B3tLtFqtQS4ekarvLVMZ+X+VlvQekbe4taUkf/rhVO3d/h0M2rfARm/pXLcPEsjjMsFgrFgSrhQIxcSVrBz8w==}
-    engines: {node: '>=18'}
-
   istanbul-lib-coverage@3.2.2:
     resolution: {integrity: sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==}
     engines: {node: '>=8'}
@@ -3619,6 +3606,9 @@ packages:
   lodash.debounce@4.0.8:
     resolution: {integrity: sha512-FT1yDzDYEoYWhnSGnpE/4Kj1fLZkDFyqRb7fNt6FdYOSxlUWAtp42Eh6Wb0rGIv/m9Bgo7x4GhQbm5Ys4SG5ow==}
 
+  lodash.isplainobject@4.0.6:
+    resolution: {integrity: sha512-oSXzaWypCMHkPC3NvBEaPHf0KsA5mvPrOPgQWDsbg8n7orZ290M0BmC/jgRZ4vcJ6DTAhjrsSYgdsW/F+MFOBA==}
+
   lodash.merge@4.6.2:
     resolution: {integrity: sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==}
 
@@ -3851,6 +3841,10 @@ packages:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
     engines: {node: '>=6'}
 
+  qs@6.15.1:
+    resolution: {integrity: sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==}
+    engines: {node: '>=0.6'}
+
   randombytes@2.1.0:
     resolution: {integrity: sha512-vYl3iOX+4CKUWuxGi9Ukhie6fsqXqS9FE2Zaic4tNFD2N2QQaXOMFbuKK4QmDHC0JO6B1Zp41J0LpT0oR68amQ==}
 
@@ -4046,10 +4040,6 @@ packages:
     resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
     engines: {node: '>=8'}
 
-  shell-quote@1.8.3:
-    resolution: {integrity: sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==}
-    engines: {node: '>= 0.4'}
-
   side-channel-list@1.0.0:
     resolution: {integrity: sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==}
     engines: {node: '>= 0.4'}
@@ -4188,6 +4178,10 @@ packages:
     resolution: {integrity: sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg==}
     engines: {node: '>=6'}
 
+  telnyx@1.27.0:
+    resolution: {integrity: sha512-cVbP3jEW4TbmNL5U0UbZc3OkLg+6dHRnMYByYfJnrGw5ZRn0XKb17Hx3fLMWmGgRFow7eqVP4hlCogbIB6T3+w==}
+    engines: {node: ^6 || >=8}
+
   temp-dir@2.0.0:
     resolution: {integrity: sha512-aoBAniQmmwtcKp/7BzsH8Cxzv8OL736p7v1ihGb5e9DJ9kTwGWHrQrVB5+lfVDzfGrdRzXch+ig7LHaY1JTOrg==}
     engines: {node: '>=8'}
@@ -4262,6 +4256,9 @@ packages:
     engines: {node: '>=18.0.0'}
     hasBin: true
 
+  tweetnacl@1.0.3:
+    resolution: {integrity: sha512-6rt+RN7aOi1nGMyC4Xa5DdYiukl2UWCbcJft7YhxReBGQD7OAM8Pbxw6YMo4r2diNEA8FEmu32YOn9rhaiE5yw==}
+
   type-check@0.4.0:
     resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}
     engines: {node: '>= 0.8.0'}
@@ -4351,6 +4348,10 @@ packages:
     resolution: {integrity: sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==}
     hasBin: true
 
+  uuid@9.0.1:
+    resolution: {integrity: sha512-b+1eJOlsR9K8HJpow9Ok3fiWOWSIcIzXodvv0rQjVoOVNpWMpxf1wZNpt4y9h10odCNrqnYp1OBzRktckBe3sA==}
+    hasBin: true
+
   victory-vendor@37.3.6:
     resolution: {integrity: sha512-SbPDPdDBYp+5MJHhBCAyI7wKM3d5ivekigc2Dk2s7pgbZ9wIgIBYGVw4zGHBml/qTFbexrofXW6Gu4noGxrOwQ==}
 
@@ -4487,11 +4488,6 @@ packages:
     engines: {node: '>= 8'}
     hasBin: true
 
-  which@4.0.0:
-    resolution: {integrity: sha512-GlaYyEb07DPxYCKhKzplCWBJtvxZcZMrL+4UkrTSJHHPyZU4mYYTv3qaOe77H7EODLSSopAUFAc6W8U4yqvscg==}
-    engines: {node: ^16.13.0 || >=18.0.0}
-    hasBin: true
-
   why-is-node-running@2.3.0:
     resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
     engines: {node: '>=8'}
@@ -6223,8 +6219,6 @@ snapshots:
 
   '@opentelemetry/semantic-conventions@1.40.0': {}
 
-  '@petamoriken/float16@3.9.3': {}
-
   '@pkgjs/parseargs@0.11.0':
     optional: true
 
@@ -7420,13 +7414,12 @@ snapshots:
 
   dom-accessibility-api@0.6.3: {}
 
-  drizzle-kit@0.30.6:
+  drizzle-kit@0.30.4:
     dependencies:
       '@drizzle-team/brocli': 0.10.2
       '@esbuild-kit/esm-loader': 2.6.5
       esbuild: 0.19.12
       esbuild-register: 3.6.0(esbuild@0.19.12)
-      gel: 2.2.0
     transitivePeerDependencies:
       - supports-color
 
@@ -7463,8 +7456,6 @@ snapshots:
 
   entities@6.0.1: {}
 
-  env-paths@3.0.0: {}
-
   es-abstract@1.24.1:
     dependencies:
       array-buffer-byte-length: 1.0.2
@@ -7826,17 +7817,6 @@ snapshots:
 
   functions-have-names@1.2.3: {}
 
-  gel@2.2.0:
-    dependencies:
-      '@petamoriken/float16': 3.9.3
-      debug: 4.4.3
-      env-paths: 3.0.0
-      semver: 7.7.4
-      shell-quote: 1.8.3
-      which: 4.0.0
-    transitivePeerDependencies:
-      - supports-color
-
   generator-function@2.0.1: {}
 
   gensync@1.0.0-beta.2: {}
@@ -8101,8 +8081,6 @@ snapshots:
 
   isexe@2.0.0: {}
 
-  isexe@3.1.5: {}
-
   istanbul-lib-coverage@3.2.2: {}
 
   istanbul-lib-report@3.0.1:
@@ -8271,6 +8249,8 @@ snapshots:
 
   lodash.debounce@4.0.8: {}
 
+  lodash.isplainobject@4.0.6: {}
+
   lodash.merge@4.6.2: {}
 
   lodash.sortby@4.7.0: {}
@@ -8469,6 +8449,10 @@ snapshots:
 
   punycode@2.3.1: {}
 
+  qs@6.15.1:
+    dependencies:
+      side-channel: 1.1.0
+
   randombytes@2.1.0:
     dependencies:
       safe-buffer: 5.2.1
@@ -8703,8 +8687,6 @@ snapshots:
 
   shebang-regex@3.0.0: {}
 
-  shell-quote@1.8.3: {}
-
   side-channel-list@1.0.0:
     dependencies:
       es-errors: 1.3.0
@@ -8858,6 +8840,14 @@ snapshots:
 
   tapable@2.3.0: {}
 
+  telnyx@1.27.0:
+    dependencies:
+      lodash.isplainobject: 4.0.6
+      qs: 6.15.1
+      safe-buffer: 5.2.1
+      tweetnacl: 1.0.3
+      uuid: 9.0.1
+
   temp-dir@2.0.0: {}
 
   tempy@0.6.0:
@@ -8928,6 +8918,8 @@ snapshots:
     optionalDependencies:
       fsevents: 2.3.3
 
+  tweetnacl@1.0.3: {}
+
   type-check@0.4.0:
     dependencies:
       prelude-ls: 1.2.1
@@ -9024,6 +9016,8 @@ snapshots:
 
   uuid@8.3.2: {}
 
+  uuid@9.0.1: {}
+
   victory-vendor@37.3.6:
     dependencies:
       '@types/d3-array': 3.2.2
@@ -9201,10 +9195,6 @@ snapshots:
     dependencies:
       isexe: 2.0.0
 
-  which@4.0.0:
-    dependencies:
-      isexe: 3.1.5
-
   why-is-node-running@2.3.0:
     dependencies:
       siginfo: 2.0.0