GRO-1636: fix scrypt keylen=64 and add email+password UAT test cases

1. Fix scrypt keylen: positional arg is output key length, not N cost.
   Correct call: scrypt(pass, salt, 64, {N:16384, r:8, p:1})
   This produces a 64-byte key matching Better Auth's expected format.

2. Update UAT_PLAYBOOK.md §4.1 with 6 new email+password login test
   cases covering all 4 UAT personas (super, groomer, customer, tester),
   renumbered session/logout/RBAC tests, and a reset-cycle survival test.

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

.dockerignore

@@ -7,3 +7,5 @@ apps/web/dist
 apps/api/dist
 packages/db/dist
 packages/types/dist
+.turbo
+screenshots/

.env.example

@@ -11,6 +11,16 @@ 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
+# database has data but the setup wizard would otherwise block access.
+SKIP_OOBE=false
+
 # ── API ───────────────────────────────────────────────────────────────────────
 PORT=3000
 CORS_ORIGIN=http://localhost:8080

.github/workflows/ci.yml

@@ -2,15 +2,10 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev]
   pull_request:
-    branches: [main]
+    branches: [main, dev]
   workflow_dispatch:
-    inputs:
-      ref:
-        description: "Branch or ref to run CI against"
-        required: false
-        default: "main"
 
 jobs:
   lint-typecheck:
@@ -20,6 +15,8 @@ jobs:
       - uses: actions/checkout@v4
 
       - uses: pnpm/action-setup@v4
+        with:
+          version: '9.15.4'
 
       - uses: actions/setup-node@v4
         with:
@@ -42,6 +39,8 @@ jobs:
       - uses: actions/checkout@v4
 
       - uses: pnpm/action-setup@v4
+        with:
+          version: '9.15.4'
 
       - uses: actions/setup-node@v4
         with:
@@ -62,6 +61,8 @@ jobs:
       - uses: actions/checkout@v4
 
       - uses: pnpm/action-setup@v4
+        with:
+          version: '9.15.4'
 
       - uses: actions/setup-node@v4
         with:
@@ -80,14 +81,8 @@ jobs:
 
       - name: Run E2E tests
         run: pnpm --filter @groombook/e2e test
-
-      - name: Upload Playwright report
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: playwright-report
-          path: apps/e2e/playwright-report/
-          retention-days: 7
+        env:
+          PLAYWRIGHT_BASE_URL: http://host.docker.internal:8080
 
       - name: Stop Docker Compose stack
         if: always()
@@ -101,6 +96,8 @@ jobs:
       - uses: actions/checkout@v4
 
       - uses: pnpm/action-setup@v4
+        with:
+          version: '9.15.4'
 
       - uses: actions/setup-node@v4
         with:
@@ -111,6 +108,8 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Build all packages
+        env:
+          VITE_API_URL: ""
         run: pnpm build
 
   docker:
@@ -119,9 +118,6 @@ jobs:
     needs: [build, e2e]
     outputs:
       tag: ${{ steps.version.outputs.tag }}
-    permissions:
-      contents: read
-      packages: write
     steps:
       - uses: actions/checkout@v4
 
@@ -142,12 +138,12 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Log in to GitHub Container Registry
+      - name: Log in to Gitea Container Registry
         uses: docker/login-action@v3
         with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
+          registry: git.farh.net
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
 
       - name: Build and push API image
         uses: docker/build-push-action@v6
@@ -157,10 +153,10 @@ jobs:
           target: runner
           push: true
           tags: |
-            ghcr.io/groombook/api:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/api:latest' || '' }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+            git.farh.net/groombook/api:${{ steps.version.outputs.tag }}
+            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/api:latest' || '' }}
+          cache-from: type=registry,ref=git.farh.net/groombook/cache:api
+          cache-to: type=registry,ref=git.farh.net/groombook/cache:api,mode=max
 
       - name: Build and push Migrate image
         uses: docker/build-push-action@v6
@@ -170,10 +166,10 @@ jobs:
           target: migrate
           push: true
           tags: |
-            ghcr.io/groombook/migrate:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/migrate:latest' || '' }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+            git.farh.net/groombook/migrate:${{ steps.version.outputs.tag }}
+            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/migrate:latest' || '' }}
+          cache-from: type=registry,ref=git.farh.net/groombook/cache:migrate
+          cache-to: type=registry,ref=git.farh.net/groombook/cache:migrate,mode=max
 
       - name: Build and push Seed image
         uses: docker/build-push-action@v6
@@ -183,10 +179,10 @@ jobs:
           target: seed
           push: true
           tags: |
-            ghcr.io/groombook/seed:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/seed:latest' || '' }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+            git.farh.net/groombook/seed:${{ steps.version.outputs.tag }}
+            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/seed:latest' || '' }}
+          cache-from: type=registry,ref=git.farh.net/groombook/cache:seed
+          cache-to: type=registry,ref=git.farh.net/groombook/cache:seed,mode=max
 
       - name: Build and push Reset image
         uses: docker/build-push-action@v6
@@ -196,10 +192,10 @@ jobs:
           target: reset
           push: true
           tags: |
-            ghcr.io/groombook/reset:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/reset:latest' || '' }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+            git.farh.net/groombook/reset:${{ steps.version.outputs.tag }}
+            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/reset:latest' || '' }}
+          cache-from: type=registry,ref=git.farh.net/groombook/cache:reset
+          cache-to: type=registry,ref=git.farh.net/groombook/cache:reset,mode=max
 
       - name: Build and push Web image
         uses: docker/build-push-action@v6
@@ -208,19 +204,16 @@ jobs:
           file: apps/web/Dockerfile
           push: true
           tags: |
-            ghcr.io/groombook/web:${{ steps.version.outputs.tag }}
-            ${{ github.ref == 'refs/heads/main' && 'ghcr.io/groombook/web:latest' || '' }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+            git.farh.net/groombook/web:${{ steps.version.outputs.tag }}
+            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/web:latest' || '' }}
+          cache-from: type=registry,ref=git.farh.net/groombook/cache:web
+          cache-to: type=registry,ref=git.farh.net/groombook/cache:web,mode=max
 
   deploy-dev:
     name: Deploy PR to groombook-dev
     runs-on: runners-groombook
     needs: [docker]
     if: github.event_name == 'pull_request'
-    permissions:
-      contents: read
-      pull-requests: write
     steps:
       - name: Install kubectl
         run: |
@@ -237,8 +230,6 @@ jobs:
           TAG="pr-$PR_NUM-${SHA::7}"
           echo "Deploying images tagged $TAG to groombook-dev..."
 
-          # Run migration with PR image
-          kubectl delete job migrate-schema -n groombook-dev --ignore-not-found
           kubectl delete job "migrate-pr-$PR_NUM" -n groombook-dev --ignore-not-found
           cat <<EOF | kubectl apply -n groombook-dev -f -
           apiVersion: batch/v1
@@ -253,7 +244,7 @@ jobs:
                 restartPolicy: Never
                 containers:
                 - name: migrate
-                  image: ghcr.io/groombook/migrate:$TAG
+                  image: git.farh.net/groombook/migrate:$TAG
                   env:
                   - name: DATABASE_URL
                     valueFrom:
@@ -264,35 +255,33 @@ jobs:
           kubectl wait --for=condition=complete "job/migrate-pr-$PR_NUM" \
             -n groombook-dev --timeout=120s
 
-          # Update deployments
-          kubectl set image deployment/api api=ghcr.io/groombook/api:$TAG -n groombook-dev
-          kubectl set image deployment/web web=ghcr.io/groombook/web:$TAG -n groombook-dev
+          kubectl set image deployment/api api=git.farh.net/groombook/api:$TAG -n groombook-dev
+          kubectl set image deployment/web web=git.farh.net/groombook/web:$TAG -n groombook-dev
 
-          # Wait for rollout
           kubectl rollout status deployment/api -n groombook-dev --timeout=300s
           kubectl rollout status deployment/web -n groombook-dev --timeout=300s
 
           echo "Deployment complete."
 
       - name: Comment on PR
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const pr = context.issue.number;
-            const tag = `pr-${pr}`;
-            await github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: pr,
-              body: [
-                '## Deployed to groombook-dev',
-                '',
-                `**Images:** \`${tag}\``,
-                '**URL:** https://dev.groombook.farh.net',
-                '',
-                'Ready for UAT validation.'
-              ].join('\n')
-            });
+        env:
+          PR_NUM: ${{ github.event.pull_request.number }}
+        run: |
+          PR_NUM="$PR_NUM"
+          BODY=$(cat <<'EOFBODY'
+          ## Deployed to groombook-dev
+
+          **Images:** `pr-'"$PR_NUM"'`
+
+          **URL:** https://dev.groombook.farh.net
+
+          Ready for UAT validation.
+          EOFBODY
+          )
+          curl -s -X POST "https://git.farh.net/api/v1/repos/groombook/app/issues/${PR_NUM}/comments" \
+            -H "Authorization: Bearer ${{ secrets.REGISTRY_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d "{\"body\": $(echo "$BODY" | jq -Rs .)}"
 
   web-e2e:
     name: Web E2E (Dev)
@@ -303,6 +292,8 @@ jobs:
       - uses: actions/checkout@v4
 
       - uses: pnpm/action-setup@v4
+        with:
+          version: '9.15.4'
 
       - uses: actions/setup-node@v4
         with:
@@ -319,33 +310,15 @@ jobs:
         run: pnpm --filter @groombook/web test:e2e
         timeout-minutes: 10
 
-      - name: Upload Playwright report
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: playwright-web-e2e-report
-          path: apps/web/playwright-report/
-          retention-days: 7
-
   cd:
     name: Update Infra Image Tags
     runs-on: ubuntu-latest
     needs: [docker]
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-    permissions:
-      contents: write
-      pull-requests: write
+    if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && github.event_name == 'push'
     steps:
-      - name: Generate infra repo token
-        id: infra-token
-        uses: tibdex/github-app-token@v2
-        with:
-          app_id: ${{ vars.GH_APP_ID }}
-          private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-
       - name: Clone groombook/infra
         run: |
-          git clone https://x-access-token:${{ steps.infra-token.outputs.token }}@github.com/groombook/infra.git /tmp/infra
+          git clone https://oauth2:${{ secrets.REGISTRY_TOKEN }}@git.farh.net/groombook/infra.git /tmp/infra
 
       - name: Install yq
         run: |
@@ -364,28 +337,24 @@ jobs:
           echo "Updating dev overlay image tags to: $TAG"
           echo "Updating migration/seed Job names with SHA: $SHORT_SHA"
           cd /tmp/infra
-          DEV_KUST="apps/groombook/overlays/dev/kustomization.yaml"
-          yq -i '(.images[] | select(.name == "ghcr.io/groombook/api")).newTag = env(TAG)' "$DEV_KUST"
-          yq -i '(.images[] | select(.name == "ghcr.io/groombook/web")).newTag = env(TAG)' "$DEV_KUST"
-          yq -i '(.images[] | select(.name == "ghcr.io/groombook/migrate")).newTag = env(TAG)' "$DEV_KUST"
-          yq -i '(.images[] | select(.name == "ghcr.io/groombook/seed")).newTag = env(TAG)' "$DEV_KUST"
-          yq -i '(.images[] | select(.name == "ghcr.io/groombook/reset")).newTag = env(TAG)' "$DEV_KUST"
+          DEV_KUST="apps/overlays/dev/kustomization.yaml"
+          yq -i '(.images[] | select(.name == "git.farh.net/groombook/api")).newTag = env(TAG)' "$DEV_KUST"
+          yq -i '(.images[] | select(.name == "git.farh.net/groombook/web")).newTag = env(TAG)' "$DEV_KUST"
+          yq -i '(.images[] | select(.name == "git.farh.net/groombook/migrate")).newTag = env(TAG)' "$DEV_KUST"
+          yq -i '(.images[] | select(.name == "git.farh.net/groombook/seed")).newTag = env(TAG)' "$DEV_KUST"
+          yq -i '(.images[] | select(.name == "git.farh.net/groombook/reset")).newTag = env(TAG)' "$DEV_KUST"
 
-          # Update migrate Job name to include short SHA (immutable template fix)
-          MIGRATE_JOB="apps/groombook/base/migrate-job.yaml"
+          MIGRATE_JOB="apps/base/migrate-job.yaml"
           if [ -f "$MIGRATE_JOB" ]; then
             yq -i '.metadata.name = "migrate-schema-" + env(SHORT_SHA)' "$MIGRATE_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$MIGRATE_JOB"
-            # Ensure ttlSecondsAfterFinished is set for automatic cleanup
             yq -i '.spec.ttlSecondsAfterFinished = (.spec.ttlSecondsAfterFinished // 86400)' "$MIGRATE_JOB"
           fi
 
-          # Update seed Job name to include short SHA (immutable template fix)
-          SEED_JOB="apps/groombook/base/seed-job.yaml"
+          SEED_JOB="apps/base/seed-job.yaml"
           if [ -f "$SEED_JOB" ]; then
             yq -i '.metadata.name = "seed-test-data-" + env(SHORT_SHA)' "$SEED_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$SEED_JOB"
-            # Ensure ttlSecondsAfterFinished is set for automatic cleanup
             yq -i '.spec.ttlSecondsAfterFinished = (.spec.ttlSecondsAfterFinished // 86400)' "$SEED_JOB"
           fi
 
@@ -394,7 +363,6 @@ jobs:
       - name: Create PR on groombook/infra
         env:
           TAG: ${{ needs.docker.outputs.tag }}
-          GH_TOKEN: ${{ steps.infra-token.outputs.token }}
         run: |
           if [ -z "$TAG" ]; then
             TAG="$(date -u +%Y.%m.%d)-${GITHUB_SHA::7}"
@@ -402,18 +370,35 @@ jobs:
 
           cd /tmp/infra
           git config user.name "groombook-engineer[bot]"
-          git config user.email "3141748+groombook-engineer[bot]@users.noreply.github.com"
+          git config user.email "groombook-engineer@farh.net"
           git checkout -b "chore/update-image-tags-${TAG}"
-          git add apps/groombook/overlays/dev/ apps/groombook/base/migrate-job.yaml apps/groombook/base/seed-job.yaml
+          git add apps/overlays/dev/ apps/base/migrate-job.yaml apps/base/seed-job.yaml
           git commit -m "chore: update image tags and migration/seed Job names to ${TAG}"
 
           git push -u origin "chore/update-image-tags-${TAG}"
 
-          # Create PR and merge immediately (no required checks on groombook/infra)
-          PR_URL=$(gh pr create \
-            --repo groombook/infra \
-            --base main \
-            --head "chore/update-image-tags-${TAG}" \
-            --title "chore: deploy ${TAG} to dev" \
-            --body "[GRO-178](/GRO/issues/GRO-178) — automated image tag update from main merge")
-          gh pr merge "$PR_URL" --merge
+          EXISTING_PR=$(curl -s "https://git.farh.net/api/v1/repos/groombook/infra/pulls?state=open&head=groombook:chore/update-image-tags-${TAG}" \
+            -H "Authorization: Bearer ${{ secrets.REGISTRY_TOKEN }}" | jq -r '.[0].number')
+          if [ -n "$EXISTING_PR" ] && [ "$EXISTING_PR" != "null" ]; then
+            echo "PR #$EXISTING_PR already exists for this tag, merging existing PR"
+            curl -s -X PUT "https://git.farh.net/api/v1/repos/groombook/infra/pulls/${EXISTING_PR}/merge" \
+              -H "Authorization: Bearer ${{ secrets.REGISTRY_TOKEN }}" \
+              -H "Content-Type: application/json" \
+              -d '{"do": "merge"}'
+          else
+            PR_RESPONSE=$(curl -s -X POST "https://git.farh.net/api/v1/repos/groombook/infra/pulls" \
+              -H "Authorization: Bearer ${{ secrets.REGISTRY_TOKEN }}" \
+              -H "Content-Type: application/json" \
+              -d "{
+                \"base\": \"main\",
+                \"head\": \"chore/update-image-tags-${TAG}\",
+                \"title\": \"chore: deploy ${TAG} to dev\",
+                \"body\": \"[GRO-178](/GRO/issues/GRO-178) — automated image tag update from main merge\"
+              }")
+            PR_NUM=$(echo "$PR_RESPONSE" | jq -r '.number')
+            echo "Created PR #$PR_NUM"
+            curl -s -X PUT "https://git.farh.net/api/v1/repos/groombook/infra/pulls/${PR_NUM}/merge" \
+              -H "Authorization: Bearer ${{ secrets.REGISTRY_TOKEN }}" \
+              -H "Content-Type: application/json" \
+              -d '{"do": "merge"}'
+          fi

.github/workflows/promote-prod.yml

@@ -14,7 +14,29 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      packages: read
     steps:
+      - name: Validate tag format
+        run: |
+          TAG="${{ inputs.tag }}"
+          if ! echo "$TAG" | grep -qE '^[0-9]{4}\.[0-9]{2}\.[0-9]{2}-[a-f0-9]{7}$'; then
+            echo "::error::Invalid tag format: '$TAG'. Expected format: YYYY.MM.DD-sha7 (e.g. 2026.03.28-f1b85bf)"
+            exit 1
+          fi
+          echo "Tag format valid: $TAG"
+
+      - name: Verify image exists in GHCR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ inputs.tag }}"
+          # Check that the API image exists — if API was pushed, web/migrate were too
+          if ! gh api "/orgs/groombook/packages/container/api/versions" --jq ".[].metadata.container.tags[]" 2>/dev/null | grep -qF "$TAG"; then
+            echo "::error::Image ghcr.io/groombook/api:$TAG not found in GHCR. Verify the tag was built and pushed."
+            exit 1
+          fi
+          echo "Image verified: ghcr.io/groombook/api:$TAG exists"
+
       - name: Generate infra repo token
         id: infra-token
         uses: tibdex/github-app-token@v2
@@ -36,7 +58,7 @@ jobs:
           TAG: ${{ inputs.tag }}
         run: |
           cd /tmp/infra
-          PROD_KUST="apps/groombook/overlays/prod/kustomization.yaml"
+          PROD_KUST="apps/overlays/prod/kustomization.yaml"
 
           SHORT_SHA="${TAG##*-}"
           export SHORT_SHA
@@ -48,14 +70,14 @@ jobs:
           yq -i '(.images[] | select(.name == "ghcr.io/groombook/seed")).newTag = env(TAG)' "$PROD_KUST"
 
           # Update migrate Job name to include short SHA (immutable template fix)
-          MIGRATE_JOB="apps/groombook/base/migrate-job.yaml"
+          MIGRATE_JOB="apps/base/migrate-job.yaml"
           if [ -f "$MIGRATE_JOB" ]; then
             yq -i '.metadata.name = "migrate-schema-" + env(SHORT_SHA)' "$MIGRATE_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$MIGRATE_JOB"
           fi
 
           # Update seed Job name to include short SHA (immutable template fix)
-          SEED_JOB="apps/groombook/base/seed-job.yaml"
+          SEED_JOB="apps/base/seed-job.yaml"
           if [ -f "$SEED_JOB" ]; then
             yq -i '.metadata.name = "seed-test-data-" + env(SHORT_SHA)' "$SEED_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$SEED_JOB"
@@ -72,7 +94,7 @@ jobs:
           git config user.name "groombook-engineer[bot]"
           git config user.email "3141748+groombook-engineer[bot]@users.noreply.github.com"
           git checkout -b "release/promote-prod-${TAG}"
-          git add apps/groombook/overlays/prod/ apps/groombook/base/migrate-job.yaml apps/groombook/base/seed-job.yaml
+          git add apps/overlays/prod/ apps/base/migrate-job.yaml apps/base/seed-job.yaml
           git commit -m "release: promote ${TAG} to production"
           git push -u origin "release/promote-prod-${TAG}"
           gh pr create \

.github/workflows/promote-to-uat.yml

@@ -38,7 +38,7 @@ jobs:
         run: |
           echo "Updating UAT overlay image tags to: $TAG"
           cd /tmp/infra
-          UAT_KUST="apps/groombook/overlays/uat/kustomization.yaml"
+          UAT_KUST="apps/overlays/uat/kustomization.yaml"
 
           if [ ! -f "$UAT_KUST" ]; then
             echo "ERROR: UAT overlay not found at $UAT_KUST. Ensure GRO-427 has been completed."
@@ -55,7 +55,7 @@ jobs:
           yq -i '(.images[] | select(.name == "ghcr.io/groombook/seed")).newTag = env(TAG)' "$UAT_KUST"
 
           # Update migrate Job name to include short SHA (immutable template fix)
-          MIGRATE_JOB="apps/groombook/base/migrate-job.yaml"
+          MIGRATE_JOB="apps/base/migrate-job.yaml"
           if [ -f "$MIGRATE_JOB" ]; then
             yq -i '.metadata.name = "migrate-schema-" + env(SHORT_SHA)' "$MIGRATE_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$MIGRATE_JOB"
@@ -64,7 +64,7 @@ jobs:
           # Update seed Job name to include short SHA (immutable template fix)
           # NOTE: Do NOT update the image tag here — let the Kustomize images transformer
           # in the UAT overlay handle it via newTag. This avoids the immutable template issue.
-          SEED_JOB="apps/groombook/base/seed-job.yaml"
+          SEED_JOB="apps/base/seed-job.yaml"
           if [ -f "$SEED_JOB" ]; then
             yq -i '.metadata.name = "seed-test-data-" + env(SHORT_SHA)' "$SEED_JOB"
             yq -i '.metadata.annotations."groombook.app/deploy-version" = env(TAG)' "$SEED_JOB"
@@ -81,7 +81,7 @@ jobs:
           git config user.name "groombook-engineer[bot]"
           git config user.email "3141748+groombook-engineer[bot]@users.noreply.github.com"
           git checkout -b "chore/update-uat-image-tags-${TAG}"
-          git add apps/groombook/overlays/uat/ apps/groombook/base/migrate-job.yaml apps/groombook/base/seed-job.yaml
+          git add apps/overlays/uat/ apps/base/migrate-job.yaml apps/base/seed-job.yaml
           git commit -m "chore: promote ${TAG} to UAT"
 
           git push -u origin "chore/update-uat-image-tags-${TAG}"

.gitignore

@@ -8,3 +8,16 @@ dist/
 .turbo/
 coverage/
 minimax-output/
