feat(GRO-106): STOP/HELP compliance + consent log

- Add detectKeyword() and handleConsentKeyword() in consent.ts
- Wire keyword detection into handleMessageReceived() in inbound.ts
- Add 24-unit test suite for consent.ts covering all keywords,
  case insensitivity, whitespace tolerance, idempotency, and
  help keyword state preservation

Fixes from QA review:
- Use getDb() instead of non-existent db export; import Db type
- Destructure clientId from findOrCreateConversation result
- Rename staffId → sentByStaffId in sendMessage call
- Remove messagingHelpReply query (column not yet in schema)

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

.env.example

@@ -11,6 +11,10 @@ AUTH_DISABLED=false
 OIDC_ISSUER=https://authentik.example.com
 OIDC_AUDIENCE=groombook
 
+# ── Webhooks ─────────────────────────────────────────────────────────────────
+# Telnyx webhook secret for validating inbound message webhooks.
+TELNYX_WEBHOOK_SECRET=your-telnyx-webhook-secret-here
+
 # ── Setup Wizard ─────────────────────────────────────────────────────────────
 # When SKIP_OOBE=true, the setup wizard is bypassed regardless of whether a
 # super user exists in the database. Useful in dev/test environments where the

.github/workflows/ci.yml

@@ -340,7 +340,7 @@ jobs:
     name: Update Infra Image Tags
     runs-on: ubuntu-latest
     needs: [docker]
-    if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && github.event_name == 'push'
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     permissions:
       contents: write
       pull-requests: write

apps/api/UAT_PLAYBOOK.md

@@ -1,63 +0,0 @@
-# GroomBook API — UAT Playbook
-
-This document captures user-acceptance test cases for GroomBook API features. Each section corresponds to a feature or bug-fix PR. Update this file when a PR changes user-facing behaviour.
-
----
-
-## 1. Appointment Booking (`/api/appointments`)
-
-### 1.1 Create Appointment
-- [ ] POST `/api/appointments` with valid payload → 201, appointment returned with generated id
-- [ ] Overlapping staff appointment → 409 conflict error returned
-- [ ] `endTime` before `startTime` → 422 error
-
-### 1.2 Update Appointment (PATCH `/api/appointments/:id`)
-- [ ] Extending `endTime` on a `scheduled` appointment triggers cascade delay prevention if downstream appointments exist
-- [ ] Extending `endTime` returns `cascade` object in response with shifted appointments
-- [ ] Extending `endTime` sends reschedule email to each affected client
-- [ ] Appointments outside business hours after shift are flagged in `cascade.flaggedForReview` instead of auto-shifted
-- [ ] Only `scheduled` and `confirmed` downstream appointments are shifted; `in_progress`, `completed`, `cancelled` are skipped
-- [ ] Cascade stops when a downstream appointment no longer conflicts with the shifted boundary
-- [ ] Shifts are included in API response under `cascade.shifted[]`
-
-### 1.3 Series (Recurring) Appointments
-- [ ] Updating one occurrence with `cascadeMode: "this_and_future"` shifts that occurrence and all future ones
-- [ ] Updating one occurrence with `cascadeMode: "all"` shifts every occurrence in the series
-
----
-
-## 2. Cascade Delay Prevention
-
-### 2.1 Basic Cascade
-- [ ] When a groomer's appointment overruns, the next same-groomer `scheduled` appointment shifts forward
-- [ ] Delta applied to both `startTime` and `endTime` (duration preserved)
-- [ ] Cascade propagates through multiple downstream appointments
-
-### 2.2 Buffer Time
-- [ ] A configurable buffer (default 15 minutes) is added between the overrunning appointment end and the shifted start
-- [ ] Cascade respects the buffer between each consecutive pair of appointments
-
-### 2.3 Business Hours Guard
-- [ ] If a proposed shift would place an appointment start or end outside business hours, it is flagged instead of shifted
-- [ ] Flagged appointments are listed in `cascade.flaggedForReview[]` with reason text
-
-### 2.4 Email Notification
-- [ ] Each shifted appointment triggers a reschedule email to the client
-- [ ] Email includes original time (struck through) and new time
-- [ ] Email is skipped silently if SMTP is not configured
-
-### 2.5 Status Transition Overrun
-- [ ] When an `in_progress` appointment's actual end time exceeds `endTime + bufferMinutes`, the cascade is triggered using the status transition path
-
----
-
-## 3. Authentication & RBAC
-
-### 3.1 Staff Authentication
-- [ ] Unauthenticated request → 401
-- [ ] Groomer role can only view/edit their own appointments → 403 for others
-- [ ] Manager role can view/edit all appointments
-
-### 3.2 Client Authentication
-- [ ] Clients can access their own appointments via tokenized links
-- [ ] Tokenized confirm/cancel links work without authentication

apps/api/package.json

@@ -24,13 +24,14 @@
     "nodemailer": "^6.9.16",
     "stripe": "^22.0.0",
     "telnyx": "^1.23.0",
-
+    "uuid": "^11.1.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^22.10.7",
     "@types/node-cron": "^3.0.11",
     "@types/nodemailer": "^6.4.17",
+    "@types/uuid": "^10.0.0",
     "@vitest/coverage-v8": "^3.2.4",
     "eslint": "^9.18.0",
     "tsx": "^4.19.2",

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

@@ -1,373 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { cascadeDelay } from "../cascade.js";
-
-// ─── Mock the DB ───────────────────────────────────────────────────────────────
-
-const mockDb = {
-  select: vi.fn(),
-  update: vi.fn(),
-};
-
-vi.mock("@groombook/db", () => ({
-  getDb: () => mockDb,
-  appointments: {
-    id: Symbol("id"),
-    staffId: Symbol("staffId"),
-    startTime: Symbol("startTime"),
-    endTime: Symbol("endTime"),
-    status: Symbol("status"),
-  },
-  clients: { id: Symbol("id"), name: Symbol("name"), email: Symbol("email") },
-  pets: { id: Symbol("id"), name: Symbol("name") },
-  services: { id: Symbol("id"), name: Symbol("name") },
-  staff: { id: Symbol("id"), name: Symbol("name") },
-  eq: (a: symbol, b: unknown) => ({ type: "eq", a, b }),
-  and: (...args: unknown[]) => ({ type: "and", args }),
-  gt: (a: symbol, b: unknown) => ({ type: "gt", a, b }),
-  inArray: (a: symbol, vals: unknown[]) => ({ type: "inArray", a, vals }),
-  asc: (a: symbol) => ({ type: "asc", a }),
-}));
-
-vi.mock("../services/email.js", () => ({
-  sendEmail: vi.fn().mockResolvedValue(true),
-}));
-
-const { sendEmail } = await import("../services/email.js");
-const { getDb } = await import("@groombook/db");
-
-// ─── Helpers ────────────────────────────────────────────────────────────────────
-
-function makeAppt(overrides: Partial<Record<string, unknown>> = {}) {
-  return {
-    id: "appt-1",
-    staffId: "groomer-1",
-    startTime: new Date("2026-05-16T10:00:00Z"),
-    endTime: new Date("2026-05-16T11:00:00Z"),
-    status: "scheduled",
-    clientId: "client-1",
-    petId: "pet-1",
-    serviceId: "svc-1",
-    ...overrides,
-  };
-}
-
-function makeEnrichedAppt(id: string, start: Date, end: Date) {
-  return {
-    id,
-    originalStartTime: start,
-    originalEndTime: end,
-    newStartTime: start,
-    newEndTime: end,
-    clientId: "client-1",
-    clientName: "Alice Smith",
-    clientEmail: "alice@example.com",
-    petName: "Buddy",
-    serviceName: "Full Groom",
-    groomerName: "Jamie",
-  };
-}
-
-// ─── Tests ─────────────────────────────────────────────────────────────────────
-
-describe("cascadeDelay", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("returns early when the triggering appointment is not found", async () => {
-    mockDb.select.mockResolvedValueOnce([]);
-
-    const result = await cascadeDelay(
-      "nonexistent",
-      new Date("2026-05-16T12:00:00Z"),
-      new Date("2026-05-16T11:00:00Z")
-    );
-
-    expect(result.shifted).toHaveLength(0);
-    expect(result.flaggedForReview).toHaveLength(0);
-  });
-
-  it("returns early when the appointment has no groomer assigned", async () => {
-    mockDb.select.mockResolvedValueOnce([{ ...makeAppt(), staffId: null }]);
-
-    const result = await cascadeDelay(
-      "appt-trigger",
-      new Date("2026-05-16T12:00:00Z"),
-      new Date("2026-05-16T11:00:00Z")
-    );
-
-    expect(result.shifted).toHaveLength(0);
-  });
-
-  it("returns early when newEndTime does not extend beyond originalEndTime", async () => {
-    mockDb.select.mockResolvedValueOnce([makeAppt()]);
-
-    const result = await cascadeDelay(
-      "appt-trigger",
-      new Date("2026-05-16T11:30:00Z"), // earlier than original 11:00
-      new Date("2026-05-16T11:00:00Z")
-    );
-
-    expect(result.shifted).toHaveLength(0);
-  });
-
-  it("returns early when there are no downstream appointments", async () => {
-    mockDb.select
-      .mockResolvedValueOnce([makeAppt()])           // triggering appt
-      .mockResolvedValueOnce([]);                     // no downstream
-
-    const result = await cascadeDelay(
-      "appt-trigger",
-      new Date("2026-05-16T11:30:00Z"),
-      new Date("2026-05-16T11:00:00Z")
-    );
-
-    expect(result.shifted).toHaveLength(0);
-  });
-
-  it("shifts a single downstream appointment by the correct delta", async () => {
-    const triggerEnd = new Date("2026-05-16T11:30:00Z"); // 30 min overrun
-    const originalEnd = new Date("2026-05-16T11:00:00Z");
-    const downstreamStart = new Date("2026-05-16T11:00:00Z");
-    const downstreamEnd = new Date("2026-05-16T12:00:00Z");
-
-    mockDb.select
-      .mockResolvedValueOnce([makeAppt({ staffId: "groomer-1" })])
-      .mockResolvedValueOnce([
-        makeAppt({
-          id: "downstream-1",
-          startTime: downstreamStart,
-          endTime: downstreamEnd,
-          status: "scheduled",
-        }),
-      ]);
-
-    const updateMock = mockDb.update.mockReturnValueThis();
-    mockDb.select.mockResolvedValueOnce([
-      {
-        clientId: "client-1",
-        clientName: "Alice",
-        clientEmail: "alice@example.com",
-        petName: "Buddy",
-        serviceName: "Full Groom",
-        groomerName: "Jamie",
-      },
-    ]);
-
-    const result = await cascadeDelay(
-      "appt-trigger",
-      triggerEnd,
-      originalEnd,
-      15 // 15 min buffer
-    );
-
-    // effectiveBoundary = 11:30 + 15min = 11:45
-    // delta = 11:45 - 11:00 = 45 min = 2_700_000 ms
-    const expectedDeltaMs = 45 * 60 * 1000;
-
-    expect(result.shifted).toHaveLength(1);
-    expect(result.shifted[0].id).toBe("downstream-1");
-    expect(result.shifted[0].newStartTime.getTime() - result.shifted[0].originalStartTime.getTime())
-      .toBe(expectedDeltaMs);
-    expect(sendEmail).toHaveBeenCalledTimes(1);
-  });
-
-  it("cascades shifts through a chain of appointments", async () => {
-    const triggerEnd = new Date("2026-05-16T12:00:00Z"); // 60 min overrun
-    const originalEnd = new Date("2026-05-16T11:00:00Z");
-
-    // Three downstream appointments, each 1 hour
-    const appt1Start = new Date("2026-05-16T11:00:00Z");
-    const appt1End   = new Date("2026-05-16T12:00:00Z");
-    const appt2Start = new Date("2026-05-16T12:00:00Z");
-    const appt2End   = new Date("2026-05-16T13:00:00Z");
-    const appt3Start = new Date("2026-05-16T13:00:00Z");
-    const appt3End   = new Date("2026-05-16T14:00:00Z");
-
-    mockDb.select
-      .mockResolvedValueOnce([makeAppt({ staffId: "groomer-1" })])
-      .mockResolvedValueOnce([
-        makeAppt({ id: "appt-2", startTime: appt2Start, endTime: appt2End, status: "confirmed" }),
-        makeAppt({ id: "appt-3", startTime: appt3Start, endTime: appt3End, status: "scheduled" }),
-      ]);
-
-    mockDb.update.mockReturnValueThis();
-
-    // Two enrich queries for the two shifted appointments
-    mockDb.select
-      .mockResolvedValueOnce([
-        {
-          clientId: "c1", clientName: "Alice", clientEmail: "alice@test.com",
-          petName: "Buddy", serviceName: "Full Groom", groomerName: "Jamie",
-        },
-      ])
-      .mockResolvedValueOnce([
-        {
-          clientId: "c2", clientName: "Bob", clientEmail: "bob@test.com",
-          petName: "Max", serviceName: "Bath", groomerName: "Jamie",
-        },
-      ]);
-
-    const result = await cascadeDelay(
-      "appt-trigger",
-      triggerEnd,
-      originalEnd,
-      15
-    );
-
-    // effectiveBoundary starts at 12:00 + 15 = 12:15
-    // appt-2: 12:00 start conflicts with 12:15 boundary → shift by 15 min → starts 12:15, ends 13:15
-    // new boundary: 13:15 + 15 = 13:30
-    // appt-3: 13:00 start conflicts with 13:30 boundary → shift by 30 min → starts 13:30, ends 14:30
-    expect(result.shifted).toHaveLength(2);
-    expect(result.shifted[0].id).toBe("appt-2");
-    expect(result.shifted[1].id).toBe("appt-3");
-    expect(mockDb.update).toHaveBeenCalledTimes(2);
-    expect(sendEmail).toHaveBeenCalledTimes(2);
-  });
-
-  it("flags but still updates boundary when shift would fall outside business hours", async () => {
-    const triggerEnd = new Date("2026-05-16T17:00:00Z");
-    const originalEnd = new Date("2026-05-16T16:00:00Z");
-
-    // Downstream appt starts at 16:00, business ends at 18:00
-    mockDb.select
-      .mockResolvedValueOnce([makeAppt({ staffId: "groomer-1" })])
-      .mockResolvedValueOnce([
-        makeAppt({
-          id: "appt-late",
-          startTime: new Date("2026-05-16T16:00:00Z"),
-          endTime:   new Date("2026-05-16T17:00:00Z"),
-          status: "scheduled",
-        }),
-      ]);
-
-    mockDb.update.mockReturnValueThis();
-    mockDb.select.mockResolvedValueOnce([
-      {
-        clientId: "c1", clientName: "Alice", clientEmail: "alice@test.com",
-        petName: "Buddy", serviceName: "Full Groom", groomerName: "Jamie",
-      },
-    ]);
-
-    // Business hours 08:00–18:00; proposed shift pushes to 17:15 start (still in hours)
-    // Try a late-night boundary: shift would push to 19:15 (outside 08:00–18:00)
-    const result = await cascadeDelay(
-      "appt-trigger",
-      new Date("2026-05-16T18:00:00Z"), // larger overrun
-      originalEnd,
-      15,
-      8,  // business start
-      18  // business end — proposed 18:15 start is outside
-    );
-
-    // The appointment at 16:00 with buffer of 15 min after 18:00 trigger:
-    // effectiveBoundary = 18:00 + 15 = 18:15 → outside business hours (18:15 > 18:00)
-    expect(result.flaggedForReview).toHaveLength(1);
-    expect(result.flaggedForReview[0].id).toBe("appt-late");
-    expect(result.flaggedForReview[0].reason).toContain("Manual review required");
-    // The appointment was NOT shifted (only flagged)
-    expect(mockDb.update).not.toHaveBeenCalled();
-  });
-
-  it("skips non-active appointments", async () => {
-    mockDb.select
-      .mockResolvedValueOnce([makeAppt({ staffId: "groomer-1" })])
-      .mockResolvedValueOnce([
-        makeAppt({ id: "in-progress-1", status: "in_progress" }),
-        makeAppt({ id: "cancelled-1",  status: "cancelled" }),
-        makeAppt({ id: "scheduled-1",  status: "scheduled" }),
-      ]);
-
-    mockDb.update.mockReturnValueThis();
-    mockDb.select.mockResolvedValueOnce([
-      {
-        clientId: "c1", clientName: "Alice", clientEmail: "alice@test.com",
-        petName: "Buddy", serviceName: "Full Groom", groomerName: "Jamie",
-      },
-    ]);
-
-    const result = await cascadeDelay(
-      "appt-trigger",
-      new Date("2026-05-16T11:30:00Z"),
-      new Date("2026-05-16T11:00:00Z"),
-      15
-    );
-
-    // Only the scheduled appointment should be shifted
-    expect(result.shifted).toHaveLength(1);
-    expect(result.shifted[0].id).toBe("scheduled-1");
-  });
-
-  it("stops cascading when an appointment no longer conflicts", async () => {
-    // Three downstream: appt-2 overlaps, appt-3 does NOT overlap, appt-4 overlaps
-    // Cascade should stop at appt-3
-    mockDb.select
-      .mockResolvedValueOnce([makeAppt({ staffId: "groomer-1" })])
-      .mockResolvedValueOnce([
-        // appt-2: starts at 11:00, ends 12:00 — overlaps boundary 11:45
-        makeAppt({ id: "appt-2", startTime: new Date("2026-05-16T11:00:00Z"), endTime: new Date("2026-05-16T12:00:00Z") }),
-        // appt-3: starts at 13:00 — already clear of shifted appt-2 (ends 12:15 + buffer)
-        makeAppt({ id: "appt-3", startTime: new Date("2026-05-16T13:00:00Z"), endTime: new Date("2026-05-16T14:00:00Z") }),
-        makeAppt({ id: "appt-4", startTime: new Date("2026-05-16T14:00:00Z"), endTime: new Date("2026-05-16T15:00:00Z") }),
-      ]);
-
-    mockDb.update.mockReturnValueThis();
-    mockDb.select.mockResolvedValueOnce([
-      {
-        clientId: "c1", clientName: "Alice", clientEmail: "alice@test.com",
-        petName: "Buddy", serviceName: "Full Groom", groomerName: "Jamie",
-      },
-    ]);
-
-    const result = await cascadeDelay(
-      "appt-trigger",
-      new Date("2026-05-16T11:30:00Z"),
-      new Date("2026-05-16T11:00:00Z"),
-      15
-    );
-
-    // Only appt-2 was shifted (appt-3 no longer conflicts after the stop condition check)
-    expect(result.shifted).toHaveLength(1);
-    expect(result.shifted[0].id).toBe("appt-2");
-  });
-
-  it("sends email notification for each shifted appointment", async () => {
-    mockDb.select
-      .mockResolvedValueOnce([makeAppt({ staffId: "groomer-1" })])
-      .mockResolvedValueOnce([
-        makeAppt({
-          id: "appt-email-test",
-          startTime: new Date("2026-05-16T11:00:00Z"),
-          endTime: new Date("2026-05-16T12:00:00Z"),
-          status: "confirmed",
-        }),
-      ]);
-
-    mockDb.update.mockReturnValueThis();
-    mockDb.select.mockResolvedValueOnce([
-      {
-        clientId: "c1",
-        clientName: "Carol",
-        clientEmail: "carol@example.com",
-        petName: "Luna",
-        serviceName: "Nail Trim",
-        groomerName: null,
-      },
-    ]);
-
-    await cascadeDelay(
-      "appt-trigger",
-      new Date("2026-05-16T11:30:00Z"),
-      new Date("2026-05-16T11:00:00Z"),
-      15
-    );
-
-    expect(sendEmail).toHaveBeenCalledWith(
-      expect.objectContaining({
-        to: "carol@example.com",
-        subject: expect.stringContaining("Rescheduled"),
-      })
-    );
-  });
-});

