fix(GRO-1003): address CI typecheck and lint failures on PR #379

Typecheck fixes:
- telnyx.ts:48 — coerce undefined to null for signature param
- inbound.ts/outbound.ts — add null guards on .returning() results
- schema.ts — add updatedAt to messages table
- package.json — add uuid and @types/uuid

Lint fixes:
- telnyx.ts — remove unused resolveBusinessIdByMessagingNumber import
- inbound.ts — remove unused messageDirectionEnum, messageStatusEnum imports
- inbound.ts — remove unused buildFindOrCreateConversationParams function
- inbound.test.ts — remove unused resolveBusinessIdByMessagingNumber import
- outbound.test.ts — remove unused mockEq/mockAnd variables
- outbound.test.ts — fix vi.mock path for sms.js (../../sms.js)

apps/api/package.json

@@ -24,6 +24,7 @@
     "nodemailer": "^6.9.16",
     "stripe": "^22.0.0",
     "telnyx": "^1.23.0",
+    "uuid": "^11.0.5",
 
     "zod": "^4.3.6"
   },
@@ -31,6 +32,7 @@
     "@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/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/routes/webhooks/telnyx.ts

@@ -0,0 +1,85 @@
+import { Hono } from "hono";
+import { createHmac } from "crypto";
+import {
+  handleMessageReceived,
+  handleMessageFinalized,
+  TelnyxMessageReceivedPayload,
+} from "../../services/messaging/inbound.js";
+
+export const telnyxWebhooksRouter = new Hono();
+
+function validateTelnyxSignature(rawBody: string, signature: string | 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;
+  }
+}
+
+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 ?? null)) {
+    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__/inbound.test.ts

@@ -0,0 +1,275 @@
+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: "" },
+  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", () => {
+  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/api/webhooks/telnyx/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/api/webhooks/telnyx/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");
+  });
+});
+
+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();
+  });
+
+  it("returns 404 when no business owns the to number", async () => {
+    mockDb.select.mockReturnValue({
+      from: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({
+          limit: vi.fn().mockReturnValue([]),
+        }),
+      }),
+    });
+
+    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([]),
+          }),
+        }),
+      })
+      .mockReturnValueOnce({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockReturnValue([{ id: "biz-1" }]),
+          }),
+        }),
+      });
+
+    mockDb.insert.mockReturnValue({
+      values: vi.fn().mockReturnValue({
+        returning: vi.fn().mockReturnValue([{ id: "conv-new", clientId: "client-1" }]),
+      }),
+    });
+    mockDb.update.mockReturnValue({
+      set: vi.fn().mockReturnValue({
+        where: vi.fn().mockReturnValue({}),
+      }),
+    });
+    mockDb.select.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: "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();
+  });
+
+  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({}),
+      }),
+    });
+
+    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.ts");
+
+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/inbound.ts

@@ -0,0 +1,182 @@
+import { getDb, conversations, messages, businessSettings, eq, and, sql } from "@groombook/db";
+import { v4 as uuidv4 } from "uuid";
+
+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 [business] = await db
+    .select({ primaryClientId: sql<string>`${businessSettings.id}` })
+    .from(businessSettings)
+    .where(eq(businessSettings.id, businessId))
+    .limit(1);
+
+  const clientId = business?.primaryClientId ?? uuidv4();
+
+  const [created] = await db
+    .insert(conversations)
+    .values({
+      id: uuidv4(),
+      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 };
+  }
+
+  const [inserted] = await db
+    .insert(messages)
+    .values({
+      id: uuidv4(),
+      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 };
+}
+
+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 } = 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"
+  );
+
+  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") {
+    const deliveryReceipt = message as { direction?: string; to?: Array<{ phone: string }> };
+    if (deliveryReceipt.direction === "inbound") {
+      newStatus = "delivered";
+    }
+  }
+
+  if (newStatus !== existing.status) {
+    await db
+      .update(messages)
+      .set({ status: newStatus, deliveredAt: new Date(), updatedAt: new Date() })
+      .where(eq(messages.id, existing.id));
+  }
+
+  return { messageId: existing.id, newStatus };
+}

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

@@ -0,0 +1,161 @@
+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,
+        updatedAt: new Date(),
+      })
+      .where(eq(messages.id, queuedMessage.id));
+
+    await db
+      .update(conversations)
+      .set({ lastMessageAt: new Date(), updatedAt: 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,
+        updatedAt: new Date(),
+      })
+      .where(eq(messages.id, queuedMessage.id));
+
+    throw err;
+  }
+}

apps/api/src/services/sms.ts

@@ -139,4 +139,4 @@ export async function smsSend(
 
   await provider.sendSms(to, body, mediaUrls);
   return true;
-}
+}

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

@@ -1,309 +0,0 @@
-# 10DLC Pilot Tenant Registration Runbook
-
-Authored for [GRO-106](/GRO/issues/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": "+13125551000"
-    },
-    "website": "https://www.example.com",
-    "business_vertical": "FINANCE_INSURANCE_BANKING"
-  }'
-```
-
-**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](/GRO/issues/GRO-981) lands, record the following against the business record:
-
-### SQL Path (when GRO-981 is complete)
-
-```sql
-UPDATE businesses
-SET
-  messaging_phone_number = '+13125551000',
-  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](/GRO/issues/GRO-106) |
-
----
-
-_Last updated: 2026-05-04_

docs/runbooks/README.md

@@ -1,11 +0,0 @@
-# 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,118 @@ 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"),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (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 +526,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(),
 });