+
+# Agent runtime artifacts — never commit
+.gh-token
+*.gh-token
+.config/gh/
+**/.config/gh/
+infra-repo
+infra-repo/
+**/instructions/.gh-token
+**/AGENT_HOME/**
+$AGENT_HOME/**
+.claude/
+.codex/

CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to GroomBook
+
+## Branch Strategy
+
+GroomBook uses a three-branch GitOps model:
+
+| Branch | Environment | Purpose |
+|--------|-------------|---------|
+| `dev` | Development | Active development target — all feature/fix PRs target this branch |
+| `uat` | UAT / Staging | Promoted from `dev` by the CTO for acceptance testing |
+| `main` | Production | Promoted from `uat` by the CEO; triggers production deployment |
+
+**Never open a PR directly to `uat` or `main`.** All work flows through `dev` first.
+
+## Developer Workflow
+
+1. **Branch from `dev`** — create a feature or fix branch:
+   ```bash
+   git checkout dev
+   git pull origin dev
+   git checkout -b feat/my-feature
+   ```
+
+2. **Open a PR targeting `dev`** — include the issue identifier in the title and cc @cpfarhood:
+   ```bash
+   gh pr create --base dev --title "feat: description (GRO-NNN)" \
+     --body $'Closes GRO-NNN\n\ncc @cpfarhood'
+   ```
+
+3. **Pipeline gates before merge to `dev`:**
+   - QA (Lint Roller) reviews first — code quality, test coverage, CI pass
+   - CTO (The Dogfather) reviews second — architecture and final approval
+   - Both must approve; 2 approving reviews required by branch protection
+
+## Promotion Flow
+
+### Dev → UAT
+
+After merging to `dev`, the CTO opens a PR from `dev` → `uat`:
+
+```bash
+gh pr create --base uat --head dev \
+  --title "chore: promote dev to uat (YYYY.MM.DD)" \
+  --body $'Promoting dev to UAT for regression and security review.\n\ncc @cpfarhood'
+```
+
+Gates:
+- Shedward Scissorhands runs regression/acceptance tests
+- Barkley Trimsworth performs security review
+- CTO approves and merges (1 approving review required)
+
+### UAT → Main (Production)
+
+After UAT passes, the CTO opens a PR from `uat` → `main` and assigns it to the CEO:
+
+```bash
+gh pr create --base main --head uat \
+  --title "chore: promote uat to main (YYYY.MM.DD)" \
+  --body $'Promoting UAT to production.\n\ncc @cpfarhood'
+```
+
+Gates:
+- CEO (Scrubs McBarkley) reviews for business alignment and merges
+- 1 approving review required; triggers auto-deploy to Production
+
+## Branch Protection Summary
+
+| Branch | Required Approvals | Who approves |
+|--------|--------------------|-------------|
+| `dev` | 2 | QA (Lint Roller) + CTO (The Dogfather) |
+| `uat` | 1 | CTO (The Dogfather) |
+| `main` | 1 | CEO (Scrubs McBarkley) |
+
+Force-pushes and branch deletions are disabled on all three branches.
+
+## Commit Style
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+- `feat:` — new feature
+- `fix:` — bug fix
+- `chore:` — maintenance (dependency updates, build config, promotions)
+- `docs:` — documentation only
+- `ci:` — CI/CD changes
+- `refactor:` — code restructure without behaviour change
+
+Reference the Paperclip issue in the commit body: `Refs GRO-NNN`.
+
+## Questions?
+
+Open a Paperclip issue in the GRO project or ask in the team channel.

UAT_PLAYBOOK.md

@@ -0,0 +1,283 @@
+# 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 (Authentik) | 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 | Email + password login (UAT Super) | 1. Navigate to UAT environment sign-in page<br>2. Select email+password flow<br>3. Enter `uat-super@groombook.dev` and UAT super password<br>4. Submit | User is logged in and redirected to dashboard with manager access |
+| TC-APP-4.1.3 | Email + password login (UAT Groomer) | 1. Navigate to UAT environment sign-in page<br>2. Select email+password flow<br>3. Enter `uat-groomer@groombook.dev` and UAT groomer password<br>4. Submit | User is logged in and redirected to dashboard with staff/groomer access |
+| TC-APP-4.1.4 | Email + password login (UAT Customer) | 1. Navigate to UAT environment sign-in page<br>2. Select email+password flow<br>3. Enter `uat-customer@groombook.dev` and UAT customer password<br>4. Submit | User is logged in with client portal access |
+| TC-APP-4.1.5 | Email + password login (UAT Tester) | 1. Navigate to UAT environment sign-in page<br>2. Select email+password flow<br>3. Enter `uat-tester@groombook.dev` and UAT tester password<br>4. Submit | User is logged in with staff/tester access |
+| TC-APP-4.1.6 | 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.7 | 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.8 | RBAC - Manager access | 1. Log in as Manager (OIDC or email+password)<br>2. Navigate to Settings, Staff Management, Reports | All administrative features are accessible |
+| TC-APP-4.1.9 | RBAC - Staff access | 1. Log in as Staff (OIDC or email+password)<br>2. Attempt to access Settings, Staff Management | Access denied or limited view, staff can only see assigned appointments |
+| TC-APP-4.1.10 | RBAC - Client access | 1. Log in as Client (email+password)<br>2. Navigate to portal<br>3. Attempt to access admin areas | Client can only view their own appointments, pets, and profile |
+| TC-APP-4.1.11 | Login after hourly reset | 1. Wait for or trigger `reset-demo-data` CronJob to run<br>2. Attempt email+password login as any UAT persona | Login succeeds — Better Auth credential accounts survive the reset cycle |
+
+### 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 |
+| TC-APP-4.5.7 | Booking wizard — size/coat selection | 1. Start new appointment booking wizard<br>2. Select a pet with sizeCategory and coatType set<br>3. Observe the service/slot selection step | Size and coat type dropdowns are displayed and persist the pet's existing values |
+| TC-APP-4.5.8 | Large/X-Large pet slot duration reflects buffer | 1. Add a pet with sizeCategory = "large" or "x-large" to an appointment<br>2. Note the service duration<br>3. Complete booking and inspect the appointment | Appointment slot includes the service duration plus the configured buffer for the pet's size category |
+| TC-APP-4.5.9 | Appointment overrun cascades downstream | 1. Book three consecutive same-groomer appointments (A → B → C)<br>2. Manually extend appointment A's endTime so it overlaps B's startTime by ≥15 min<br>3. Observe appointment B | Appointment B (and C if still overlapping) is automatically shifted forward by the overrun delta + buffer; no error thrown |
+| TC-APP-4.5.10 | Cascaded appointments appear at new times | 1. Complete TC-APP-4.5.9<br>2. Check the calendar/list view | Appointments B and C are now shown at their shifted start/end times |
+| TC-APP-4.5.11 | Client receives reschedule notification email | 1. Complete TC-APP-4.5.9<br>2. Check the client's email (or notification log) | Client receives an email with subject/lines indicating their appointment was rescheduled from original time to new time |
+| TC-APP-4.5.12 | Appointment flagged when shift crosses day boundary | 1. Book appointment D for late afternoon (e.g. 17:30)<br>2. Extend a prior appointment so D would shift to the next day<br>3. Observe D | Appointment D is flagged for manual review and is NOT auto-shifted to the next day |
+| TC-APP-4.5.13 | Only scheduled/confirmed appointments are cascaded | 1. Start a cascade scenario (TC-APP-4.5.9) where a downstream appointment is already `in_progress`<br>2. Complete the cascade | The `in_progress` appointment is not shifted; cascade continues to next eligible appointment |
+
+### 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.9.1 Communication Tab
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-APP-4.9.6 | View message history (conversation exists) | 1. Log in as client with existing conversation<br>2. Navigate to Communication tab | Real message history is displayed (not mock data) |
+| TC-APP-4.9.7 | Empty state (no conversation yet) | 1. Log in as client with no conversation<br>2. Navigate to Communication tab | Empty state is shown; app does not crash or show mock messages |
+| TC-APP-4.9.8 | Composer disabled | 1. Log in as client<br>2. Navigate to Communication tab | Composer/Reply field is hidden or disabled with tooltip "Reply from your phone" |
+| TC-APP-4.9.9 | Cross-tenant isolation | 1. As client A, retrieve session token<br>2. Attempt to fetch client B conversation via API | Request returns 403 or empty; client A cannot access client B messages |
+
+### 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 |
+
+### 4.20 Staff Messages
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-APP-4.20.1 | Staff messages inbox loads | 1. Log in as Staff<br>2. Navigate to Messages | Conversation list renders with client phone and last message preview |
+| TC-APP-4.20.2 | Open conversation | 1. Select a conversation from the list | Full message thread loads chronologically |
+| TC-APP-4.20.3 | Send message | 1. Type a reply and submit | Message appears in thread; POST /api/conversations/:id/messages succeeds |
+| TC-APP-4.20.4 | Empty state | 1. Log in as Staff with no conversations | Empty state shown; no crash |
+| TC-APP-4.20.5 | Unread indicator | 1. Client sends a new message | Thread marked unread until staff views it |
+| TC-APP-4.20.6 | Cross-tenant isolation | 1. Staff from Business A attempts to read Business B conversations | 403 or empty response returned |
+
+
+### 4.21 SMS Consent (STOP/HELP Keyword Handler)
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-APP-4.21.1 | STOP → unsubscribe + auto-reply | 1. Send `STOP` (case-insensitive, with whitespace) from a subscribed client's phone number | Client is opted out (`smsOptIn=false`, `smsOptOutDate` set), event is logged, user receives auto-reply: "You have been unsubscribed and will no longer receive messages. Reply START to resubscribe." |
+| TC-APP-4.21.2 | START → resubscribe + auto-reply | 1. Send `START` (case-insensitive) from an opted-out client's phone number | Client is opted back in (`smsOptIn=true`, `smsConsentDate` updated, `smsOptOutDate` cleared), event is logged, user receives auto-reply: "You have been resubscribed to messages. Reply STOP to unsubscribe. Msg & data rates may apply." |
+| TC-APP-4.21.3 | HELP → no opt-in change + default reply | 1. Send `HELP` (case-insensitive) from any client's phone number | No change to opt-in state, no database update, event is logged, user receives auto-reply: "Reply STOP to unsubscribe or START to resubscribe. For help, contact your groomer directly." |
+| TC-APP-4.21.4 | STOPALL / UNSUBSCRIBE / CANCEL / END / QUIT → opt-out | 1. Send each alias from a subscribed client's phone | Same behaviour as STOP: opt-out applied, correct reply sent |
+| TC-APP-4.21.5 | UNSTOP / YES / SUBSCRIBE → opt-in | 1. Send each alias from an opted-out client's phone | Same behaviour as START: opt-in applied, correct reply sent |
+| TC-APP-4.21.6 | INFO → help reply | 1. Send `INFO` from any client's phone | Same behaviour as HELP: no state change, help reply returned |
+| TC-APP-4.21.7 | Double STOP (idempotency) | 1. Send `STOP` from an already-opted-out client | Event is logged, no update call made, idempotent — no duplicate update |
+| TC-APP-4.21.8 | Double START (idempotency) | 1. Send `START` from an already-subscribed client | Event is logged, no update call made, idempotent — no duplicate update |
+| TC-APP-4.21.9 | Case insensitivity | 1. Send `stop`, `Stop`, `sToP`, ` stop ` from subscribed client | All variants are detected and handled as opt-out |
+| TC-APP-4.21.10 | Whitespace trimming | 1. Send `  START  ` or `\tSTOP\n` | Keywords are trimmed before matching |
+| TC-APP-4.21.11 | Non-keyword messages ignored | 1. Send `STOP IT`, `help me`, `hello` | Returns null from `detectKeyword`, no consent event inserted, no reply sent |
+| TC-APP-4.21.12 | Consent event audit log | 1. After any keyword, query `messageConsentEvents` table | Record exists with correct `clientId`, `businessId`, `kind`, and `source: "sms_keyword"` |
+## 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").

apps/api/Dockerfile

@@ -12,6 +12,7 @@ RUN pnpm install --frozen-lockfile
 
 # Build
 FROM deps AS builder
+RUN mkdir -p /home/node/.cache/node/corepack
 COPY packages/ packages/
 COPY apps/api/ apps/api/
 RUN pnpm --filter @groombook/types build && \
@@ -34,6 +35,9 @@ COPY --from=builder /app/packages/types/dist packages/types/dist
 RUN pnpm install --frozen-lockfile --prod
 
 EXPOSE 3000
+RUN apk add --no-cache curl
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:3000/health || exit 1
 CMD ["node", "apps/api/dist/index.js"]
 
 # Migrate stage — runs drizzle-kit migrate against the database
@@ -46,4 +50,4 @@ CMD ["pnpm", "db:seed"]
 
 # Reset stage — drops all tables, re-runs migrations, and re-seeds
 FROM builder AS reset
-CMD ["pnpm", "db:reset"]
+CMD ["pnpm", "db:reset"]

apps/api/package.json

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

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

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { resolveBufferMinutes } from "../lib/buffer.js";
+
+// ─── Mock types matching schema ─────────────────────────────────────────────
+
+interface MockBufferTimeRule {
+  id: string;
+  serviceId: string;
+  sizeCategory: string | null;
+  coatType: string | null;
+  bufferMinutes: number;
+}
+
+interface MockService {
+  id: string;
+  name: string;
+  defaultBufferMinutes: number;
+}
+
+// ─── Mock db factory ─────────────────────────────────────────────────────────
+// Simulates Drizzle query builder: db.select().from(t).where(eq(...)) → await → array
+// For services we use db.select().from(t).where(eq(...)).limit(1) → await → first item
+
+function createMockDb(rules: MockBufferTimeRule[], services: MockService[]) {
+  let callCount = 0;
+
+  return {
+    select: vi.fn(() => {
+      callCount++;
+      const rulesQuery = {
+        from: () => ({
+          where: () => rules, // await resolves directly to rules array
+        }),
+      };
+      const serviceQuery = {
+        from: () => ({
+          where: () => ({
+            limit: () => services, // await resolves to services array
+          }),
+        }),
+      };
+      // First select call → rules, second → services
+      return callCount === 1 ? rulesQuery : serviceQuery;
+    }),
+  } as any;
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("resolveBufferMinutes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns exact match when serviceId + sizeCategory + coatType all match", async () => {
+    const db = createMockDb(
+      [
+        { id: "rule-1", serviceId: "svc-1", sizeCategory: "medium", coatType: "short", bufferMinutes: 15 },
+        { id: "rule-2", serviceId: "svc-1", sizeCategory: "medium", coatType: null, bufferMinutes: 10 },
+        { id: "rule-3", serviceId: "svc-1", sizeCategory: null, coatType: null, bufferMinutes: 5 },
+      ],
+      []
+    );
+
+    const result = await resolveBufferMinutes({
+      serviceId: "svc-1",
+      sizeCategory: "medium",
+      coatType: "short",
+      db,
+    });
+
+    expect(result).toBe(15);
+  });
+
+  it("returns service + size match when no exact match", async () => {
+    const db = createMockDb(
+      [
+        { id: "rule-1", serviceId: "svc-1", sizeCategory: "medium", coatType: null, bufferMinutes: 10 },
+        { id: "rule-2", serviceId: "svc-1", sizeCategory: null, coatType: null, bufferMinutes: 5 },
+      ],
+      []
+    );
+
+    const result = await resolveBufferMinutes({
+      serviceId: "svc-1",
+      sizeCategory: "medium",
+      coatType: "long",
+      db,
+    });
+
+    expect(result).toBe(10);
+  });
+
+  it("returns service + coat match when no exact or size match", async () => {
+    const db = createMockDb(
+      [
+        { id: "rule-1", serviceId: "svc-1", sizeCategory: null, coatType: "wire", bufferMinutes: 12 },
+        { id: "rule-2", serviceId: "svc-1", sizeCategory: null, coatType: null, bufferMinutes: 5 },
+      ],
+      []
+    );
+
+    const result = await resolveBufferMinutes({
+      serviceId: "svc-1",
+      sizeCategory: "large",
+      coatType: "wire",
+      db,
+    });
+
+    expect(result).toBe(12);
+  });
+
+  it("returns service-only match when no partial matches", async () => {
+    const db = createMockDb(
+      [{ id: "rule-1", serviceId: "svc-1", sizeCategory: null, coatType: null, bufferMinutes: 7 }],
+      []
+    );
+
+    const result = await resolveBufferMinutes({
+      serviceId: "svc-1",
+      sizeCategory: "large",
+      coatType: "long",
+      db,
+    });
+
+    expect(result).toBe(7);
+  });
+
+  it("falls back to service.defaultBufferMinutes when no rules exist", async () => {
+    const db = createMockDb([], [{ id: "svc-1", name: "Bath", defaultBufferMinutes: 8 }]);
+
+    const result = await resolveBufferMinutes({
+      serviceId: "svc-1",
+      sizeCategory: "small",
+      coatType: "curly",
+      db,
+    });
+
+    expect(result).toBe(8);
+  });
+
+  it("falls back to 0 when no rules and no service default", async () => {
+    const db = createMockDb([], []);
+
+    const result = await resolveBufferMinutes({
+      serviceId: "svc-1",
+      sizeCategory: "small",
+      coatType: null,
+      db,
+    });
+
+    expect(result).toBe(0);
+  });
+
+  it("exact match beats partial matches (priority verification)", async () => {
+    const db = createMockDb(
+      [
+        { id: "rule-1", serviceId: "svc-1", sizeCategory: "medium", coatType: "short", bufferMinutes: 20 },
+        { id: "rule-2", serviceId: "svc-1", sizeCategory: "medium", coatType: null, bufferMinutes: 15 },
+        { id: "rule-3", serviceId: "svc-1", sizeCategory: null, coatType: null, bufferMinutes: 10 },
+      ],
+      [{ id: "svc-1", name: "Groom", defaultBufferMinutes: 5 }]
+    );
+
+    const result = await resolveBufferMinutes({
+      serviceId: "svc-1",
+      sizeCategory: "medium",
+      coatType: "short",
+      db,
+    });
+
+    // Exact match (20) should win over service+size (15) and service default (5)
+    expect(result).toBe(20);
+  });
+
+  it("handles null sizeCategory and null coatType at rule level", async () => {
+    const db = createMockDb(
+      [{ id: "rule-1", serviceId: "svc-1", sizeCategory: null, coatType: null, bufferMinutes: 6 }],
+      []
+    );
+
+    const result = await resolveBufferMinutes({
+      serviceId: "svc-1",
+      sizeCategory: null,
+      coatType: null,
+      db,
+    });
+
+    expect(result).toBe(6);
+  });
+
+  it("prefers service+size over service-only when both exist", async () => {
+    const db = createMockDb(
+      [
+        { id: "rule-1", serviceId: "svc-1", sizeCategory: "large", coatType: null, bufferMinutes: 14 },
+        { id: "rule-2", serviceId: "svc-1", sizeCategory: null, coatType: null, bufferMinutes: 3 },
+      ],
+      [{ id: "svc-1", name: "Groom", defaultBufferMinutes: 1 }]
+    );
+
+    const result = await resolveBufferMinutes({
+      serviceId: "svc-1",
+      sizeCategory: "large",
+      coatType: "smooth",
+      db,
+    });
+
+    expect(result).toBe(14);
+  });
+});

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

@@ -27,12 +27,14 @@ const DISABLED_CLIENT = {
 // ─── Queue-based mock DB ──────────────────────────────────────────────────────
 
 let selectRows: Record<string, unknown>[] = [];
+let appointmentRows: Record<string, unknown>[] = [];
 let insertedValues: Record<string, unknown>[] = [];
 let updatedValues: Record<string, unknown>[] = [];
 let deletedId: string | null = null;
 
 function resetMock() {
   selectRows = [];
+  appointmentRows = [];
   insertedValues = [];
   updatedValues = [];
   deletedId = null;
@@ -58,10 +60,19 @@ vi.mock("@groombook/db", () => {
     { get: (t, p) => (p === "_name" ? "clients" : { table: "clients", column: p }) }
   );
 
+  const appointments = new Proxy(
+    { _name: "appointments" },
+    { get: (t, p) => (p === "_name" ? "appointments" : { table: "appointments", column: p }) }
+  );
+
   return {
     getDb: () => ({
       select: () => ({
-        from: () => makeChainable(selectRows),
+        from: (table: unknown) => {
+          const tableName = (table as { _name?: string })._name;
+          const rows = tableName === "appointments" ? appointmentRows : selectRows;
+          return makeChainable(rows);
+        },
       }),
       insert: () => ({
         values: (vals: Record<string, unknown>) => {
@@ -95,8 +106,10 @@ vi.mock("@groombook/db", () => {
       }),
     }),
     clients,
+    appointments,
     eq: vi.fn(),
     and: vi.fn(),
+    or: vi.fn(),
   };
 });
 
@@ -182,10 +195,11 @@ describe("POST /clients", () => {
     expect(insertedValues[0]!.name).toBe("Charlie");
   });
 
-  it("creates a client with only required name field", async () => {
-    const res = await jsonRequest("POST", "/clients", { name: "Dana" });
+  it("creates a client with name and email", async () => {
+    const res = await jsonRequest("POST", "/clients", { name: "Dana", email: "dana@example.com" });
     expect(res.status).toBe(201);
     expect(insertedValues[0]!.name).toBe("Dana");
+    expect(insertedValues[0]!.email).toBe("dana@example.com");
   });
 
   it("rejects empty name", async () => {

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

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

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

@@ -0,0 +1,318 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Hono } from "hono";
+
+// ─── Mock data ────────────────────────────────────────────────────────────────
+
+const STAFF_ROW = {
+  id: "staff-uuid-1",
+  email: "groomer@groombook.com",
+  name: "Groomer",
+  role: "groomer" as const,
+  businessId: "business-uuid-1",
+  active: true,
+  userId: null,
+  oidcSub: null,
+  isSuperUser: false,
+  icalToken: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+const BUSINESS_SETTINGS = {
+  id: "business-uuid-1",
+  businessName: "Test Salon",
+};
+
+const CONV_1 = {
+  id: "conv-uuid-1",
+  businessId: "business-uuid-1",
+  clientId: "client-uuid-1",
+  channel: "sms",
+  externalNumber: "+15551111111",
+  businessNumber: "+15552222222",
+  lastMessageAt: new Date("2025-01-10T10:00:00Z"),
+  status: "active",
+  createdAt: new Date("2025-01-01T00:00:00Z"),
+  updatedAt: new Date("2025-01-10T10:00:00Z"),
+  staffReadAt: null,
+};
+
+const MSG_INBOUND_1 = {
+  id: "msg-uuid-1",
+  conversationId: "conv-uuid-1",
+  direction: "inbound",
+  body: "Hello",
+  status: "delivered",
+  sentByStaffId: null,
+  createdAt: new Date("2025-01-10T09:00:00Z"),
+  deliveredAt: new Date("2025-01-10T09:01:00Z"),
+};
+
+const MSG_OUTBOUND_1 = {
+  id: "msg-uuid-2",
+  conversationId: "conv-uuid-1",
+  direction: "outbound",
+  body: "Hi Alice!",
+  status: "delivered",
+  sentByStaffId: "staff-uuid-1",
+  createdAt: new Date("2025-01-10T10:00:00Z"),
+  deliveredAt: new Date("2025-01-10T10:01:00Z"),
+};
+
+// ─── Queue-based mock DB ──────────────────────────────────────────────────────
+
+let selectRows: Record<string, unknown>[] = [];
+let selectRows2: Record<string, unknown>[] = [];
+let selectRows3: Record<string, unknown>[] = [];
+let updatedValues: Record<string, unknown>[] = [];
+let selectCallCount = 0;
+
+function resetMock() {
+  selectRows = [];
+  selectRows2 = [];
+  selectRows3 = [];
+  updatedValues = [];
+  selectCallCount = 0;
+}
+
+function resetAll() {
+  resetMock();
+  vi.clearAllMocks();
+}
+
+const mockSendMessage = vi.hoisted(() => vi.fn());
+
+vi.mock("@groombook/db", () => {
+  function makeChainable(data: unknown[]): unknown {
+    const arr = [...data];
+    const chain = new Proxy(arr, {
+      get(target, prop) {
+        if (prop === "where" || prop === "orderBy" || prop === "limit" || prop === "innerJoin") {
+          return () => chain;
+        }
+        if (prop === "from") {
+          return (table: unknown) => {
+            const tableName = (table as { _name?: string })._name;
+            const rows = tableName === "businessSettings" ? [BUSINESS_SETTINGS] : selectRows;
+            return makeChainable(rows);
+          };
+        }
+        // @ts-expect-error proxy
+        return target[prop];
+      },
+    });
+    return chain;
+  }
+
+  const conversations = new Proxy(
+    { _name: "conversations" },
+    { get: (t, p) => (p === "_name" ? "conversations" : { table: "conversations", column: p }) }
+  );
+
+  const messages = new Proxy(
+    { _name: "messages" },
+    { get: (t, p) => (p === "_name" ? "messages" : { table: "messages", column: p }) }
+  );
+
+  const clients = new Proxy(
+    { _name: "clients" },
+    { get: (t, p) => (p === "_name" ? "clients" : { table: "clients", column: p }) }
+  );
+
+  const businessSettings = new Proxy(
+    { _name: "businessSettings" },
+    { get: (t, p) => (p === "_name" ? "businessSettings" : { table: "businessSettings", column: p }) }
+  );
+
+  return {
+    getDb: () => ({
+      select: () => ({
+        from: (table: unknown) => {
+          const tableName = (table as { _name?: string })._name;
+          if (tableName === "businessSettings") return makeChainable([BUSINESS_SETTINGS]);
+          if (tableName === "messages") {
+            // Return selectRows3 if it has data (POST re-query), else cycle through selectRows/selectRows2
+            if (selectRows3.length > 0) {
+              return makeChainable(selectRows3);
+            }
+            if (selectCallCount === 0 || selectCallCount === 1) {
+              const rows = selectCallCount === 0 ? selectRows : selectRows2;
+              selectCallCount++;
+              return makeChainable(rows);
+            }
+            return makeChainable(selectRows);
+          }
+          return makeChainable(selectRows);
+        },
+      }),
+      update: () => ({
+        set: (vals: Record<string, unknown>) => ({
+          where: () => {
+            updatedValues.push(vals);
+            return { returning: () => [vals] };
+          },
+        }),
+      }),
+      insert: () => ({
+        values: (vals: Record<string, unknown>) => {
+          return { returning: () => [{ ...vals, id: "msg-uuid-new" }] };
+        },
+      }),
+    }),
+    conversations,
+    messages,
+    clients,
+    businessSettings,
+    eq: vi.fn((a, b) => ({ type: "eq", a, b })),
+    and: vi.fn((...args) => ({ type: "and", args })),
+    desc: vi.fn((col) => ({ type: "desc", col })),
+    lt: vi.fn((a, b) => ({ type: "lt", a, b })),
+    sql: vi.fn(() => ({ __type: "sql" })),
+    isNull: vi.fn((col) => ({ type: "isNull", col })),
+    count: vi.fn((col) => ({ type: "count", col })),
+  };
+});
+
+vi.mock("../services/messaging/outbound.js", () => ({
+  sendMessage: mockSendMessage,
+}));
+
+// ─── App setup ────────────────────────────────────────────────────────────────
+
+const { conversationsRouter } = await import("../routes/conversations.js");
+
+const app = new Hono();
+app.use("*", async (c, next) => {
+  // @ts-expect-error — test-only context injection
+  c.set("staff", STAFF_ROW);
+  await next();
+});
+app.route("/conversations", conversationsRouter);
+
+function jsonRequest(method: string, path: string, body?: unknown) {
+  return app.request(path, {
+    method,
+    headers: { "Content-Type": "application/json" },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+}
+
+beforeEach(() => resetAll());
+
+// ─── GET /conversations ───────────────────────────────────────────────────────
+
+describe("GET /api/conversations", () => {
+  it("returns conversations sorted by recency with unread count", async () => {
+    selectRows = [
+      { ...CONV_1, clientName: "Alice", clientPhone: "+15551111111", channel: "sms" },
+    ];
+    selectRows2 = [{ count: "1" }];
+    const res = await app.request("/conversations");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.items).toHaveLength(1);
+    expect(body.items[0]!.id).toBe("conv-uuid-1");
+    expect(body.items[0]!.clientName).toBe("Alice");
+  });
+
+  it("supports cursor-based pagination", async () => {
+    selectRows = [];
+    const res = await app.request("/conversations?cursor=conv-uuid-1&limit=1");
+    expect(res.status).toBe(200);
+  });
+
+  it("enforces max limit of 50", async () => {
+    selectRows = [];
+    const res = await app.request("/conversations?limit=200");
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── GET /conversations/:id/messages ─────────────────────────────────────────
+
+describe("GET /api/conversations/:id/messages", () => {
+  it("returns paginated messages and marks conversation as read", async () => {
+    selectRows = [{ ...MSG_INBOUND_1 }, { ...MSG_OUTBOUND_1 }];
+    const res = await app.request("/conversations/conv-uuid-1/messages");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.items).toHaveLength(2);
+    expect(body.items[0]!.id).toBe("msg-uuid-1");
+    expect(updatedValues.some((u) => u.staffReadAt !== undefined)).toBe(true);
+  });
+
+  it("returns 404 when conversation belongs to different business", async () => {
+    selectRows = [];
+    const res = await app.request("/conversations/conv-uuid-other/messages");
+    expect(res.status).toBe(404);
+  });
+
+  it("returns 401 when not authenticated", async () => {
+    const appNoAuth = new Hono();
+    appNoAuth.route("/conversations", conversationsRouter);
+    const res = await appNoAuth.request("/conversations/conv-uuid-1/messages");
+    expect(res.status).toBe(401);
+  });
+});
+
+// ─── POST /conversations/:id/messages ─────────────────────────────────────────
+
+describe("POST /api/conversations/:id/messages", () => {
+  beforeEach(() => {
+    resetMock();
+    vi.clearAllMocks();
+    selectRows = [{ ...CONV_1, clientName: "Alice", clientPhone: "+15551111111", channel: "sms" }];
+    selectRows2 = [];
+    selectRows3 = [{ id: "msg-uuid-new", conversationId: "conv-uuid-1", direction: "outbound" as const, body: "Hello Alice!", status: "queued" as const, sentByStaffId: "staff-uuid-1", createdAt: new Date(), deliveredAt: null }];
+    updatedValues = [];
+  });
+
+  it("sends via outbound service and returns 201", async () => {
+    mockSendMessage.mockResolvedValueOnce({
+      messageId: "msg-uuid-new",
+      providerMessageId: "provider-msg-1",
+      status: "queued",
+      suppressed: false,
+    });
+
+    const res = await jsonRequest("POST", "/conversations/conv-uuid-1/messages", {
+      body: "Hello Alice!",
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.id).toBe("msg-uuid-new");
+  });
+
+  it("returns 409 when client opted out", async () => {
+    mockSendMessage.mockResolvedValueOnce({ suppressed: true });
+
+    const res = await jsonRequest("POST", "/conversations/conv-uuid-1/messages", {
+      body: "Hello",
+    });
+    expect(res.status).toBe(409);
+    const body = await res.json();
+    expect(body.error).toMatch(/opted out/i);
+  });
+
+  it("returns 404 for cross-tenant conversation", async () => {
+    selectRows = [];
+    const res = await jsonRequest("POST", "/conversations/conv-uuid-other/messages", {
+      body: "Hello",
+    });
+    expect(res.status).toBe(404);
+  });
+
+  it("rejects empty body", async () => {
+    const res = await jsonRequest("POST", "/conversations/conv-uuid-1/messages", {
+      body: "",
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("rejects body over 1600 chars", async () => {
+    const res = await jsonRequest("POST", "/conversations/conv-uuid-1/messages", {
+      body: "a".repeat(1601),
+    });
+    expect(res.status).toBe(400);
+  });
+});

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

@@ -40,11 +40,17 @@ const APPOINTMENT = {
 let selectSessionRow: Record<string, unknown> | null = null;
 let selectAppointmentRow: Record<string, unknown> | null = null;
 let updatedValues: Record<string, unknown>[] = [];
+let selectBusinessSettingsRow: Record<string, unknown> | null = null;
+let selectConversationRow: Record<string, unknown> | null = null;
+let selectMessageRows: Record<string, unknown>[] = [];
 
 function resetMock() {
   selectSessionRow = null;
   selectAppointmentRow = null;
   updatedValues = [];
+  selectBusinessSettingsRow = null;
+  selectConversationRow = null;
+  selectMessageRows = [];
 }
 
 vi.mock("@groombook/db", () => {
@@ -72,6 +78,26 @@ vi.mock("@groombook/db", () => {
     { get: (t, p) => (p === "_name" ? "appointments" : { table: "appointments", column: p }) }
   );
 
+const businessSettings = new Proxy(
+    { _name: "businessSettings" },
+    { get: (t, p) => (p === "_name" ? "businessSettings" : { table: "businessSettings", column: p }) }
+  );
+
+  const conversations = new Proxy(
+    { _name: "conversations" },
+    { get: (t, p) => (p === "_name" ? "conversations" : { table: "conversations", column: p }) }
+  );
+
+  const messages = new Proxy(
+    { _name: "messages" },
+    { get: (t, p) => (p === "_name" ? "messages" : { table: "messages", column: p }) }
+  );
+
+  const impersonationAuditLogs = new Proxy(
+    { _name: "impersonationAuditLogs" },
+    { get: (t, p) => (p === "_name" ? "impersonationAuditLogs" : { table: "impersonationAuditLogs", column: p }) }
+  );
+
   return {
     getDb: () => ({
       select: () => ({
@@ -82,6 +108,15 @@ vi.mock("@groombook/db", () => {
           if (table._name === "appointments") {
             return makeChainable(selectAppointmentRow ? [selectAppointmentRow] : []);
           }
+          if (table._name === "businessSettings") {
+            return makeChainable(selectBusinessSettingsRow ? [selectBusinessSettingsRow] : []);
+          }
+          if (table._name === "conversations") {
+            return makeChainable(selectConversationRow ? [selectConversationRow] : []);
+          }
+          if (table._name === "messages") {
+            return makeChainable(selectMessageRows);
+          }
           return makeChainable([]);
         },
       }),
@@ -99,11 +134,21 @@ vi.mock("@groombook/db", () => {
           }),
         }),
       }),
+      insert: () => ({
+        values: () => ({
+          returning: () => [],
+        }),
+      }),
     }),
     impersonationSessions,
     appointments,
+    impersonationAuditLogs,
+    businessSettings,
+    conversations,
+    messages,
     eq: vi.fn(),
     and: vi.fn(),
+    desc: vi.fn((col: unknown) => ({ _name: "desc", col })),
   };
 });
 
@@ -420,4 +465,117 @@ describe("POST /portal/appointments/:id/cancel", () => {
     );
     expect(res.status).toBe(404);
   });
+});
+
+// ─── Conversation routes ───────────────────────────────────────────────────────
+
+const BUSINESS_ID = "880e8400-e29b-41d4-a716-446655440008";
+const CONVERSATION_ID = "990e8400-e29b-41d4-a716-446655440009";
+
+const CONVERSATION = {
+  id: CONVERSATION_ID,
+  clientId: CLIENT_ID,
+  businessId: BUSINESS_ID,
+  channel: "sms",
+  status: "active",
+  lastMessageAt: new Date().toISOString(),
+  createdAt: new Date().toISOString(),
+};
+
+const MESSAGE_1 = {
+  id: "m1",
+  conversationId: CONVERSATION_ID,
+  direction: "inbound",
+  body: "Hello",
+  status: "delivered",
+  createdAt: new Date().toISOString(),
+  deliveredAt: new Date().toISOString(),
+};
+
+const MESSAGE_2 = {
+  id: "m2",
+  conversationId: CONVERSATION_ID,
+  direction: "outbound",
+  body: "Hi there!",
+  status: "delivered",
+  createdAt: new Date(Date.now() + 1000).toISOString(),
+  deliveredAt: new Date().toISOString(),
+};
+
+function jsonGet(path: string, headers?: Record<string, string>) {
+  return app.request(path, { method: "GET", headers });
+}
+
+describe("GET /portal/conversation", () => {
+  it("returns 204 when no conversation exists", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectBusinessSettingsRow = { id: BUSINESS_ID };
+    selectConversationRow = null;
+    const res = await jsonGet("/portal/conversation", { "X-Impersonation-Session-Id": SESSION_ID });
+    expect(res.status).toBe(204);
+  });
+
+  it("returns conversation for the authenticated client", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectBusinessSettingsRow = { id: BUSINESS_ID };
+    selectConversationRow = { ...CONVERSATION };
+    const res = await jsonGet("/portal/conversation", { "X-Impersonation-Session-Id": SESSION_ID });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.id).toBe(CONVERSATION_ID);
+    expect(body.channel).toBe("sms");
+    expect(body.status).toBe("active");
+  });
+
+  it("returns 204 when client A's session has no conversation (cross-tenant isolation)", async () => {
+    // Cross-tenant isolation is enforced at the query level via portalClientId scoping.
+    // The mock cannot replicate eq() filtering — this test verifies the query is issued
+    // and no conversation is returned when the mock has no row for the session's clientId.
+    // Real DB: eq() on clientId ensures client A never sees client B's conversation.
+    selectSessionRow = { ...ACTIVE_SESSION, clientId: "client-a" };
+    selectBusinessSettingsRow = { id: BUSINESS_ID };
+    selectConversationRow = null; // client-a has no conversation
+    const res = await jsonGet("/portal/conversation", { "X-Impersonation-Session-Id": SESSION_ID });
+    expect(res.status).toBe(204);
+  });
+});
+
+describe("GET /portal/conversation/messages", () => {
+  it("returns 204 when no conversation exists", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectBusinessSettingsRow = { id: BUSINESS_ID };
+    selectConversationRow = null;
+    const res = await jsonGet("/portal/conversation/messages", { "X-Impersonation-Session-Id": SESSION_ID });
+    expect(res.status).toBe(204);
+  });
+
+  it("returns paginated messages", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectBusinessSettingsRow = { id: BUSINESS_ID };
+    selectConversationRow = { ...CONVERSATION };
+    selectMessageRows = [MESSAGE_2, MESSAGE_1];
+    const res = await jsonGet("/portal/conversation/messages", { "X-Impersonation-Session-Id": SESSION_ID });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.messages).toHaveLength(2);
+    expect(body.messages[0].id).toBe("m2");
+    expect(body.messages[1].id).toBe("m1");
+    expect(body.nextCursor).toBeNull();
+  });
+
+  it("returns messages and nextCursor reflects if more exist", async () => {
+    // Note: the mock does not enforce limit(), so it returns all messages.
+    // nextCursor is null when all messages fit (mock behavior).
+    // Real DB enforces limit and sets nextCursor when messages.length === limit.
+    selectSessionRow = ACTIVE_SESSION;
+    selectBusinessSettingsRow = { id: BUSINESS_ID };
+    selectConversationRow = { ...CONVERSATION };
+    selectMessageRows = [MESSAGE_1, MESSAGE_2];
+    const res = await jsonGet("/portal/conversation/messages?limit=1", { "X-Impersonation-Session-Id": SESSION_ID });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.messages.length).toBeGreaterThan(0);
+    // mock has no limit enforcement, so nextCursor may be null
+    expect(body).toHaveProperty("nextCursor");
+  });
 });

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

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

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

@@ -418,6 +418,48 @@ describe("GET /setup/status — OOBE bootstrap logic", () => {
     expect(body.showAuthProviderStep).toBe(false); // DB config already exists
     expect(body.authConfigExists).toBe(true);
   });
+
+  it("SKIP_OOBE=true bypasses setup check regardless of DB state", async () => {
+    dbStaffRows = []; // no super user
+    dbAuthConfigRows = [];
+    process.env.SKIP_OOBE = "true";
+
+    const app = makeApp();
+    const { status, body } = await getStatus(app);
+
+    expect(status).toBe(200);
+    expect(body.needsSetup).toBe(false);
+    expect(body.showAuthProviderStep).toBe(false);
+    expect(body.authConfigExists).toBe(false);
+    expect(body.authEnvVarsSet).toBe(false);
+    expect(body.skipped).toBe(true);
+  });
+
+  it("SKIP_OOBE=1 also bypasses setup check", async () => {
+    dbStaffRows = [];
+    dbAuthConfigRows = [];
+    process.env.SKIP_OOBE = "1";
+
+    const app = makeApp();
+    const { status, body } = await getStatus(app);
+
+    expect(status).toBe(200);
+    expect(body.needsSetup).toBe(false);
+    expect(body.skipped).toBe(true);
+  });
+
+  it("SKIP_OOBE=yes also bypasses setup check", async () => {
+    dbStaffRows = [];
+    dbAuthConfigRows = [];
+    process.env.SKIP_OOBE = "yes";
+
+    const app = makeApp();
+    const { status, body } = await getStatus(app);
+
+    expect(status).toBe(200);
+    expect(body.needsSetup).toBe(false);
+    expect(body.skipped).toBe(true);
+  });
 });
 
 describe("POST /setup/auth-provider — OOBE bootstrap", () => {

apps/api/src/index.ts

@@ -8,6 +8,7 @@ import { petsRouter } from "./routes/pets.js";
 import { servicesRouter } from "./routes/services.js";
 import { appointmentsRouter } from "./routes/appointments.js";
 import { waitlistRouter } from "./routes/waitlist.js";
+import { conversationsRouter } from "./routes/conversations.js";
 import { portalRouter } from "./routes/portal.js";
 import { staffRouter } from "./routes/staff.js";
 import { invoicesRouter } from "./routes/invoices.js";
@@ -19,7 +20,7 @@ import { impersonationRouter } from "./routes/impersonation.js";
 import { settingsRouter } from "./routes/settings.js";
 import { authProviderRouter } from "./routes/authProvider.js";
 import { searchRouter } from "./routes/search.js";
-import { getPresignedGetUrl } from "./lib/s3.js";
+import { getObject } from "./lib/s3.js";
 import { calendarRouter } from "./routes/calendar.js";
 import { setupRouter } from "./routes/setup.js";
 import { getDb, businessSettings, eq, staff } from "@groombook/db";
@@ -28,15 +29,32 @@ import { resolveStaffMiddleware, requireRole, requireRoleOrSuperUser, requireSup
 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();
 
 // Global middleware
+const TRUSTED_ORIGINS = (process.env.CORS_ORIGIN ?? "http://localhost:5173")
+  .split(",")
+  .map((o) => o.trim());
+
+const ALLOWED_ORIGIN = process.env.CORS_ORIGIN ?? "http://localhost:5173";
+
 app.use("*", logger());
 app.use(
   "/api/*",
   cors({
-    origin: process.env.CORS_ORIGIN ?? "http://localhost:5173",
+    origin: (origin, ctx) => {
+      if (!origin) {
+        return ALLOWED_ORIGIN;
+      }
+      if (TRUSTED_ORIGINS.includes(origin)) {
+        return origin;
+      }
+      ctx.status(403);
+      return null;
+    },
     credentials: true,
   })
 );
@@ -50,31 +68,108 @@ app.route("/api/book", bookRouter);
 // Public portal routes — client-facing, authenticated via impersonation session header
 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);
 
+// Magic bytes for allowed image types
+const ALLOWED_IMAGE_TYPES: Record<string, Uint8Array> = {
+  "image/png": new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+  "image/jpeg": new Uint8Array([0xff, 0xd8, 0xff]),
+  "image/gif": new Uint8Array([0x47, 0x49, 0x46, 0x38]),
+  "image/webp": new Uint8Array([0x52, 0x49, 0x46, 0x46]), // followed by size then WEBP
+};
+
+/**
+ * Validates that the given base64 content matches the declared MIME type
+ * by checking magic bytes. Returns null if valid, or the field to clear if not.
+ */
+function validateLogoMagicBytes(
+  logoBase64: string | null,
+  logoMimeType: string | null
+): "logoBase64" | "logoMimeType" | null {
+  if (!logoBase64 || !logoMimeType) return null;
+
+  const expectedMagic = ALLOWED_IMAGE_TYPES[logoMimeType];
+  if (!expectedMagic) return "logoMimeType"; // unknown MIME type — reject
+
+  try {
+    const binary = Buffer.from(logoBase64, "base64");
+    // WebP needs a special check (RIFF....WEBP at offset 0, size at offset 4)
+    if (logoMimeType === "image/webp") {
+      if (binary.length < 12) return "logoBase64";
+      const webpMagic = binary.slice(0, 4);
+      const webpSig = binary.slice(8, 12);
+      if (
+        webpMagic[0] !== 0x52 ||
+        webpMagic[1] !== 0x49 ||
+        webpMagic[2] !== 0x46 ||
+        webpMagic[3] !== 0x46 ||
+        webpSig[0] !== 0x57 ||
+        webpSig[1] !== 0x45 ||
+        webpSig[2] !== 0x42 ||
+        webpSig[3] !== 0x50
+      ) {
+        return "logoBase64";
+      }
+      return null;
+    }
+
+    // All other types: check prefix
+    if (binary.length < expectedMagic.length) return "logoBase64";
+    for (let i = 0; i < expectedMagic.length; i++) {
+      if (binary[i] !== expectedMagic[i]) return "logoBase64";
+    }
+    return null;
+  } catch {
+    return "logoBase64";
+  }
+}
+
+// Public logo proxy — no auth required, streams logo from S3 so browser never sees raw S3 URL
+app.get("/api/branding/logo", async (c) => {
+  const db = getDb();
+  const [row] = await db.select().from(businessSettings).limit(1);
+  if (!row) return c.json({ error: "Settings not found" }, 404);
+  if (!row.logoKey) return c.json({ error: "No logo on file" }, 404);
+
+  const { body, contentType } = await getObject(row.logoKey);
+  return new Response(Buffer.from(body), {
+    status: 200,
+    headers: {
+      "Content-Type": contentType,
+      "Cache-Control": "public, max-age=86400",
+    },
+  });
+});
+
 // Public branding endpoint — no auth required, returns business name/colors/logo
 app.get("/api/branding", async (c) => {
   const db = getDb();
   const [row] = await db.select().from(businessSettings).limit(1);
   const settings = row ?? { businessName: "GroomBook", primaryColor: "#4f8a6f", accentColor: "#8b7355", logoBase64: null, logoMimeType: null, logoKey: null };
 
-  let logoUrl: string | null = null;
-  if (settings.logoKey) {
-    try {
-      logoUrl = await getPresignedGetUrl(settings.logoKey);
-    } catch {
-      // If S3 URL generation fails, fall back to legacy base64
-    }
-  }
+  // Return the public proxy path so browser never sees a raw S3 URL
+  const logoUrl = settings.logoKey ? "/api/branding/logo" : null;
+
+  // Defensive: validate magic bytes to prevent MIME type confusion attacks
+  // via the legacy base64 logo fields
+  const badField = validateLogoMagicBytes(settings.logoBase64 ?? null, settings.logoMimeType ?? null);
+  const safeLogoBase64 = badField === "logoBase64" ? null : settings.logoBase64;
+  const safeLogoMimeType = badField === "logoMimeType" ? null : settings.logoMimeType;
 
   return c.json({
     businessName: settings.businessName,
     primaryColor: settings.primaryColor,
     accentColor: settings.accentColor,
     logoUrl,
-    logoBase64: settings.logoBase64,
-    logoMimeType: settings.logoMimeType,
+    logoBase64: safeLogoBase64,
+    logoMimeType: safeLogoMimeType,
   });
 });
 