apps/api/src/index.ts

@@ -29,6 +29,7 @@ import { devRouter } from "./routes/dev.js";
 import { adminSeedRouter } from "./routes/admin/seed.js";
 import { startReminderScheduler } from "./services/reminders.js";
 import { webhooksRouter } from "./routes/stripe-webhooks.js";
+import { telnyxWebhooksRouter } from "./routes/webhooks/telnyx.js";
 
 const app = new Hono();
 
@@ -69,6 +70,9 @@ app.route("/api/portal", portalRouter);
 // Public Stripe webhook endpoint — signature-verified, no auth required
 app.route("/api/webhooks/stripe", webhooksRouter);
 
+// Public Telnyx messaging webhook — signature-verified, no auth required
+app.route("/api/webhooks/telnyx", telnyxWebhooksRouter);
+
 // Dev/demo routes — config is always public, users endpoint is guarded internally
 app.route("/api/dev", devRouter);
 

apps/api/src/lib/auth.ts

@@ -97,6 +97,9 @@ export async function initAuth(): Promise<void> {
           window: 10,
           storage: "memory",
           customRules: {
+            "/sign-in/social": { max: 10, window: 60 },
+            "/sign-in/email": { max: 10, window: 60 },
+            "/sign-up/email": { max: 5, window: 60 },
             "/get-session": false,
           },
         },
@@ -247,6 +250,9 @@ export async function initAuth(): Promise<void> {
         window: 10,
         storage: "memory",
         customRules: {
+          "/sign-in/social": { max: 10, window: 60 },
+          "/sign-in/email": { max: 10, window: 60 },
+          "/sign-up/email": { max: 5, window: 60 },
           "/get-session": false,
         },
       },

apps/api/src/lib/cascade.ts

