docs(integrations): operator setup runbook for Google + WhatsApp + SMTP + n8n#121
Merged
Conversation
…+ SMTP + n8n Per-credential procedural runbook so the operator can wire production keys for every external integration in one ~45-minute sitting. Background: investigation in PRs #114/#115/#120 confirmed the live-mode code paths for both Google Maps (geocoding + route-optimisation) and WhatsApp Business (Cloud API send + signature-verified webhook) are already implemented and tested. The remaining gap is operator-side account/credential setup that Claude cannot do — Google Cloud project creation, Meta Developer App, WhatsApp Business Account, phone-number registration, message-template approvals, etc. The runbook covers, in order: 1. Vercel env-var scope rules (Production-only for real keys; redeploy required after every change; uncheck "Use existing Build Cache"). 2. Google Cloud — project + Geocoding API + Route Optimization API + restricted server key + optional referrer-restricted browser key, with verification curl that exercises the live geocoding endpoint. 3. WhatsApp Business — Meta Developer App, Business Manager, WABA, phone number, the four required IDs/tokens, system-user-issued never-expiring access token (NOT the temporary 24h one), webhook subscription pointing at /api/webhooks/whatsapp with verify-token handshake, and message template approval flow per registry key. 4. SMTP — provider env vars + verified sending domain. 5. n8n — when to bother + which env vars + the pseudo-random-N8N_API_KEY-on-preview footgun from memory. 6. AUTH — listed for completeness (already done). 7. Phase 0 unblock — one-click GH Actions seed-demo-database run on main to bring 20 invoices into prod and close UAT defect D-2. 8. Quick verification matrix — single curl that should return "configured" across the integration board. 9. Cost expectations — <CHF 90/month at single-practice volume. 10. Operator stop-gate checklist. Pure docs. No code changes. Complements (does not replace) docs/ENVIRONMENT.md. https://claude.ai/code/session_01JBMfnqc8QXZRqCG3Tm7hHx
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an operator-facing runbook (docs/INTEGRATIONS_SETUP.md) intended to guide production wiring of external integrations (Google Maps, WhatsApp Cloud API, SMTP, and n8n) via Vercel environment variables, with verification steps and a post-setup checklist.
Changes:
- Introduces a step-by-step “click here / paste this / verify with curl” setup procedure for Google Maps, WhatsApp, SMTP, and n8n.
- Documents Vercel env-var scoping + redeploy requirements, plus a Phase 0 demo-seed unblock path.
- Provides a final verification matrix and operator stop-gate checklist.
Comment on lines
+287
to
+298
| ```json | ||
| { | ||
| "status": "healthy", | ||
| "checks": { | ||
| "database": { "status": "up" }, | ||
| "environment": { "status": "ok", "missing": [] }, | ||
| "googleMaps": { "status": "configured" }, | ||
| "whatsapp": { "status": "configured" }, | ||
| "smtp": { "status": "configured" }, | ||
| "n8n": { "status": "configured" } | ||
| } | ||
| } |
Copilot review on PR #121 caught eight factual inaccuracies in the runbook (most because I wrote from inferred knowledge rather than verified code paths). Each fix below is grounded in a re-read of the relevant source file. - Integration table (Line 19): the demo/live switch lives in the integration *clients* (lib/integrations/google-maps.client.ts, lib/integrations/smtp.client.ts), not in the services (geocoding.service / route-optimizer.service / email.service). Rewrote the row "where the demo path is implemented" to point at the correct file. Also clarified that webhook signature verification on /api/webhooks/whatsapp uses HMAC SHA256 against WHATSAPP_APP_SECRET. - Health-check baseline (Line 27 + Line 298 expected JSON): n8n reports up/unreachable (not configured/unconfigured); the response has six check groups (not the five I'd implied earlier). Documented the exact shape per check group, the rules that produce the top-level status (healthy / degraded / unhealthy), and the example "expected" JSON now matches what /api/health actually returns. - Mapbox reference (Line 81): repo doesn't use Mapbox for the map fallback; it renders a static placeholder when NEXT_PUBLIC_GOOGLE_MAPS_BROWSER_KEY is unset. Reworded. - Geocode verification (Line 107): /api/route-planning/geocode persists coordinates to the Yard record but returns only { success, message }. Updated the expected response and added a follow-up GET /api/yards/:id step to confirm lat/long stored. - Template wording (Line 175 + Line 180): reminders today use whatsappService.sendTextMessage (free text from reminder.service.ts), not sendTemplateMessage. Replaced the misleading "all flows use templates" claim with a clear table: appointment confirmations need template approval today; reminders + stock-replies will need it for outside-window sends. Template body strings live in lib/services/{reminder,stock-reply}.service.ts build* functions, NOT in messages/{en,fr}.json — pointed operators at the actual source so they don't waste time grepping the i18n catalogs. - WhatsApp outbound smoke test (Line 202): the original example POSTed to /api/demo/simulate-whatsapp which is an INBOUND webhook simulator (and is blocked when DEMO_MODE=false), so it could never exercise a real send. Replaced with two safe operator paths: (a) trigger /api/reminders/check on a backdated due date, or (b) book a real test appointment through the operator UI. Both exercise sendTemplateMessage / sendTextMessage against the live Meta endpoint when DEMO_MODE=false on Production. - Stop-gate count (Line 327): said "five health-check items" but there are six (database + environment + n8n + whatsapp + smtp + googleMaps). Fixed the count and reworded the smoke-test list to reference real operator UI paths instead of imagined endpoints. No code changes; pure documentation correctness. https://claude.ai/code/session_01JBMfnqc8QXZRqCG3Tm7hHx
6 tasks
Contributor
|
Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
2 tasks
RJK134
added a commit
that referenced
this pull request
May 8, 2026
…ons (#122) * chore(memory): add Phase E + sandbox-gate + runbook-verification lessons Three new entries to .claude/memory.md based on lessons earned in the 2026-05-08 session. - Sandbox local gate (2026-05-08): npm install completes in ~2 min and enables the full five-check gate locally. Saves a CI cycle on first-pass code edits. Build needs SKIP_ENV_VALIDATION=true to bypass scripts/check-env.ts in this sandbox. - Runbook verification rule (2026-05-08): verify every file path / response shape / endpoint behaviour with grep against the actual code before writing it in operator-facing docs. PR #121 first draft had 8 factual errors caught by Copilot review — including pointing operators at a non-existent audit.service.ts and at /api/demo/simulate-whatsapp (which is inbound-only) for outbound WhatsApp testing. - Phase E semantics (2026-05-08): /api/dashboard pendingRecallsCount is "pending recall actions" (sum of dental + vaccination counts), matching the recalls page row count exactly. Future extensions to the recall workspace should preserve the "actions, not horses" semantic — a single horse.count with OR would deduplicate per horse and produce a count that disagrees with /api/recalls totals. Other entries already present from PR #115's memory updates: form-encoded sign-in trap, prod-DB 0-invoices state, 9-template count, Vercel MCP zero-team-scope, 25 UAT cases, lifecycle exercise. https://claude.ai/code/session_01JBMfnqc8QXZRqCG3Tm7hHx * chore(memory): address Copilot review on PR #122 - Add `npx prisma validate` to the gate list so it matches the "five-check" label and CLAUDE.md's standing rule. - Reword the SKIP_ENV_VALIDATION note: clarify it's a local/sandbox bypass only, never to be set on Vercel project env (which must run check-env normally). https://claude.ai/code/session_01JBMfnqc8QXZRqCG3Tm7hHx * chore(memory): reorder gate commands to match standing rule VADE review nit on PR #122 — standing rule lists prisma validate before test; the session-note line had them swapped. Reordered to lint -> typecheck -> prisma validate -> test -> build for consistency. https://claude.ai/code/session_01JBMfnqc8QXZRqCG3Tm7hHx * chore(memory): clarify SKIP_ENV_VALIDATION note includes CI stubs Agent-Logs-Url: https://github.com/RJK134/EquiSmile/sessions/7c4e5837-c56f-4225-8e32-fcabc5b03062 Co-authored-by: RJK134 <167345619+RJK134@users.noreply.github.com> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Operator-facing setup runbook —
docs/INTEGRATIONS_SETUP.md— bundling the credential / account / Vercel env-var work needed to flip every external integration from demo mode to live mode.Why this is the deliverable instead of code:
What's in the doc
seed-demo-databaseonmainto bring 20 invoices into prod and close UAT defect D-2.curl /api/healththat should return"configured"across the board.Pairs with PR #120 (Phase E)
DEMO_MODE=falseon Production.Test plan
docs/UAT_v2_VALIDATION.mdwith PASS verdicts.Stop-gate
Final merge belongs to Richard or Freddie. This runbook can land independently of PR #120 — they touch different files.
https://claude.ai/code/session_01JBMfnqc8QXZRqCG3Tm7hHx
Generated by Claude Code
Note
Low Risk
Low risk because this PR only adds documentation and does not change runtime code paths. Risk is limited to potential operator confusion if steps/env var names are incorrect.
Overview
Adds a new operator-facing runbook
docs/INTEGRATIONS_SETUP.mdthat documents the end-to-end steps to switch external integrations from demo to live.Covers required Vercel env vars and verification commands for Google Maps (Geocoding + Route Optimization), WhatsApp Cloud API (including webhook setup and long-lived tokens), optional SMTP and n8n configuration, plus a one-click workflow to seed demo finance data and a final health-check matrix/stop-gate checklist.
Reviewed by Cursor Bugbot for commit 896ca45. Configure here.