@@ -105,7 +200,13 @@ api.use("*", resolveStaffMiddleware);
 // Better-Auth handler — mounted as sub-app to handle all /api/auth/* routes
 // authMiddleware and resolveStaffMiddleware both skip /api/auth/ paths
 const authRouter = new Hono();
-authRouter.all("/*", (c) => getAuth().handler(c.req.raw));
+authRouter.all("/*", (c) => {
+  try {
+    return getAuth().handler(c.req.raw);
+  } catch {
+    return c.json({ error: "Authentication not configured" }, 503);
+  }
+});
 api.route("/auth", authRouter);
 
 // ── Role guards ────────────────────────────────────────────────────────────────
@@ -117,7 +218,7 @@ api.on(["POST", "PATCH", "DELETE"], "/staff/*", requireRoleOrSuperUser("manager"
 api.use("/admin/*", requireRoleOrSuperUser("manager"));
 api.use("/admin/settings/*", requireSuperUser());
 api.use("/reports/*", requireRole("manager"));
-api.use("/invoices/*", requireRole("manager"));
+api.use("/invoices/*", requireRole("manager", "groomer"));
 api.use("/impersonation/*", requireRole("manager"));
 
 // Manager + Receptionist only (groomers have no access): appointment-groups, grooming-logs, waitlist
@@ -163,6 +264,7 @@ api.route("/pets", petsRouter);
 api.route("/services", servicesRouter);
 api.route("/appointments", appointmentsRouter);
 api.route("/waitlist", waitlistRouter);
+api.route("/conversations", conversationsRouter);
 api.route("/staff", staffRouter);
 api.route("/invoices", invoicesRouter);
 api.route("/reports", reportsRouter);
@@ -173,13 +275,29 @@ api.route("/admin/settings", settingsRouter);
 api.route("/admin/auth-provider", authProviderRouter);
 api.route("/admin/seed", adminSeedRouter);
 api.route("/search", searchRouter);
+api.route("/conversations", conversationsRouter);
 
 const port = Number(process.env.PORT ?? 3000);
 await initAuth();
 console.log(`API server listening on port ${port}`);
-serve({ fetch: app.fetch, port });
+const server = serve({ fetch: app.fetch, port });
 
 // Start background reminder scheduler (runs every minute to check for upcoming appointments)
 startReminderScheduler();
 
+function shutdown() {
+  console.log("Shutting down gracefully...");
+  server.close(() => {
+    console.log("HTTP server closed");
+    process.exit(0);
+  });
+  setTimeout(() => {
+    console.error("Forced shutdown after timeout");
+    process.exit(1);
+  }, 10_000);
+}
+
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+
 export default app;

apps/api/src/lib/auth.ts

@@ -1,9 +1,9 @@
 import { betterAuth } from "better-auth";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { genericOAuth } from "better-auth/plugins";
-import { google, github } from "better-auth/social-providers";
 import { getDb, authProviderConfig, eq } from "@groombook/db";
 import { decryptSecret } from "@groombook/db";
+import { sendEmail } from "../services/email.js";
 
 const BETTER_AUTH_SECRET = process.env.BETTER_AUTH_SECRET;
 const BETTER_AUTH_URL = process.env.BETTER_AUTH_URL ?? "http://localhost:3000";
@@ -89,8 +89,20 @@ export async function initAuth(): Promise<void> {
       console.warn("[auth] AUTH_DISABLED=true — building placeholder auth instance");
       authInstance = betterAuth({
         database: drizzleAdapter(getDb(), { provider: "pg" }),
-        secret: BETTER_AUTH_SECRET ?? "placeholder-secret-do-not-use-in-prod",
+        secret: BETTER_AUTH_SECRET!,
         baseURL: BETTER_AUTH_URL,
+        rateLimit: {
+          enabled: true,
+          max: 100,
+          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,
+          },
+        },
         plugins: [
           genericOAuth({
             config: [
@@ -171,18 +183,58 @@ export async function initAuth(): Promise<void> {
     const hasGoogle = !!(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET);
     const hasGitHub = !!(process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET);
 
-    const socialPlugins = [];
-    if (hasGoogle) {
-      socialPlugins.push(google({
-        clientId: process.env.GOOGLE_CLIENT_ID!,
-        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-      }));
-    }
-    if (hasGitHub) {
-      socialPlugins.push(github({
-        clientId: process.env.GITHUB_CLIENT_ID!,
-        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-      }));
+    const issuerUrlObj = new URL(providerConfig.issuerUrl);
+    const issuerHostname = issuerUrlObj.hostname;
+
+    const discoveryUrlStr = `${providerConfig.issuerUrl}/.well-known/openid-configuration`;
+    let oidcConfig: Record<string, string> = {};
+    try {
+      const discoveryRes = await fetch(discoveryUrlStr);
+      if (discoveryRes.ok) {
+        const discovery = await discoveryRes.json() as {
+          authorization_endpoint?: string;
+          token_endpoint?: string;
+          userinfo_endpoint?: string;
+        };
+        const replaceHost = (url: string, newHost: string) => {
+          try {
+            const parsed = new URL(url);
+            const newParsed = new URL(newHost);
+            return `${newParsed.origin}${parsed.pathname}${parsed.search}`;
+          } catch {
+            return url;
+          }
+        };
+        const authzUrl = discovery.authorization_endpoint;
+        const tokenUrl = discovery.token_endpoint;
+        const userInfoUrl = discovery.userinfo_endpoint;
+        if (authzUrl && tokenUrl && userInfoUrl) {
+          const authzUrlObj = new URL(authzUrl);
+          // Only validate authorizationUrl hostname against issuer — token/userinfo
+          // may legitimately use internal hostnames (OIDC_INTERNAL_BASE) for server-to-server calls.
+          if (authzUrlObj.hostname !== issuerHostname) {
+            throw new Error(
+              `[FATAL] OIDC discovery URL hostname mismatch: expected '${issuerHostname}' but got '${authzUrlObj.hostname}'. This may indicate a man-in-the-middle attack.`
+            );
+          }
+          oidcConfig = {
+            authorizationUrl: authzUrl,
+            tokenUrl: providerConfig.internalBaseUrl
+              ? replaceHost(tokenUrl, providerConfig.internalBaseUrl)
+              : tokenUrl,
+            userInfoUrl: providerConfig.internalBaseUrl
+              ? replaceHost(userInfoUrl, providerConfig.internalBaseUrl)
+              : userInfoUrl,
+          };
+          console.log("[auth] OIDC discovery successful, provider:", providerConfig.providerId);
+        } else {
+          console.warn("[auth] OIDC discovery missing required endpoints, using discoveryUrl only");
+        }
+      } else {
+        console.warn(`[auth] OIDC discovery failed (${discoveryRes.status}), using discoveryUrl only`);
+      }
+    } catch (err) {
+      console.warn(`[auth] OIDC discovery fetch failed: ${err}, using discoveryUrl only`);
     }
 
     // Build Better-Auth instance using resolved config
@@ -192,6 +244,34 @@ export async function initAuth(): Promise<void> {
       }),
       secret: BETTER_AUTH_SECRET,
       baseURL: BETTER_AUTH_URL,
+      rateLimit: {
+        enabled: true,
+        max: 100,
+        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,
+        },
+      },
+      account: {
+        storeStateStrategy: "cookie" as const,
+      },
+      emailAndPassword: {
+        enabled: true,
+        emailVerification: {
+          sendVerificationEmail: async ({ user, url }: { user: { email: string }; url: string }) => {
+            await sendEmail({
+              to: user.email,
+              subject: "Verify your GroomBook email",
+              text: `Click the link to verify your email: ${url}`,
+              html: `<p>Click the link to verify your email:</p><a href="${url}">${url}</a>`,
+            });
+          },
+        },
+      },
       plugins: [
         genericOAuth({
           config: [
@@ -199,21 +279,27 @@ export async function initAuth(): Promise<void> {
               providerId: providerConfig.providerId,
               clientId: providerConfig.clientId,
               clientSecret: providerConfig.clientSecret,
-              ...(providerConfig.internalBaseUrl
-                ? {
-                    authorizationUrl: `${new URL(providerConfig.issuerUrl).origin}/application/o/authorize/`,
-                    tokenUrl: `${providerConfig.internalBaseUrl}/application/o/token/`,
-                    userInfoUrl: `${providerConfig.internalBaseUrl}/application/o/userinfo/`,
-                  }
-                : {
-                    discoveryUrl: `${providerConfig.issuerUrl}/.well-known/openid-configuration`,
-                  }),
+              discoveryUrl: discoveryUrlStr,
+              ...(Object.keys(oidcConfig).length > 0 ? oidcConfig : {}),
               scopes: providerConfig.scopes.split(" ").filter(Boolean),
             },
           ],
         }),
-        ...socialPlugins,
       ],
+      socialProviders: {
+        ...(hasGoogle ? {
+          google: {
+            clientId: process.env.GOOGLE_CLIENT_ID!,
+            clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+          },
+        } : {}),
+        ...(hasGitHub ? {
+          github: {
+            clientId: process.env.GITHUB_CLIENT_ID!,
+            clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+          },
+        } : {}),
+      },
       session: {
         expiresIn: 60 * 60 * 24 * 7, // 7 days
         updateAge: 60 * 60 * 24, // 1 day

apps/api/src/lib/buffer.ts

@@ -0,0 +1,66 @@
+import { eq } from "@groombook/db";
+import { bufferTimeRules, services, type Db } from "@groombook/db";
+
+export async function resolveBufferMinutes({
+  serviceId,
+  sizeCategory,
+  coatType,
+  db,
+}: {
+  serviceId: string;
+  sizeCategory: string | null;
+  coatType: string | null;
+  db: Db;
+}): Promise<number> {
+  // Query all rules for this service in one DB call
+  const allRules = await db
+    .select()
+    .from(bufferTimeRules)
+    .where(eq(bufferTimeRules.serviceId, serviceId));
+
+  // Priority 1: exact match (serviceId + sizeCategory + coatType all match)
+  const exact = allRules.find(
+    (r) =>
+      r.sizeCategory === sizeCategory &&
+      r.coatType === coatType
+  );
+  if (exact) return exact.bufferMinutes;
+
+  // Priority 2: service + size, null coatType
+  const serviceSize = allRules.find(
+    (r) =>
+      r.sizeCategory === sizeCategory &&
+      r.coatType === null
+  );
+  if (serviceSize) return serviceSize.bufferMinutes;
+
+  // Priority 3: service + coat, null sizeCategory
+  const serviceCoat = allRules.find(
+    (r) =>
+      r.sizeCategory === null &&
+      r.coatType === coatType
+  );
+  if (serviceCoat) return serviceCoat.bufferMinutes;
+
+  // Priority 4: service only (null sizeCategory, null coatType)
+  const serviceOnly = allRules.find(
+    (r) =>
+      r.sizeCategory === null &&
+      r.coatType === null
+  );
+  if (serviceOnly) return serviceOnly.bufferMinutes;
+
+  // Priority 5: fallback to service.defaultBufferMinutes
+  const [service] = await db
+    .select({ defaultBufferMinutes: services.defaultBufferMinutes })
+    .from(services)
+    .where(eq(services.id, serviceId))
+    .limit(1);
+
+  if (service?.defaultBufferMinutes != null) {
+    return service.defaultBufferMinutes;
+  }
+
+  // Priority 6: final fallback to 0
+  return 0;
+}

apps/api/src/lib/cascade.ts

@@ -0,0 +1,281 @@
+import { eq, and, gt, or, asc } from "@groombook/db";
+import { appointments, clients, pets, services, staff, type Db } from "@groombook/db";
+import { resolveBufferMinutes } from "./buffer.js";
+import { sendEmail, buildRescheduleNotificationEmail } from "../services/email.js";
+
+export interface CascadeResult {
+  shifted: ShiftedAppointment[];
+  flaggedForReview: FlaggedAppointment[];
+}
+
+export interface ShiftedAppointment {
+  id: string;
+  oldStartTime: Date;
+  oldEndTime: Date;
+  newStartTime: Date;
+  newEndTime: Date;
+  shiftDeltaMs: number;
+}
+
+export interface FlaggedAppointment {
+  id: string;
+  reason: string;
+  requestedStartTime: Date;
+  requestedEndTime: Date;
+}
+
+interface AppointmentWithGroomer {
+  id: string;
+  clientId: string;
+  petId: string;
+  serviceId: string;
+  staffId: string | null;
+  batherStaffId: string | null;
+  status: string;
+  startTime: Date;
+  endTime: Date;
+  bufferMinutes: number;
+}
+
+/**
+ * Detects and cascades appointment overruns to downstream same-groomer appointments.
+ *
+ * Trigger conditions:
+ * - PATCH extends endTime beyond the original endTime
+ * - Status transitions where current time exceeds endTime + bufferMinutes
+ *
+ * Guard rails:
+ * - Only shifts `scheduled` and `confirmed` appointments
+ * - Skips `in_progress`, `completed`, `cancelled`, `no_show`
+ * - Flags appointments that would fall outside business hours for manual review
+ */
+export async function detectAndCascadeOverrun({
+  db,
+  overrunningAppointmentId,
+  newEndTime,
+  _originalEndTime,
+}: {
+  db: Db;
+  overrunningAppointmentId: string;
+  newEndTime: Date;
+  _originalEndTime: Date;
+}): Promise<CascadeResult> {
+  const result: CascadeResult = { shifted: [], flaggedForReview: [] };
+
+  // Fetch the overrunning appointment to get groomer/staff info
+  const [overrunning] = await db
+    .select()
+    .from(appointments)
+    .where(eq(appointments.id, overrunningAppointmentId))
+    .limit(1);
+
+  if (!overrunning) return result;
+
+  const groomerId = overrunning.staffId;
+  if (!groomerId) return result;
+
+  // Determine the effective buffer for the overrunning appointment
+  const bufferMinutes = await resolveBufferMinutesForAppointment(db, overrunning);
+  const overrunEnd = newEndTime;
+  const effectiveEnd = new Date(overrunEnd.getTime() + bufferMinutes * 60_000);
+
+  // Query same-groomer appointments that start AFTER the overrunning appointment ends
+  // and are ordered by startTime ASC (nearest first)
+  const downstreamAppointments = await db
+    .select()
+    .from(appointments)
+    .where(
+      and(
+        eq(appointments.staffId, groomerId),
+        gt(appointments.startTime, overrunning.endTime),
+        or(
+          eq(appointments.status, "scheduled"),
+          eq(appointments.status, "confirmed")
+        )
+      )
+    )
+    .orderBy(asc(appointments.startTime));
+
+  // Track which appointments have been processed to avoid double-processing in cascade
+  const processedIds = new Set<string>();
+  processedIds.add(overrunningAppointmentId);
+
+  let currentOverrunEnd = effectiveEnd;
+
+  for (const downstream of downstreamAppointments) {
+    if (processedIds.has(downstream.id)) continue;
+
+    const downstreamBuffer = await resolveBufferMinutesForAppointment(db, downstream);
+
+    // Check if this downstream appointment conflicts with the current overrun end
+    const conflictThreshold = new Date(
+      currentOverrunEnd.getTime() + downstreamBuffer * 60_000
+    );
+
+    if (conflictThreshold <= downstream.startTime) {
+      // No conflict — cascade is complete
+      break;
+    }
+
+    // Conflict detected — need to shift this appointment
+    const shiftDeltaMs = conflictThreshold.getTime() - downstream.startTime.getTime();
+    const newStartTime = new Date(downstream.startTime.getTime() + shiftDeltaMs);
+    const newEndTime = new Date(downstream.endTime.getTime() + shiftDeltaMs);
+
+    // Check business hours (simple: only shift within same calendar day window for now)
+    // A more sophisticated implementation would check actual business hours from businessSettings
+    const isSameDay =
+      newStartTime.toDateString() === downstream.startTime.toDateString();
+
+    if (!isSameDay) {
+      result.flaggedForReview.push({
+        id: downstream.id,
+        reason: `Shifted appointment would fall on a different day (${newStartTime.toDateString()})`,
+        requestedStartTime: newStartTime,
+        requestedEndTime: newEndTime,
+      });
+      // Continue cascade check — we still process downstream appointments
+      currentOverrunEnd = newEndTime;
+      processedIds.add(downstream.id);
+      continue;
+    }
+
+    // Apply the shift
+    await db
+      .update(appointments)
+      .set({
+        startTime: newStartTime,
+        endTime: newEndTime,
+        updatedAt: new Date(),
+      })
+      .where(eq(appointments.id, downstream.id));
+
+    result.shifted.push({
+      id: downstream.id,
+      oldStartTime: downstream.startTime,
+      oldEndTime: downstream.endTime,
+      newStartTime,
+      newEndTime,
+      shiftDeltaMs,
+    });
+
+    // Update current overrun end for next iteration
+    currentOverrunEnd = newEndTime;
+    processedIds.add(downstream.id);
+  }
+
+  // Send notifications for all shifted appointments
+  for (const shifted of result.shifted) {
+    await notifyShiftedAppointment(db, shifted);
+  }
+
+  return result;
+}
+
+/**
+ * Determines if an appointment update represents an overrun that triggers cascade logic.
+ */
+export function isOverrun({
+  originalEndTime,
+  newEndTime,
+  _originalStartTime,
+  _newStartTime,
+  status,
+  currentTime,
+  bufferMinutes,
+}: {
+  originalEndTime: Date;
+  newEndTime: Date;
+  _originalStartTime: Date;
+  _newStartTime?: Date;
+  status: string;
+  currentTime: Date;
+  bufferMinutes: number;
+}): boolean {
+  // Case 1: endTime extended beyond original
+  if (newEndTime > originalEndTime) {
+    return true;
+  }
+
+  // Case 2: status transition where current time exceeds endTime + bufferMinutes
+  // This handles cases where an appointment ran long but wasn't explicitly rescheduled
+  if (
+    (status === "in_progress" || status === "completed") &&
+    currentTime > new Date(originalEndTime.getTime() + bufferMinutes * 60_000)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+async function resolveBufferMinutesForAppointment(
+  db: Db,
+  appt: AppointmentWithGroomer
+): Promise<number> {
+  // First check if the appointment has an explicit bufferMinutes override
+  if (appt.bufferMinutes > 0) {
+    return appt.bufferMinutes;
+  }
+
+  // Fall back to buffer time rules based on service + pet characteristics
+  const [pet] = await db
+    .select({ sizeCategory: pets.sizeCategory, coatType: pets.coatType })
+    .from(pets)
+    .where(eq(pets.id, appt.petId))
+    .limit(1);
+
+  if (!pet) return 0;
+
+  return resolveBufferMinutes({
+    serviceId: appt.serviceId,
+    sizeCategory: pet.sizeCategory,
+    coatType: pet.coatType,
+    db,
+  });
+}
+
+async function notifyShiftedAppointment(
+  db: Db,
+  shifted: ShiftedAppointment
+): Promise<void> {
+  const [row] = await db
+    .select({
+      clientName: clients.name,
+      clientEmail: clients.email,
+      clientEmailOptOut: clients.emailOptOut,
+      petName: pets.name,
+      serviceName: services.name,
+      groomerName: staff.name,
+      appointmentStartTime: appointments.startTime,
+    })
+    .from(appointments)
+    .innerJoin(clients, eq(clients.id, appointments.clientId))
+    .innerJoin(pets, eq(pets.id, appointments.petId))
+    .innerJoin(services, eq(services.id, appointments.serviceId))
+    .leftJoin(staff, eq(staff.id, appointments.staffId))
+    .where(eq(appointments.id, shifted.id))
+    .limit(1);
+
+  if (!row) return;
+  const { clientName, clientEmail, clientEmailOptOut, petName, serviceName, groomerName } = row;
+
+  if (!clientEmail || clientEmailOptOut) return;
+  if (!petName || !serviceName) return;
+
+  console.log(
+    `[cascade] Notifying shift for appointment ${shifted.id}: ` +
+      `${shifted.oldStartTime.toISOString()} → ${shifted.newStartTime.toISOString()}`
+  );
+
+  await sendEmail(
+    buildRescheduleNotificationEmail(clientEmail, {
+      clientName,
+      petName,
+      serviceName,
+      groomerName: groomerName ?? null,
+      oldStartTime: shifted.oldStartTime,
+      newStartTime: shifted.newStartTime,
+    })
+  );
+}

apps/api/src/lib/s3.ts

@@ -67,3 +67,41 @@ export async function deleteObject(key: string): Promise<void> {
     })
   );
 }
+
+/** Read an object from S3 and return its body buffer and content type. */
+export async function getObject(key: string): Promise<{ body: Buffer; contentType: string }> {
+  const client = getS3Client();
+  const response = await client.send(
+    new GetObjectCommand({
+      Bucket: getBucket(),
+      Key: key,
+    })
+  );
+  const chunks: Uint8Array[] = [];
+  // response.Body is a Readable stream; collect chunks into a buffer
+  for await (const chunk of response.Body as AsyncIterable<Uint8Array>) {
+    chunks.push(chunk);
+  }
+  const body = Buffer.concat(chunks);
+  const contentType = response.ContentType ?? "application/octet-stream";
+  return { body, contentType };
+}
+
+/** Upload an object directly to S3 (server-side only, not a pre-signed URL). */
+export async function putObject(
+  key: string,
+  body: Buffer | Uint8Array | string,
+  contentType: string,
+  contentLength: number
+): Promise<void> {
+  const client = getS3Client();
+  await client.send(
+    new PutObjectCommand({
+      Bucket: getBucket(),
+      Key: key,
+      Body: body,
+      ContentType: contentType,
+      ContentLength: contentLength,
+    })
+  );
+}

apps/api/src/middleware/auth.ts

@@ -23,8 +23,8 @@ if (process.env.AUTH_DISABLED === "true") {
 }
 
 export const authMiddleware: MiddlewareHandler = async (c, next) => {
-  // Better-Auth's own routes handle their own auth (OAuth callbacks, session mgmt)
-  if (c.req.path.startsWith("/api/auth/")) {
+  const path = c.req.path;
+  if (path.startsWith("/api/auth/") || path.startsWith("/api/webhooks/")) {
     await next();
     return;
   }
@@ -37,7 +37,14 @@ export const authMiddleware: MiddlewareHandler = async (c, next) => {
     return;
   }
 
-  const session = await getAuth().api.getSession({
+  let auth;
+  try {
+    auth = getAuth();
+  } catch {
+    return c.json({ error: "Authentication not configured" }, 503);
+  }
+
+  const session = await auth.api.getSession({
     headers: c.req.raw.headers,
   });
 

apps/api/src/middleware/portalAudit.ts

@@ -0,0 +1,45 @@
+import type { MiddlewareHandler } from "hono";
+import { getDb, impersonationAuditLogs } from "@groombook/db";
+import type { PortalEnv } from "./portalSession.js";
+
+/**
+ * Server-side audit logging middleware for portal routes.
+ * Applied after validatePortalSession in the middleware chain.
+ *
+ * After the route handler completes (await next()), inserts an audit log entry
+ * into impersonationAuditLogs:
+ *   - sessionId: from c.get("portalSessionId")
+ *   - action: "{METHOD} {routePath}" (e.g., "GET /portal/appointments")
+ *   - pageVisited: c.req.path
+ *   - metadata: { method, statusCode: c.res.status }
+ *
+ * Log entries are written for both success and error responses.
+ * Does NOT throw if audit logging fails — errors are logged but the user's
+ * request is not affected.
+ */
+export const portalAudit: MiddlewareHandler<PortalEnv> = async (c, next) => {
+  await next();
+
+  const sessionId = c.get("portalSessionId");
+  if (!sessionId) return;
+
+  const method = c.req.method;
+  const routePath = c.req.path;
+  const pageVisited = c.req.path;
+  const statusCode = c.res.status;
+
+  try {
+    const db = getDb();
+    await db
+      .insert(impersonationAuditLogs)
+      .values({
+        sessionId,
+        action: `${method} ${routePath}`,
+        pageVisited,
+        metadata: { method, statusCode },
+      })
+      .returning();
+  } catch (err) {
+    console.error("[portalAudit] Failed to write audit log:", err);
+  }
+};

apps/api/src/middleware/portalSession.ts

@@ -0,0 +1,40 @@
+import type { MiddlewareHandler } from "hono";
+import { and, eq, getDb, impersonationSessions } from "@groombook/db";
+
+export interface PortalEnv {
+  Variables: {
+    portalClientId: string;
+    portalSessionId: string;
+  };
+}
+
+/**
+ * Validates the X-Impersonation-Session-Id header against the impersonationSessions table.
+ * Must be applied to all portal routes.
+ *
+ * Reads x-session-id from request headers, queries impersonationSessions for a row where
+ * id = sessionId AND status = 'active', and checks session.expiresAt > new Date().
+ * Returns 401 if session is invalid/missing/expired.
+ * On success, sets c.set("portalClientId", session.clientId) and c.set("portalSessionId", session.id).
+ */
+export const validatePortalSession: MiddlewareHandler<PortalEnv> = async (c, next) => {
+  const sessionId = c.req.header("X-Impersonation-Session-Id");
+  if (!sessionId) {
+    return c.json({ error: "Unauthorized" }, 401);
+  }
+
+  const db = getDb();
+  const [session] = await db
+    .select()
+    .from(impersonationSessions)
+    .where(and(eq(impersonationSessions.id, sessionId), eq(impersonationSessions.status, "active")))
+    .limit(1);
+
+  if (!session || session.expiresAt <= new Date()) {
+    return c.json({ error: "Unauthorized" }, 401);
+  }
+
+  c.set("portalClientId", session.clientId);
+  c.set("portalSessionId", session.id);
+  await next();
+};

apps/api/src/middleware/rbac.ts

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

apps/api/src/routes/appointmentGroups.ts

@@ -16,8 +16,9 @@ import {
   services,
   staff,
 } from "@groombook/db";
+import type { AppEnv } from "../middleware/rbac.js";
 
-export const appointmentGroupsRouter = new Hono();
+export const appointmentGroupsRouter = new Hono<AppEnv>();
 
 // ─── Schemas ──────────────────────────────────────────────────────────────────
 
@@ -49,6 +50,8 @@ appointmentGroupsRouter.get("/", async (c) => {
   const clientId = c.req.query("clientId");
   const from = c.req.query("from");
   const to = c.req.query("to");
+  const staffRow = c.get("staff");
+  const isGroomer = staffRow?.role === "groomer";
 
   const groupConditions = clientId
     ? [eq(appointmentGroups.clientId, clientId)]
@@ -88,6 +91,16 @@ appointmentGroupsRouter.get("/", async (c) => {
     }))
     .filter((g) => !from || g.appointments.length > 0);
 
+  if (isGroomer) {
+    return c.json(
+      result.filter((g) =>
+        g.appointments.some(
+          (a) => a.staffId === staffRow.id || a.batherStaffId === staffRow.id
+        )
+      )
+    );
+  }
+
   return c.json(result);
 });
 
@@ -96,6 +109,8 @@ appointmentGroupsRouter.get("/", async (c) => {
 appointmentGroupsRouter.get("/:id", async (c) => {
   const db = getDb();
   const id = c.req.param("id");
+  const staffRow = c.get("staff");
+  const isGroomer = staffRow?.role === "groomer";
 
   const [group] = await db
     .select()
@@ -111,6 +126,7 @@ appointmentGroupsRouter.get("/:id", async (c) => {
       serviceId: appointments.serviceId,
       serviceName: services.name,
       staffId: appointments.staffId,
+      batherStaffId: appointments.batherStaffId,
       staffName: staff.name,
       status: appointments.status,
       startTime: appointments.startTime,
@@ -125,6 +141,15 @@ appointmentGroupsRouter.get("/:id", async (c) => {
     .where(eq(appointments.groupId, id))
     .orderBy(appointments.startTime);
 
+  if (
+    isGroomer &&
+    !groupAppts.some(
+      (a) => a.staffId === staffRow.id || a.batherStaffId === staffRow.id
+    )
+  ) {
+    return c.json({ error: "Forbidden" }, 403);
+  }
+
   const [client] = await db
     .select({ name: clients.name, email: clients.email })
     .from(clients)
@@ -140,6 +165,13 @@ appointmentGroupsRouter.post(
   zValidator("json", createGroupSchema),
   async (c) => {
     const db = getDb();
+    const staffRow = c.get("staff");
+    if (staffRow?.role === "groomer") {
+      return c.json(
+        { error: "Forbidden: groomers cannot create group bookings" },
+        403
+      );
+    }
     const body = c.req.valid("json");
     const startTime = new Date(body.startTime);
 
@@ -244,6 +276,28 @@ appointmentGroupsRouter.patch(
     const db = getDb();
     const id = c.req.param("id");
     const body = c.req.valid("json");
+    const staffRow = c.get("staff");
+    const isGroomer = staffRow?.role === "groomer";
+
+    const [group] = await db
+      .select({ id: appointmentGroups.id })
+      .from(appointmentGroups)
+      .where(eq(appointmentGroups.id, id));
+    if (!group) return c.json({ error: "Not found" }, 404);
+
+    if (isGroomer) {
+      const groupAppts = await db
+        .select({ staffId: appointments.staffId, batherStaffId: appointments.batherStaffId })
+        .from(appointments)
+        .where(eq(appointments.groupId, id));
+      if (
+        !groupAppts.some(
+          (a) => a.staffId === staffRow.id || a.batherStaffId === staffRow.id
+        )
+      ) {
+        return c.json({ error: "Forbidden" }, 403);
+      }
+    }
 
     const [updated] = await db
       .update(appointmentGroups)
@@ -261,6 +315,8 @@ appointmentGroupsRouter.patch(
 appointmentGroupsRouter.delete("/:id", async (c) => {
   const db = getDb();
   const id = c.req.param("id");
+  const staffRow = c.get("staff");
+  const isGroomer = staffRow?.role === "groomer";
 
   const [group] = await db
     .select({ id: appointmentGroups.id })
@@ -268,6 +324,20 @@ appointmentGroupsRouter.delete("/:id", async (c) => {
     .where(eq(appointmentGroups.id, id));
   if (!group) return c.json({ error: "Not found" }, 404);
 
+  if (isGroomer) {
+    const groupAppts = await db
+      .select({ staffId: appointments.staffId, batherStaffId: appointments.batherStaffId })
+      .from(appointments)
+      .where(eq(appointments.groupId, id));
+    if (
+      !groupAppts.some(
+        (a) => a.staffId === staffRow.id || a.batherStaffId === staffRow.id
+      )
+    ) {
+      return c.json({ error: "Forbidden" }, 403);
+    }
+  }
+
   await db
     .update(appointments)
     .set({ status: "cancelled", updatedAt: new Date() })

apps/api/src/routes/appointments.ts

@@ -21,8 +21,33 @@ import {
 } from "@groombook/db";
 import { buildConfirmationEmail, sendEmail } from "../services/email.js";
 import { notifyWaitlistForAppointment } from "../services/waitlistNotify.js";
+import {
+  detectAndCascadeOverrun,
+  isOverrun,
+} from "../lib/cascade.js";
 import type { AppEnv } from "../middleware/rbac.js";
 
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  maxRetries: number,
+  delayMs: number,
+  context: string
+): Promise<void> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      await fn();
+      return;
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxRetries) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+  console.error(`[appointments] ${context}: ${lastError}`);
+}
+
 export const appointmentsRouter = new Hono<AppEnv>();
 
 const createAppointmentSchema = z.object({
@@ -41,6 +66,10 @@ const createAppointmentSchema = z.object({
       frequencyWeeks: z.number().int().min(1).max(52),
       count: z.number().int().min(2).max(52),
     })
+    .refine(
+      (r) => r.frequencyWeeks * r.count <= 52,
+      { message: "Recurrence series must not exceed 1 year" }
+    )
     .optional(),
 });
 
@@ -163,6 +192,28 @@ appointmentsRouter.post(
           }
         }
 
+        if (apptFields.batherStaffId) {
+          const bathConflicts = await tx
+            .select({ id: appointments.id })
+            .from(appointments)
+            .where(
+              and(
+                or(
+                  eq(appointments.staffId, apptFields.batherStaffId),
+                  eq(appointments.batherStaffId, apptFields.batherStaffId)
+                ),
+                lt(appointments.startTime, end),
+                gte(appointments.endTime, start),
+                ne(appointments.status, "cancelled"),
+                ne(appointments.status, "no_show"),
+              )
+            )
+            .limit(1);
+          if (bathConflicts.length > 0) {
+            throw Object.assign(new Error("conflict"), { statusCode: 409 });
+          }
+        }
+
         if (!recurrence) {
           // Single appointment
           const [inserted] = await tx
@@ -186,11 +237,54 @@ appointmentsRouter.post(
           recurrence.frequencyWeeks * 7 * 24 * 60 * 60 * 1000;
 
         let first: typeof appointments.$inferSelect | undefined;
+        const conflictingInstances: number[] = [];
         for (let i = 0; i < recurrence.count; i++) {
           const instanceStart = new Date(start.getTime() + i * intervalMs);
           const instanceEnd = new Date(
             instanceStart.getTime() + durationMs
           );
+
+          if (apptFields.staffId) {
+            const conflicts = await tx
+              .select({ id: appointments.id })
+              .from(appointments)
+              .where(
+                and(
+                  eq(appointments.staffId, apptFields.staffId),
+                  lt(appointments.startTime, instanceEnd),
+                  gte(appointments.endTime, instanceStart),
+                  ne(appointments.status, "cancelled"),
+                  ne(appointments.status, "no_show"),
+                )
+              )
+              .limit(1);
+            if (conflicts.length > 0) {
+              conflictingInstances.push(i);
+            }
+          }
+
+          if (apptFields.batherStaffId) {
+            const conflicts = await tx
+              .select({ id: appointments.id })
+              .from(appointments)
+              .where(
+                and(
+                  or(
+                    eq(appointments.staffId, apptFields.batherStaffId),
+                    eq(appointments.batherStaffId, apptFields.batherStaffId)
+                  ),
+                  lt(appointments.startTime, instanceEnd),
+                  gte(appointments.endTime, instanceStart),
+                  ne(appointments.status, "cancelled"),
+                  ne(appointments.status, "no_show"),
+                )
+              )
+              .limit(1);
+            if (conflicts.length > 0) {
+              conflictingInstances.push(i);
+            }
+          }
+
           const [inserted] = await tx
             .insert(appointments)
             .values({
@@ -201,9 +295,19 @@ appointmentsRouter.post(
               seriesIndex: i,
             })
             .returning();
+          if (!inserted) throw new Error(`Insert failed for occurrence ${i}`);
           if (i === 0) first = inserted;
         }
 
+        if (conflictingInstances.length > 0) {
+          throw Object.assign(
+            new Error(
+              `Conflicts detected at occurrence(s): ${conflictingInstances.join(", ")}`
+            ),
+            { statusCode: 409 }
+          );
+        }
+
         if (!first) throw new Error("No appointments created");
         return first;
       });
@@ -221,9 +325,12 @@ appointmentsRouter.post(
     }
 
     // Send confirmation email (fire-and-forget — never fails the request)
-    sendConfirmationEmail(db, firstRow).catch((err) => {
-      console.error("[appointments] Failed to send confirmation email:", err);
-    });
+    withRetry(
+      () => sendConfirmationEmail(db, firstRow),
+      2,
+      1000,
+      `Failed to send confirmation email for appointment ${firstRow.id}`
+    );
 
     return c.json(firstRow, 201);
   }
@@ -235,44 +342,35 @@ async function sendConfirmationEmail(
   db: ReturnType<typeof getDb>,
   appt: typeof appointments.$inferSelect
 ): Promise<void> {
-  const [client] = await db
-    .select({ name: clients.name, email: clients.email, emailOptOut: clients.emailOptOut })
-    .from(clients)
-    .where(eq(clients.id, appt.clientId))
+  const [row] = await db
+    .select({
+      clientName: clients.name,
+      clientEmail: clients.email,
+      clientEmailOptOut: clients.emailOptOut,
+      petName: pets.name,
+      serviceName: services.name,
+      groomerName: staff.name,
+    })
+    .from(appointments)
+    .innerJoin(clients, eq(clients.id, appointments.clientId))
+    .innerJoin(pets, eq(pets.id, appointments.petId))
+    .innerJoin(services, eq(services.id, appointments.serviceId))
+    .leftJoin(staff, eq(staff.id, appointments.staffId))
+    .where(eq(appointments.id, appt.id))
     .limit(1);
 
-  if (!client || !client.email || client.emailOptOut) return;
+  if (!row) return;
+  const { clientName, clientEmail, clientEmailOptOut, petName, serviceName, groomerName } = row;
 
-  const [pet] = await db
-    .select({ name: pets.name })
-    .from(pets)
-    .where(eq(pets.id, appt.petId))
-    .limit(1);
-
-  const [service] = await db
-    .select({ name: services.name })
-    .from(services)
-    .where(eq(services.id, appt.serviceId))
-    .limit(1);
-
-  let groomerName: string | null = null;
-  if (appt.staffId) {
-    const [groomer] = await db
-      .select({ name: staff.name })
-      .from(staff)
-      .where(eq(staff.id, appt.staffId))
-      .limit(1);
-    groomerName = groomer?.name ?? null;
-  }
-
-  if (!pet || !service) return;
+  if (!clientEmail || clientEmailOptOut) return;
+  if (!petName || !serviceName) return;
 
   const sent = await sendEmail(
-    buildConfirmationEmail(client.email, {
-      clientName: client.name,
-      petName: pet.name,
-      serviceName: service.name,
-      groomerName,
+    buildConfirmationEmail(clientEmail, {
+      clientName,
+      petName,
+      serviceName,
+      groomerName: groomerName ?? null,
       startTime: appt.startTime,
     })
   );
@@ -352,6 +450,76 @@ appointmentsRouter.patch(
 
           let firstUpdated: typeof appointments.$inferSelect | undefined;
           for (const appt of affected) {
+            const newStart =
+              startDeltaMs !== 0
+                ? new Date(appt.startTime.getTime() + startDeltaMs)
+                : appt.startTime;
+            const newEnd =
+              endDeltaMs !== 0
+                ? new Date(appt.endTime.getTime() + endDeltaMs)
+                : appt.endTime;
+            const newStaffId =
+              updateFields.staffId !== undefined
+                ? updateFields.staffId
+                : appt.staffId;
+            const newBatherStaffId =
+              updateFields.batherStaffId !== undefined
+                ? updateFields.batherStaffId
+                : appt.batherStaffId;
+
+            if (
+              newStaffId &&
+              (startDeltaMs !== 0 ||
+                endDeltaMs !== 0 ||
+                updateFields.staffId !== undefined)
+            ) {
+              const conflicts = await tx
+                .select({ id: appointments.id })
+                .from(appointments)
+                .where(
+                  and(
+                    eq(appointments.staffId, newStaffId),
+                    lt(appointments.startTime, newEnd),
+                    gte(appointments.endTime, newStart),
+                    ne(appointments.status, "cancelled"),
+                    ne(appointments.status, "no_show"),
+                    ne(appointments.id, appt.id),
+                  )
+                )
+                .limit(1);
+              if (conflicts.length > 0) {
+                throw Object.assign(new Error("conflict"), { statusCode: 409 });
+              }
+            }
+
+            if (
+              newBatherStaffId &&
+              (startDeltaMs !== 0 ||
+                endDeltaMs !== 0 ||
+                updateFields.batherStaffId !== undefined)
+            ) {
+              const conflicts = await tx
+                .select({ id: appointments.id })
+                .from(appointments)
+                .where(
+                  and(
+                    or(
+                      eq(appointments.staffId, newBatherStaffId),
+                      eq(appointments.batherStaffId, newBatherStaffId)
+                    ),
+                    lt(appointments.startTime, newEnd),
+                    gte(appointments.endTime, newStart),
+                    ne(appointments.status, "cancelled"),
+                    ne(appointments.status, "no_show"),
+                    ne(appointments.id, appt.id),
+                  )
+                )
+                .limit(1);
+              if (conflicts.length > 0) {
+                throw Object.assign(new Error("conflict"), { statusCode: 409 });
+              }
+            }
+
             const apptUpdate: Record<string, unknown> = {
               updatedAt: new Date(),
             };
@@ -387,6 +555,13 @@ appointmentsRouter.patch(
         if (statusCode === 404) return c.json({ error: "Not found" }, 404);
         if (statusCode === 422)
           return c.json({ error: "endTime must be after startTime" }, 422);
+        if (statusCode === 409)
+          return c.json(
+            {
+              error: "Staff member has a conflicting appointment at this time",
+            },
+            409
+          );
         throw err;
       }
 
@@ -398,7 +573,8 @@ appointmentsRouter.patch(
     const needsConflictCheck =
       updateFields.startTime !== undefined ||
       updateFields.endTime !== undefined ||
-      updateFields.staffId !== undefined;
+      updateFields.staffId !== undefined ||
+      updateFields.batherStaffId !== undefined;
 
     const update: Record<string, unknown> = {
       ...updateFields,
@@ -412,6 +588,7 @@ appointmentsRouter.patch(
       // (fixes #18). Also falls back to the existing staffId when staffId is
       // omitted from the request, so rescheduling always checks conflicts (fixes #19).
       let row: typeof appointments.$inferSelect | undefined;
+      let originalEndTime: Date | undefined;
       try {
         row = await db.transaction(async (tx) => {
           const [current] = await tx
@@ -423,6 +600,9 @@ appointmentsRouter.patch(
             throw Object.assign(new Error("not found"), { statusCode: 404 });
           }
 
+          // Preserve original endTime for cascade detection after update
+          originalEndTime = current.endTime;
+
           const start = updateFields.startTime
             ? new Date(updateFields.startTime)
             : current.startTime;
@@ -434,6 +614,11 @@ appointmentsRouter.patch(
             updateFields.staffId !== undefined
               ? updateFields.staffId
               : current.staffId;
+          // Use provided batherStaffId (may be null to unassign); fall back to existing
+          const batherStaffId =
+            updateFields.batherStaffId !== undefined
+              ? updateFields.batherStaffId
+              : current.batherStaffId;
 
           if (end <= start) {
             throw Object.assign(new Error("end before start"), {
@@ -461,6 +646,29 @@ appointmentsRouter.patch(
             }
           }
 
+          if (batherStaffId) {
+            const bathConflicts = await tx
+              .select({ id: appointments.id })
+              .from(appointments)
+              .where(
+                and(
+                  or(
+                    eq(appointments.staffId, batherStaffId),
+                    eq(appointments.batherStaffId, batherStaffId)
+                  ),
+                  lt(appointments.startTime, end),
+                  gte(appointments.endTime, start),
+                  ne(appointments.status, "cancelled"),
+                  ne(appointments.status, "no_show"),
+                  ne(appointments.id, id),
+                )
+              )
+              .limit(1);
+            if (bathConflicts.length > 0) {
+              throw Object.assign(new Error("conflict"), { statusCode: 409 });
+            }
+          }
+
           const [updated] = await tx
             .update(appointments)
             .set(update)
@@ -484,6 +692,29 @@ appointmentsRouter.patch(
       }
 
       if (!row) return c.json({ error: "Not found" }, 404);
+
+      // Cascade delay prevention: detect overrun and shift downstream appointments
+      if (
+        originalEndTime &&
+        updateFields.endTime &&
+        isOverrun({
+          originalEndTime,
+          newEndTime: new Date(updateFields.endTime),
+          _originalStartTime: row.startTime,
+          status: row.status,
+          currentTime: new Date(),
+          bufferMinutes: row.bufferMinutes ?? 0,
+        })
+      ) {
+        const cascadeResult = await detectAndCascadeOverrun({
+          db,
+          overrunningAppointmentId: id,
+          newEndTime: new Date(updateFields.endTime),
+          _originalEndTime: originalEndTime,
+        });
+        return c.json({ ...row, cascade: cascadeResult });
+      }
+
       return c.json(row);
     }
 
@@ -535,9 +766,12 @@ appointmentsRouter.delete("/:id", async (c) => {
 
     const apptDate = current.startTime.toISOString().slice(0, 10);
     const apptTime = current.startTime.toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit", hour12: true });
-    notifyWaitlistForAppointment(id, apptDate, apptTime, current.serviceId).catch((err) => {
-      console.error("[appointments] Failed to notify waitlist:", err);
-    });
+    withRetry(
+      () => notifyWaitlistForAppointment(id, apptDate, apptTime, current.serviceId),
+      2,
+      1000,
+      `Failed to notify waitlist for appointment ${id}`
+    );
 
     return c.json({ ok: true });
   }
@@ -560,9 +794,12 @@ appointmentsRouter.delete("/:id", async (c) => {
     .returning();
   if (!row) return c.json({ error: "Not found" }, 404);
 
-  notifyWaitlistForAppointment(id, apptDate, apptTime, current.serviceId).catch((err) => {
-    console.error("[appointments] Failed to notify waitlist:", err);
-  });
+  withRetry(
+    () => notifyWaitlistForAppointment(id, apptDate, apptTime, current.serviceId),
+    2,
+    1000,
+    `Failed to notify waitlist for appointment ${id}`
+  );
 
   return c.json({ ok: true });
 });

apps/api/src/routes/book.ts

@@ -38,11 +38,12 @@ bookRouter.get("/services", async (c) => {
 
 // ─── GET /api/book/availability ─────────────────────────────────────────────
 // Public: return ISO startTime strings for slots where ≥1 groomer is free
-// Query params: serviceId (uuid), date (YYYY-MM-DD)
+// Query params: serviceId (uuid), date (YYYY-MM-DD), petSizeCategory, petCoatType
 
 bookRouter.get("/availability", async (c) => {
   const serviceId = c.req.query("serviceId");
   const dateStr = c.req.query("date");
+  const petSizeCategory = c.req.query("petSizeCategory") ?? undefined;
 
   if (!serviceId || !dateStr) {
     return c.json({ error: "serviceId and date are required" }, 400);
@@ -58,6 +59,12 @@ bookRouter.get("/availability", async (c) => {
     .where(and(eq(services.id, serviceId), eq(services.active, true)));
   if (!service) return c.json({ error: "Service not found" }, 404);
 
+  // Buffer-aware duration: extra time for large/x-large or complex coats
+  const extraBuffer = (petSizeCategory === "large" || petSizeCategory === "xlarge")
+    ? (service.defaultBufferMinutes ?? 0)
+    : 0;
+  const durationMinutes = service.durationMinutes + extraBuffer;
+
   const groomers = await db
     .select({ id: staff.id })
     .from(staff)
@@ -89,7 +96,7 @@ bookRouter.get("/availability", async (c) => {
 
   const slots = generateAvailableSlots({
     dateStr,
-    durationMinutes: service.durationMinutes,
+    durationMinutes,
     groomerIds: groomers.map((g) => g.id),
     booked,
   });
@@ -102,13 +109,22 @@ bookRouter.get("/availability", async (c) => {
 
 const bookingSchema = z.object({
   serviceId: z.string().uuid(),
-  startTime: z.string().datetime(),
+  startTime: z.string().datetime().refine(
+    (dt) => new Date(dt) > new Date(),
+    { message: "Appointment must be in the future" }
+  ),
   clientName: z.string().min(1).max(200),
   clientEmail: z.string().email(),
   clientPhone: z.string().max(50).optional(),
   petName: z.string().min(1).max(200),
   petSpecies: z.string().min(1).max(100),
   petBreed: z.string().max(100).optional(),
+  petSizeCategory: z
+    .enum(["small", "medium", "large", "xlarge"])
+    .optional(),
+  petCoatType: z
+    .enum(["smooth", "double", "curly", "wire", "long", "hairless"])
+    .optional(),
   notes: z.string().max(2000).optional(),
 });
 
@@ -126,7 +142,7 @@ bookRouter.post(
       .where(and(eq(services.id, body.serviceId), eq(services.active, true)));
     if (!service) return c.json({ error: "Service not found" }, 404);
 
-    const end = new Date(start.getTime() + service.durationMinutes * 60_000);
+    let end = new Date(start.getTime() + service.durationMinutes * 60_000);
 
     // Find all active groomers
     const groomers = await db
@@ -188,11 +204,18 @@ bookRouter.post(
         name: body.petName,
         species: body.petSpecies,
         breed: body.petBreed ?? null,
+        sizeCategory: body.petSizeCategory ?? null,
+        coatType: body.petCoatType ?? null,
       })
       .returning();
     const pet = petInserted[0];
     if (!pet) return c.json({ error: "Failed to create pet" }, 500);
 
+    // Buffer-aware end time: large/x-large pets add service bufferMinutes
+    if (body.petSizeCategory === "large" || body.petSizeCategory === "xlarge") {
+      end = new Date(start.getTime() + (service.durationMinutes + (service.defaultBufferMinutes ?? 0)) * 60_000);
+    }
+
     // Insert appointment in a transaction to guard against race conditions
     let appointment;
     try {
@@ -265,29 +288,36 @@ bookRouter.get("/confirm/:token", async (c) => {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Reject if appointment is in the past
   if (appt.startTime < new Date()) {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Idempotent confirm: if already confirmed, redirect to success
   if (appt.confirmationStatus === "confirmed") {
     return c.redirect(`${BASE_URL()}/booking/confirmed`);
   }
 
-  // Reject if already cancelled
   if (appt.confirmationStatus === "cancelled") {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  await db
+  const updated = await db
     .update(appointments)
     .set({
       confirmationStatus: "confirmed",
       confirmedAt: new Date(),
       updatedAt: new Date(),
     })
-    .where(eq(appointments.id, appt.id));
+    .where(
+      and(
+        eq(appointments.confirmationToken, token),
+        eq(appointments.confirmationStatus, "pending")
+      )
+    )
+    .returning();
+
+  if (updated.length === 0) {
+    return c.redirect(`${BASE_URL()}/booking/error`);
+  }
 
   return c.redirect(`${BASE_URL()}/booking/confirmed`);
 });
@@ -309,19 +339,15 @@ bookRouter.get("/cancel/:token", async (c) => {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Reject if appointment is in the past
   if (appt.startTime < new Date()) {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Reject if already cancelled (token was nullified — this path won't normally hit,
-  // but guard against edge cases where token lookup still works)
   if (appt.confirmationStatus === "cancelled") {
     return c.redirect(`${BASE_URL()}/booking/error`);
   }
 
-  // Single-use cancellation: nullify token after use
-  await db
+  const updated = await db
     .update(appointments)
     .set({
       confirmationStatus: "cancelled",
@@ -329,7 +355,17 @@ bookRouter.get("/cancel/:token", async (c) => {
       confirmationToken: null,
       updatedAt: new Date(),
     })
-    .where(eq(appointments.id, appt.id));
+    .where(
+      and(
+        eq(appointments.confirmationToken, token),
+        eq(appointments.confirmationStatus, "pending")
+      )
+    )
+    .returning();
+
+  if (updated.length === 0) {
+    return c.redirect(`${BASE_URL()}/booking/error`);
+  }
 
   return c.redirect(`${BASE_URL()}/booking/cancelled`);
 });

apps/api/src/routes/calendar.ts

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

apps/api/src/routes/clients.ts

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

apps/api/src/routes/conversations.ts

@@ -0,0 +1,274 @@
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import { z } from "zod/v3";
+import {
+  and,
+  eq,
+  desc,
+  lt,
+  sql,
+  getDb,
+  conversations,
+  messages,
+  clients,
+  businessSettings,
+} from "@groombook/db";
+import type { AppEnv } from "../middleware/rbac.js";
+import { sendMessage } from "../services/messaging/outbound.js";
+
+export const conversationsRouter = new Hono<AppEnv>();
+
+const sendMessageSchema = z.object({
+  body: z.string().min(1).max(1600),
+});
+
+// GET /api/conversations — List conversations
+conversationsRouter.get("/", async (c) => {
+  const db = getDb();
+  const staffRow = c.get("staff");
+  if (!staffRow) return c.json({ error: "Unauthorized" }, 401);
+
+  const [settings] = await db
+    .select({ id: businessSettings.id })
+    .from(businessSettings)
+    .limit(1);
+  if (!settings) return c.json({ error: "Business not found" }, 404);
+
+  const cursor = c.req.query("cursor") || undefined;
+  const limit = Math.min(Number(c.req.query("limit") || "20"), 50);
+
+  let baseQuery = db
+    .select({
+      id: conversations.id,
+      clientId: conversations.clientId,
+      lastMessageAt: conversations.lastMessageAt,
+      status: conversations.status,
+      staffReadAt: conversations.staffReadAt,
+      clientName: clients.name,
+      clientPhone: clients.phone,
+      channel: conversations.channel,
+    })
+    .from(conversations)
+    .innerJoin(clients, eq(conversations.clientId, clients.id))
+    .where(eq(conversations.businessId, settings.id))
+    .orderBy(desc(conversations.lastMessageAt))
+    .limit(limit + 1);
+
+  if (cursor) {
+    const [cursorRow] = await db
+      .select({ lastMessageAt: conversations.lastMessageAt })
+      .from(conversations)
+      .where(eq(conversations.id, cursor))
+      .limit(1);
+    if (cursorRow?.lastMessageAt) {
+      baseQuery = db
+        .select({
+          id: conversations.id,
+          clientId: conversations.clientId,
+          lastMessageAt: conversations.lastMessageAt,
+          status: conversations.status,
+          staffReadAt: conversations.staffReadAt,
+          clientName: clients.name,
+          clientPhone: clients.phone,
+          channel: conversations.channel,
+        })
+        .from(conversations)
+        .innerJoin(clients, eq(conversations.clientId, clients.id))
+        .where(
+          and(
+            eq(conversations.businessId, settings.id),
+            lt(conversations.lastMessageAt, cursorRow.lastMessageAt)
+          )
+        )
+        .orderBy(desc(conversations.lastMessageAt))
+        .limit(limit + 1);
+    }
+  }
+
+  const rows = await baseQuery;
+
+  const hasMore = rows.length > limit;
+  if (hasMore) rows.pop();
+
+  const items = await Promise.all(
+    rows.map(async (row) => {
+      const [unreadRow] = await db
+        .select({ count: sql<number>`count(*)` })
+        .from(messages)
+        .where(
+          and(
+            eq(messages.conversationId, row.id),
+            eq(messages.direction, "inbound"),
+            sql`${messages.createdAt} > COALESCE(${row.staffReadAt}, '1970-01-01'::timestamp)`
+          )
+        )
+        .limit(1);
+
+      const [lastMsg] = await db
+        .select({
+          body: messages.body,
+          direction: messages.direction,
+          createdAt: messages.createdAt,
+        })
+        .from(messages)
+        .where(eq(messages.conversationId, row.id))
+        .orderBy(desc(messages.createdAt))
+        .limit(1);
+
+      return {
+        id: row.id,
+        clientId: row.clientId,
+        clientName: row.clientName,
+        clientPhone: row.clientPhone,
+        channel: row.channel,
+        lastMessageAt: row.lastMessageAt,
+        status: row.status,
+        unreadCount: Number(unreadRow?.count ?? 0),
+        lastMessage: lastMsg ?? null,
+      };
+    })
+  );
+
+  const lastRow = rows[rows.length - 1];
+  const nextCursor = hasMore && lastRow ? lastRow.id : null;
+  return c.json({ items, nextCursor });
+});
+
+// GET /api/conversations/:id/messages — List messages for a conversation
+conversationsRouter.get("/:id/messages", async (c) => {
+  const db = getDb();
+  const staffRow = c.get("staff");
+  if (!staffRow) return c.json({ error: "Unauthorized" }, 401);
+
+  const conversationId = c.req.param("id");
+  const cursor = c.req.query("cursor") || undefined;
+  const limit = Math.min(Number(c.req.query("limit") || "50"), 100);
+
+  const [settings] = await db
+    .select({ id: businessSettings.id })
+    .from(businessSettings)
+    .limit(1);
+  if (!settings) return c.json({ error: "Business not found" }, 404);
+
+  const [conv] = await db
+    .select({ id: conversations.id })
+    .from(conversations)
+    .where(
+      and(eq(conversations.id, conversationId), eq(conversations.businessId, settings.id))
+    )
+    .limit(1);
+  if (!conv) return c.json({ error: "Not found" }, 404);
+
+  await db
+    .update(conversations)
+    .set({ staffReadAt: new Date() })
+    .where(eq(conversations.id, conversationId));
+
+  let query = db
+    .select({
+      id: messages.id,
+      direction: messages.direction,
+      body: messages.body,
+      status: messages.status,
+      sentByStaffId: messages.sentByStaffId,
+      createdAt: messages.createdAt,
+      deliveredAt: messages.deliveredAt,
+    })
+    .from(messages)
+    .where(eq(messages.conversationId, conversationId))
+    .orderBy(desc(messages.createdAt))
+    .limit(limit + 1);
+
+  if (cursor) {
+    const [cursorRow] = await db
+      .select({ createdAt: messages.createdAt })
+      .from(messages)
+      .where(eq(messages.id, cursor))
+      .limit(1);
+    if (cursorRow?.createdAt) {
+      query = db
+        .select({
+          id: messages.id,
+          direction: messages.direction,
+          body: messages.body,
+          status: messages.status,
+          sentByStaffId: messages.sentByStaffId,
+          createdAt: messages.createdAt,
+          deliveredAt: messages.deliveredAt,
+        })
+        .from(messages)
+        .where(
+          and(
+            eq(messages.conversationId, conversationId),
+            lt(messages.createdAt, cursorRow.createdAt)
+          )
+        )
+        .orderBy(desc(messages.createdAt))
+        .limit(limit + 1);
+    }
+  }
+
+  const rows = await query;
+  const hasMore = rows.length > limit;
+  if (hasMore) rows.pop();
+
+  const lastRow = rows[rows.length - 1];
+  const nextCursor = hasMore && lastRow ? lastRow.id : null;
+  return c.json({ items: rows, nextCursor });
+});
+
+// POST /api/conversations/:id/messages — Send a message
+conversationsRouter.post(
+  "/:id/messages",
+  zValidator("json", sendMessageSchema),
+  async (c) => {
+    const db = getDb();
+    const staffRow = c.get("staff");
+    if (!staffRow) return c.json({ error: "Unauthorized" }, 401);
+
+    const conversationId = c.req.param("id");
+    const { body } = c.req.valid("json");
+
+    const [settings] = await db
+      .select({ id: businessSettings.id })
+      .from(businessSettings)
+      .limit(1);
+    if (!settings) return c.json({ error: "Business not found" }, 404);
+
+    const [conv] = await db
+      .select({ id: conversations.id, clientId: conversations.clientId })
+      .from(conversations)
+      .where(
+        and(eq(conversations.id, conversationId), eq(conversations.businessId, settings.id))
+      )
+      .limit(1);
+    if (!conv) return c.json({ error: "Not found" }, 404);
+
+    const result = await sendMessage({
+      businessId: settings.id,
+      clientId: conv.clientId,
+      body,
+      sentByStaffId: staffRow.id,
+    });
+
+    if (result.suppressed) {
+      return c.json({ error: "Client has opted out of SMS" }, 409);
+    }
+
+    const [msg] = await db
+      .select({
+        id: messages.id,
+        direction: messages.direction,
+        body: messages.body,
+        status: messages.status,
+        sentByStaffId: messages.sentByStaffId,
+        createdAt: messages.createdAt,
+        deliveredAt: messages.deliveredAt,
+      })
+      .from(messages)
+      .where(eq(messages.id, result.messageId))
+      .limit(1);
+
+    return c.json(msg, 201);
+  }
+);

apps/api/src/routes/groomingLogs.ts

@@ -1,9 +1,10 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { desc, eq, getDb, groomingVisitLogs } from "@groombook/db";
+import { and, desc, eq, getDb, groomingVisitLogs, appointments, or } from "@groombook/db";
+import type { AppEnv } from "../middleware/rbac.js";
 
-export const groomingLogsRouter = new Hono();
+export const groomingLogsRouter = new Hono<AppEnv>();
 
 const createLogSchema = z.object({
   petId: z.string().uuid(),
@@ -20,6 +21,26 @@ groomingLogsRouter.get("/", async (c) => {
   const db = getDb();
   const petId = c.req.query("petId");
   if (!petId) return c.json({ error: "petId is required" }, 400);
+  const staffRow = c.get("staff");
+  const isGroomer = staffRow?.role === "groomer";
+
+  if (isGroomer) {
+    const [appt] = await db
+      .select({ id: appointments.id })
+      .from(appointments)
+      .where(
+        and(
+          eq(appointments.petId, petId),
+          or(
+            eq(appointments.staffId, staffRow.id),
+            eq(appointments.batherStaffId, staffRow.id)
+          )
+        )
+      )
+      .limit(1);
+    if (!appt) return c.json({ error: "Forbidden" }, 403);
+  }
+
   const rows = await db
     .select()
     .from(groomingVisitLogs)
@@ -33,11 +54,50 @@ groomingLogsRouter.post(
   zValidator("json", createLogSchema),
   async (c) => {
     const db = getDb();
-    const { groomedAt, ...rest } = c.req.valid("json");
+    const { groomedAt, petId, appointmentId, ...rest } = c.req.valid("json");
+    const staffRow = c.get("staff");
+    const isGroomer = staffRow?.role === "groomer";
+
+    if (isGroomer) {
+      if (appointmentId) {
+        const [appt] = await db
+          .select({ id: appointments.id })
+          .from(appointments)
+          .where(
+            and(
+              eq(appointments.id, appointmentId),
+              or(
+                eq(appointments.staffId, staffRow.id),
+                eq(appointments.batherStaffId, staffRow.id)
+              )
+            )
+          )
+          .limit(1);
+        if (!appt) return c.json({ error: "Forbidden" }, 403);
+      } else {
+        const [appt] = await db
+          .select({ id: appointments.id })
+          .from(appointments)
+          .where(
+            and(
+              eq(appointments.petId, petId),
+              or(
+                eq(appointments.staffId, staffRow.id),
+                eq(appointments.batherStaffId, staffRow.id)
+              )
+            )
+          )
+          .limit(1);
+        if (!appt) return c.json({ error: "Forbidden" }, 403);
+      }
+    }
+
     const [row] = await db
       .insert(groomingVisitLogs)
       .values({
         ...rest,
+        petId,
+        appointmentId: appointmentId ?? null,
         groomedAt: groomedAt ? new Date(groomedAt) : new Date(),
       })
       .returning();
@@ -47,10 +107,37 @@ groomingLogsRouter.post(
 
 groomingLogsRouter.delete("/:id", async (c) => {
   const db = getDb();
-  const [row] = await db
+  const id = c.req.param("id");
+  const staffRow = c.get("staff");
+  const isGroomer = staffRow?.role === "groomer";
+
+  const [log] = await db
+    .select()
+    .from(groomingVisitLogs)
+    .where(eq(groomingVisitLogs.id, id))
+    .limit(1);
+  if (!log) return c.json({ error: "Not found" }, 404);
+
+  if (isGroomer) {
+    const [appt] = await db
+      .select({ id: appointments.id })
+      .from(appointments)
+      .where(
+        and(
+          eq(appointments.petId, log.petId),
+          or(
+            eq(appointments.staffId, staffRow.id),
+            eq(appointments.batherStaffId, staffRow.id)
+          )
+        )
+      )
+      .limit(1);
+    if (!appt) return c.json({ error: "Forbidden" }, 403);
+  }
+
+  await db
     .delete(groomingVisitLogs)
-    .where(eq(groomingVisitLogs.id, c.req.param("id")))
+    .where(eq(groomingVisitLogs.id, id))
     .returning();
-  if (!row) return c.json({ error: "Not found" }, 404);
   return c.json({ ok: true });
 });

apps/api/src/routes/invoices.ts

@@ -8,13 +8,24 @@ import {
   invoices,
   invoiceLineItems,
   invoiceTipSplits,
+  refunds,
   appointments,
   services,
   clients,
   sql,
 } from "@groombook/db";
+import type { AppEnv, StaffRole } from "../middleware/rbac.js";
+import { requireRole } from "../middleware/rbac.js";
 
-export const invoicesRouter = new Hono();
+export const invoicesRouter = new Hono<AppEnv>();
+
+// Convert Zod validation errors from 422 to 400
+invoicesRouter.onError((err, c) => {
+  if (err instanceof z.ZodError) {
+    return c.json({ error: "Validation failed", issues: err.issues }, 400);
+  }
+  throw err;
+});
 
 const createInvoiceSchema = z.object({
   appointmentId: z.string().uuid().optional(),
@@ -40,56 +51,73 @@ const updateInvoiceSchema = z.object({
   taxCents: z.number().int().nonnegative().optional(),
   tipCents: z.number().int().nonnegative().optional(),
   notes: z.string().max(2000).nullable().optional(),
+  tipSplits: z.array(
+    z.object({
+      staffId: z.string().uuid().nullable(),
+      staffName: z.string().min(1).max(200),
+      sharePct: z.number().min(0).max(100),
+    })
+  ).optional(),
 });
 
 // List invoices
-invoicesRouter.get("/", async (c) => {
-  const db = getDb();
-  const clientId = c.req.query("clientId");
-  const appointmentId = c.req.query("appointmentId");
-  const status = c.req.query("status");
-  const limit = Math.min(parseInt(c.req.query("limit") || "50", 10), 200);
-  const offset = parseInt(c.req.query("offset") || "0", 10);
-
-  const conditions = [];
-  if (clientId) conditions.push(eq(invoices.clientId, clientId));
-  if (appointmentId) conditions.push(eq(invoices.appointmentId, appointmentId));
-  if (status) conditions.push(eq(invoices.status, status as "draft" | "pending" | "paid" | "void"));
-
-  const whereClause = conditions.length > 0 ? and(...conditions) : undefined;
-
-  const [totalResult] = await db
-    .select({ count: sql<number>`count(*)` })
-    .from(invoices)
-    .where(whereClause);
-
-  const rows = await db
-    .select({
-      id: invoices.id,
-      appointmentId: invoices.appointmentId,
-      clientId: invoices.clientId,
-      clientName: clients.name,
-      subtotalCents: invoices.subtotalCents,
-      taxCents: invoices.taxCents,
-      tipCents: invoices.tipCents,
-      totalCents: invoices.totalCents,
-      status: invoices.status,
-      paymentMethod: invoices.paymentMethod,
-      paidAt: invoices.paidAt,
-      notes: invoices.notes,
-      createdAt: invoices.createdAt,
-      updatedAt: invoices.updatedAt,
-    })
-    .from(invoices)
-    .leftJoin(clients, eq(invoices.clientId, clients.id))
-    .where(whereClause)
-    .orderBy(invoices.createdAt)
-    .limit(limit)
-    .offset(offset);
-
-  return c.json({ data: rows, total: totalResult?.count ?? 0 });
+const listInvoicesQuerySchema = z.object({
+  clientId: z.string().uuid().optional(),
+  appointmentId: z.string().uuid().optional(),
+  status: z.enum(["draft", "pending", "paid", "void"]).optional(),
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+  offset: z.coerce.number().int().min(0).default(0),
 });
 
+invoicesRouter.get(
+  "/",
+  zValidator("query", listInvoicesQuerySchema),
+  async (c) => {
+    const db = getDb();
+    const { clientId, appointmentId, status, limit, offset } = c.req.valid("query");
+
+    const conditions = [];
+    if (clientId) conditions.push(eq(invoices.clientId, clientId));
+    if (appointmentId) conditions.push(eq(invoices.appointmentId, appointmentId));
+    if (status) conditions.push(eq(invoices.status, status as "draft" | "pending" | "paid" | "void"));
+
+    const whereClause = conditions.length > 0 ? and(...conditions) : undefined;
+
+    const [totalResult] = await db
+      .select({ count: sql<number>`count(*)` })
+      .from(invoices)
+      .where(whereClause);
+
+    const rows = await db
+      .select({
+        id: invoices.id,
+        appointmentId: invoices.appointmentId,
+        clientId: invoices.clientId,
+        clientName: clients.name,
+        subtotalCents: invoices.subtotalCents,
+        taxCents: invoices.taxCents,
+        tipCents: invoices.tipCents,
+        totalCents: invoices.totalCents,
+        status: invoices.status,
+        paymentMethod: invoices.paymentMethod,
+        paidAt: invoices.paidAt,
+        notes: invoices.notes,
+        stripePaymentIntentId: invoices.stripePaymentIntentId,
+        stripeRefundId: invoices.stripeRefundId,
+        createdAt: invoices.createdAt,
+        updatedAt: invoices.updatedAt,
+      })
+      .from(invoices)
+      .leftJoin(clients, eq(invoices.clientId, clients.id))
+      .where(whereClause)
+      .orderBy(invoices.createdAt)
+      .limit(limit)
+      .offset(offset);
+
+    return c.json({ data: rows, total: totalResult?.count ?? 0 });
+  }
+);
+
 // Get single invoice with line items and tip splits
 invoicesRouter.get("/:id", async (c) => {
   const db = getDb();
@@ -103,7 +131,17 @@ invoicesRouter.get("/:id", async (c) => {
     db.select().from(invoiceTipSplits).where(eq(invoiceTipSplits.invoiceId, id)),
   ]);
 
-  return c.json({ ...invoice, lineItems, tipSplits });
+  let cardLast4: string | null = null;
+  let paymentStatus: string | null = null;
+  if (invoice.stripePaymentIntentId) {
+    const details = await getPaymentIntentDetails(invoice.stripePaymentIntentId);
+    if (details) {
+      cardLast4 = details.cardLast4;
+      paymentStatus = details.paymentStatus;
+    }
+  }
+
+  return c.json({ ...invoice, lineItems, tipSplits, cardLast4, paymentStatus });
 });
 
 // Save tip splits for an invoice (replaces existing splits)
@@ -116,8 +154,8 @@ const tipSplitSchema = z.object({
     })
   ).min(1).refine(
     (splits) => {
-      const total = splits.reduce((sum, s) => sum + s.sharePct, 0);
-      return Math.abs(total - 100) < 0.01;
+      const totalBps = splits.reduce((sum, s) => sum + Math.round(s.sharePct * 100), 0);
+      return totalBps === 10000;
     },
     { message: "Split percentages must sum to 100" }
   ),
@@ -161,12 +199,13 @@ invoicesRouter.post(
       }
     });
 
-    const splits = await db
-      .select()
-      .from(invoiceTipSplits)
-      .where(eq(invoiceTipSplits.invoiceId, id));
+    const [updatedInvoice] = await db.select().from(invoices).where(eq(invoices.id, id));
+    const [lineItems, tipSplits] = await Promise.all([
+      db.select().from(invoiceLineItems).where(eq(invoiceLineItems.invoiceId, id)),
+      db.select().from(invoiceTipSplits).where(eq(invoiceTipSplits.invoiceId, id)),
+    ]);
 
-    return c.json(splits, 201);
+    return c.json({ ...updatedInvoice, lineItems, tipSplits }, 201);
   }
 );
 
@@ -291,6 +330,13 @@ invoicesRouter.post("/from-appointment/:appointmentId", async (c) => {
   return c.json({ ...invoice, lineItems: [lineItem] }, 201);
 });
 
+const ALLOWED_TRANSITIONS: Record<string, string[]> = {
+  draft: ["pending", "void"],
+  pending: ["draft", "paid", "void"],
+  paid: ["void"],
+  void: [],
+};
+
 // Update invoice
 invoicesRouter.patch(
   "/:id",
@@ -306,11 +352,33 @@ invoicesRouter.patch(
       .where(eq(invoices.id, id));
     if (!current) return c.json({ error: "Not found" }, 404);
 
-    if (current.status === "void") {
-      return c.json({ error: "Cannot modify a voided invoice" }, 422);
+    if (body.status !== undefined) {
+      const allowed = ALLOWED_TRANSITIONS[current.status] ?? [];
+      if (!allowed.includes(body.status)) {
+        return c.json(
+          { error: `Invalid status transition from ${current.status} to ${body.status}` },
+          422
+        );
+      }
     }
 
-    const update: Record<string, unknown> = { ...body, updatedAt: new Date() };
+    const tipCents = body.tipCents ?? current.tipCents;
+
+    // Validate tip splits when marking invoice as paid
+    if (body.status === "paid" && tipCents > 0 && body.tipSplits !== undefined) {
+      if (body.tipSplits.length === 0) {
+        return c.json({ error: "Tip splits are required when tip amount is greater than zero" }, 400);
+      }
+      const totalPct = body.tipSplits.reduce((sum, s) => sum + s.sharePct, 0);
+      if (Math.abs(totalPct - 100) > 0.01) {
+        return c.json({ error: "Tip split percentages must sum to 100%" }, 400);
+      }
+    }
+
+    // Destructure tipSplits out — it belongs to a separate table, not the invoices column
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { tipSplits: _tipSplits, ...updateBody } = body as Record<string, unknown>;
+    const update: Record<string, unknown> = { ...updateBody, updatedAt: new Date() };
 
     // Auto-set paidAt when marking as paid
     if (body.status === "paid" && !body.paidAt && !current.paidAt) {
@@ -324,17 +392,177 @@ invoicesRouter.patch(
       update.totalCents = current.subtotalCents + newTaxCents + newTipCents;
     }
 
-    const [updated] = await db
-      .update(invoices)
-      .set(update)
-      .where(eq(invoices.id, id))
-      .returning();
+    // Wrap tip split persistence and invoice update in a single atomic transaction
+    const [updated, lineItems] = await db.transaction(async (tx) => {
+      if (body.status === "paid" && tipCents > 0 && body.tipSplits !== undefined) {
+        await tx.delete(invoiceTipSplits).where(eq(invoiceTipSplits.invoiceId, id));
+        const splits = body.tipSplits;
+        if (splits.length > 0) {
+          let remaining = tipCents;
+          const rows = splits.map((s, i) => {
+            const isLast = i === splits.length - 1;
+            const shareCents = isLast ? remaining : Math.round((s.sharePct / 100) * tipCents);
+            if (!isLast) remaining -= shareCents;
+            return {
+              invoiceId: id,
+              staffId: s.staffId,
+              staffName: s.staffName,
+              sharePct: s.sharePct.toFixed(2),
+              shareCents,
+            };
+          });
+          await tx.insert(invoiceTipSplits).values(rows);
+        }
+      }
 
-    const lineItems = await db
-      .select()
-      .from(invoiceLineItems)
-      .where(eq(invoiceLineItems.invoiceId, id));
+      const [updatedInvoice] = await tx
+        .update(invoices)
+        .set(update)
+        .where(eq(invoices.id, id))
+        .returning();
+
+      const lineItems = await tx
+        .select()
+        .from(invoiceLineItems)
+        .where(eq(invoiceLineItems.invoiceId, id));
+
+      return [updatedInvoice, lineItems];
+    });
 
     return c.json({ ...updated, lineItems });
   }
 );
+
+// ─── Refund ───────────────────────────────────────────────────────────────────
+
+import { processRefund, getPaymentIntentDetails } from "../services/payment.js";
+
+const refundSchema = z.object({
+  amountCents: z.number().int().nonnegative().optional(),
+  idempotencyKey: z.string().max(255).optional(),
+});
+
+invoicesRouter.post(
+  "/:id/refund",
+  zValidator("json", refundSchema),
+  async (c) => {
+    const db = getDb();
+    const staff = c.get("staff");
+    if (!staff) return c.json({ error: "Forbidden" }, 403);
+    if (staff.role !== "manager" && !staff.isSuperUser) {
+      return c.json({ error: "Manager role required" }, 403);
+    }
+
+    const id = c.req.param("id");
+    const body = c.req.valid("json");
+
+    const [invoice] = await db.select().from(invoices).where(eq(invoices.id, id));
+    if (!invoice) return c.json({ error: "Not found" }, 404);
+    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) {
+        const [existing] = await tx
+          .select()
+          .from(refunds)
+          .where(eq(refunds.idempotencyKey, body.idempotencyKey));
+        if (existing) {
+          return c.json({ refundId: existing.stripeRefundId });
+        }
+      }
+
+      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,
+        stripeRefundId: refundId,
+        idempotencyKey: body.idempotencyKey ?? null,
+        amountCents: body.amountCents ?? null,
+      });
+
+      return c.json({ refundId });
+    });
+  }
+);
+
+// Payment stats for admin dashboard
+invoicesRouter.get("/stats/summary", requireRole("manager" as StaffRole), async (c) => {
+  try {
+    const db = getDb();
+    const now = new Date();
+    const startOfMonth = new Date(now.getFullYear(), now.getMonth(), 1);
+
+    const [revenueResult] = await db
+      .select({ total: sql<number>`coalesce(sum(total_cents), 0)` })
+      .from(invoices)
+      .where(and(eq(invoices.status, "paid"), sql`${invoices.paidAt} >= ${startOfMonth}`));
+
+    const [outstandingResult] = await db
+      .select({ total: sql<number>`coalesce(sum(total_cents), 0)` })
+      .from(invoices)
+      .where(eq(invoices.status, "pending"));
+
+    const [refundsResult] = await db
+      .select({ total: sql<number>`coalesce(sum(amount_cents), 0)` })
+      .from(refunds)
+      .where(sql`${refunds.createdAt} >= ${startOfMonth}`);
+
+    const methodBreakdown = await db
+      .select({
+        method: invoices.paymentMethod,
+        total: sql<number>`count(*)`,
+      })
+      .from(invoices)
+      .where(and(eq(invoices.status, "paid"), sql`${invoices.paidAt} >= ${startOfMonth}`))
+      .groupBy(invoices.paymentMethod);
+
+    return c.json({
+      revenueThisMonth: revenueResult?.total ?? 0,
+      outstanding: outstandingResult?.total ?? 0,
+      refundsThisMonth: refundsResult?.total ?? 0,
+      methodBreakdown,
+    });
+  } catch (err) {
+    console.error("stats/summary error:", err);
+    return c.json({
+      revenueThisMonth: 0,
+      outstanding: 0,
+      refundsThisMonth: 0,
+      methodBreakdown: [],
+    });
+  }
+});
+
+// Get Stripe payment details for an invoice (card last4, payment status, refund status)
+invoicesRouter.get("/:id/stripe-details", async (c) => {
+  const db = getDb();
+  const id = c.req.param("id");
+
+  const [invoice] = await db.select().from(invoices).where(eq(invoices.id, id));
+  if (!invoice) return c.json({ error: "Not found" }, 404);
+
+  let cardLast4: string | null = null;
+  let paymentStatus: string | null = null;
+
+  if (invoice.stripePaymentIntentId) {
+    const details = await getPaymentIntentDetails(invoice.stripePaymentIntentId);
+    if (details) {
+      cardLast4 = details.cardLast4;
+      paymentStatus = details.paymentStatus;
+    }
+  }
+
+  return c.json({
+    stripePaymentIntentId: invoice.stripePaymentIntentId,
+    stripeRefundId: invoice.stripeRefundId,
+    cardLast4,
+    paymentStatus,
+  });
+});

apps/api/src/routes/pets.ts

@@ -213,7 +213,11 @@ petsRouter.post(
 
     // Delete the previous photo from storage to avoid orphaned objects
     if (pet.photoKey) {
-      await deleteObject(pet.photoKey);
+      try {
+        await deleteObject(pet.photoKey);
+      } catch (err) {
+        console.warn(`Failed to delete previous photo ${pet.photoKey}, orphaned object may remain:`, err);
+      }
     }
 
     const [row] = await db
@@ -240,7 +244,11 @@ petsRouter.delete("/:petId/photo", async (c) => {
   if (!pet) return c.json({ error: "Pet not found" }, 404);
   if (!pet.photoKey) return c.json({ error: "No photo on file" }, 404);
 
-  await deleteObject(pet.photoKey);
+  try {
+    await deleteObject(pet.photoKey);
+  } catch (err) {
+    console.warn(`Failed to delete photo ${pet.photoKey} from S3, orphaned object may remain:`, err);
+  }
   await db
     .update(pets)
     .set({ photoKey: null, photoUploadedAt: null, updatedAt: new Date() })

apps/api/src/routes/portal.ts

@@ -1,33 +1,84 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { and, eq, inArray } from "@groombook/db";
-import { getDb, appointments, impersonationSessions, waitlistEntries, clients, pets, services, staff, invoices, invoiceLineItems } from "@groombook/db";
-import type { AppEnv } from "../middleware/rbac.js";
+import { and, eq, inArray, desc, lt } from "@groombook/db";
+import { getDb, appointments, impersonationSessions, waitlistEntries, clients, pets, services, staff, invoices, invoiceLineItems, businessSettings, conversations, messages } from "@groombook/db";
+import { validatePortalSession } from "../middleware/portalSession.js";
+import { portalAudit } from "../middleware/portalAudit.js";
+import type { PortalEnv } from "../middleware/portalSession.js";
 
-export const portalRouter = new Hono<AppEnv>();
+export const portalRouter = new Hono<PortalEnv>();
 
-// ─── Session helper ───────────────────────────────────────────────────────────
+// Dev-mode session creation — must be registered BEFORE the /* middleware so it is
+// NOT subject to validatePortalSession/portalAudit (GRO-778 fix). This endpoint creates
+// the impersonation session and has no X-Impersonation-Session-Id header yet.
+const devSessionSchema = z.object({
+  clientId: z.string().uuid(),
+});
 
-async function getClientIdFromSession(sessionId: string | null | undefined): Promise<string | null> {
-  if (!sessionId) return null;
-  const db = getDb();
-  const [session] = await db
-    .select()
-    .from(impersonationSessions)
-    .where(and(eq(impersonationSessions.id, sessionId), eq(impersonationSessions.status, "active")))
-    .limit(1);
-  if (!session || session.expiresAt <= new Date()) return null;
-  return session.clientId;
-}
+portalRouter.post(
+  "/dev-session",
+  zValidator("json", devSessionSchema),
+  async (c) => {
+    if (process.env.AUTH_DISABLED !== "true") {
+      return c.json({ error: "Not available when auth is enabled" }, 403);
+    }
+
+    const db = getDb();
+    const body = c.req.valid("json");
+
+    const [client] = await db
+      .select()
+      .from(clients)
+      .where(eq(clients.id, body.clientId))
+      .limit(1);
+    if (!client) {
+      return c.json({ error: "Client not found" }, 404);
+    }
+
+    const DEMO_STAFF_ID = "00000000-0000-0000-0000-000000000001";
+
+    let staffId = DEMO_STAFF_ID;
+    const [demoStaff] = await db
+      .select({ id: staff.id })
+      .from(staff)
+      .where(eq(staff.id, DEMO_STAFF_ID))
+      .limit(1);
+
+    if (!demoStaff) {
+      const [firstStaff] = await db
+        .select({ id: staff.id })
+        .from(staff)
+        .where(eq(staff.active, true))
+        .limit(1);
+      if (!firstStaff) {
+        return c.json({ error: "No staff records found. Run the database seed." }, 500);
+      }
+      staffId = firstStaff.id;
+    }
+
+    const [session] = await db
+      .insert(impersonationSessions)
+      .values({
+        staffId,
+        clientId: body.clientId,
+        reason: "dev-mode-client-portal",
+        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
+      })
+      .returning();
+
+    return c.json(session, 201);
+  }
+);
+
+// Apply middleware to all portal routes
+portalRouter.use("/*", validatePortalSession, portalAudit);
 
 // ─── GET routes ──────────────────────────────────────────────────────────────
 
 portalRouter.get("/me", async (c) => {
   const db = getDb();
-  const sessionId = c.req.header("X-Impersonation-Session-Id");
-  const clientId = await getClientIdFromSession(sessionId);
-  if (!clientId) return c.json({ error: "Unauthorized" }, 401);
+  const clientId = c.get("portalClientId");
 
   const [client] = await db.select().from(clients).where(eq(clients.id, clientId)).limit(1);
   if (!client) return c.json({ error: "Not found" }, 404);
@@ -35,6 +86,12 @@ portalRouter.get("/me", async (c) => {
   return c.json({ id: client.id, name: client.name, email: client.email, phone: client.phone });
 });
 
+portalRouter.get("/config", async (c) => {
+  return c.json({
+    stripePublishableKey: process.env.STRIPE_PUBLISHABLE_KEY ?? "",
+  });
+});
+
 portalRouter.get("/services", async (c) => {
   const db = getDb();
   const allServices = await db.select().from(services).where(eq(services.active, true));
@@ -43,11 +100,8 @@ portalRouter.get("/services", async (c) => {
 
 portalRouter.get("/appointments", async (c) => {
   const db = getDb();
-  const sessionId = c.req.header("X-Impersonation-Session-Id");
-  const clientId = await getClientIdFromSession(sessionId);
-  if (!clientId) return c.json({ error: "Unauthorized" }, 401);
+  const clientId = c.get("portalClientId");
 
-  const now = new Date();
   const allAppts = await db
     .select({
       id: appointments.id,
@@ -87,27 +141,20 @@ portalRouter.get("/appointments", async (c) => {
     staff: a.staffId ? { id: staffMap[a.staffId]?.id, name: staffMap[a.staffId]?.name } : null,
   }));
 
-  const upcoming = appts.filter(a => a.startTime > now && a.status !== "cancelled");
-  const past = appts.filter(a => a.startTime <= now || a.status === "cancelled");
-
-  return c.json({ upcoming, past });
+  return c.json({ appointments: appts });
 });
 
 portalRouter.get("/pets", async (c) => {
   const db = getDb();
-  const sessionId = c.req.header("X-Impersonation-Session-Id");
-  const clientId = await getClientIdFromSession(sessionId);
-  if (!clientId) return c.json({ error: "Unauthorized" }, 401);
+  const clientId = c.get("portalClientId");
 
   const clientPets = await db.select().from(pets).where(eq(pets.clientId, clientId));
-  return c.json(clientPets.map(p => ({ id: p.id, name: p.name, breed: p.breed, weightKg: p.weightKg, dateOfBirth: p.dateOfBirth, photoKey: p.photoKey, groomingNotes: p.groomingNotes })));
+  return c.json(clientPets.map(p => ({ id: p.id, name: p.name, breed: p.breed, weight: p.weightKg, birthDate: p.dateOfBirth, photoUrl: p.photoKey, notes: p.groomingNotes })));
 });
 
 portalRouter.get("/invoices", async (c) => {
   const db = getDb();
-  const sessionId = c.req.header("X-Impersonation-Session-Id");
-  const clientId = await getClientIdFromSession(sessionId);
-  if (!clientId) return c.json({ error: "Unauthorized" }, 401);
+  const clientId = c.get("portalClientId");
 
   const clientInvoices = await db.select().from(invoices).where(eq(invoices.clientId, clientId));
   const invoiceIds = clientInvoices.map(i => i.id);
@@ -123,11 +170,104 @@ portalRouter.get("/invoices", async (c) => {
     id: inv.id,
     status: inv.status,
     totalCents: inv.totalCents,
-    createdAt: inv.createdAt,
+    date: inv.createdAt,
     lineItems: (itemsByInvoice[inv.id] || []).map(li => ({ id: li.id, description: li.description, quantity: li.quantity, unitPriceCents: li.unitPriceCents, totalCents: li.totalCents })),
   })));
 });
 
+// ─── Conversation routes ──────────────────────────────────────────────────────
+
+portalRouter.get("/conversation", async (c) => {
+  const db = getDb();
+  const clientId = c.get("portalClientId");
+
+  const [settings] = await db.select({ id: businessSettings.id }).from(businessSettings).limit(1);
+  if (!settings) return c.json({ error: "Business not configured" }, 500);
+  const businessId = settings.id;
+
+  const [conversation] = await db
+    .select({
+      id: conversations.id,
+      channel: conversations.channel,
+      lastMessageAt: conversations.lastMessageAt,
+      status: conversations.status,
+      createdAt: conversations.createdAt,
+    })
+    .from(conversations)
+    .where(and(eq(conversations.clientId, clientId), eq(conversations.businessId, businessId)))
+    .limit(1);
+
+  if (!conversation) {
+    return c.body(null, 204);
+  }
+
+  return c.json(conversation);
+});
+
+portalRouter.get("/conversation/messages", async (c) => {
+  const db = getDb();
+  const clientId = c.get("portalClientId");
+  const cursor = c.req.query("cursor") || undefined;
+  const limit = Math.min(Number(c.req.query("limit") || "50"), 100);
+
+  const [settings] = await db.select({ id: businessSettings.id }).from(businessSettings).limit(1);
+  if (!settings) return c.json({ error: "Business not configured" }, 500);
+  const businessId = settings.id;
+
+  const [conversation] = await db
+    .select({ id: conversations.id })
+    .from(conversations)
+    .where(and(eq(conversations.clientId, clientId), eq(conversations.businessId, businessId)))
+    .limit(1);
+
+  if (!conversation) {
+    return c.body(null, 204);
+  }
+
+  let query = db
+    .select({
+      id: messages.id,
+      direction: messages.direction,
+      body: messages.body,
+      status: messages.status,
+      createdAt: messages.createdAt,
+      deliveredAt: messages.deliveredAt,
+    })
+    .from(messages)
+    .where(eq(messages.conversationId, conversation.id))
+    .orderBy(desc(messages.createdAt))
+    .limit(limit);
+
+  if (cursor) {
+    const [cursorMsg] = await db
+      .select({ createdAt: messages.createdAt })
+      .from(messages)
+      .where(eq(messages.id, cursor))
+      .limit(1);
+    if (cursorMsg) {
+      query = db
+        .select({
+          id: messages.id,
+          direction: messages.direction,
+          body: messages.body,
+          status: messages.status,
+          createdAt: messages.createdAt,
+          deliveredAt: messages.deliveredAt,
+        })
+        .from(messages)
+        .where(and(eq(messages.conversationId, conversation.id), lt(messages.createdAt, cursorMsg.createdAt)))
+        .orderBy(desc(messages.createdAt))
+        .limit(limit);
+    }
+  }
+
+  const messagesResult = await query;
+
+  const nextCursor = messagesResult.length === limit ? messagesResult[messagesResult.length - 1]!.id : null;
+
+  return c.json({ messages: messagesResult, nextCursor });
+});
+
 // ─── Appointment action routes ────────────────────────────────────────────────
 
 const customerNotesSchema = z.object({
@@ -142,12 +282,7 @@ portalRouter.patch(
     const db = getDb();
     const id = c.req.param("id");
     const body = c.req.valid("json");
-
-    const sessionId = c.req.header("X-Impersonation-Session-Id");
-    const clientId = await getClientIdFromSession(sessionId);
-    if (!clientId) {
-      return c.json({ error: "Unauthorized" }, 401);
-    }
+    const clientId = c.get("portalClientId");
 
     const [appt] = await db
       .select()
@@ -190,12 +325,7 @@ portalRouter.patch(
 portalRouter.post("/appointments/:id/confirm", async (c) => {
   const db = getDb();
   const id = c.req.param("id");
-
-  const sessionId = c.req.header("X-Impersonation-Session-Id");
-  const clientId = await getClientIdFromSession(sessionId);
-  if (!clientId) {
-    return c.json({ error: "Unauthorized" }, 401);
-  }
+  const clientId = c.get("portalClientId");
 
   const [appt] = await db
     .select()
@@ -244,12 +374,7 @@ portalRouter.post("/appointments/:id/confirm", async (c) => {
 portalRouter.post("/appointments/:id/cancel", async (c) => {
   const db = getDb();
   const id = c.req.param("id");
-
-  const sessionId = c.req.header("X-Impersonation-Session-Id");
-  const clientId = await getClientIdFromSession(sessionId);
-  if (!clientId) {
-    return c.json({ error: "Unauthorized" }, 401);
-  }
+  const clientId = c.get("portalClientId");
 
   const [appt] = await db
     .select()
@@ -313,28 +438,7 @@ portalRouter.post(
   async (c) => {
     const db = getDb();
     const body = c.req.valid("json");
-    const sessionId = c.req.header("X-Impersonation-Session-Id");
-
-    let clientId: string | null = null;
-    if (sessionId) {
-      const [session] = await db
-        .select()
-        .from(impersonationSessions)
-        .where(
-          and(
-            eq(impersonationSessions.id, sessionId),
-            eq(impersonationSessions.status, "active")
-          )
-        )
-        .limit(1);
-      if (session && session.expiresAt > new Date()) {
-        clientId = session.clientId;
-      }
-    }
-
-    if (!clientId) {
-      return c.json({ error: "Unauthorized" }, 401);
-    }
+    const clientId = c.get("portalClientId");
 
     const [entry] = await db
       .insert(waitlistEntries)
@@ -358,26 +462,7 @@ portalRouter.patch(
     const db = getDb();
     const id = c.req.param("id");
     const body = c.req.valid("json");
-    const sessionId = c.req.header("X-Impersonation-Session-Id");
-
-    if (!sessionId) {
-      return c.json({ error: "Unauthorized" }, 401);
-    }
-
-    const [session] = await db
-      .select()
-      .from(impersonationSessions)
-      .where(
-        and(
-          eq(impersonationSessions.id, sessionId),
-          eq(impersonationSessions.status, "active")
-        )
-      )
-      .limit(1);
-
-    if (!session || session.expiresAt <= new Date()) {
-      return c.json({ error: "Unauthorized" }, 401);
-    }
+    const clientId = c.get("portalClientId");
 
     const [existing] = await db
       .select()
@@ -386,7 +471,7 @@ portalRouter.patch(
       .limit(1);
 
     if (!existing) return c.json({ error: "Not found" }, 404);
-    if (existing.clientId !== session.clientId) {
+    if (existing.clientId !== clientId) {
       return c.json({ error: "Forbidden" }, 403);
     }
 
@@ -408,26 +493,7 @@ portalRouter.patch(
 portalRouter.delete("/waitlist/:id", async (c) => {
   const db = getDb();
   const id = c.req.param("id");
-  const sessionId = c.req.header("X-Impersonation-Session-Id");
-
-  if (!sessionId) {
-    return c.json({ error: "Unauthorized" }, 401);
-  }
-
-  const [session] = await db
-    .select()
-    .from(impersonationSessions)
-    .where(
-      and(
-        eq(impersonationSessions.id, sessionId),
-        eq(impersonationSessions.status, "active")
-      )
-    )
-    .limit(1);
-
-  if (!session || session.expiresAt <= new Date()) {
-    return c.json({ error: "Unauthorized" }, 401);
-  }
+  const clientId = c.get("portalClientId");
 
   const [entry] = await db
     .select()
@@ -436,7 +502,7 @@ portalRouter.delete("/waitlist/:id", async (c) => {
     .limit(1);
 
   if (!entry) return c.json({ error: "Not found" }, 404);
-  if (entry.clientId !== session.clientId) {
+  if (entry.clientId !== clientId) {
     return c.json({ error: "Forbidden" }, 403);
   }
 
@@ -448,71 +514,101 @@ portalRouter.delete("/waitlist/:id", async (c) => {
   return c.json({ ok: true });
 });
 
-// ─── Dev-mode session creation ──────────────────────────────────────────────
-// Allows the dev login selector to vend an impersonation session for a client
-// without requiring manager auth. Only available when AUTH_DISABLED=true.
+// ─── Payment routes ───────────────────────────────────────────────────────────
 
-const devSessionSchema = z.object({
-  clientId: z.string().uuid(),
+import {
+  createPaymentIntent,
+  listPaymentMethods,
+  detachPaymentMethod,
+  createSetupIntent,
+  getOrCreateStripeCustomer,
+  getStripeClient,
+} from "../services/payment.js";
+
+const payMultipleSchema = z.object({
+  invoiceIds: z.array(z.string().uuid()).min(1),
 });
 
 portalRouter.post(
-  "/dev-session",
-  zValidator("json", devSessionSchema),
+  "/invoices/pay-multiple",
+  zValidator("json", payMultipleSchema),
   async (c) => {
-    if (process.env.AUTH_DISABLED !== "true") {
-      return c.json({ error: "Not available when auth is enabled" }, 403);
-    }
-
     const db = getDb();
     const body = c.req.valid("json");
+    const clientId = c.get("portalClientId");
 
-    // Verify client exists
-    const [client] = await db
+    const invoiceRows = await db
       .select()
-      .from(clients)
-      .where(eq(clients.id, body.clientId))
-      .limit(1);
-    if (!client) {
-      return c.json({ error: "Client not found" }, 404);
+      .from(invoices)
+      .where(inArray(invoices.id, body.invoiceIds));
+
+    if (invoiceRows.length !== body.invoiceIds.length) {
+      return c.json({ error: "One or more invoices not found" }, 404);
     }
 
-    // Find a staff record to associate with the dev impersonation session.
-    // Use the demo-manager if it exists (created by seed with known ID),
-    // otherwise fall back to the first active staff record.
-    // This avoids hardcoding a UUID that may not exist in all environments.
-    const DEMO_STAFF_ID = "00000000-0000-0000-0000-000000000001";
-
-    let staffId = DEMO_STAFF_ID;
-    const [demoStaff] = await db
-      .select({ id: staff.id })
-      .from(staff)
-      .where(eq(staff.id, DEMO_STAFF_ID))
-      .limit(1);
-
-    if (!demoStaff) {
-      // Fall back to any active staff member
-      const [firstStaff] = await db
-        .select({ id: staff.id })
-        .from(staff)
-        .where(eq(staff.active, true))
-        .limit(1);
-      if (!firstStaff) {
-        return c.json({ error: "No staff records found. Run the database seed." }, 500);
+    for (const inv of invoiceRows) {
+      if (inv.clientId !== clientId) return c.json({ error: "Forbidden" }, 403);
+      if (inv.status === "draft" || inv.status === "void") {
+        return c.json({ error: `Invoice ${inv.id} cannot be paid (draft or void)` }, 422);
+      }
+      if (inv.status === "paid") {
+        return c.json({ error: `Invoice ${inv.id} is already paid` }, 422);
       }
-      staffId = firstStaff.id;
     }
 
-    const [session] = await db
-      .insert(impersonationSessions)
-      .values({
-        staffId,
-        clientId: body.clientId,
-        reason: "dev-mode-client-portal",
-        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
-      })
-      .returning();
+    const firstInvoice = invoiceRows[0];
+    if (!firstInvoice) return c.json({ error: "No invoices found" }, 400);
+    const allSameClient = invoiceRows.every(inv => inv.clientId === firstInvoice.clientId);
+    if (!allSameClient) {
+      return c.json({ error: "All invoices must belong to the same client" }, 422);
+    }
 
-    return c.json(session, 201);
+    const stripePublishableKey = process.env.STRIPE_PUBLISHABLE_KEY ?? "";
+    const result = await createPaymentIntent(body.invoiceIds, clientId);
+    if (!result) return c.json({ error: "Payment service unavailable" }, 503);
+
+    return c.json({ clientSecret: result.clientSecret, publishableKey: stripePublishableKey });
   }
-);
+);
+
+portalRouter.get("/payment-methods", async (c) => {
+  const clientId = c.get("portalClientId");
+
+  const methods = await listPaymentMethods(clientId);
+  if (methods === null) return c.json({ error: "Payment service unavailable" }, 503);
+  return c.json(methods);
+});
+
+portalRouter.post("/payment-methods", async (c) => {
+  const clientId = c.get("portalClientId");
+
+  const stripePublishableKey = process.env.STRIPE_PUBLISHABLE_KEY ?? "";
+  const customerId = await getOrCreateStripeCustomer(clientId);
+  if (!customerId) return c.json({ error: "Could not create customer" }, 500);
+
+  const result = await createSetupIntent(customerId);
+  if (!result) return c.json({ error: "Payment service unavailable" }, 503);
+
+  return c.json({ clientSecret: result.clientSecret, publishableKey: stripePublishableKey });
+});
+
+portalRouter.delete("/payment-methods/:id", async (c) => {
+  const clientId = c.get("portalClientId");
+
+  const paymentMethodId = c.req.param("id");
+
+  const stripeCustomerId = await getOrCreateStripeCustomer(clientId);
+  if (!stripeCustomerId) return c.json({ error: "No payment method found" }, 404);
+
+  const stripe = getStripeClient();
+  if (!stripe) return c.json({ error: "Payment service unavailable" }, 503);
+
+  const paymentMethod = await stripe.paymentMethods.retrieve(paymentMethodId);
+  if (!paymentMethod || paymentMethod.customer !== stripeCustomerId) {
+    return c.json({ error: "Payment method not found" }, 404);
+  }
+
+  const ok = await detachPaymentMethod(paymentMethodId);
+  if (!ok) return c.json({ error: "Failed to detach payment method" }, 500);
+  return c.json({ ok: true });
+});

apps/api/src/routes/reports.ts

@@ -286,6 +286,10 @@ reportsRouter.get("/clients", async (c) => {
   ninetyDaysAgo.setUTCDate(ninetyDaysAgo.getUTCDate() - 90);
   const ninetyDaysAgoISO = ninetyDaysAgo.toISOString();
 
+  const page = Math.max(1, parseInt(c.req.query("page") ?? "1", 10) || 1);
+  const limit = Math.min(100, Math.max(1, parseInt(c.req.query("limit") ?? "20", 10) || 20));
+  const offset = (page - 1) * limit;
+
   const churnRisk = await db
     .select({
       clientId: clients.id,
@@ -298,15 +302,34 @@ reportsRouter.get("/clients", async (c) => {
     .having(
       sql`MAX(${appointments.startTime}) < ${ninetyDaysAgoISO}::timestamptz OR MAX(${appointments.startTime}) IS NULL`
     )
-    .orderBy(sql`MAX(${appointments.startTime}) ASC NULLS FIRST`);
+    .orderBy(sql`MAX(${appointments.startTime}) ASC NULLS FIRST`)
+    .limit(limit)
+    .offset(offset);
+
+  const [churnCountRow] = await db
+    .select({ total: sql<number>`count(*)::int` })
+    .from(
+      db
+        .select({ id: clients.id })
+        .from(clients)
+        .leftJoin(appointments, eq(appointments.clientId, clients.id))
+        .groupBy(clients.id)
+        .having(
+          sql`MAX(${appointments.startTime}) < ${ninetyDaysAgoISO}::timestamptz OR MAX(${appointments.startTime}) IS NULL`
+        )
+        .as("churn_count")
+    );
+  const churnRiskTotal = churnCountRow?.total ?? 0;
 
   return c.json({
     from: from.toISOString(),
     to: to.toISOString(),
     newClients,
     activeInPeriodCount: activeInPeriod.length,
-    churnRisk: churnRisk.slice(0, 20), // top 20 at-risk clients
-    churnRiskTotal: churnRisk.length,
+    churnRisk,
+    churnRiskTotal,
+    page,
+    limit,
   });
 });
 

apps/api/src/routes/services.ts

@@ -9,7 +9,7 @@ const createServiceSchema = z.object({
   name: z.string().min(1).max(200),
   description: z.string().max(2000).optional(),
   basePriceCents: z.number().int().positive(),
-  durationMinutes: z.number().int().positive(),
+  durationMinutes: z.number().int().positive().max(480),
   active: z.boolean().default(true),
 });
 

apps/api/src/routes/settings.ts

@@ -2,7 +2,7 @@ import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
 import { eq, getDb, businessSettings } from "@groombook/db";
-import { getPresignedUploadUrl, getPresignedGetUrl, deleteObject } from "../lib/s3.js";
+import { getPresignedUploadUrl, deleteObject, putObject, getObject } from "../lib/s3.js";
 import { requireSuperUser } from "../middleware/rbac.js";
 
 export const settingsRouter = new Hono();
@@ -100,6 +100,77 @@ settingsRouter.post(
   }
 );
 
+/**
+ * POST /api/admin/settings/logo/upload
+ * Proxy upload through the API server to avoid mixed-content issues with
+ * pre-signed URLs that use the internal HTTP endpoint. The file is uploaded
+ * directly to S3 from the server using the internal endpoint.
+ */
+settingsRouter.post("/logo/upload", requireSuperUser(), async (c) => {
+  const db = getDb();
+
+  // Parse multipart form data (file field)
+  const body = await c.req.parseBody({ all: true });
+  const file = body["file"];
+
+  if (!file || !(file instanceof File)) {
+    return c.json({ error: "No file provided" }, 400);
+  }
+
+  const contentType = file.type;
+  if (!ALLOWED_LOGO_TYPES.has(contentType)) {
+    return c.json(
+      {
+        error:
+          "contentType must be one of: image/png, image/svg+xml, image/jpeg, image/webp",
+      },
+      400
+    );
+  }
+
+  const fileSizeBytes = file.size;
+  if (fileSizeBytes > MAX_LOGO_SIZE) {
+    return c.json({ error: "File must not exceed 512 KB" }, 400);
+  }
+
+  const rows = await db.select().from(businessSettings).limit(1);
+  if (!rows[0]) {
+    return c.json({ error: "Settings not found" }, 404);
+  }
+  const settingsId = rows[0].id;
+
+  const ext = contentType.split("/")[1] ?? "png";
+  const key = `logos/${settingsId}/${Date.now()}.${ext}`;
+
+  // Read file into buffer and upload directly to S3 (bypasses pre-signed URL)
+  const arrayBuffer = await file.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+  await putObject(key, buffer, contentType, fileSizeBytes);
+
+  // Delete previous S3 object if any
+  if (rows[0].logoKey) {
+    await deleteObject(rows[0].logoKey);
+  }
+
+  // Update database with new logo key
+  const [updated] = await db
+    .update(businessSettings)
+    .set({
+      logoKey: key,
+      logoBase64: null,
+      logoMimeType: null,
+      updatedAt: new Date(),
+    })
+    .where(eq(businessSettings.id, settingsId))
+    .returning();
+
+  if (!updated) {
+    return c.json({ error: "Settings not found" }, 404);
+  }
+
+  return c.json({ ok: true, logoKey: updated.logoKey });
+});
+
 /**
  * POST /api/admin/settings/logo/confirm
  * Called after the client has successfully uploaded to the presigned URL.
@@ -144,7 +215,8 @@ settingsRouter.post(
 
 /**
  * GET /api/admin/settings/logo
- * Returns a presigned GET URL for the logo.
+ * Proxies the logo from S3 so the browser never sees an S3 URL.
+ * Returns the image bytes with proper Content-Type.
  */
 settingsRouter.get("/logo", async (c) => {
   const db = getDb();
@@ -153,8 +225,14 @@ settingsRouter.get("/logo", async (c) => {
   if (!row) return c.json({ error: "Settings not found" }, 404);
   if (!row.logoKey) return c.json({ error: "No logo on file" }, 404);
 
-  const url = await getPresignedGetUrl(row.logoKey);
-  return c.json({ url, logoKey: row.logoKey });
+  const { body, contentType } = await getObject(row.logoKey);
+  return new Response(Buffer.from(body), {
+    status: 200,
+    headers: {
+      "Content-Type": contentType,
+      "Cache-Control": "public, max-age=86400",
+    },
+  });
 });
 
 /**

apps/api/src/routes/setup.ts

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

apps/api/src/routes/staff.ts

@@ -18,6 +18,10 @@ const createStaffSchema = z.object({
 
 const updateStaffSchema = createStaffSchema.partial().omit({ email: true });
 
+const linkUserSchema = z.object({
+  userId: z.string().min(1),
+});
+
 staffRouter.get("/me", async (c) => {
   const staffRow = c.get("staff");
   return c.json(staffRow);
@@ -106,6 +110,32 @@ staffRouter.patch("/:id", zValidator("json", updateStaffSchema), async (c) => {
   return c.json(row);
 });
 
+staffRouter.patch("/:id/link-user", zValidator("json", linkUserSchema), async (c) => {
+  const db = getDb();
+  const targetId = c.req.param("id");
+  const body = c.req.valid("json");
+  const currentStaff = c.get("staff");
+
+  if (currentStaff.role !== "manager" && !currentStaff.isSuperUser) {
+    return c.json({ error: "Forbidden: only managers or super users can link staff to users" }, 403);
+  }
+
+  const [existing] = await db
+    .select()
+    .from(staff)
+    .where(eq(staff.id, targetId))
+    .limit(1);
+  if (!existing) return c.json({ error: "Not found" }, 404);
+
+  const [updated] = await db
+    .update(staff)
+    .set({ userId: body.userId, updatedAt: new Date() })
+    .where(eq(staff.id, targetId))
+    .returning();
+
+  return c.json(updated);
+});
+
 staffRouter.delete("/:id", async (c) => {
   const db = getDb();
   const id = c.req.param("id");

apps/api/src/routes/stripe-webhooks.ts

@@ -0,0 +1,119 @@
+import { Hono } from "hono";
+import Stripe from "stripe";
+import { z } from "zod/v3";
+import { eq, getDb, invoices } from "@groombook/db";
+import { getStripeClient } from "../services/payment.js";
+
+export const webhooksRouter = new Hono();
+
+webhooksRouter.post("/stripe", async (c) => {
+  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
+  if (!webhookSecret) {
+    return c.json({ error: "Webhook secret not configured" }, 503);
+  }
+
+  const signature = c.req.header("stripe-signature");
+  if (!signature) {
+    return c.json({ error: "Missing signature" }, 401);
+  }
+
+  let rawBody: string;
+  try {
+    rawBody = await c.req.text();
+  } catch {
+    return c.json({ error: "Could not read body" }, 400);
+  }
+
+  const stripe = getStripeClient();
+  if (!stripe) {
+    return c.json({ error: "Stripe not configured" }, 503);
+  }
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(rawBody, signature, webhookSecret);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Invalid signature";
+    return c.json({ error: message }, 401);
+  }
+
+  const db = getDb();
+
+  if (event.type === "payment_intent.succeeded") {
+    const pi = event.data.object as Stripe.PaymentIntent;
+    if (pi.metadata?.groombook_invoice_ids) {
+      const invoiceIds = pi.metadata.groombook_invoice_ids.split(",");
+      for (const invoiceId of invoiceIds) {
+        if (!invoiceId) continue;
+        const parsed = z.string().uuid().safeParse(invoiceId.trim());
+        if (!parsed.success) continue;
+        const invoiceIdTrimmed = invoiceId.trim();
+        const [inv] = await db
+          .select()
+          .from(invoices)
+          .where(eq(invoices.id, invoiceIdTrimmed))
+          .limit(1);
+        if (!inv) continue;
+        if (inv.stripePaymentIntentId && inv.stripePaymentIntentId !== pi.id) continue;
+        await db
+          .update(invoices)
+          .set({
+            status: "paid",
+            paymentMethod: "card",
+            paidAt: new Date(),
+            stripePaymentIntentId: pi.id,
+            updatedAt: new Date(),
+          })
+          .where(eq(invoices.id, invoiceIdTrimmed));
+      }
+    }
+  } else if (event.type === "payment_intent.payment_failed") {
+    const pi = event.data.object as Stripe.PaymentIntent;
+    if (pi.metadata?.groombook_invoice_ids) {
+      const invoiceIds = pi.metadata.groombook_invoice_ids.split(",");
+      for (const invoiceId of invoiceIds) {
+        if (!invoiceId) continue;
+        const parsed = z.string().uuid().safeParse(invoiceId.trim());
+        if (!parsed.success) continue;
+        const invoiceIdTrimmed = invoiceId.trim();
+        await db
+          .update(invoices)
+          .set({
+            paymentFailureReason: pi.last_payment_error?.message ?? "Payment failed",
+            updatedAt: new Date(),
+          })
+          .where(eq(invoices.id, invoiceIdTrimmed));
+      }
+    }
+  } else if (event.type === "charge.refunded") {
+    const charge = event.data.object as Stripe.Charge;
+    if (typeof charge.payment_intent === "string" && charge.payment_intent) {
+      const [inv] = await db
+        .select({ id: invoices.id })
+        .from(invoices)
+        .where(eq(invoices.stripePaymentIntentId, charge.payment_intent))
+        .limit(1);
+      if (inv) {
+        const refundId =
+          typeof charge.refunded === "boolean" && charge.refunded
+            ? `ch_${charge.id}_refund`
+            : null;
+        await db
+          .update(invoices)
+          .set({
+            status: "void",
+            stripeRefundId: refundId,
+            updatedAt: new Date(),
+          })
+          .where(eq(invoices.id, inv.id));
+      }
+    }
+  } else if (event.type === "charge.dispute.created") {
+    const dispute = event.data.object as Stripe.Dispute;
+    console.error(
+      `[Stripe Webhook] Dispute created for payment intent: ${dispute.payment_intent}`
+    );
+  }
+
+  return c.json({ received: true });
+});

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

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

apps/api/src/services/email.ts

@@ -201,3 +201,52 @@ export function buildWaitlistNotificationEmail(
 <p>— Groom Book</p>`,
   };
 }
+
+// ─── Reschedule notification email ────────────────────────────────────────────
+
+interface RescheduleEmailData {
+  clientName: string;
+  petName: string;
+  serviceName: string;
+  groomerName: string | null;
+  oldStartTime: Date;
+  newStartTime: Date;
+}
+
+export function buildRescheduleNotificationEmail(
+  to: string,
+  data: RescheduleEmailData
+): Mail.Options {
+  const oldTime = formatDateTime(data.oldStartTime);
+  const newTime = formatDateTime(data.newStartTime);
+  const groomer = data.groomerName ? ` with ${data.groomerName}` : "";
+  return {
+    to,
+    subject: `Appointment Rescheduled — ${data.petName}'s appointment has been moved`,
+    text: [
+      `Hi ${data.clientName},`,
+      ``,
+      `Your appointment has been rescheduled.`,
+      ``,
+      `  Pet:      ${data.petName}`,
+      `  Service:  ${data.serviceName}`,
+      `  Was:      ${oldTime}${groomer}`,
+      `  Now:      ${newTime}${groomer}`,
+      ``,
+      `If you have any questions or need to make changes, please contact us.`,
+      ``,
+      `— Groom Book`,
+    ].join("\n"),
+    html: `
+<p>Hi ${data.clientName},</p>
+<p>Your appointment has been <strong>rescheduled</strong>.</p>
+<table style="border-collapse:collapse;margin:1em 0">
+  <tr><td style="padding:4px 12px 4px 0;font-weight:600;color:#6b7280">Pet</td><td>${data.petName}</td></tr>
+  <tr><td style="padding:4px 12px 4px 0;font-weight:600;color:#6b7280">Service</td><td>${data.serviceName}</td></tr>
+  <tr><td style="padding:4px 12px 4px 0;font-weight:600;color:#ef4444">Was</td><td style="text-decoration:line-through;color:#ef4444">${oldTime}${groomer}</td></tr>
+  <tr><td style="padding:4px 12px 4px 0;font-weight:600;color:#10b981">Now</td><td style="color:#10b981">${newTime}${groomer}</td></tr>
+</table>
+<p>If you have any questions or need to make changes, please contact us.</p>
+<p>— Groom Book</p>`,
+  };
+}

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

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

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

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

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

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

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

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

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

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

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

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

apps/api/src/services/payment.ts

@@ -0,0 +1,180 @@
+import Stripe from "stripe";
+import { getDb, clients, eq, inArray, invoices } from "@groombook/db";
+
+let _stripe: Stripe | null | undefined;
+
+export function getStripeClient(): Stripe | null {
+  if (_stripe === undefined) {
+    const secretKey = process.env.STRIPE_SECRET_KEY;
+    if (!secretKey) return null;
+    _stripe = new Stripe(secretKey);
+  }
+  return _stripe;
+}
+
+export async function getOrCreateStripeCustomer(clientId: string): Promise<string | null> {
+  const stripe = getStripeClient();
+  if (!stripe) return null;
+
+  const db = getDb();
+  const [client] = await db.select().from(clients).where(eq(clients.id, clientId)).limit(1);
+  if (!client) return null;
+
+  if (client.stripeCustomerId) return client.stripeCustomerId;
+
+  const customer = await stripe.customers.create({
+    metadata: { groombook_client_id: clientId },
+  });
+
+  await db
+    .update(clients)
+    .set({ stripeCustomerId: customer.id, updatedAt: new Date() })
+    .where(eq(clients.id, clientId));
+
+  return customer.id;
+}
+
+export async function createPaymentIntent(
+  invoiceIdOrIds: string | string[],
+  clientId: string
+): Promise<{ clientSecret: string; paymentIntentId: string } | null> {
+  const stripe = getStripeClient();
+  if (!stripe) return null;
+
+  const db = getDb();
+  const invoiceIds = Array.isArray(invoiceIdOrIds) ? invoiceIdOrIds : [invoiceIdOrIds];
+  const firstInvoiceId = invoiceIds[0];
+  if (!firstInvoiceId) return null;
+
+  const invoiceRows = await db
+    .select()
+    .from(invoices)
+    .where(eq(invoices.id, firstInvoiceId));
+
+  const [invoice] = invoiceRows;
+  if (!invoice) return null;
+
+  let totalCents = invoice.totalCents;
+  if (invoiceIds.length > 1) {
+    const allInvoices = await db
+      .select({ totalCents: invoices.totalCents })
+      .from(invoices)
+      .where(inArray(invoices.id, invoiceIds));
+    totalCents = allInvoices.reduce((sum, inv) => sum + inv.totalCents, 0);
+  }
+
+  const stripeCustomerId = await getOrCreateStripeCustomer(clientId);
+  if (!stripeCustomerId) return null;
+
+  const paymentIntent = await stripe.paymentIntents.create({
+    amount: totalCents,
+    currency: "usd",
+    customer: stripeCustomerId,
+    metadata: {
+      groombook_invoice_ids: invoiceIds.join(","),
+      groombook_client_id: clientId,
+    },
+    automatic_payment_methods: { enabled: true },
+  });
+
+  for (const invId of invoiceIds) {
+    await db
+      .update(invoices)
+      .set({ stripePaymentIntentId: paymentIntent.id, updatedAt: new Date() })
+      .where(eq(invoices.id, invId));
+  }
+
+  const clientSecret = paymentIntent.client_secret;
+  if (!clientSecret) return null;
+
+  return { clientSecret, paymentIntentId: paymentIntent.id };
+}
+
+export async function processRefund(
+  invoiceId: string,
+  amountCents?: number
+): Promise<{ refundId: string } | null> {
+  const stripe = getStripeClient();
+  if (!stripe) return null;
+
+  const db = getDb();
+  const [invoice] = await db.select().from(invoices).where(eq(invoices.id, invoiceId)).limit(1);
+  if (!invoice?.stripePaymentIntentId) return null;
+
+  const refund = await stripe.refunds.create({
+    payment_intent: invoice.stripePaymentIntentId,
+    amount: amountCents,
+  });
+
+  await db
+    .update(invoices)
+    .set({ stripeRefundId: refund.id, updatedAt: new Date() })
+    .where(eq(invoices.id, invoiceId));
+
+  return { refundId: refund.id };
+}
+
+export async function listPaymentMethods(clientId: string): Promise<Stripe.PaymentMethod[] | null> {
+  const stripe = getStripeClient();
+  if (!stripe) return null;
+
+  const stripeCustomerId = await getOrCreateStripeCustomer(clientId);
+  if (!stripeCustomerId) return null;
+
+  const methods = await stripe.paymentMethods.list({
+    customer: stripeCustomerId,
+    type: "card",
+  });
+
+  return methods.data;
+}
+
+export async function attachPaymentMethod(
+  clientId: string,
+  paymentMethodId: string
+): Promise<boolean> {
+  const stripe = getStripeClient();
+  if (!stripe) return false;
+
+  const stripeCustomerId = await getOrCreateStripeCustomer(clientId);
+  if (!stripeCustomerId) return false;
+
+  await stripe.paymentMethods.attach(paymentMethodId, { customer: stripeCustomerId });
+  return true;
+}
+
+export async function detachPaymentMethod(paymentMethodId: string): Promise<boolean> {
+  const stripe = getStripeClient();
+  if (!stripe) return false;
+
+  await stripe.paymentMethods.detach(paymentMethodId);
+  return true;
+}
+
+export async function createSetupIntent(customerId: string): Promise<{ clientSecret: string } | null> {
+  const stripe = getStripeClient();
+  if (!stripe) return null;
+
+  const setupIntent = await stripe.setupIntents.create({
+    customer: customerId,
+    payment_method_types: ["card"],
+  });
+
+  return { clientSecret: setupIntent.client_secret! };
+}
+
+export async function getPaymentIntentDetails(
+  paymentIntentId: string
+): Promise<{ cardLast4: string | null; paymentStatus: string | null } | null> {
+  const stripe = getStripeClient();
+  if (!stripe) return null;
+
+  const pi = await stripe.paymentIntents.retrieve(paymentIntentId, { expand: ["payment_method"] });
+  const cardLast4 = pi.payment_method
+    ? (pi.payment_method as Stripe.PaymentMethod).card?.last4 ?? null
+    : null;
+  return {
+    cardLast4,
+    paymentStatus: pi.status ?? null,
+  };
+}

apps/api/src/services/reminders.ts

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

apps/api/src/services/sms.ts

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

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

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

apps/e2e/playwright.config.ts

@@ -19,7 +19,7 @@ export default defineConfig({
   reporter: process.env.CI ? "github" : "list",
 
   use: {
-    baseURL: "http://localhost:8080",
+    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? "http://localhost:8080",
     trace: "on-first-retry",
     screenshot: "only-on-failure",
     serviceWorkers: "block",

apps/e2e/tests/clients.spec.ts

@@ -63,3 +63,52 @@ test("clicking a client shows their details", async ({ page }) => {
   // Email appears in both the list row and the detail panel once selected
   await expect(page.getByText("alice@example.com")).toHaveCount(2);
 });
+
+test("direct URL navigation to client detail fetches data and renders client name", async ({ page }) => {
+  // Mock individual client fetch for direct navigation
+  await page.route("/api/clients/client-1", (route) =>
+    route.fulfill({ json: MOCK_CLIENTS[0] })
+  );
+  // Mock pets for this client
+  await page.route("/api/pets**", (route) =>
+    route.fulfill({ json: [] })
+  );
+
+  await page.goto("/admin/clients/client-1");
+  // Client name must be visible without any clicking
+  await expect(page.getByText("Alice Johnson")).toBeVisible();
+  // Should show back to list link
+  await expect(page.getByText("← Back to list")).toBeVisible();
+});
+
+test("direct URL navigation shows loading then client", async ({ page }) => {
+  let resolvePets: (value: unknown) => void;
+  const petsPromise = new Promise((resolve) => { resolvePets = resolve; });
+
+  await page.route("/api/clients/client-1", (route) =>
+    route.fulfill({ json: MOCK_CLIENTS[0] })
+  );
+  await page.route("/api/pets**", async (route) => {
+    await petsPromise;
+    await route.fulfill({ json: [] });
+  });
+
+  const navigationPromise = page.goto("/admin/clients/client-1");
+  // Should show loading state briefly
+  await expect(page.getByText("Loading client…")).toBeVisible();
+  // Resolve pets and wait for navigation
+  resolvePets!();
+  await navigationPromise;
+  // After data loads, client name is shown
+  await expect(page.getByText("Alice Johnson")).toBeVisible();
+});
+
+test("direct URL navigation shows error state on failure", async ({ page }) => {
+  await page.route("/api/clients/nonexistent", (route) =>
+    route.fulfill({ status: 404, json: { error: "Client not found" } })
+  );
+
+  await page.goto("/admin/clients/nonexistent");
+  await expect(page.getByText(/client not found/i)).toBeVisible();
+  await expect(page.getByText("← Back to clients")).toBeVisible();
+});

apps/e2e/tests/navigation.spec.ts

@@ -44,7 +44,20 @@ test.beforeEach(async ({ page }) => {
         json: { newClients: [], activeInPeriodCount: 0, churnRisk: [], churnRiskTotal: 0 },
       });
     }
-    // Appointments, clients, services, staff, invoices, book, etc.
+    if (url.includes("/api/invoices/stats/summary")) {
+      return route.fulfill({
+        json: {
+          revenueThisMonth: 0,
+          outstanding: 0,
+          refundsThisMonth: 0,
+          methodBreakdown: [],
+        },
+      });
+    }
+    if (url.includes("/api/invoices")) {
+      return route.fulfill({ json: { data: [], total: 0 } });
+    }
+    // Appointments, clients, services, staff, book, etc.
     return route.fulfill({ json: [] });
   });
 });
@@ -82,6 +95,7 @@ test("admin staff page loads", async ({ page }) => {
 
 test("admin invoices page loads", async ({ page }) => {
   await page.goto("/admin/invoices");
+  await page.waitForLoadState("domcontentloaded");
   await expect(page.getByText("GroomBook")).toBeVisible();
   await expect(page.getByRole("link", { name: "Invoices" })).toBeVisible();
 });

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

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

apps/web/.env.production

@@ -1 +1 @@
-VITE_API_URL=
+VITE_API_URL=https://uat.groombook.dev

apps/web/Dockerfile

@@ -11,6 +11,8 @@ RUN pnpm install --frozen-lockfile
 
 # Build
 FROM deps AS builder
+ARG VITE_API_URL=
+ENV VITE_API_URL=
 COPY packages/types/ packages/types/
 COPY apps/web/ apps/web/
 RUN pnpm --filter @groombook/web build
@@ -20,3 +22,5 @@ FROM nginx:alpine AS runner
 COPY apps/web/nginx.conf /etc/nginx/conf.d/default.conf
 COPY --from=builder /app/apps/web/dist /usr/share/nginx/html
 EXPOSE 80
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:80/ || exit 1

apps/web/e2e/playwright.config.ts

@@ -3,7 +3,7 @@ import { defineConfig, devices } from "@playwright/test";
 /**
  * Playwright configuration for GroomBook Web E2E tests.
  *
- * Targets the deployed dev environment at groombook.dev.farh.net.
+ * Targets the deployed dev environment at dev.groombook.dev.
  * Uses the dev login selector (/login) for authentication — no hardcoded credentials.
  *
  * Run locally:
@@ -19,7 +19,7 @@ export default defineConfig({
   reporter: process.env.CI ? "github" : "list",
 
   use: {
-    baseURL: "https://groombook.dev.farh.net",
+    baseURL: "https://dev.groombook.dev",
     trace: "on-first-retry",
     screenshot: "only-on-failure",
     serviceWorkers: "block",

apps/web/nginx.conf

@@ -3,10 +3,22 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
+    # Security headers
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
+
     # Cache static assets
     location ~* \.(js|css|png|svg|ico|woff2)$ {
         expires 1y;
         add_header Cache-Control "public, immutable";
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+        add_header X-XSS-Protection "1; mode=block" always;
+        add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
     }
 
     # Proxy API calls to the API service

apps/web/package.json

@@ -14,8 +14,10 @@
   },
   "dependencies": {
     "@groombook/types": "workspace:*",
+    "@stripe/react-stripe-js": "^6.1.0",
+    "@stripe/stripe-js": "^9.1.0",
     "@tailwindcss/vite": "^4.2.2",
-    "better-auth": "^1.0.0",
+    "better-auth": "^1.5.6",
     "lucide-react": "^0.577.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

apps/web/public/demo-pets/dog-basset-brown-white.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>You have no right to access this object because of bucket acl.</Message>
+  <RequestId>69D96C853FAECD363909C4A0</RequestId>
+  <HostId>hailuo-image-algeng-data-us.oss-us-east-1.aliyuncs.com</HostId>
+  <EC>0003-00000001</EC>
+  <RecommendDoc>https://api.alibabacloud.com/troubleshoot?q=0003-00000001</RecommendDoc>
+</Error>

apps/web/public/demo-pets/dog-bichon-white-groomed.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>You have no right to access this object because of bucket acl.</Message>
+  <RequestId>69D96CFC84D7A9333708F278</RequestId>
+  <HostId>hailuo-image-algeng-data-us.oss-us-east-1.aliyuncs.com</HostId>
+  <EC>0003-00000001</EC>
+  <RecommendDoc>https://api.alibabacloud.com/troubleshoot?q=0003-00000001</RecommendDoc>
+</Error>

apps/web/public/demo-pets/dog-boxer-fawn-athletic.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>You have no right to access this object because of bucket acl.</Message>
+  <RequestId>69D96D48D7892E37386B9ACB</RequestId>
+  <HostId>hailuo-image-algeng-data-us.oss-us-east-1.aliyuncs.com</HostId>
+  <EC>0003-00000001</EC>
+  <RecommendDoc>https://api.alibabacloud.com/troubleshoot?q=0003-00000001</RecommendDoc>
+</Error>

apps/web/public/demo-pets/dog-cavalier-cream-gentle.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>You have no right to access this object because of bucket acl.</Message>
+  <RequestId>69D96C25663D703833F23607</RequestId>
+  <HostId>hailuo-image-algeng-data-us.oss-us-east-1.aliyuncs.com</HostId>
+  <EC>0003-00000001</EC>
+  <RecommendDoc>https://api.alibabacloud.com/troubleshoot?q=0003-00000001</RecommendDoc>
+</Error>

apps/web/public/demo-pets/dog-cocker-buff-friendly.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>You have no right to access this object because of bucket acl.</Message>
+  <RequestId>69D96D89851C843332073968</RequestId>
+  <HostId>hailuo-image-algeng-data-us.oss-us-east-1.aliyuncs.com</HostId>
+  <EC>0003-00000001</EC>
+  <RecommendDoc>https://api.alibabacloud.com/troubleshoot?q=0003-00000001</RecommendDoc>
+</Error>

apps/web/public/demo-pets/dog-dachshund-black-tan.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>You have no right to access this object because of bucket acl.</Message>
+  <RequestId>69D96C9C5A03D33730C61AD8</RequestId>
+  <HostId>hailuo-image-algeng-data-us.oss-us-east-1.aliyuncs.com</HostId>
+  <EC>0003-00000001</EC>
+  <RecommendDoc>https://api.alibabacloud.com/troubleshoot?q=0003-00000001</RecommendDoc>
+</Error>

apps/web/public/demo-pets/dog-pomeranian-white-studio.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>You have no right to access this object because of bucket acl.</Message>
+  <RequestId>69D96BEB91911B30317E3BE8</RequestId>
+  <HostId>hailuo-image-algeng-data-us.oss-us-east-1.aliyuncs.com</HostId>
+  <EC>0003-00000001</EC>
+  <RecommendDoc>https://api.alibabacloud.com/troubleshoot?q=0003-00000001</RecommendDoc>
+</Error>

apps/web/public/demo-pets/dog-schnauzer-black-groomed.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>You have no right to access this object because of bucket acl.</Message>
+  <RequestId>69D96BFB7B92D33535D6D90D</RequestId>
+  <HostId>hailuo-image-algeng-data-us.oss-us-east-1.aliyuncs.com</HostId>
+  <EC>0003-00000001</EC>
+  <RecommendDoc>https://api.alibabacloud.com/troubleshoot?q=0003-00000001</RecommendDoc>
+</Error>

apps/web/public/demo-pets/dog-setter-red-sunlit.png

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Error>
+  <Code>AccessDenied</Code>
+  <Message>You have no right to access this object because of bucket acl.</Message>
+  <RequestId>69D96B8BDF4B473630A2E120</RequestId>
+  <HostId>hailuo-image-algeng-data-us.oss-us-east-1.aliyuncs.com</HostId>
+  <EC>0003-00000001</EC>
+  <RecommendDoc>https://api.alibabacloud.com/troubleshoot?q=0003-00000001</RecommendDoc>
+</Error>