@@ -1,341 +0,0 @@
-/**
- * Cascade delay prevention — `apps/api/src/lib/cascade.ts`
- *
- * Triggered after a PATCH /appointments/:id call extends an appointment's
- * endTime beyond its original value. Queries same-groomer downstream
- * appointments, shifts them forward by (overrunEnd + buffer − downstreamStart),
- * and cascades the shift through the chain. Clients are notified by email.
- *
- * Guard rails:
- *  - Only shifts `scheduled` and `confirmed` appointments.
- *  - Flags out-of-business-hours shifts for manual review instead of auto-shifting.
- *  - Returns the full list of shifted appointments.
- */
-
-import { eq, and, gt, lte, asc, ne, inArray } from "drizzle-orm";
-import { getDb, appointments, clients, pets, services, staff } from "@groombook/db";
-import { sendEmail } from "../services/email.js";
-
-// ─── Types ──────────────────────────────────────────────────────────────────────
-
-export interface CascadeResult {
-  shifted: ShiftedAppointment[];
-  flaggedForReview: FlaggedAppointment[];
-  /** Time in ms each downstream appointment was pushed forward */
-  cascadeLog: CascadeLogEntry[];
-}
-
-export interface ShiftedAppointment {
-  id: string;
-  originalStartTime: Date;
-  originalEndTime: Date;
-  newStartTime: Date;
-  newEndTime: Date;
-  clientId: string;
-  clientName: string;
-  clientEmail: string;
-  petName: string;
-  serviceName: string;
-  groomerName: string | null;
-}
-
-export interface FlaggedAppointment {
-  id: string;
-  originalStartTime: Date;
-  proposedStartTime: Date;
-  proposedEndTime: Date;
-  reason: string;
-}
-
-export interface CascadeLogEntry {
-  appointmentId: string;
-  deltaMs: number;
-  triggeredBy: string;
-}
-
-// ─── Config ───────────────────────────────────────────────────────────────────
-
-/** Default inter-appointment buffer in minutes. Overridden by services.bufferMinutes. */
-export const DEFAULT_BUFFER_MINUTES = 15;
-
-/** Default business hours (used when no settings row exists). */
-export const DEFAULT_BUSINESS_START_HOUR = 8; // 08:00
-export const DEFAULT_BUSINESS_END_HOUR = 18; // 18:00
-
-// ─── Core cascade ───────────────────────────────────────────────────────────────
-
-/**
- * Detect and cascade appointment overruns.
- *
- * @param triggeringAppointmentId  The appointment that just overran.
- * @param newEndTime               The updated endTime set by the caller.
- * @param originalEndTime          The appointment's endTime before the update.
- * @param bufferMinutes             Minutes of buffer between appointments (default 15).
- * @param businessStartHour         Business opening hour (0–23, default 8).
- * @param businessEndHour           Business closing hour (0–23, default 18).
- */
-export async function cascadeDelay(
-  triggeringAppointmentId: string,
-  newEndTime: Date,
-  originalEndTime: Date,
-  bufferMinutes: number = DEFAULT_BUFFER_MINUTES,
-  businessStartHour: number = DEFAULT_BUSINESS_START_HOUR,
-  businessEndHour: number = DEFAULT_BUSINESS_END_HOUR
-): Promise<CascadeResult> {
-  const db = getDb();
-
-  const bufferMs = bufferMinutes * 60_000;
-  const overrunEnd = newEndTime;
-
-  // ── 1. Load the triggering appointment ────────────────────────────────────────
-  const [triggering] = await db
-    .select()
-    .from(appointments)
-    .where(eq(appointments.id, triggeringAppointmentId))
-    .limit(1);
-
-  if (!triggering) {
-    return { shifted: [], flaggedForReview: [], cascadeLog: [] };
-  }
-
-  if (!triggering.staffId) {
-    // Unassigned appointments cannot cascade
-    return { shifted: [], flaggedForReview: [], cascadeLog: [] };
-  }
-
-  const groomerId = triggering.staffId;
-
-  // ── 2. Guard: only trigger when endTime actually extended ──────────────────────
-  if (overrunEnd <= originalEndTime) {
-    return { shifted: [], flaggedForReview: [], cascadeLog: [] };
-  }
-
-  const result: CascadeResult = { shifted: [], flaggedForReview: [], cascadeLog: [] };
-
-  // ── 3. Fetch all downstream same-groomer active appointments ──────────────────
-  const downstream = await db
-    .select()
-    .from(appointments)
-    .where(
-      and(
-        eq(appointments.staffId, groomerId),
-        gt(appointments.startTime, originalEndTime),
-        inArray(appointments.status, ["scheduled", "confirmed"]),
-      )
-    )
-    .orderBy(asc(appointments.startTime));
-
-  if (downstream.length === 0) return result;
-
-  // ── 4. Cascade loop ────────────────────────────────────────────────────────────
-  // Keep track of current effective boundary after each shift.
-  // Start from the new endTime of the triggering appointment plus buffer.
-  let effectiveBoundary = new Date(overrunEnd.getTime() + bufferMs);
-
-  for (const appt of downstream) {
-    const conflictStart = appt.startTime;
-    const conflictEnd = appt.endTime;
-    const apptDurationMs = conflictEnd.getTime() - conflictStart.getTime();
-
-    // Does this appointment overlap the effective boundary?
-    if (effectiveBoundary.getTime() >= conflictEnd.getTime()) {
-      // No conflict — this appointment and all later ones are unaffected
-      break;
-    }
-
-    const proposedStart = new Date(effectiveBoundary);
-    const proposedEnd = new Date(proposedStart.getTime() + apptDurationMs);
-
-    // ── Business-hours guard ────────────────────────────────────────────────────
-    const proposedStartHour = proposedStart.getHours() + proposedStart.getMinutes() / 60;
-    const proposedEndHour = proposedEnd.getHours() + proposedEnd.getMinutes() / 60;
-    const outOfHours =
-      proposedStartHour < businessStartHour ||
-      proposedEndHour > businessEndHour;
-
-    if (outOfHours) {
-      result.flaggedForReview.push({
-        id: appt.id,
-        originalStartTime: appt.startTime,
-        proposedStartTime: proposedStart,
-        proposedEndTime: proposedEnd,
-        reason:
-          `Would push appointment outside business hours ` +
-          `(${businessStartHour}:00–${businessEndHour}:00). ` +
-          `Manual review required.`,
-      });
-      // Update boundary anyway — later appointments may still conflict
-      effectiveBoundary = new Date(proposedEnd.getTime() + bufferMs);
-      continue;
-    }
-
-    // ── Perform the shift ──────────────────────────────────────────────────────
-    const deltaMs = proposedStart.getTime() - appt.startTime.getTime();
-
-    await db
-      .update(appointments)
-      .set({ startTime: proposedStart, endTime: proposedEnd, updatedAt: new Date() })
-      .where(eq(appointments.id, appt.id));
-
-    result.cascadeLog.push({
-      appointmentId: appt.id,
-      deltaMs,
-      triggeredBy: triggeringAppointmentId,
-    });
-
-    // ── Load client/pet/service info for notification ──────────────────────────
-    const enriched = await enrichAppointment(appt.id);
-    if (enriched) {
-      result.shifted.push({
-        id: appt.id,
-        originalStartTime: appt.startTime,
-        originalEndTime: appt.endTime,
-        newStartTime: proposedStart,
-        newEndTime: proposedEnd,
-        ...enriched,
-      });
-    }
-
-    // Advance boundary to the end of this shifted appointment plus buffer
-    effectiveBoundary = new Date(proposedEnd.getTime() + bufferMs);
-  }
-
-  // ── 5. Send notifications ────────────────────────────────────────────────────
-  for (const shifted of result.shifted) {
-    await sendRescheduleNotification(shifted).catch((err) =>
-      console.error(`[cascade] Failed to send notification for ${shifted.id}:`, err)
-    );
-  }
-
-  return result;
-}
-
-/**
- * Shortcut for status-transition overruns (current time > endTime + bufferMinutes).
- * Delegates to `cascadeDelay` using the current appointment data.
- */
-export async function cascadeOnStatusOverrun(
-  appointmentId: string,
-  bufferMinutes: number = DEFAULT_BUFFER_MINUTES,
-  businessStartHour: number = DEFAULT_BUSINESS_START_HOUR,
-  businessEndHour: number = DEFAULT_BUSINESS_END_HOUR
-): Promise<CascadeResult> {
-  const db = getDb();
-  const [appt] = await db
-    .select()
-    .from(appointments)
-    .where(eq(appointments.id, appointmentId))
-    .limit(1);
-
-  if (!appt) return { shifted: [], flaggedForReview: [], cascadeLog: [] };
-
-  const now = new Date();
-  const bufferMs = bufferMinutes * 60_000;
-
-  if (now.getTime() <= appt.endTime.getTime() + bufferMs) {
-    // Not actually in overrun
-    return { shifted: [], flaggedForReview: [], cascadeLog: [] };
-  }
-
-  // Use current time as the new endTime (the appointment is already running over)
-  return cascadeDelay(
-    appointmentId,
-    now,
-    appt.endTime,
-    bufferMinutes,
-    businessStartHour,
-    businessEndHour
-  );
-}
-
-// ─── Helpers ────────────────────────────────────────────────────────────────────
-
-interface EnrichedFields {
-  clientId: string;
-  clientName: string;
-  clientEmail: string;
-  petName: string;
-  serviceName: string;
-  groomerName: string | null;
-}
-
-async function enrichAppointment(
-  apptId: string
-): Promise<EnrichedFields | null> {
-  const db = getDb();
-  const [row] = await db
-    .select({
-      clientId: appointments.clientId,
-      clientName: clients.name,
-      clientEmail: clients.email,
-      petName: pets.name,
-      serviceName: services.name,
-      groomerName: staff.name,
-    })
-    .from(appointments)
-    .innerJoin(clients, eq(clients.id, appointments.clientId))
-    .innerJoin(pets, eq(pets.id, appointments.petId))
-    .innerJoin(services, eq(services.id, appointments.serviceId))
-    .leftJoin(staff, eq(staff.id, appointments.staffId))
-    .where(eq(appointments.id, apptId))
-    .limit(1);
-
-  if (!row) return null;
-  return {
-    clientId: row.clientId,
-    clientName: row.clientName,
-    clientEmail: row.clientEmail,
-    petName: row.petName,
-    serviceName: row.serviceName,
-    groomerName: row.groomerName,
-  };
-}
-
-async function sendRescheduleNotification(
-  shifted: ShiftedAppointment
-): Promise<void> {
-  const time = formatDateTime(shifted.newStartTime);
-  const original = formatDateTime(shifted.originalStartTime);
-  const groomer = shifted.groomerName ? ` with ${shifted.groomerName}` : "";
-
-  await sendEmail({
-    to: shifted.clientEmail,
-    subject: `Appointment Rescheduled — ${shifted.petName}`,
-    text: [
-      `Hi ${shifted.clientName},`,
-      ``,
-      `Your appointment for ${shifted.petName} has been rescheduled.`,
-      ``,
-      `  Was:    ${original}${groomer}`,
-      `  Now:    ${time}${groomer}`,
-      ``,
-      `We apologize for any inconvenience. If this new time doesn't work for you, please contact us as soon as possible.`,
-      ``,
-      `— Groom Book`,
-    ].join("\n"),
-    html: `<p>Hi ${shifted.clientName},</p>
-<p>Your appointment for <strong>${shifted.petName}</strong> has been rescheduled.</p>
-<table style="border-collapse:collapse;margin:1em 0">
-  <tr><td style="padding:4px 12px 4px 0;font-weight:600;color:#6b7280">Previous time</td><td style="text-decoration:line-through;color:#9ca3af">${original}${groomer}</td></tr>
-  <tr><td style="padding:4px 12px 4px 0;font-weight:600;color:#6b7280">New time</td><td>${time}${groomer}</td></tr>
-</table>
-<p>If this new time doesn't work for you, please contact us as soon as possible.</p>
-<p>— Groom Book</p>`,
-  });
-
-  console.info(
-    `[cascade] Notified ${shifted.clientEmail} of reschedule for ${shifted.petName} ` +
-      `(${shifted.id}): ${original} → ${time}`
-  );
-}
-
-function formatDateTime(d: Date): string {
-  return d.toLocaleString("en-US", {
-    weekday: "long",
-    year: "numeric",
-    month: "long",
-    day: "numeric",
-    hour: "2-digit",
-    minute: "2-digit",
-  });
-}

apps/api/src/routes/appointments.ts

@@ -20,7 +20,6 @@ import {
   staff,
 } from "@groombook/db";
 import { buildConfirmationEmail, sendEmail } from "../services/email.js";
-import { cascadeDelay } from "../lib/cascade.js";
 import { notifyWaitlistForAppointment } from "../services/waitlistNotify.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
