Define webhook payload schema and types
epic-pause-status-notifications-backend-pipeline-task-001 — Define TypeScript interfaces and Zod validation schemas for the Supabase database webhook payload received by the pause status webhook handler. Include peer_mentor_profiles INSERT and UPDATE event shapes, status column transition types (active→paused, paused→active), and error response types.
Acceptance Criteria
Technical Requirements
Implementation Notes
Supabase database webhook payloads follow a fixed envelope: { type: 'INSERT'|'UPDATE'|'DELETE', table: string, schema: string, record: T, old_record: T | null }. Model the record shape directly from the peer_mentor_profiles table columns — at minimum: id (uuid), status (text), coordinator_id (uuid), created_at (timestamp). Use Zod's z.discriminatedUnion('type', [...]) to handle INSERT vs UPDATE shapes with different old_record nullability. Export both the Zod schema (for runtime validation) and the inferred TypeScript type (z.infer
Place this file at supabase/functions/pause-status-webhook/types.ts.
Testing Requirements
No runtime tests needed for this task — types are compile-time artifacts. However, write Zod schema unit tests (Deno test or Jest) covering: (1) valid INSERT payload passes, (2) valid UPDATE payload passes, (3) missing 'type' field fails with error, (4) invalid status value fails, (5) null old_record on INSERT passes, (6) non-null old_record on UPDATE passes.
These tests serve as living documentation of the schema contract.
Supabase Edge Functions have cold start latency that may push coordinator notification delivery beyond the 5-second SLA, particularly during low-traffic periods when the function is not warm.
Mitigation & Contingency
Mitigation: Keep the Edge Function lightweight — delegate all heavy logic to the orchestrator layer and avoid large dependency bundles. Measure p95 end-to-end latency in staging and document actual SLA achievable.
Contingency: If cold start latency consistently breaches 5 seconds, introduce a keep-warm ping from the nightly-scheduler or document the actual p95 latency in the feature spec and adjust the acceptance criterion to reflect the realistic bound.
Supabase database webhooks may fire duplicate events for a single status change under retry conditions, causing coordinators to receive multiple identical notifications for one pause event.
Mitigation & Contingency
Mitigation: Add idempotency checking in the webhook handler using the event timestamp and peer mentor ID. Store a notification dispatch record in the pause-status-record-repository and skip dispatch if a record for the same event already exists.
Contingency: If duplicates slip through in production, add a de-duplication filter in the notification centre UI layer so the coordinator sees at most one card per event, and implement a cleanup job for the notifications table.
A peer mentor with multi-chapter membership may have more than one responsible coordinator. The orchestrator design currently targets a single coordinator, and resolving multiple recipients may require schema changes to the org membership query.
Mitigation & Contingency
Mitigation: Review the multi-chapter-membership-service patterns before implementing the orchestrator's coordinator resolution. Design the dispatcher call to accept an array of coordinator IDs from the outset so adding multiple recipients is non-breaking.
Contingency: If multi-coordinator dispatch is out of scope for this epic, document the limitation and create a follow-up task. Default to the primary coordinator (lowest chapter hierarchy level) as the single recipient in the interim.