Compare commits
14 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Chris Farhood
|
dbc30b8463 | ||
 the-dogfather-cto[bot]
|
a70dbbd2c1 | ||
|
Chris Farhood
|
a61614c4a9 | ||
|
the-dogfather-cto[bot]
|
28a78a79d5 | ||
|
Chris Farhood
|
35c72a6c4b | ||
|
groombook-engineer[bot]
|
2d88f18f75 | ||
|
the-dogfather-cto[bot]
|
9363929f32 | ||
|
Chris Farhood
|
2c2a69f20b | ||
|
the-dogfather-cto[bot]
|
e52d561454 | ||
|
groombook-engineer[bot]
|
49dd698d22 | ||
|
Chris Farhood
|
305394baaf | ||
|
groombook-engineer[bot]
|
706c91b3ac | ||
|
Hugh Hackman
|
39f5c83049 | ||
|
Hugh Hackman
|
6c0cdb33fe |
@@ -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
|
||||
|
||||
+234
@@ -0,0 +1,234 @@
|
||||
# UAT Playbook
|
||||
|
||||
## 1. Overview
|
||||
|
||||
GroomBook is an open-source, self-hostable pet grooming business management & CRM platform. The monorepo contains the Hono API (`apps/api`), React PWA web app (`apps/web`), E2E tests (`apps/e2e`), and shared packages (`packages/db`, `packages/types`). Tech stack: Hono + React 19 + Vite + PostgreSQL + Drizzle ORM + Authentik OIDC.
|
||||
|
||||
## 2. Environments
|
||||
|
||||
| Environment | URL | Notes |
|
||||
|-------------|-----|-------|
|
||||
| Dev | `https://dev.groombook.dev` | Development environment for active development |
|
||||
| UAT | `https://uat.groombook.dev` | User Acceptance Testing environment |
|
||||
| Production | `https://demo.groombook.dev` | Production/demo environment |
|
||||
|
||||
**Local Development:** Run `docker compose up --build` at repository root. Web app available at `localhost:8080`, API at `localhost:3000`.
|
||||
|
||||
## 3. Pre-conditions
|
||||
|
||||
- UAT environment is accessible at `https://uat.groombook.dev`
|
||||
- Test accounts are seeded with the following personas:
|
||||
- **Manager:** Full administrative access
|
||||
- **Staff:** Limited access to assigned appointments and clients
|
||||
- **Client:** Portal access to view and manage their own appointments
|
||||
- OIDC is configured with Authentik at `https://auth.farh.net`
|
||||
- Seed data is populated:
|
||||
- Sample clients and pets
|
||||
- Grooming services with pricing and duration
|
||||
- Existing appointments
|
||||
- Stripe test keys are configured for payment flow testing
|
||||
- Email/SMS providers (Telnyx, etc.) are configured for notification testing
|
||||
|
||||
## 4. Test Cases
|
||||
|
||||
### 4.1 Authentication
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.1.1 | OIDC login | 1. Navigate to UAT environment<br>2. Click "Login with Authentik"<br>3. Enter test credentials<br>4. Authorize the application | User is redirected to app dashboard, session is established |
|
||||
| TC-APP-4.1.2 | Session persistence | 1. Log in as any user<br>2. Close browser tab<br>3. Reopen browser and navigate to UAT | User remains logged in, no re-authentication required |
|
||||
| TC-APP-4.1.3 | Logout | 1. Log in as any user<br>2. Click logout button<br>3. Attempt to access protected route | User is logged out and redirected to login page |
|
||||
| TC-APP-4.1.4 | RBAC - Manager access | 1. Log in as Manager<br>2. Navigate to Settings, Staff Management, Reports | All administrative features are accessible |
|
||||
| TC-APP-4.1.5 | RBAC - Staff access | 1. Log in as Staff<br>2. Attempt to access Settings, Staff Management | Access denied or limited view, staff can only see assigned appointments |
|
||||
| TC-APP-4.1.6 | RBAC - Client access | 1. Log in as Client<br>2. Navigate to portal<br>3. Attempt to access admin areas | Client can only view their own appointments, pets, and profile |
|
||||
|
||||
### 4.2 Setup Wizard / OOBE
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.2.1 | First-run setup | 1. Access fresh UAT environment with no configuration<br>2. Complete setup wizard: business name, hours, services | Configuration is saved, dashboard loads with setup complete |
|
||||
| TC-APP-4.2.2 | Setup validation | 1. Start setup wizard<br>2. Leave required fields blank<br>3. Attempt to proceed | Validation errors displayed, cannot proceed without required fields |
|
||||
| TC-APP-4.2.3 | Skip setup (if already configured) | 1. Access configured environment<br>2. Attempt to access setup wizard | Redirected to dashboard or setup is marked as complete |
|
||||
|
||||
### 4.3 Client Management
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.3.1 | Create new client | 1. Navigate to Clients page<br>2. Click "Add Client"<br>3. Fill in client details (name, email, phone, address)<br>4. Save | Client is created and appears in client list |
|
||||
| TC-APP-4.3.2 | Edit client | 1. Select existing client<br>2. Click "Edit"<br>3. Modify client details<br>4. Save | Changes are saved and reflected in client profile |
|
||||
| TC-APP-4.3.3 | Search clients | 1. Navigate to Clients page<br>2. Enter client name or email in search<br>3. Press Enter/submit | Search results display matching clients |
|
||||
| TC-APP-4.3.4 | Archive client | 1. Select active client<br>2. Click "Archive"<br>3. Confirm action | Client is marked as archived, no longer appears in active client list |
|
||||
|
||||
### 4.4 Pet Management
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.4.1 | Add pet to client | 1. Select client<br>2. Click "Add Pet"<br>3. Fill in pet details (name, breed, weight, notes)<br>4. Save | Pet is added to client's pet list |
|
||||
| TC-APP-4.4.2 | Edit pet information | 1. Select pet from client profile<br>2. Click "Edit"<br>3. Modify pet details<br>4. Save | Changes are saved and reflected |
|
||||
| TC-APP-4.4.3 | View grooming history | 1. Select pet with past appointments<br>2. Navigate to "History" tab | All past grooming appointments and notes are displayed |
|
||||
| TC-APP-4.4.4 | Add breed notes | 1. Edit pet<br>2. Add breed-specific notes (temperament, special handling)<br>3. Save | Notes are saved and visible to staff when scheduling |
|
||||
|
||||
### 4.5 Appointment Scheduling
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.5.1 | Create new appointment | 1. Navigate to Calendar or Appointments page<br>2. Click "New Appointment"<br>3. Select client, pet, service, staff, date/time<br>4. Save | Appointment is created and appears in calendar |
|
||||
| TC-APP-4.5.2 | Modify appointment | 1. Select existing appointment<br>2. Click "Edit"<br>3. Change date/time, staff, or service<br>4. Save | Changes are saved and calendar updates |
|
||||
| TC-APP-4.5.3 | Cancel appointment | 1. Select upcoming appointment<br>2. Click "Cancel"<br>3. Confirm and optionally select reason | Appointment is marked as cancelled, slot becomes available |
|
||||
| TC-APP-4.5.4 | Calendar view (day/week/month) | 1. Navigate to Calendar<br>2. Switch between day, week, and month views | Calendar displays appointments in selected time range correctly |
|
||||
| TC-APP-4.5.5 | Appointment groups | 1. Create multiple appointments for same time slot<br>2. View in calendar | Appointments are grouped/linked appropriately |
|
||||
| TC-APP-4.5.6 | Appointment availability check | 1. Attempt to book appointment during unavailable slot | System shows conflict or prevents double-booking |
|
||||
|
||||
### 4.6 Services
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.6.1 | List all services | 1. Navigate to Services page | All configured grooming services are listed |
|
||||
| TC-APP-4.6.2 | Create new service | 1. Click "Add Service"<br>2. Enter service name, description, duration, price<br>3. Save | Service is created and appears in list |
|
||||
| TC-APP-4.6.3 | Edit service | 1. Select existing service<br>2. Modify pricing or duration<br>3. Save | Changes are saved and reflected |
|
||||
| TC-APP-4.6.4 | Deactivate service | 1. Select service<br>2. Click "Deactivate"<br>3. Confirm | Service is marked as inactive, not available for new appointments |
|
||||
|
||||
### 4.7 Staff Management
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.7.1 | List all staff | 1. Navigate to Staff page | All staff members are listed with roles and status |
|
||||
| TC-APP-4.7.2 | Add new staff member | 1. Click "Add Staff"<br>2. Enter staff details and assign role<br>3. Save | Staff member is created and can be assigned to appointments |
|
||||
| TC-APP-4.7.3 | Assign RBAC role | 1. Select staff member<br>2. Change role (e.g., from Staff to Manager)<br>3. Save | Role change takes effect immediately |
|
||||
| TC-APP-4.7.4 | Impersonate client | 1. As Manager, select client<br>2. Click "Impersonate"<br>3. Verify audit log | Manager views client's perspective, action is logged |
|
||||
| TC-APP-4.7.5 | End impersonation | 1. While impersonating, click "End Impersonation" | Session returns to Manager's view |
|
||||
|
||||
### 4.8 Invoicing & Payments
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.8.1 | Generate invoice | 1. Select completed appointment<br>2. Click "Generate Invoice"<br>3. Review invoice details | Invoice is created with correct services, pricing, and taxes |
|
||||
| TC-APP-4.8.2 | Process Stripe payment | 1. Open invoice<br>2. Click "Pay Now"<br>3. Enter Stripe test card details<br>4. Submit | Payment is processed, invoice marked as paid |
|
||||
| TC-APP-4.8.3 | Add tip | 1. Before or after payment, add tip amount<br>2. Save | Tip is added to invoice total |
|
||||
| TC-APP-4.8.4 | Generate receipt | 1. After payment, click "Generate Receipt"<br>2. Download or view receipt | Receipt is generated with payment details |
|
||||
| TC-APP-4.8.5 | Process refund | 1. Select paid invoice<br>2. Click "Refund"<br>3. Enter refund amount and reason<br>4. Confirm | Refund is processed via Stripe, invoice status updated |
|
||||
| TC-APP-4.8.6 | Failed payment handling | 1. Attempt payment with declined card<br>2. Verify error handling | Appropriate error message displayed, invoice remains unpaid |
|
||||
|
||||
### 4.9 Customer Portal
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.9.1 | Client login | 1. Access portal URL<br>2. Log in with client credentials | Client lands on portal dashboard |
|
||||
| TC-APP-4.9.2 | View appointments | 1. Navigate to "My Appointments"<br>2. Review upcoming and past appointments | All client's appointments are listed |
|
||||
| TC-APP-4.9.3 | Confirm appointment | 1. Select upcoming appointment<br>2. Click "Confirm" | Appointment is marked as confirmed by client |
|
||||
| TC-APP-4.9.4 | Cancel appointment | 1. Select upcoming appointment<br>2. Click "Cancel"<br>3. Provide reason | Appointment is cancelled, notification sent to business |
|
||||
| TC-APP-4.9.5 | View appointment history | 1. Navigate to "History" tab | All past appointments with details are shown |
|
||||
|
||||
### 4.10 Waitlist
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.10.1 | Add client to waitlist | 1. Navigate to Waitlist page<br>2. Click "Add to Waitlist"<br>3. Select client, pet, preferred dates<br>4. Save | Client is added to waitlist |
|
||||
| TC-APP-4.10.2 | View waitlist | 1. Navigate to Waitlist page | All waitlisted requests are displayed with priority |
|
||||
| TC-APP-4.10.3 | Promote to appointment | 1. Select waitlist entry<br>2. Click "Promote to Appointment"<br>3. Select available slot | Appointment is created from waitlist, entry removed |
|
||||
| TC-APP-4.10.4 | Remove from waitlist | 1. Select waitlist entry<br>2. Click "Remove"<br>3. Confirm | Entry is removed from waitlist |
|
||||
|
||||
### 4.11 Search
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.11.1 | Global search for clients | 1. Use global search bar<br>2. Enter client name or email<br>3. Select "Clients" | Search returns matching clients |
|
||||
| TC-APP-4.11.2 | Global search for pets | 1. Use global search bar<br>2. Enter pet name or breed<br>3. Select "Pets" | Search returns matching pets with owner info |
|
||||
| TC-APP-4.11.3 | Search filters | 1. Perform search<br>2. Apply filters (date range, status, etc.) | Results are filtered according to criteria |
|
||||
| TC-APP-4.11.4 | No results handling | 1. Search for non-existent term<br>2. Verify UI | "No results found" message displayed |
|
||||
|
||||
### 4.12 Reports
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.12.1 | Revenue dashboard | 1. Navigate to Reports > Revenue<br>2. Select date range | Revenue metrics displayed (total, by service, by staff) |
|
||||
| TC-APP-4.12.2 | Staff utilization | 1. Navigate to Reports > Utilization<br>2. Select date range | Staff hours booked vs. available shown |
|
||||
| TC-APP-4.12.3 | Trend analytics | 1. Navigate to Reports > Trends<br>2. Select metric and time period | Trend chart displays with data points |
|
||||
| TC-APP-4.12.4 | Export report | 1. View any report<br>2. Click "Export"<br>3. Select format (CSV, PDF) | Report file is downloaded |
|
||||
|
||||
### 4.13 Calendar
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.13.1 | Generate iCal feed | 1. Navigate to Calendar<br>2. Click "iCal Feed"<br>3. Copy URL | iCal feed URL is generated for external calendar apps |
|
||||
| TC-APP-4.13.2 | Calendar sync (external) | 1. Import iCal feed into external calendar (Google, Outlook)<br>2. Verify sync | Appointments appear in external calendar |
|
||||
| TC-APP-4.13.3 | Calendar availability display | 1. View calendar in any view mode | Available and booked slots are visually distinct |
|
||||
|
||||
### 4.14 Email Reminders
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.14.1 | Configure email reminders | 1. Navigate to Settings > Notifications<br>2. Set reminder timing (24h, 1h before)<br>3. Save | Configuration is saved |
|
||||
| TC-APP-4.14.2 | Verify reminder delivery | 1. Create appointment for tomorrow<br>2. Wait for reminder trigger<br>3. Check test email account | Reminder email is received with correct details |
|
||||
| TC-APP-4.14.3 | SMS notification | 1. Configure SMS provider (Telnyx)<br>2. Enable SMS reminders<br>3. Create appointment | SMS is sent to client's phone number |
|
||||
| TC-APP-4.14.4 | Notification preferences | 1. As client, access portal settings<br>2. Toggle email/SMS preferences | Preferences are respected for future notifications |
|
||||
|
||||
### 4.15 Grooming Logs
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.15.1 | Log grooming entry | 1. Select pet<br>2. Click "Add Grooming Log"<br>3. Enter details (date, services, notes, photos)<br>4. Save | Log entry is created and linked to pet |
|
||||
| TC-APP-4.15.2 | View grooming history | 1. Select pet<br>2. Navigate to "Grooming History" | All log entries are displayed chronologically |
|
||||
| TC-APP-4.15.3 | Add photos to log | 1. Create or edit grooming log<br>2. Upload before/after photos<br>3. Save | Photos are attached to log entry |
|
||||
| TC-APP-4.15.4 | Edit grooming log | 1. Select existing log entry<br>2. Modify notes or services<br>3. Save | Changes are saved |
|
||||
|
||||
### 4.16 Settings
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.16.1 | Business settings | 1. Navigate to Settings > Business<br>2. Update business name, hours, contact info<br>3. Save | Settings are saved and reflected app-wide |
|
||||
| TC-APP-4.16.2 | App configuration | 1. Navigate to Settings > App<br>2. Configure theme, time zone, date format<br>3. Save | Configuration takes effect immediately |
|
||||
| TC-APP-4.16.3 | Payment settings | 1. Navigate to Settings > Payments<br>2. Configure Stripe keys, tax rates<br>3. Save | Payment settings are updated |
|
||||
| TC-APP-4.16.4 | Notification settings | 1. Navigate to Settings > Notifications<br>2. Configure email/SMS providers and defaults<br>3. Save | Notification configuration is saved |
|
||||
|
||||
### 4.17 Mobile / PWA
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.17.1 | Install prompt | 1. Access app on mobile device (or DevTools mobile view)<br>2. Verify install prompt appears | "Add to Home Screen" prompt is shown |
|
||||
| TC-APP-4.17.2 | Responsive design (mobile) | 1. Resize viewport to 390x844 (iPhone dimensions)<br>2. Navigate through app | All pages are usable and properly formatted |
|
||||
| TC-APP-4.17.3 | Offline basics | 1. Load app<br>2. Enable offline mode in DevTools<br>3. Navigate to previously loaded pages | Cached content is displayed, offline indicator shown |
|
||||
| TC-APP-4.17.4 | Touch interactions | 1. On mobile viewport, tap buttons, forms, and navigation<br>2. Verify responsiveness | All touch targets are accessible and responsive |
|
||||
|
||||
### 4.18 Navigation
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.18.1 | All major sections accessible | 1. Click each main navigation item<br>2. Verify page loads | All sections (Dashboard, Calendar, Clients, Pets, Appointments, Reports, Settings) load successfully |
|
||||
| TC-APP-4.18.2 | No broken links | 1. Navigate through app<br>2. Click various links and buttons | No 404 errors or dead ends encountered |
|
||||
| TC-APP-4.18.3 | No blank pages | 1. Navigate to each section and sub-section<br>2. Verify content is displayed | All pages render with appropriate content |
|
||||
| TC-APP-4.18.4 | Back/forward navigation | 1. Navigate through multiple pages<br>2. Use browser back and forward buttons | Navigation history works correctly |
|
||||
|
||||
### 4.19 Error States
|
||||
|
||||
| # | Scenario | Steps | Expected |
|
||||
|---|----------|-------|----------|
|
||||
| TC-APP-4.19.1 | Form with bad data | 1. On any form, enter invalid email, phone, or dates<br>2. Submit | Validation errors display specific issues |
|
||||
| TC-APP-4.19.2 | Missing required fields | 1. On any form, leave required fields blank<br>2. Submit | Clear error messages indicate which fields are required |
|
||||
| TC-APP-4.19.3 | Empty states | 1. Navigate to pages with no data (empty calendar, no clients)<br>2. Verify UI | Helpful empty state message with call-to-action displayed |
|
||||
| TC-APP-4.19.4 | Network error handling | 1. Disable network in DevTools<br>2. Attempt actions that require API calls<br>3. Re-enable network | Appropriate error message shown, app recovers when network restored |
|
||||
|
||||
## 5. Pass/Fail Criteria
|
||||
|
||||
**Pass:** All test cases execute without errors. Expected results match actual results. No regressions are observed. All functionality works as documented.
|
||||
|
||||
**Fail:** Any unexpected result is encountered. For failures, document:
|
||||
- Severity (Critical, High, Medium, Low)
|
||||
- Steps to reproduce
|
||||
- Actual vs. expected behavior
|
||||
- Screenshot(s) if applicable
|
||||
- Browser and device information
|
||||
|
||||
**Regressions:** If a previously working feature fails during this UAT run, it is considered a regression and must be addressed before the release can proceed.
|
||||
|
||||
## 6. Update Policy
|
||||
|
||||
**Any PR that changes user-facing behaviour MUST update this file.**
|
||||
|
||||
When modifying features that affect:
|
||||
- User workflows (authentication, scheduling, payments, etc.)
|
||||
- UI/UX (navigation, forms, responsive design)
|
||||
- Configuration (settings, integrations)
|
||||
- Data visibility (reports, search, filtering)
|
||||
|
||||
The corresponding test case(s) in Section 4 must be updated to reflect the new behaviour. The PR description must reference which playbook section was updated (e.g., "Updated UAT_PLAYBOOK.md §4.5 — new appointment group scheduling feature").
|
||||
@@ -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",
|
||||
|
||||
@@ -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);
|
||||
|
||||
|
||||
@@ -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,
|
||||
},
|
||||
},
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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 });
|
||||
});
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,200 @@
|
||||
import { getDb, conversations, messages, businessSettings, clients, eq, and } 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 [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 } = 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") {
|
||||
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 };
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -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"));
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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 },
|
||||
|
||||
@@ -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 },
|
||||
|
||||
@@ -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_
|
||||
@@ -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._
|
||||
Generated
+19
@@ -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: {}
|
||||
|
||||
Reference in New Issue
Block a user