@@ -581,15 +580,6 @@ appointmentsRouter.patch(
     if (updateFields.endTime) update.endTime = new Date(updateFields.endTime);
 
     if (needsConflictCheck) {
-      // Capture original endTime before the transaction so we can detect an
-      // overrun and trigger cascade delay prevention after the update.
-      const [preUpdate] = await db
-        .select({ originalEndTime: appointments.endTime })
-        .from(appointments)
-        .where(eq(appointments.id, id))
-        .limit(1);
-      const originalEndTime = preUpdate?.originalEndTime ?? null;
-
       // Wrap conflict check + update in a transaction to prevent race conditions
       // (fixes #18). Also falls back to the existing staffId when staffId is
       // omitted from the request, so rescheduling always checks conflicts (fixes #19).
@@ -694,23 +684,7 @@ appointmentsRouter.patch(
       }
 
       if (!row) return c.json({ error: "Not found" }, 404);
-
-      // Cascade delay prevention: detect if endTime was extended and cascade
-      // downstream appointments if so. Runs after the main update commits.
-      const cascadeResult =
-        updateFields.endTime &&
-        originalEndTime &&
-        new Date(updateFields.endTime) > originalEndTime
-          ? await cascadeDelay(id, new Date(updateFields.endTime), originalEndTime)
-          : { shifted: [], flaggedForReview: [], cascadeLog: [] };
-
-      return c.json({
-        ...row,
-        cascade:
-          cascadeResult.shifted.length > 0 || cascadeResult.flaggedForReview.length > 0
-            ? cascadeResult
-            : undefined,
-      });
+      return c.json(row);
     }
 
     const [row] = await db

apps/api/src/routes/invoices.ts

@@ -14,7 +14,8 @@ import {
   clients,
   sql,
 } from "@groombook/db";
-import type { AppEnv } from "../middleware/rbac.js";
+import type { AppEnv, StaffRole } from "../middleware/rbac.js";
+import { requireRole } from "../middleware/rbac.js";
 
 export const invoicesRouter = new Hono<AppEnv>();
 
@@ -460,6 +461,9 @@ invoicesRouter.post(
     if (invoice.status !== "paid") {
       return c.json({ error: "Refund only allowed on paid invoices" }, 422);
     }
+    if (!invoice.stripePaymentIntentId) {
+      return c.json({ error: "Invoice has no Stripe payment intent" }, 422);
+    }
 
     return await db.transaction(async (tx) => {
       if (body.idempotencyKey) {
@@ -472,16 +476,9 @@ invoicesRouter.post(
         }
       }
 
-      let refundId: string;
-
-      if (invoice.stripePaymentIntentId) {
-        const result = await processRefund(id, body.amountCents);
-        if (!result) return c.json({ error: "Refund failed" }, 500);
-        refundId = result.refundId;
-      } else {
-        // Manual refund — no Stripe call needed
-        refundId = `manual_${id}_${Date.now()}`;
-      }
+      const result = await processRefund(id, body.amountCents);
+      if (!result) return c.json({ error: "Refund failed" }, 500);
+      const refundId = result.refundId;
 
       await tx.insert(refunds).values({
         invoiceId: id,
@@ -496,7 +493,7 @@ invoicesRouter.post(
 );
 
 // Payment stats for admin dashboard
-invoicesRouter.get("/stats/summary", async (c) => {
+invoicesRouter.get("/stats/summary", requireRole("manager" as StaffRole), async (c) => {
   try {
     const db = getDb();
     const now = new Date();

apps/api/src/routes/webhooks/telnyx.ts

@@ -0,0 +1,59 @@
+import { Hono } from "hono";
+import { validateTelnyxSignature } from "../../services/sms.js";
+import {
+  handleMessageReceived,
+  handleMessageFinalized,
+  TelnyxMessageReceivedPayload,
+} from "../../services/messaging/inbound.js";
+
+export const telnyxWebhooksRouter = new Hono();
+
+telnyxWebhooksRouter.post("/messaging", async (c) => {
+  const signature = c.req.header("telnyx-signature");
+
+  let rawBody: string;
+  try {
+    rawBody = await c.req.text();
+  } catch {
+    return c.json({ error: "Could not read body" }, 400);
+  }
+
+  if (!validateTelnyxSignature(rawBody, signature)) {
+    return c.json({ error: "Invalid signature" }, 401);
+  }
+
+  let payload: TelnyxMessageReceivedPayload;
+  try {
+    payload = JSON.parse(rawBody) as TelnyxMessageReceivedPayload;
+  } catch {
+    return c.json({ error: "Invalid JSON" }, 400);
+  }
+
+  const eventType = payload.data?.event_type;
+  if (!eventType) {
+    return c.json({ error: "Missing event_type" }, 400);
+  }
+
+  if (eventType === "message.received") {
+    try {
+      await handleMessageReceived(payload);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "Unknown error";
+      if (msg.startsWith("No business owns")) {
+        return c.json({ error: "Unknown messaging number" }, 404);
+      }
+      return c.json({ error: msg }, 500);
+    }
+    return c.json({ received: true });
+  }
+
+  if (eventType === "message.finalized") {
+    const result = await handleMessageFinalized(payload);
+    if (result) {
+      return c.json({ received: true, messageId: result.messageId, status: result.newStatus });
+    }
+    return c.json({ received: true, messageId: null });
+  }
+
+  return c.json({ received: true });
+});

apps/api/src/services/messaging/__tests__/consent.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { detectKeyword } from "../consent.js";
+
+const mockDb = {
+  insert: vi.fn(),
+  update: vi.fn(),
+  select: vi.fn(),
+};
+
+vi.mock("@groombook/db", () => ({
+  getDb: () => mockDb,
+  clients: {},
+  messageConsentEvents: {},
+  businessSettings: {},
+  eq: vi.fn(),
+}));
+
+const { handleConsentKeyword } = await import("../consent.js");
+
+describe("detectKeyword", () => {
+  it.each([
+    ["STOP", "opt_out"],
+    ["STOPALL", "opt_out"],
+    ["UNSUBSCRIBE", "opt_out"],
+    ["CANCEL", "opt_out"],
+    ["END", "opt_out"],
+    ["QUIT", "opt_out"],
+  ])("opt-out keyword %s → opt_out", (keyword, expected) => {
+    expect(detectKeyword(keyword)).toEqual({ kind: expected });
+  });
+
+  it.each([
+    ["START", "opt_in"],
+    ["UNSTOP", "opt_in"],
+    ["YES", "opt_in"],
+    ["SUBSCRIBE", "opt_in"],
+  ])("opt-in keyword %s → opt_in", (keyword, expected) => {
+    expect(detectKeyword(keyword)).toEqual({ kind: expected });
+  });
+
+  it.each([
+    ["HELP", "help"],
+    ["INFO", "help"],
+  ])("help keyword %s → help", (keyword, expected) => {
+    expect(detectKeyword(keyword)).toEqual({ kind: expected });
+  });
+
+  it("is case insensitive", () => {
+    expect(detectKeyword("stop")).toEqual({ kind: "opt_out" });
+    expect(detectKeyword("Stop")).toEqual({ kind: "opt_out" });
+    expect(detectKeyword("sToP")).toEqual({ kind: "opt_out" });
+  });
+
+  it("trims whitespace", () => {
+    expect(detectKeyword("  STOP  ")).toEqual({ kind: "opt_out" });
+    expect(detectKeyword("\tSTART\n")).toEqual({ kind: "opt_in" });
+  });
+
+  it("returns null for non-keyword messages", () => {
+    expect(detectKeyword("hello")).toBeNull();
+    expect(detectKeyword("STOP IT")).toBeNull();
+    expect(detectKeyword("help me")).toBeNull();
+  });
+});
+
+describe("handleConsentKeyword", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb.insert.mockReturnValue({
+      values: vi.fn().mockResolvedValue([{ id: "event-1" }]),
+    } as any);
+    mockDb.update.mockReturnValue({
+      set: vi.fn().mockReturnValue({
+        where: vi.fn().mockResolvedValue([]),
+      }),
+    } as any);
+  });
+
+  const baseOpts = {
+    clientId: "client-1",
+    businessId: "biz-1",
+    db: mockDb as unknown as ReturnType<typeof import("@groombook/db").getDb>,
+  };
+
+  describe("opt_out", () => {
+    it("inserts consent event with sms_keyword source", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
+
+      expect(mockDb.insert).toHaveBeenCalledOnce();
+    });
+
+    it("sets smsOptIn=false and smsOptOutDate when currently opted in", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
+
+      expect(mockDb.update).toHaveBeenCalled();
+    });
+
+    it("is idempotent — second opt-out logs event but skips client update", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: false }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
+
+      expect(mockDb.update).not.toHaveBeenCalled();
+    });
+
+    it("returns unsubscribe reply text", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
+          }),
+        }),
+      } as any);
+
+      const result = await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
+      expect(result.replyText).toBe(
+        "You have been unsubscribed and will no longer receive messages. Reply START to resubscribe."
+      );
+    });
+  });
+
+  describe("opt_in", () => {
+    it("sets smsOptIn=true and smsConsentDate when currently opted out", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: false, smsConsentDate: null }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
+
+      expect(mockDb.update).toHaveBeenCalled();
+    });
+
+    it("clears smsOptOutDate on opt-in after opt-out", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: false }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
+
+      expect(mockDb.update).toHaveBeenCalled();
+    });
+
+    it("is idempotent — second opt-in skips client update", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
+          }),
+        }),
+      } as any);
+
+      await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
+
+      expect(mockDb.update).not.toHaveBeenCalled();
+    });
+
+    it("returns resubscribe reply text", async () => {
+      mockDb.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ smsOptIn: false }]),
+          }),
+        }),
+      } as any);
+
+      const result = await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
+      expect(result.replyText).toBe(
+        "You have been resubscribed to messages. Reply STOP to unsubscribe. Msg & data rates may apply."
+      );
+    });
+  });
+
+  describe("help", () => {
+    it("returns default help reply without querying businessSettings", async () => {
+      const result = await handleConsentKeyword({ ...baseOpts, kind: "help" });
+
+      expect(mockDb.update).not.toHaveBeenCalled();
+      expect(mockDb.select).not.toHaveBeenCalled();
+      expect(result.replyText).toBe(
+        "Reply STOP to unsubscribe or START to resubscribe. For help, contact your groomer directly."
+      );
+    });
+  });
+});

apps/api/src/services/messaging/__tests__/inbound.test.ts

@@ -0,0 +1,313 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  findOrCreateConversation,
+  upsertMessage,
+  handleMessageReceived,
+  handleMessageFinalized,
+  TelnyxMessageReceivedPayload,
+} from "../inbound.js";
+import * as schema from "@groombook/db";
+
+vi.mock("@groombook/db", () => ({
+  getDb: vi.fn(),
+  conversations: { id: "", businessId: "", clientId: "", externalNumber: "", businessNumber: "", channel: "", lastMessageAt: null, status: "", createdAt: null, updatedAt: null },
+  messages: { id: "", conversationId: "", direction: "", body: "", status: "", providerMessageId: "", sentByStaffId: null, createdAt: null, deliveredAt: null, readByClientAt: null },
+  businessSettings: { id: "", messagingPhoneNumber: "" },
+  clients: { id: "", name: "", email: "", phone: "", status: "" },
+  eq: vi.fn(),
+  and: vi.fn(),
+  sql: vi.fn(),
+}));
+
+const mockDb = {
+  select: vi.fn().mockReturnThis(),
+  from: vi.fn().mockReturnThis(),
+  where: vi.fn().mockReturnThis(),
+  limit: vi.fn().mockReturnThis(),
+  insert: vi.fn().mockReturnThis(),
+  update: vi.fn().mockReturnThis(),
+  returning: vi.fn().mockReturnThis(),
+};
+
+vi.mocked(schema.getDb).mockReturnValue(mockDb as unknown as ReturnType<typeof schema.getDb>);
+
+const makePayload = (
+  eventType: "message.received" | "message.sent" | "message.finalized",
+  messageId: string,
+  fromPhone: string,
+  toPhone: string,
+  body = "Hello"
+): TelnyxMessageReceivedPayload => ({
+  data: {
+    id: "evt-1",
+    event_type: eventType,
+    payload: {
+      message: {
+        id: messageId,
+        from: { phone: fromPhone, carrier: "carrier" },
+        to: [{ phone: toPhone }],
+        body,
+      },
+    },
+  },
+});
+
+describe("signature validation via route", () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  it("returns 401 when telnyx-signature header is missing", async () => {
+    const { telnyxWebhooksRouter } = await import("../../../routes/webhooks/telnyx.js");
+    const payload = JSON.stringify(makePayload("message.received", "msg-123", "+1555111", "+1555222"));
+    const req = new Request("http://localhost/messaging", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: payload,
+    });
+    const res = await telnyxWebhooksRouter.fetch(req);
+    expect(res.status).toBe(401);
+  });
+
+  it("returns 401 when signature does not match", async () => {
+    process.env.TELNYX_WEBHOOK_SECRET = "test-secret";
+    const { telnyxWebhooksRouter } = await import("../../../routes/webhooks/telnyx.js");
+    const payload = JSON.stringify(makePayload("message.received", "msg-123", "+1555111", "+1555222"));
+    const req = new Request("http://localhost/messaging", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "telnyx-signature": "sha256=bad",
+      },
+      body: payload,
+    });
+    const res = await telnyxWebhooksRouter.fetch(req);
+    expect(res.status).toBe(401);
+  });
+});
+
+describe("findOrCreateConversation", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb.select.mockReset();
+    mockDb.from.mockReset();
+    mockDb.where.mockReset();
+    mockDb.limit.mockReset();
+    mockDb.insert.mockReset();
+    mockDb.update.mockReset();
+    mockDb.returning.mockReset();
+  });
+
+  it("returns existing conversation when found", async () => {
+    mockDb.select.mockReturnValue({
+      from: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue([{ id: "conv-1", clientId: "client-1" }]),
+        }),
+      }),
+    });
+
+    const result = await findOrCreateConversation("biz-1", "+1555111", "+1555222");
+    expect(result.id).toBe("conv-1");
+  });
+
+  it("creates new conversation when none exists", async () => {
+    mockDb.select.mockReturnValue({
+      from: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue([]),
+        }),
+      }),
+    });
+    mockDb.insert.mockReturnValue({
+      values: vi.fn().mockReturnValue({
+        returning: vi.fn().mockReturnValue([{ id: "conv-2", clientId: "client-2" }]),
+      }),
+    });
+
+    const result = await findOrCreateConversation("biz-1", "+1555111", "+1555222");
+    expect(result.id).toBe("conv-2");
+  });
+
+  it("creates placeholder client for unknown phone then creates conversation", async () => {
+    mockDb.select
+      .mockReturnValueOnce({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockReturnValue([]),
+          }),
+        }),
+      })
+      .mockReturnValueOnce({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockReturnValue([]),
+          }),
+        }),
+      });
+    mockDb.insert.mockReturnValue({
+      values: vi.fn().mockReturnValue({
+        returning: vi.fn().mockReturnValue([{ id: "conv-3", clientId: "client-3" }]),
+      }),
+    });
+
+    const result = await findOrCreateConversation("biz-1", "+1555111", "+1555222");
+    expect(result.id).toBe("conv-3");
+    expect(result.clientId).toBe("client-3");
+  });
+});
+
+describe("upsertMessage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns isNew=false when message with providerMessageId already exists", async () => {
+    mockDb.select.mockReturnValue({
+      from: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue([{ id: "msg-existing" }]),
+        }),
+      }),
+    });
+
+    const result = await upsertMessage("msg-123", "conv-1", "inbound", "Hello", "received");
+    expect(result.isNew).toBe(false);
+    expect(result.id).toBe("msg-existing");
+  });
+
+  it("inserts new message and returns isNew=true", async () => {
+    mockDb.select.mockReturnValue({
+      from: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue([]),
+        }),
+      }),
+    });
+    mockDb.insert.mockReturnValue({
+      values: vi.fn().mockReturnValue({
+        returning: vi.fn().mockReturnValue([{ id: "msg-new" }]),
+      }),
+    });
+
+    const result = await upsertMessage("msg-new-123", "conv-1", "inbound", "New message", "queued");
+    expect(result.isNew).toBe(true);
+    expect(result.id).toBe("msg-new");
+  });
+});
+
+describe("handleMessageReceived", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb.select.mockReset();
+    mockDb.from.mockReset();
+    mockDb.where.mockReset();
+    mockDb.limit.mockReset();
+    mockDb.insert.mockReset();
+    mockDb.update.mockReset();
+    mockDb.returning.mockReset();
+    mockDb.select.mockImplementation(() => ({
+      from: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue([]),
+        }),
+      }),
+    }));
+  });
+
+  it("returns 404 when no business owns the to number", async () => {
+    const payload = makePayload("message.received", "msg-123", "+1555111", "+1555000");
+    await expect(handleMessageReceived(payload)).rejects.toThrow("No business owns messaging number");
+  });
+
+  it("creates conversation and message for valid inbound", async () => {
+    mockDb.select
+      .mockReturnValueOnce({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockReturnValue([{ id: "biz-1" }]),
+          }),
+        }),
+      })
+      .mockReturnValueOnce({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockReturnValue([]),
+          }),
+        }),
+      });
+    mockDb.insert
+      .mockReturnValueOnce({
+        values: vi.fn().mockReturnValue({
+          returning: vi.fn().mockReturnValue([{ id: "client-new" }]),
+        }),
+      })
+      .mockReturnValueOnce({
+        values: vi.fn().mockReturnValue({
+          returning: vi.fn().mockReturnValue([{ id: "conv-new", clientId: "client-new" }]),
+        }),
+      });
+    mockDb.update.mockReturnValueOnce({
+      set: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({}),
+      }),
+    });
+    mockDb.insert.mockReturnValueOnce({
+      values: vi.fn().mockReturnValue({
+        returning: vi.fn().mockReturnValue([{ id: "msg-new" }]),
+      }),
+    });
+
+    const payload = makePayload("message.received", "msg-abc", "+1555111", "+1555222", "Test message");
+    const result = await handleMessageReceived(payload);
+    expect(result.messageId).toBe("msg-new");
+  });
+});
+
+describe("handleMessageFinalized", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDb.select.mockReset();
+    mockDb.from.mockReset();
+    mockDb.where.mockReset();
+    mockDb.limit.mockReset();
+    mockDb.insert.mockReset();
+    mockDb.update.mockReset();
+    mockDb.returning.mockReset();
+  });
+
+  it("returns null when message not found", async () => {
+    mockDb.select.mockReturnValue({
+      from: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue([]),
+        }),
+      }),
+    });
+
+    const payload = makePayload("message.finalized", "msg-unknown", "+1555111", "+1555222");
+    const result = await handleMessageFinalized(payload);
+    expect(result).toBeNull();
+  });
+
+  it("updates status to delivered for finalized inbound", async () => {
+    mockDb.select.mockReturnValue({
+      from: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue([{ id: "msg-1", status: "sent" }]),
+        }),
+      }),
+    });
+    mockDb.update.mockReturnValue({
+      set: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          returning: vi.fn().mockReturnValue([{ id: "msg-1" }]),
+        }),
+      }),
+    });
+
+    const payload = makePayload("message.finalized", "msg-1", "+1555111", "+1555222");
+    const result = await handleMessageFinalized(payload);
+    expect(result?.newStatus).toBe("delivered");
+  });
+});

apps/api/src/services/messaging/__tests__/outbound.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const mockSendSms = vi.fn();
+const mockGetDb = vi.fn();
+const mockUuidv4 = vi.fn();
+
+vi.mock("../../sms.js", () => ({
+  sendSms: mockSendSms,
+}));
+
+vi.mock("@groombook/db", () => ({
+  getDb: () => mockGetDb(),
+  conversations: {},
+  messages: {},
+  clients: {},
+  businessSettings: {},
+  eq: vi.fn((a, b) => [a, b]),
+  and: vi.fn((...args) => args),
+}));
+
+vi.mock("uuid", () => ({
+  v4: () => mockUuidv4(),
+}));
+
+const { sendMessage, MissingTenantPhoneNumberError } = await import("../outbound.js");
+
+describe("sendMessage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockUuidv4.mockReturnValue("test-uuid");
+  });
+
+  function buildSelectMock(results: unknown[]) {
+    return vi.fn().mockReturnValue({
+      from: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          limit: vi.fn().mockResolvedValue(results),
+        }),
+      }),
+    });
+  }
+
+  it("returns suppressed=true when client has no phone", async () => {
+    mockGetDb.mockReturnValue({
+      select: buildSelectMock([{ phone: null, smsOptIn: true }]),
+    });
+
+    const result = await sendMessage({
+      businessId: "biz-1",
+      clientId: "client-1",
+      body: "Hello",
+    });
+
+    expect(result).toEqual({ suppressed: true });
+    expect(mockSendSms).not.toHaveBeenCalled();
+  });
+
+  it("returns suppressed=true when client has opted out of SMS", async () => {
+    mockGetDb.mockReturnValue({
+      select: buildSelectMock([{ phone: "+1234567890", smsOptIn: false }]),
+    });
+
+    const result = await sendMessage({
+      businessId: "biz-1",
+      clientId: "client-1",
+      body: "Hello",
+    });
+
+    expect(result).toEqual({ suppressed: true });
+    expect(mockSendSms).not.toHaveBeenCalled();
+  });
+
+  it("throws MissingTenantPhoneNumberError when tenant has no messaging phone", async () => {
+    mockGetDb.mockReturnValue({
+      select: vi
+        .fn()
+        .mockReturnValueOnce({
+          from: vi.fn().mockReturnValue({
+            where: vi.fn().mockReturnValue({
+              limit: vi.fn().mockResolvedValue([{ phone: "+1234567890", smsOptIn: true }]),
+            }),
+          }),
+        })
+        .mockReturnValueOnce({
+          from: vi.fn().mockReturnValue({
+            where: vi.fn().mockReturnValue({
+              limit: vi.fn().mockResolvedValue([{ messagingPhoneNumber: null }]),
+            }),
+          }),
+        }),
+    });
+
+    await expect(
+      sendMessage({ businessId: "biz-1", clientId: "client-1", body: "Hello" })
+    ).rejects.toThrow(MissingTenantPhoneNumberError);
+  });
+
+  it("persists provider message id on success", async () => {
+    const messageId = "msg-1";
+    const conversationId = "conv-1";
+
+    mockGetDb.mockReturnValue({
+      select: vi
+        .fn()
+        .mockReturnValueOnce({
+          from: vi.fn().mockReturnValue({
+            where: vi.fn().mockReturnValue({
+              limit: vi.fn().mockResolvedValue([{ phone: "+1234567890", smsOptIn: true }]),
+            }),
+          }),
+        })
+        .mockReturnValueOnce({
+          from: vi.fn().mockReturnValue({
+            where: vi.fn().mockReturnValue({
+              limit: vi.fn().mockResolvedValue([{ messagingPhoneNumber: "+1987654321" }]),
+            }),
+          }),
+        })
+        .mockReturnValueOnce({
+          from: vi.fn().mockReturnValue({
+            where: vi.fn().mockReturnValue({
+              limit: vi.fn().mockResolvedValue([{ id: conversationId }]),
+            }),
+          }),
+        }),
+      insert: vi.fn().mockReturnValue({
+        values: vi.fn().mockReturnValue({
+          returning: vi.fn().mockResolvedValue([{ id: messageId }]),
+        }),
+      }),
+      update: vi.fn().mockReturnValue({
+        set: vi.fn().mockReturnValue({
+          where: vi.fn().mockResolvedValue([]),
+        }),
+      }),
+    });
+
+    mockSendSms.mockResolvedValue({ messageId: "provider-msg-1", status: "sent" });
+
+    const result = await sendMessage({
+      businessId: "biz-1",
+      clientId: "client-1",
+      body: "Hello",
+    });
+
+    expect(result).toEqual({
+      messageId,
+      providerMessageId: "provider-msg-1",
+      status: "sent",
+      suppressed: false,
+    });
+    expect(mockSendSms).toHaveBeenCalledWith("+1234567890", "Hello", undefined);
+  });
+
+  it("persists error on Telnyx failure", async () => {
+    const messageId = "msg-1";
+
+    mockGetDb.mockReturnValue({
+      select: vi
+        .fn()
+        .mockReturnValueOnce({
+          from: vi.fn().mockReturnValue({
+            where: vi.fn().mockReturnValue({
+              limit: vi.fn().mockResolvedValue([{ phone: "+1234567890", smsOptIn: true }]),
+            }),
+          }),
+        })
+        .mockReturnValueOnce({
+          from: vi.fn().mockReturnValue({
+            where: vi.fn().mockReturnValue({
+              limit: vi.fn().mockResolvedValue([{ messagingPhoneNumber: "+1987654321" }]),
+            }),
+          }),
+        })
+        .mockReturnValueOnce({
+          from: vi.fn().mockReturnValue({
+            where: vi.fn().mockReturnValue({
+              limit: vi.fn().mockResolvedValue([]),
+            }),
+          }),
+        }),
+      insert: vi.fn().mockReturnValue({
+        values: vi.fn().mockReturnValue({
+          returning: vi.fn().mockResolvedValue([{ id: messageId }]),
+        }),
+      }),
+      update: vi.fn().mockReturnValue({
+        set: vi.fn().mockReturnValue({
+          where: vi.fn().mockResolvedValue([]),
+        }),
+      }),
+    });
+
+    mockSendSms.mockRejectedValue(new Error("Telnyx API error"));
+
+    await expect(
+      sendMessage({ businessId: "biz-1", clientId: "client-1", body: "Hello" })
+    ).rejects.toThrow("Telnyx API error");
+  });
+});

apps/api/src/services/messaging/consent.ts

@@ -0,0 +1,77 @@
+import { getDb, clients, messageConsentEvents, eq } from "@groombook/db";
+import type { Db } from "@groombook/db";
+
+export type KeywordKind = "opt_in" | "opt_out" | "help";
+
+const OPT_OUT_KEYWORDS = new Set(["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"]);
+const OPT_IN_KEYWORDS = new Set(["START", "UNSTOP", "YES", "SUBSCRIBE"]);
+const HELP_KEYWORDS = new Set(["HELP", "INFO"]);
+
+export function detectKeyword(body: string): { kind: KeywordKind } | null {
+  const normalized = body.trim().toUpperCase();
+  if (OPT_OUT_KEYWORDS.has(normalized)) return { kind: "opt_out" };
+  if (OPT_IN_KEYWORDS.has(normalized)) return { kind: "opt_in" };
+  if (HELP_KEYWORDS.has(normalized)) return { kind: "help" };
+  return null;
+}
+
+export async function handleConsentKeyword(opts: {
+  clientId: string;
+  businessId: string;
+  kind: KeywordKind;
+  db: Db;
+}): Promise<{ replyText: string }> {
+  const { clientId, businessId, kind, db: database } = opts;
+
+  await database.insert(messageConsentEvents).values({
+    clientId,
+    businessId,
+    kind,
+    source: "sms_keyword",
+  });
+
+  if (kind === "opt_out") {
+    const [existing] = await database
+      .select({ smsOptIn: clients.smsOptIn })
+      .from(clients)
+      .where(eq(clients.id, clientId))
+      .limit(1);
+
+    if (existing?.smsOptIn !== false) {
+      await database
+        .update(clients)
+        .set({ smsOptIn: false, smsOptOutDate: new Date() })
+        .where(eq(clients.id, clientId));
+    }
+
+    return {
+      replyText: "You have been unsubscribed and will no longer receive messages. Reply START to resubscribe.",
+    };
+  }
+
+  if (kind === "opt_in") {
+    const [existing] = await database
+      .select({ smsOptIn: clients.smsOptIn, smsConsentDate: clients.smsConsentDate })
+      .from(clients)
+      .where(eq(clients.id, clientId))
+      .limit(1);
+
+    if (existing?.smsOptIn !== true) {
+      await database
+        .update(clients)
+        .set({ smsOptIn: true, smsConsentDate: new Date(), smsOptOutDate: null })
+        .where(eq(clients.id, clientId));
+    }
+
+    return {
+      replyText:
+        "You have been resubscribed to messages. Reply STOP to unsubscribe. Msg & data rates may apply.",
+    };
+  }
+
+  // kind === "help"
+  const replyText =
+    "Reply STOP to unsubscribe or START to resubscribe. For help, contact your groomer directly.";
+
+  return { replyText };
+}

apps/api/src/services/messaging/inbound.ts

@@ -0,0 +1,218 @@
+import { getDb, conversations, messages, businessSettings, clients, eq, and } from "@groombook/db";
+import { v4 as uuidv4 } from "uuid";
+import { detectKeyword, handleConsentKeyword } from "./consent.js";
+import { sendMessage } from "./outbound.js";
+
+export interface TelnyxMessageReceivedPayload {
+  data: {
+    id: string;
+    event_type: "message.received" | "message.sent" | "message.finalized";
+    payload: {
+      message: {
+        id: string;
+        from: { phone: string; carrier?: string };
+        to: { phone: string }[];
+        body: string;
+        media?: Array<{ type: string; url: string }>;
+      };
+      recording?: unknown;
+      leg_count?: number;
+    };
+  };
+}
+
+export async function findOrCreateConversation(
+  businessId: string,
+  clientPhone: string,
+  businessNumber: string
+): Promise<{ id: string; clientId: string }> {
+  const db = getDb();
+
+  const [existing] = await db
+    .select({ id: conversations.id, clientId: conversations.clientId })
+    .from(conversations)
+    .where(
+      and(
+        eq(conversations.businessId, businessId),
+        eq(conversations.externalNumber, clientPhone),
+        eq(conversations.businessNumber, businessNumber)
+      )
+    )
+    .limit(1);
+
+  if (existing) {
+    return { id: existing.id, clientId: existing.clientId };
+  }
+
+  const [existingClient] = await db
+    .select({ id: clients.id })
+    .from(clients)
+    .where(eq(clients.phone, clientPhone))
+    .limit(1);
+
+  const clientId = existingClient?.id ?? uuidv4();
+
+  if (!existingClient) {
+    await db.insert(clients).values({
+      id: clientId,
+      name: clientPhone,
+      email: `sms-${uuidv4()}@placeholder.local`,
+      phone: clientPhone,
+      status: "active",
+    });
+  }
+
+  const [created] = await db
+    .insert(conversations)
+    .values({
+      id: crypto.randomUUID(),
+      businessId,
+      clientId,
+      channel: "sms",
+      externalNumber: clientPhone,
+      businessNumber,
+      lastMessageAt: new Date(),
+      status: "active",
+    })
+    .returning({ id: conversations.id, clientId: conversations.clientId });
+
+  if (!created) throw new Error("Failed to create conversation");
+
+  return { id: created.id, clientId: created.clientId };
+}
+
+export async function upsertMessage(
+  providerMessageId: string,
+  conversationId: string,
+  direction: "inbound" | "outbound",
+  body: string,
+  status: "queued" | "sent" | "delivered" | "failed" | "received",
+  sentByStaffId?: string
+): Promise<{ id: string; isNew: boolean }> {
+  const db = getDb();
+
+  const [existing] = await db
+    .select({ id: messages.id })
+    .from(messages)
+    .where(eq(messages.providerMessageId, providerMessageId))
+    .limit(1);
+
+  if (existing) {
+    return { id: existing.id, isNew: false };
+  }
+
+  try {
+    const [inserted] = await db
+      .insert(messages)
+      .values({
+        id: crypto.randomUUID(),
+        conversationId,
+        direction,
+        body,
+        status,
+        providerMessageId,
+        sentByStaffId: sentByStaffId ?? null,
+      })
+      .returning({ id: messages.id });
+
+    if (!inserted) throw new Error("Failed to insert message");
+    return { id: inserted.id, isNew: true };
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("unique")) {
+      const [existing] = await db
+        .select({ id: messages.id })
+        .from(messages)
+        .where(eq(messages.providerMessageId, providerMessageId))
+        .limit(1);
+      if (existing) return { id: existing.id, isNew: false };
+    }
+    throw err;
+  }
+}
+
+export async function resolveBusinessIdByMessagingNumber(toNumber: string): Promise<string | null> {
+  const db = getDb();
+  const [settings] = await db
+    .select({ id: businessSettings.id })
+    .from(businessSettings)
+    .where(eq(businessSettings.messagingPhoneNumber, toNumber))
+    .limit(1);
+  return settings?.id ?? null;
+}
+
+export async function handleMessageReceived(payload: TelnyxMessageReceivedPayload): Promise<{ conversationId: string; messageId: string }> {
+  const { message } = payload.data.payload;
+  const fromPhone = message.from.phone;
+  const toPhone = message.to[0]?.phone;
+
+  if (!toPhone) {
+    throw new Error("No recipient phone in payload");
+  }
+
+  const businessId = await resolveBusinessIdByMessagingNumber(toPhone);
+  if (!businessId) {
+    throw new Error(`No business owns messaging number: ${toPhone}`);
+  }
+
+  const { id: conversationId, clientId } = await findOrCreateConversation(businessId, fromPhone, toPhone);
+
+  await getDb()
+    .update(conversations)
+    .set({ lastMessageAt: new Date(), updatedAt: new Date() })
+    .where(eq(conversations.id, conversationId));
+
+  const { id: messageId } = await upsertMessage(
+    message.id,
+    conversationId,
+    "inbound",
+    message.body,
+    "received"
+  );
+
+  const keyword = detectKeyword(message.body ?? "");
+  if (keyword) {
+    const { replyText } = await handleConsentKeyword({
+      clientId,
+      businessId,
+      kind: keyword.kind,
+      db: getDb(),
+    });
+    await sendMessage({
+      businessId,
+      clientId,
+      body: replyText,
+      sentByStaffId: undefined,
+    });
+  }
+
+  return { conversationId, messageId };
+}
+
+export async function handleMessageFinalized(payload: TelnyxMessageReceivedPayload): Promise<{ messageId: string; newStatus: string } | null> {
+  const { message } = payload.data.payload;
+
+  if (!message.id) return null;
+
+  const db = getDb();
+  const [existing] = await db
+    .select({ id: messages.id, status: messages.status })
+    .from(messages)
+    .where(eq(messages.providerMessageId, message.id))
+    .limit(1);
+
+  if (!existing) return null;
+
+  let newStatus = existing.status;
+  if (payload.data.event_type === "message.finalized") {
+    newStatus = "delivered";
+  }
+
+  if (newStatus !== existing.status) {
+    await db
+      .update(messages)
+      .set({ status: newStatus, deliveredAt: new Date() })
+      .where(eq(messages.id, existing.id));
+  }
+
+  return { messageId: existing.id, newStatus };
+}

apps/api/src/services/messaging/outbound.ts

@@ -0,0 +1,159 @@
+import { getDb, conversations, messages, clients, businessSettings, eq, and } from "@groombook/db";
+import { v4 as uuidv4 } from "uuid";
+import { sendSms } from "../sms.js";
+
+export interface SendMessageOptions {
+  businessId: string;
+  clientId: string;
+  body: string;
+  sentByStaffId?: string;
+  mediaUrls?: string[];
+}
+
+export interface SendMessageResult {
+  messageId: string;
+  providerMessageId: string;
+  status: string;
+  suppressed: false;
+}
+
+export interface SendMessageSuppressed {
+  suppressed: true;
+}
+
+export type SendMessageResponse = SendMessageResult | SendMessageSuppressed;
+
+export class MissingTenantPhoneNumberError extends Error {
+  constructor() {
+    super("Tenant messagingPhoneNumber is not configured");
+    this.name = "MissingTenantPhoneNumberError";
+  }
+}
+
+async function findOrCreateConversation(
+  businessId: string,
+  clientId: string,
+  externalNumber: string,
+  businessNumber: string
+): Promise<{ id: string }> {
+  const db = getDb();
+
+  const [existing] = await db
+    .select({ id: conversations.id })
+    .from(conversations)
+    .where(
+      and(
+        eq(conversations.businessId, businessId),
+        eq(conversations.externalNumber, externalNumber),
+        eq(conversations.businessNumber, businessNumber)
+      )
+    )
+    .limit(1);
+
+  if (existing) return { id: existing.id };
+
+  const [created] = await db
+    .insert(conversations)
+    .values({
+      id: uuidv4(),
+      businessId,
+      clientId,
+      channel: "sms",
+      externalNumber,
+      businessNumber,
+      lastMessageAt: new Date(),
+      status: "active",
+    })
+    .returning({ id: conversations.id });
+
+  if (!created) throw new Error("Failed to create conversation");
+
+  return { id: created.id };
+}
+
+async function resolveFromNumber(businessId: string): Promise<string | null> {
+  const db = getDb();
+  const [settings] = await db
+    .select({ messagingPhoneNumber: businessSettings.messagingPhoneNumber })
+    .from(businessSettings)
+    .where(eq(businessSettings.id, businessId))
+    .limit(1);
+  return settings?.messagingPhoneNumber ?? null;
+}
+
+export async function sendMessage(opts: SendMessageOptions): Promise<SendMessageResponse> {
+  const db = getDb();
+  const { businessId, clientId, body, sentByStaffId, mediaUrls } = opts;
+
+  const [client] = await db
+    .select({ phone: clients.phone, smsOptIn: clients.smsOptIn })
+    .from(clients)
+    .where(eq(clients.id, clientId))
+    .limit(1);
+
+  if (!client?.phone) {
+    return { suppressed: true };
+  }
+
+  if (!client.smsOptIn) {
+    return { suppressed: true };
+  }
+
+  const from = await resolveFromNumber(businessId);
+  if (!from) throw new MissingTenantPhoneNumberError();
+
+  const to = client.phone;
+  const conversationId = (await findOrCreateConversation(businessId, clientId, to, from)).id;
+
+  const [queuedMessage] = await db
+    .insert(messages)
+    .values({
+      id: uuidv4(),
+      conversationId,
+      direction: "outbound",
+      body,
+      status: "queued",
+      sentByStaffId: sentByStaffId ?? null,
+    })
+    .returning({ id: messages.id });
+
+  if (!queuedMessage) throw new Error("Failed to insert queued message");
+
+  try {
+    const result = await sendSms(to, body, mediaUrls);
+
+    await db
+      .update(messages)
+      .set({
+        status: "sent",
+        providerMessageId: result.messageId,
+      })
+      .where(eq(messages.id, queuedMessage.id));
+
+    await db
+      .update(conversations)
+      .set({ lastMessageAt: new Date() })
+      .where(eq(conversations.id, conversationId));
+
+    return {
+      messageId: queuedMessage.id,
+      providerMessageId: result.messageId,
+      status: result.status,
+      suppressed: false,
+    };
+  } catch (err) {
+    const errorCode = err instanceof Error ? err.name : "UNKNOWN";
+    const errorMessage = err instanceof Error ? err.message : String(err);
+
+    await db
+      .update(messages)
+      .set({
+        status: "failed",
+        errorCode,
+        errorMessage,
+      })
+      .where(eq(messages.id, queuedMessage.id));
+
+    throw err;
+  }
+}

apps/api/src/services/sms.ts

@@ -32,6 +32,35 @@ function isE164(phone: string): boolean {
   return /^\+[1-9]\d{7,14}$/.test(phone);
 }
 
+export function validateTelnyxSignature(
+  rawBody: string,
+  signature: string | undefined | null
+): boolean {
+  if (!signature) return false;
+  const secret = process.env.TELNYX_WEBHOOK_SECRET;
+  if (!secret) return false;
+
+  try {
+    const hmac = createHmac("sha256", secret);
+    const expected = `sha256=${hmac.update(rawBody).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;
+  }
+}
+
 export async function sendSms(
   to: string,
   body: string,
@@ -74,33 +103,7 @@ export class TelnyxProvider implements SmsProvider {
   }
 
   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;
-    }
+    return validateTelnyxSignature(JSON.stringify(req.body), req.headers.get("telnyx-signature"));
   }
 }
 

apps/e2e/tests/portal-data.spec.ts

@@ -72,9 +72,15 @@ test.describe("Portal Data Integrity", () => {
   });
 
   test("billing section renders without JS errors", async ({ page }) => {
-    // Mock billing endpoint
-    await page.route("**/api/billing**", (route) =>
-      route.fulfill({ json: { invoices: [], balanceCents: 0 } })
+    // Mock portal billing endpoints
+    await page.route("**/api/portal/config**", (route) =>
+      route.fulfill({ json: { stripePublishableKey: "" } })
+    );
+    await page.route("**/api/portal/invoices**", (route) =>
+      route.fulfill({ json: [] })
+    );
+    await page.route("**/api/portal/payment-methods**", (route) =>
+      route.fulfill({ json: [] })
     );
 
     const consoleErrors: string[] = [];

apps/web/src/index.css

@@ -82,3 +82,13 @@ input:focus, select:focus, textarea:focus {
 ::-webkit-scrollbar-thumb:hover {
   background: #94a3b8;
 }
+
+/* ─── Scrollbar hide utility ─── */
+.scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+
+.scrollbar-hide::-webkit-scrollbar {
+  display: none;
+}

apps/web/src/portal/sections/BillingPayments.tsx

@@ -130,7 +130,7 @@ function BillingPaymentsInner({ sessionId, readOnly }: BillingPaymentsProps) {
         </div>
       )}
 
-      <div className="flex gap-2 flex-wrap overflow-x-auto">
+      <div className="flex gap-2 overflow-x-auto scrollbar-hide">
         {([
           { id: "invoices" as const, label: "Invoices", icon: DollarSign },
           { id: "payment" as const, label: "Payment Methods", icon: CreditCard },

apps/web/src/portal/sections/PetProfiles.tsx

@@ -182,7 +182,7 @@ export function PetProfiles({ sessionId, readOnly }: Props) {
       )}
 
       {/* Tabs */}
-      <div className="flex gap-1 bg-white rounded-xl border border-stone-200 p-1 overflow-x-auto">
+      <div className="flex gap-1 bg-white rounded-xl border border-stone-200 p-1 overflow-x-auto scrollbar-hide">
         {([
           { id: "info", label: "Basic Info", icon: PawPrint },
           { id: "medical", label: "Medical", icon: Heart },

docs/runbooks/10dlc-pilot-registration.md

@@ -0,0 +1,309 @@
+# 10DLC Pilot Tenant Registration Runbook
+
+Authored for GRO-106 Phase 1.
+
+---
+
+## Pre-Flight Checklist
+
+Before starting Telnyx registration, collect the following:
+
+| Item | Details |
+|------|---------|
+| Legal business name | Exact name on EIN / business registration |
+| EIN (Employer Identification Number) | 9-digit IRS format: XX-XXXXXXX |
+| Business type | Sole Proprietor / LLC / Corporation |
+| Primary contact email | General contact address (postmaster@, info@, etc.) |
+| Primary contact phone | Direct line for carrier verification |
+| Website URL | Must be live and contain privacy policy |
+| Sample message templates | See [Sample Templates](#sample-message-templates) below |
+| Messaging use case | Customer Care / Account Notification |
+
+---
+
+## Step 1 — Telnyx Account Requirements
+
+- Active Telnyx account with billing configured.
+- Role required: **Admin** or **Super User** to register brands and campaigns.
+
+---
+
+## Step 2 — Brand Registration
+
+### Via Telnyx Console
+
+1. Log in to [Telnyx Portal](https://portal.telnyx.com).
+2. Navigate to **Messaging → A2P 10DLC → Brands**.
+3. Click **Register Brand**.
+4. Fill in:
+   - **Brand Name**: Legal business name
+   - **Legal Company Name**: Exact EIN name
+   - **Company Type**: Select from dropdown
+   - **EIN**: XX-XXXXXXX
+   - **Primary Contact**: Name, email, phone
+   - **Website**: Must be accessible
+   - **BusinessVertical**: Select appropriate vertical
+5. Acknowledge the **Terms of Service**.
+6. Submit.
+
+### Via API
+
+```bash
+curl -X POST https://api.telnyx.com/v2/10dlc/brands \
+  -H "Authorization: Bearer $TELNYX_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Your Legal Business Name",
+    "legal_company_name": "Your Legal Business Name",
+    "company_type": "llc",
+    "ein": "XX-XXXXXXX",
+    "primary_contact": {
+      "name": "Jane Doe",
+      "email": "compliance@example.com",
+      "phone": "+1XXXXXXXXXX"
+    },
+    "website": "https://www.example.com",
+    "business_vertical": "PROFESSIONAL_SERVICES"
+  }'
+```
+
+**Response fields to record:**
+- `brand_id` — required for campaign registration
+- `brand_score` — affects campaign vetting speed
+
+### Expected Fees
+
+| Fee Type | Amount |
+|----------|--------|
+| Brand registration fee | ~$0 (no direct fee from Telnyx) |
+| Campaign registration fee | ~$15–$25 per campaign (Telnyx fee, subject to change) |
+| Carrier fees | Passed through from T-Mobile/AT&T/Verizon |
+
+### Expected Approval Window
+
+- **Vetting by Telnyx**: 1–3 business days after submission.
+- **Carrier (T-Mobile/AT&T/Verizon) review**: 2–5 business days after Telnyx approval.
+- Total end-to-end: **3–8 business days**.
+
+---
+
+## Step 3 — Campaign Registration
+
+### Use Case Selection
+
+- **Primary**: Customer Care
+- **Secondary**: Account Notification
+
+### Via Telnyx Console
+
+1. Navigate to **Messaging → A2P 10DLC → Campaigns**.
+2. Click **Register Campaign**.
+3. Select **Brand** (use the brand registered in Step 2).
+4. Fill in:
+   - **Campaign Name**: e.g., `groombook-pilot-customer-care`
+   - **Use Case**: Customer Care / Account Notification
+   - **Sample Messages**: Paste exactly the templates from [Sample Templates](#sample-message-templates) below.
+   - **Description**: Brief description of messaging program
+   - **Estimated Volume**: Enter monthly estimate (e.g., 500)
+5. Submit.
+
+### Via API
+
+```bash
+curl -X POST https://api.telnyx.com/v2/10dlc/campaigns \
+  -H "Authorization: Bearer $TELNYX_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "brand_id": "YOUR_BRAND_ID",
+    "name": "groombook-pilot-customer-care",
+    "use_case": "CUSTOMER_CARE",
+    "sample_messages": [
+      "Hi {{first_name}}, this is a reminder from {{business_name}} that your appointment is scheduled for {{date}} at {{time}}. Reply STOP to opt out.",
+      "Your appointment with {{business_name}} is confirmed for {{date}}. Need to reschedule? Reply HELP or call us at {{phone}}."
+    ],
+    "description": "Appointment reminders and account notifications for grooming clients",
+    "estimated_monthly_volume": 500
+  }'
+```
+
+**Response fields to record:**
+- `campaign_id` — required for messaging profile
+- `status` — initially `PENDING`, transitions to `ACTIVE` after carrier approval
+
+### Campaign Vetting — STOP/HELP Language Requirements
+
+Every campaign **must** include compliant STOP/HELP messaging. The following must appear in your sample messages or be included in your terms of service:
+
+- **STOP**: Users can text `STOP` to opt out of all messages.
+- **HELP**: Users can text `HELP` to receive contact information.
+
+Example STOP/HELP block:
+
+```
+Text STOP to opt out. Text HELP for help. Msg & data rates may apply.
+```
+
+---
+
+## Step 4 — Messaging Profile + Phone Number Provisioning
+
+### Create Messaging Profile
+
+1. In Telnyx Portal, navigate to **Messaging → Messaging Profiles**.
+2. Click **Create Messaging Profile**.
+3. Name it (e.g., `groombook-pilot-prod`).
+4. Copy the **Messaging Profile ID** (`messaging_profile_id`) — record this in the DB.
+
+### Provision a 10DLC Phone Number
+
+1. Navigate to **Messaging → Phone Numbers**.
+2. Search for a number in your desired area code.
+3. Confirm the number is 10DLC-capable.
+4. Purchase the number.
+
+### Associate Number with Messaging Profile
+
+```bash
+# Assign number to messaging profile
+curl -X PATCH https://api.telnyx.com/v2/phone_numbers/YOUR_PHONE_NUMBER_ID \
+  -H "Authorization: Bearer $TELNYX_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
+  }'
+```
+
+---
+
+## Step 5 — Record in Database
+
+Once GRO-981 lands, record the following against the business record:
+
+### SQL Path (when GRO-981 is complete)
+
+```sql
+UPDATE businesses
+SET
+  messaging_phone_number = '+1XXXXXXXXXX',
+  telnyx_messaging_profile_id = 'YOUR_MESSAGING_PROFILE_ID',
+  telnyx_brand_id = 'YOUR_BRAND_ID',
+  telnyx_campaign_id = 'YOUR_CAMPAIGN_ID',
+  telnyx_brand_status = 'APPROVED',
+  telnyx_campaign_status = 'ACTIVE',
+  updated_at = NOW()
+WHERE id = 'pilot_business_id';
+```
+
+### Manual Admin Path (before GRO-981)
+
+Until GRO-981 is complete, use the Telnyx Portal to verify and record values manually in your internal ops sheet:
+
+| Field | Value |
+|-------|-------|
+| `messagingPhoneNumber` | +1XXXXXXXXXX |
+| `telnyxMessagingProfileId` | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
+| `telnyxBrandId` | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
+| `telnyxCampaignId` | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
+| `brandStatus` | APPROVED / PENDING |
+| `campaignStatus` | ACTIVE / PENDING |
+
+---
+
+## Sample Message Templates
+
+These must match exactly what your system will send. Vetting reviewers compare templates against actual traffic.
+
+### Transactional Appointment Reminder
+
+```
+Hi {{first_name}}, this is a reminder from {{business_name}} that your appointment is scheduled for {{date}} at {{time}}. Reply STOP to opt out. Msg & data rates may apply.
+```
+
+### Manual Staff Message
+
+```
+Your appointment with {{business_name}} is confirmed for {{date}}. Need to reschedule? Reply HELP for assistance or call us at {{phone}}. Msg & data rates may apply.
+```
+
+---
+
+## Failure Modes + Retry Guidance
+
+### Vetting Rejection — Brand
+
+| Rejection Reason | Common Fix |
+|-----------------|------------|
+| Legal name mismatch with EIN | Ensure exact EIN name matches legal company name exactly |
+| Website not accessible / missing privacy policy | Add privacy policy page to website before resubmitting |
+| Incomplete primary contact | Provide direct phone and real email (no noreply) |
+| High-risk business vertical | Contact Telnyx support for pre-screening before resubmitting |
+
+### Campaign Rejection
+
+| Rejection Reason | Common Fix |
+|-----------------|------------|
+| Sample messages do not match actual traffic | Update sample messages to match exactly what the system sends |
+| Missing STOP/HELP language | Add compliant STOP/HELP block to sample messages |
+| Volume estimate too low/high | Revise estimate to be realistic |
+| Use case mismatch | Re-select use case that matches actual messaging |
+
+### Re-submission
+
+After fixing the rejection reason, re-submit via the same API endpoint. Telnyx will re-run vetting (typically 24–48 hours).
+
+---
+
+## Cost Summary
+
+### Telnyx Fees (as of 2026)
+
+| Fee Type | Amount | Notes |
+|----------|--------|-------|
+| 10DLC number (monthly) | ~$1.00–$2.50/number | Varies by type and area code |
+| Outbound message | $0.005–$0.015/message | Depends on destination carrier |
+| Inbound message | Included | No charge for received messages |
+| Campaign registration | ~$15–$25 one-time | Per campaign, subject to change |
+
+### Carrier Fees (T-Mobile / AT&T / Verizon)
+
+| Carrier | Outbound Fee | Notes |
+|---------|-------------|-------|
+| T-Mobile | ~$0.005–$0.01/message | Varies by message size (segment) |
+| AT&T | ~$0.005–$0.015/message | Varies by message size (segment) |
+| Verizon | ~$0.005–$0.01/message | Varies by message size (segment) |
+
+**Note**: Carrier fees are subject to change. Check [Telnyx pricing page](https://telnyx.com/pricing) and carrier fee schedules for current rates.
+
+### Example Monthly Cost (Pilot — 500 messages/month)
+
+| Line Item | Cost |
+|-----------|------|
+| 1x 10DLC number | ~$2.00 |
+| 500 outbound messages | ~$5.00–$7.50 |
+| Carrier pass-through | ~$2.50–$7.50 |
+| **Estimated Monthly Total** | **~$9.50–$17.00** |
+
+---
+
+## Rollback / De-provisioning
+
+If the pilot tenant must be de-provisioned:
+
+1. Release the phone number: Telnyx Portal → Phone Numbers → Release.
+2. Archive the campaign: set status to `INACTIVE` via API or console.
+3. Remove DB record: clear `messagingPhoneNumber`, `telnyxMessagingProfileId`, `telnyxCampaignId` fields in the business record.
+4. Brand can remain registered (no harm) but will not be used.
+
+---
+
+## Contacts
+
+| Resource | Contact |
+|----------|---------|
+| Telnyx Support | support@telnyx.com |
+| Telnyx Dashboard | portal.telnyx.com |
+| Internal Engineering | Raise issue in GRO-106 |
+
+---
+
+_Owner: Engineering · Last updated: 2026-05-04_

docs/runbooks/README.md

@@ -0,0 +1,11 @@
+# GroomBook Runbooks
+
+Operational runbooks for GroomBook staff and operators.
+
+| Runbook | Description | Status |
+|---------|-------------|--------|
+| [10DLC Pilot Registration](./10dlc-pilot-registration.md) | Register a pilot grooming business as an A2P 10DLC brand + campaign on Telnyx | Active |
+
+---
+
+_To add a runbook, create a markdown file in this directory and update this table._

packages/db/migrations/0030_messaging.sql

@@ -0,0 +1,72 @@
+-- Migration: 0030_messaging.sql
+-- Messaging schema: conversations, messages, attachments, consent events + business messaging settings
+
+-- ─── Enums ───────────────────────────────────────────────────────────────────
+
+CREATE TYPE "messaging_channel" AS ENUM ('sms', 'mms');
+CREATE TYPE "message_direction" AS ENUM ('inbound', 'outbound');
+CREATE TYPE "message_status" AS ENUM ('queued', 'sent', 'delivered', 'failed', 'received');
+CREATE TYPE "message_consent_kind" AS ENUM ('opt_in', 'opt_out', 'help');
+
+-- ─── Tables ───────────────────────────────────────────────────────────────────
+
+CREATE TABLE "conversations" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "business_id" uuid NOT NULL,
+  "client_id" uuid NOT NULL REFERENCES "clients"("id") ON DELETE CASCADE,
+  "channel" "messaging_channel" NOT NULL,
+  "external_number" text NOT NULL,
+  "business_number" text NOT NULL,
+  "last_message_at" timestamp,
+  "status" text NOT NULL DEFAULT 'active',
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "updated_at" timestamp NOT NULL DEFAULT now()
+);
+
+CREATE INDEX "idx_conversations_business_id_last_message_at" ON "conversations"("business_id", "last_message_at" DESC);
+CREATE UNIQUE INDEX "uq_conversations_business_client_number" ON "conversations"("business_id", "client_id", "business_number");
+
+CREATE TABLE "messages" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "conversation_id" uuid NOT NULL REFERENCES "conversations"("id") ON DELETE CASCADE,
+  "direction" "message_direction" NOT NULL,
+  "body" text,
+  "status" "message_status" NOT NULL DEFAULT 'queued',
+  "provider_message_id" text,
+  "error_code" text,
+  "error_message" text,
+  "sent_by_staff_id" uuid REFERENCES "staff"("id") ON DELETE SET NULL,
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "delivered_at" timestamp,
+  "read_by_client_at" timestamp
+);
+
+CREATE INDEX "idx_messages_conversation_id_created_at" ON "messages"("conversation_id", "created_at" DESC);
+CREATE UNIQUE INDEX "uq_messages_provider_message_id" ON "messages"("provider_message_id");
+
+CREATE TABLE "message_attachments" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "message_id" uuid NOT NULL REFERENCES "messages"("id") ON DELETE CASCADE,
+  "content_type" text NOT NULL,
+  "url" text NOT NULL,
+  "size" integer NOT NULL,
+  "provider_media_id" text
+);
+
+CREATE INDEX "idx_message_attachments_message_id" ON "message_attachments"("message_id");
+
+CREATE TABLE "message_consent_events" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "client_id" uuid NOT NULL REFERENCES "clients"("id") ON DELETE CASCADE,
+  "business_id" uuid NOT NULL,
+  "kind" "message_consent_kind" NOT NULL,
+  "source" text,
+  "created_at" timestamp NOT NULL DEFAULT now()
+);
+
+CREATE INDEX "idx_message_consent_events_client_id" ON "message_consent_events"("client_id");
+
+-- ─── Business Settings extensions ────────────────────────────────────────────
+
+ALTER TABLE "business_settings" ADD COLUMN "messaging_phone_number" text;
+ALTER TABLE "business_settings" ADD COLUMN "telnyx_messaging_profile_id" text;

packages/db/migrations/meta/_journal.json

@@ -204,6 +204,20 @@
       "when": 1775741667192,
       "tag": "0028_sms_reminders",
       "breakpoints": true
+    },
+    {
+      "idx": 29,
+      "version": "7",
+      "when": 1775784467192,
+      "tag": "0029_db_indexes_constraints",
+      "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1775828067192,
+      "tag": "0030_messaging",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema.ts

@@ -406,6 +406,117 @@ export const impersonationAuditLogs = pgTable(
   (t) => [index("impersonation_audit_logs_session_id_idx").on(t.sessionId)]
 );
 
+// ─── Messaging ───────────────────────────────────────────────────────────────
+
+export const messagingChannelEnum = pgEnum("messaging_channel", ["sms", "mms"]);
+
+export const messageDirectionEnum = pgEnum("message_direction", [
+  "inbound",
+  "outbound",
+]);
+
+export const messageStatusEnum = pgEnum("message_status", [
+  "queued",
+  "sent",
+  "delivered",
+  "failed",
+  "received",
+]);
+
+export const messageConsentKindEnum = pgEnum("message_consent_kind", [
+  "opt_in",
+  "opt_out",
+  "help",
+]);
+
+export const conversations = pgTable(
+  "conversations",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    businessId: uuid("business_id").notNull(),
+    clientId: uuid("client_id")
+      .notNull()
+      .references(() => clients.id, { onDelete: "cascade" }),
+    channel: messagingChannelEnum("channel").notNull(),
+    externalNumber: text("external_number").notNull(),
+    businessNumber: text("business_number").notNull(),
+    lastMessageAt: timestamp("last_message_at"),
+    status: text("status").notNull().default("active"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (t) => [
+    index("idx_conversations_business_id_last_message_at").on(
+      t.businessId,
+      t.lastMessageAt.desc()
+    ),
+    unique("uq_conversations_business_client_number").on(
+      t.businessId,
+      t.clientId,
+      t.businessNumber
+    ),
+  ]
+);
+
+export const messages = pgTable(
+  "messages",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    conversationId: uuid("conversation_id")
+      .notNull()
+      .references(() => conversations.id, { onDelete: "cascade" }),
+    direction: messageDirectionEnum("direction").notNull(),
+    body: text("body"),
+    status: messageStatusEnum("status").notNull().default("queued"),
+    providerMessageId: text("provider_message_id"),
+    errorCode: text("error_code"),
+    errorMessage: text("error_message"),
+    sentByStaffId: uuid("sent_by_staff_id").references(() => staff.id, {
+      onDelete: "set null",
+    }),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    deliveredAt: timestamp("delivered_at"),
+    readByClientAt: timestamp("read_by_client_at"),
+  },
+  (t) => [
+    index("idx_messages_conversation_id_created_at").on(
+      t.conversationId,
+      t.createdAt.desc()
+    ),
+    unique("uq_messages_provider_message_id").on(t.providerMessageId),
+  ]
+);
+
+export const messageAttachments = pgTable(
+  "message_attachments",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    messageId: uuid("message_id")
+      .notNull()
+      .references(() => messages.id, { onDelete: "cascade" }),
+    contentType: text("content_type").notNull(),
+    url: text("url").notNull(),
+    size: integer("size").notNull(),
+    providerMediaId: text("provider_media_id"),
+  },
+  (t) => [index("idx_message_attachments_message_id").on(t.messageId)]
+);
+
+export const messageConsentEvents = pgTable(
+  "message_consent_events",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    clientId: uuid("client_id")
+      .notNull()
+      .references(() => clients.id, { onDelete: "cascade" }),
+    businessId: uuid("business_id").notNull(),
+    kind: messageConsentKindEnum("kind").notNull(),
+    source: text("source"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (t) => [index("idx_message_consent_events_client_id").on(t.clientId)]
+);
+
 export const businessSettings = pgTable("business_settings", {
   id: uuid("id").primaryKey().defaultRandom(),
   businessName: text("business_name").notNull().default("GroomBook"),
@@ -414,6 +525,8 @@ export const businessSettings = pgTable("business_settings", {
   logoKey: text("logo_key"),
   primaryColor: text("primary_color").notNull().default("#4f8a6f"),
   accentColor: text("accent_color").notNull().default("#8b7355"),
+  messagingPhoneNumber: text("messaging_phone_number"),
+  telnyxMessagingProfileId: text("telnyx_messaging_profile_id"),
   createdAt: timestamp("created_at").notNull().defaultNow(),
   updatedAt: timestamp("updated_at").notNull().defaultNow(),
 });

packages/db/src/seed.ts

@@ -883,7 +883,6 @@ async function seed() {
   let appointmentCount = 0;
   let invoiceCount = 0;
   let visitLogCount = 0;
-  let paidInvoiceCounter = 0;
 
   // Process in batches per client to keep memory manageable
   const apptBatchSize = 100;
@@ -978,11 +977,8 @@ async function seed() {
 
         const invoiceStatus = rand() < 0.95 ? "paid" as const : "pending" as const;
         const paidAt = invoiceStatus === "paid" ? new Date(endTime.getTime() + randInt(5, 30) * 60 * 1000) : null;
-        paidInvoiceCounter++;
-        const stripePaymentIntentId = invoiceStatus === "paid"
-          ? `pi_test_seed_${String(paidInvoiceCounter).padStart(6, "0")}`
-          : null;
 
+        const stripePaymentIntentId = invoiceStatus === "paid" && rand() < 0.2 ? `pi_test_${uuid().replace(/-/g, "").slice(0, 24)}` : null;
         invoiceBatch.push({
           id: invoiceId,
           appointmentId: apptId,
@@ -1098,16 +1094,14 @@ async function seed() {
       const taxCents = Math.round(effectivePrice * 0.08);
       const totalCents = effectivePrice + taxCents + tipCents;
       const paidAt = new Date(endTime.getTime() + randInt(5, 30) * 60 * 1000);
-      paidInvoiceCounter++;
+      const stripePaymentIntentId = rand() < 0.2 ? `pi_test_${uuid().replace(/-/g, "").slice(0, 24)}` : null;
 
       invoiceBatch.push({
         id: invoiceId, appointmentId: apptId, clientId,
         subtotalCents: effectivePrice, taxCents, tipCents, totalCents,
         status: "paid" as const,
         paymentMethod: pick(["cash", "card", "card", "card", "check"]) as "cash" | "card" | "check",
-        paidAt,
-        stripePaymentIntentId: `pi_test_seed_${String(paidInvoiceCounter).padStart(6, "0")}`,
-        notes: null,
+        paidAt, stripePaymentIntentId, notes: null,
       });
       lineItemBatch.push({
         id: uuid(), invoiceId, description: svc.name, quantity: 1,

pnpm-lock.yaml

@@ -46,6 +46,9 @@ importers:
       telnyx:
         specifier: ^1.23.0
         version: 1.27.0
+      uuid:
+        specifier: ^11.1.1
+        version: 11.1.1
       zod:
         specifier: ^4.3.6
         version: 4.3.6
@@ -59,6 +62,9 @@ importers:
       '@types/nodemailer':
         specifier: ^6.4.17
         version: 6.4.23
+      '@types/uuid':
+        specifier: ^10.0.0
+        version: 10.0.0
       '@vitest/coverage-v8':
         specifier: ^3.2.4
         version: 3.2.4(vitest@3.2.4(@types/node@22.19.15)(jiti@2.6.1)(jsdom@26.1.0)(lightningcss@1.32.0)(terser@5.46.1)(tsx@4.21.0))
@@ -2334,6 +2340,9 @@ packages:
   '@types/use-sync-external-store@0.0.6':
     resolution: {integrity: sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==}
 
+  '@types/uuid@10.0.0':
+    resolution: {integrity: sha512-7gqG38EyHgyP1S+7+xomFtL+ZNHcKv6DwNaCZmJmo1vgMugyF3TCnXVg4t1uk89mLNwnLtnY3TpOpCOyp1/xHQ==}
+
   '@typescript-eslint/eslint-plugin@8.57.1':
     resolution: {integrity: sha512-Gn3aqnvNl4NGc6x3/Bqk1AOn0thyTU9bqDRhiRnUWezgvr2OnhYCWCgC8zXXRVqBsIL1pSDt7T9nJUe0oM0kDQ==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -4344,12 +4353,18 @@ packages:
     peerDependencies:
       react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
+  uuid@11.1.1:
+    resolution: {integrity: sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==}
+    hasBin: true
+
   uuid@8.3.2:
     resolution: {integrity: sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==}
+    deprecated: uuid@10 and below is no longer supported.  For ESM codebases, update to uuid@latest.  For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
     hasBin: true
 
   uuid@9.0.1:
     resolution: {integrity: sha512-b+1eJOlsR9K8HJpow9Ok3fiWOWSIcIzXodvv0rQjVoOVNpWMpxf1wZNpt4y9h10odCNrqnYp1OBzRktckBe3sA==}
+    deprecated: uuid@10 and below is no longer supported.  For ESM codebases, update to uuid@latest.  For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
     hasBin: true
 
   victory-vendor@37.3.6:
@@ -6910,6 +6925,8 @@ snapshots:
 
   '@types/use-sync-external-store@0.0.6': {}
 
+  '@types/uuid@10.0.0': {}
+
   '@typescript-eslint/eslint-plugin@8.57.1(@typescript-eslint/parser@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)':
     dependencies:
       '@eslint-community/regexpp': 4.12.2
@@ -9014,6 +9031,8 @@ snapshots:
     dependencies:
       react: 19.2.4
 
+  uuid@11.1.1: {}
+
   uuid@8.3.2: {}
 
   uuid@9.0.1: {}