Vapi motivational-interviewing voice call when a daily sit is missed

[auerbachb]

Background

Re-engagement today is text-only: miss-a-day push (#247) and the 8PM failure-reason reminder (#527). Product owner wants a stronger, human-feeling nudge: an outbound phone call via Vapi (voice-AI agent) that runs a motivational-interviewing conversation to help a lapsing user get back to meditating. Net-new — no prior issue or code (confirmed: no voice-agent / MI logic anywhere; only web-push exists).

Problem

Push notifications are easy to ignore, and there's no escalated intervention when someone stops practicing. There is no mechanism to place a call, run an MI conversation, or schedule such calls.

Proposed solution

• Delivery — Vapi: a backend scheduler initiates an outbound call through the Vapi API; the MI assistant/script is configured on Vapi's side (Vapi supports this). We pass user context (name, current streak, days missed) into the assistant.
• User-set schedule: the user sets a start time X and stop time Y. If no qualifying session is completed by X, place a call; repeat every hour from X until Y — or until a qualifying sit is completed that day, whichever comes first. Completing a sit cancels the remaining calls for the day.
• Opt-in required: off by default; the user must explicitly opt in and provide a phone number; store consent (+ timestamp).
• Trigger engine: reuse the existing "no sit yet today" / miss-a-day detection (Miss-a-day push notification with shortened-session follow-up #247/What happens if you miss a day recovery pattern? #238/iOS parity: 8PM failure-reason reminder + log-reason flow (port web PR #466) #527) and extend the notification cron (src/lib/notification-scheduler.ts + /api/cron/dispatch-notifications) to evaluate due calls hourly per user within [X, Y]; timezone handling per the iOS: daily practice reminders not delivering despite toggles enabled #561 fix.
• Settings UI (iOS-first): a Notifications/Settings section to opt in, enter phone number, and set X and Y (mirroring the existing Reminder-time / Quiet-hours controls). Web parity later.
• Cost/pricing: single-user (product owner) testing only for now — defer per-user caps/pricing.
• Privacy/ToS: add call + consent disclosure to privacy/ToS docs later (follow-up, not MVP-blocking).

Acceptance Criteria

• Opt-in setting (off by default) with phone-number capture + explicit consent recorded (with timestamp)
• User sets start time X and stop time Y for the call window
• With no qualifying session completed by X, a Vapi call is placed; it repeats hourly until Y or until a qualifying sit is completed that day
• Completing any qualifying sit cancels the remaining calls for that day
• The Vapi assistant runs an MI conversation and receives user context (streak / days-missed / name)
• Call attempts + outcomes are logged; a Vapi/API failure does not crash the scheduler
• No calls fire outside [X, Y] or when opted out
• End-to-end works for the single test user (product owner)

Test Plan

• Opt in, set X/Y, don't sit → receive a call at X, another an hour later, stopping at Y
• Complete a sit before X → no call; complete after the first call → remaining calls cancelled
• Opt out → no calls placed
• Backend unit tests: hourly due-call evaluation within [X,Y], cancel-on-completion, opt-in gating, timezone
• Vapi call initiation + context payload verified (mock the Vapi API)

Notes / Open questions

• Vapi keys in env (never commit); decide MVP: static MI prompt vs context-injected assistant.
• "Qualifying session" = any completed sit (standard/quick/breath) — align with the "any meditation counts" theme (iOS: habit widget + streak ignore quick/breath sits — show days as missed #589/iOS: breath-counting sit should satisfy the app-blocking gate #590).
• Schema additions: phoneNumber, callOptIn (+ consent timestamp), callWindowStart/callWindowStop on the user record.
• Scheduler: extend the existing notification cron vs a parallel call-cron — decide at implementation.
• Cost/rate limits and privacy/ToS disclosure deferred (single-user testing now).
• Platform: backend + Vapi are platform-agnostic; opt-in/schedule UI iOS-first, web parity later.
• Natural phasing: (1) schema + opt-in/settings + consent, (2) scheduler hourly evaluation, (3) Vapi call + MI context, (4) logging/outcomes.
• Related: Miss-a-day push notification with shortened-session follow-up #247, iOS parity: 8PM failure-reason reminder + log-reason flow (port web PR #466) #527, What happens if you miss a day recovery pattern? #238 (re-engagement + miss-a-day), iOS: daily practice reminders not delivering despite toggles enabled #561 (scheduler timezone).

[github-actions]

@coderabbitai plan

[coderabbitai]

🔗 Related PRs

#482 - feat: aphorisms toggle — web + iOS parity (#88) [merged]
#518 - feat(audio): voice countdown mode for final minute (#507) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Extend notification_preferences (not the users table) with opt-in, E.164 phone, consent timestamp, and HH:MM window fields, mirroring the existing quiet-hours/reminder-time patterns end-to-end (schema → typed helpers → PATCH validation → DTOs → iOS UI).
• Reuse the existing 5-minute dispatch-notifications cron and its claim/release + #561 timezone logic, adding a pure hourly-slot due-evaluation helper and a call-dispatch branch that cancels remaining calls once any qualifying sit is completed.
• Add a server-only Vapi client following the daily.ts/apns.ts conventions (env-guarded, typed error, result-object, timeout) plus a dedicated call_attempts log table for outcomes, keeping notification_dispatches as a minimal hour-granular dedup marker.
• Mirror the logic across the established test tiers (mocked-DB scheduler unit tests, Vapi client mock, route contract tests) and document the new type's non-daily window semantics.

Design Choices

Design Choice 1: Where should the new call fields (opt-in, phone number, consent timestamp, window start/stop) be stored?

Options Considered:

1. Add columns to the users table.
2. Add columns to the notification_preferences table alongside the existing scheduling/time-window fields.

Chosen Option: 2

Rationale: The call window is a scheduling/notification concern that directly mirrors quietHoursStart/End, dailyReminderTime, and tz, so co-locating it keeps validation, serialization, DTOs, and the single PATCH endpoint consistent with existing patterns.

Design Choice 2: Should call evaluation add a new hourly cron or extend the existing 5-minute cron?

Options Considered:

1. Add a separate hourly cron (0 * * * *) with its own route.
2. Extend the existing 5-minute dispatch-notifications cron to also evaluate due calls, using an hour-granular windowKey slot for dedup.

Chosen Option: 2

Rationale: Reuses the proven per-user try/catch isolation, claim/release idempotency, and #561 timezone logic; honors arbitrary start minutes; and avoids introducing a second cron entry and its plan-limit uncertainty.

Design Choice 3: How should call attempts/outcomes and hourly-slot idempotency be recorded?

Options Considered:

1. Add status/error columns to notification_dispatches.
2. Reuse notification_dispatches (with an hour-granular windowKey) purely for slot claim/dedup, and add a new dedicated call_attempts log table (status + error, mirroring buddySessionCalendarEvents) for outcomes.

Chosen Option: 2

Rationale: Preserves the minimal dedup semantics of notification_dispatches while giving proper outcome/error auditing via a table shaped like existing per-attempt log tables.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Data model, preferences API, and consent capture

Establish the persistence and API surface for the opt-in, phone number, consent timestamp, and call window, following the existing notification_preferences conventions so the rest of the stack (scheduler, iOS) has a stable contract.

Task 1: Extend the notification preferences schema and migration

Add the new call-related columns to the preferences table and a matching additive migration.

• Update src/db/schema.ts notificationPreferences to add: callOptIn boolean (default false, not null), callPhoneNumber nullable varchar (E.164, e.g. length 20), callConsentAt nullable timestamp with timezone (records when consent was granted), and callWindowStart/callWindowStop nullable varchar(5) (HH:MM, mirroring quiet hours).
• Consider a CHECK constraint mirroring the "all-or-none" precedent so that when callOptIn is true, phone number and window fields are present (or enforce this only in API validation to keep the migration simple — prefer API validation for flexibility).
• Add a new idempotent migration drizzle/notification_preferences_call_window_<issue#>_incremental.sql using ALTER TABLE ... ADD COLUMN IF NOT EXISTS ..., following the additive style in existing notification_preferences_*_incremental.sql files.

Task 2: Extend preferences row typing, defaults, serialization, and validators

Wire the new columns through the typed preferences helpers.

• Update src/lib/notification-preferences.ts: add the new fields to NotificationPreferencesRow, DEFAULT_NOTIFICATION_PREFERENCES (opt-in false, phone/consent/window null), and serializeNotificationPreferences (emit callConsentAt as ISO string like updatedAt).
• Add validation helpers here: an E.164 phone validator (mirror the shared-validation structure of src/lib/username.ts) and reuse the existing HH:MM timePattern for the window fields.

Task 3: Extend the preferences PATCH/GET route with consent semantics

Accept and validate the new fields via the existing endpoint, capturing consent atomically.

• Update src/app/api/notifications/preferences/route.ts PATCH handler to accept callOptIn (boolean), callPhoneNumber (validated E.164 or explicit null to clear, using the double-optional "clear" semantics already used for quiet hours), and callWindowStart/callWindowStop (validated HH:MM, required-together like quiet hours; 400 on partial).
• Enforce opt-in gating: when callOptIn transitions to true, require a valid phone number and both window fields to be present (in this patch or already stored); reject with 400 otherwise.
• Set callConsentAt to the current timestamp when callOptIn becomes true (and clear it when opting out) so consent + timestamp are captured together per acceptance criteria.

🤖 Prompt for AI agents

Implement the persistence and API layer for the new missed-sit-call opt-in
feature by extending the existing `notification_preferences` table and its
API/validation layer, mirroring the existing quiet-hours/reminder-time patterns.

1. Schema and migration:
- In `src/db/schema.ts`, add to `notificationPreferences`: `callOptIn` boolean
(default `false`, not null), `callPhoneNumber` nullable `varchar` sized for
E.164 (e.g. length 20), `callConsentAt` nullable timestamp with timezone, and
`callWindowStart`/`callWindowStop` nullable `varchar(5)` in `HH:MM` format
mirroring quiet hours.
- Decide whether to enforce the "opt-in requires phone + window" rule via a DB
CHECK constraint or leave it to API validation (prefer API validation for
simplicity).
- Add a new additive migration file
`drizzle/notification_preferences_call_window_<issue#>_incremental.sql` using
`ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...`, matching the style of existing
`notification_preferences_*_incremental.sql` files.

2. Typed helpers:
- In `src/lib/notification-preferences.ts`, extend `NotificationPreferencesRow`,
`DEFAULT_NOTIFICATION_PREFERENCES` (opt-in `false`; phone/consent/window
`null`), and `serializeNotificationPreferences` (serialize `callConsentAt` as an
ISO string like `updatedAt`).
- Add an E.164 phone validator (mirroring the validation structure in
`src/lib/username.ts`) and reuse the existing `HH:MM` `timePattern` for
validating the window fields.

3. API route:
- In `src/app/api/notifications/preferences/route.ts`, extend the PATCH handler
to accept `callOptIn` (boolean), `callPhoneNumber` (validated E.164, or explicit
`null` to clear using the existing double-optional clear semantics), and
`callWindowStart`/`callWindowStop` (validated `HH:MM`, required together, 400 on
partial).
- Enforce gating logic: if `callOptIn` transitions to `true`, require a valid
phone number and both window fields (either in the current patch or already
persisted); otherwise return 400.
- When `callOptIn` becomes `true`, set `callConsentAt` to the current timestamp;
when opting out, clear `callConsentAt`.

Phase 2: Vapi client and call-attempt logging

Introduce the outbound-call integration boundary and durable outcome logging, isolated from scheduler orchestration.

Task 1: Add a server-only Vapi client module

Create the outbound-call API wrapper following existing external-client conventions.

• Add src/lib/vapi.ts with import "server-only", an env guard (requireVapiApiKey() reading VAPI_API_KEY, plus VAPI_ASSISTANT_ID and VAPI_PHONE_NUMBER_ID) mirroring src/lib/daily.ts.
• Implement a single initiateMissedSitCall({ phoneNumber, variableValues }) that POSTs to Vapi's /call endpoint with assistantId, phoneNumberId, customer.number (E.164), and assistantOverrides.variableValues carrying name, streak, daysMissed (per web-search payload shape).
• Follow the apns.ts result-object philosophy: return a discriminated { ok: true, callId } | { ok: false, status, reason } for expected provider failures and only throw on unexpected transport errors; add an explicit request timeout via AbortSignal.timeout(...) and a typed VapiApiError like DailyApiError.
• Add the new VAPI_* variables to .env.example (commented-out, grouped, with "server-only / never commit" comment) following the documented convention.

Task 2: Add a call-attempt log table

Persist each attempt's outcome for auditing without overloading the dedup marker.

• Add a callAttempts table in src/db/schema.ts mirroring buddySessionCalendarEvents: id, userId (FK, cascade), windowKey/slot identifier, status varchar(20) with a CHECK constraint (e.g. 'initiated' | 'failed'), error text nullable, external callId nullable, and createdAt (with timezone).
• Add the corresponding additive migration drizzle/call_attempts_<issue#>_incremental.sql using CREATE TABLE IF NOT EXISTS and a guarded CHECK constraint, following existing migration style.

🤖 Prompt for AI agents

Build the outbound-call integration boundary (Vapi client) and its outcome
logging table, kept separate from scheduler orchestration.

1. Vapi client (`src/lib/vapi.ts`):
- Add `import "server-only"` at the top.
- Add an env guard function (e.g. `requireVapiApiKey()`) that reads
`VAPI_API_KEY`, plus reads `VAPI_ASSISTANT_ID` and `VAPI_PHONE_NUMBER_ID`,
mirroring the pattern in `src/lib/daily.ts`.
- Implement `initiateMissedSitCall({ phoneNumber, variableValues })` that POSTs
to Vapi's `/call` endpoint with `assistantId`, `phoneNumberId`,
`customer.number` (E.164 formatted), and `assistantOverrides.variableValues`
containing `name`, `streak`, `daysMissed`.
- Follow the `apns.ts` result-object approach: return a discriminated union `{
ok: true, callId } | { ok: false, status, reason }` for expected provider
failures; only throw for unexpected transport errors. Add a request timeout via
`AbortSignal.timeout(...)`. Add a typed `VapiApiError` class analogous to
`DailyApiError`.
- Update `.env.example` to add the new `VAPI_*` variables, commented out,
grouped together, with a "server-only / never commit" style comment, following
existing convention.

2. Call attempt log table:
- In `src/db/schema.ts`, add a `callAttempts` table mirroring the shape of
`buddySessionCalendarEvents`: columns `id`, `userId` (FK with cascade delete), a
`windowKey`/slot identifier column, `status` as `varchar(20)` with a CHECK
constraint limiting values (e.g. `'initiated' | 'failed'`), nullable `error`
text, nullable external `callId`, and `createdAt` timestamp with timezone.
- Add a new additive migration `drizzle/call_attempts_<issue#>_incremental.sql`
using `CREATE TABLE IF NOT EXISTS` plus a guarded CHECK constraint, matching the
existing migration style in the repo.

Phase 3: Scheduler hourly call-window evaluation

Extend the existing cron-driven scheduler to evaluate and place due calls per user, preserving idempotency, per-user error isolation, and #561 timezone handling.

Task 1: Implement pure call-window due evaluation

Add the time-window logic analogous to the existing reminder-window helpers.

• In src/lib/notification-scheduler.ts, add a pure helper (mirroring isWithinCronWindow/evaluateReminderDispatchWindow) that, given the user's local parts (from getLocalParts) and callWindowStart/callWindowStop, determines whether the current tick falls within the inclusive 5-minute window after an hourly slot time (slots at start, start+60, start+120, … while ≤ stop).
• Compute an hour-granular windowKey for the intended slot (e.g. YYYY-MM-DD-HHMM of the slot in local time), reusing the midnight dayOffset/addCalendarDays anchoring so slots near boundaries dedup against the intended local date.
• Ensure no slot is emitted outside [start, stop] and none when the window fields are unset — satisfying "no calls outside [X, Y]."

Task 2: Add the call dispatch branch to the batch job

Integrate call evaluation into dispatchDueNotifications with cancellation and idempotency.

• Extend the candidate query to also select rows where callOptIn = true; add call fields to the idx_notification_preferences_dispatch index via a follow-up DROP INDEX/CREATE INDEX migration if needed for candidate selection efficiency.
• Within the existing per-user try/catch block, when a call slot is due: skip if userCompletedSessionOnDate(userId, localDateKey) is true (cancels remaining calls once any qualifying sit is completed that day), then claimNotificationDispatch with a new notificationType (e.g. "missed_sit_call") and the hourly windowKey.
• On successful claim, gather context (name via a user lookup, loadUserStreak, and days-missed derived from last completed session date), call initiateMissedSitCall, and write a callAttempts row with outcome; on ok: false or thrown error, log with structured console.error/console.warn, record a failed attempt, and release the claim so a later tick can retry — matching the existing release-on-failure pattern.
• Add a callsInitiated counter to the returned summary object so the cron response and tests can assert it; ensure a Vapi failure never aborts the loop (per-user isolation already provides this).

Task 3: Surface the new counter through the cron route

Expose call dispatch results without changing cron auth/schedule.

• Update src/app/api/cron/dispatch-notifications/route.ts to include the new callsInitiated field in the returned JSON, keeping the same isAuthorizedCron gating and */5 * * * * schedule (no vercel.json change needed).

🤖 Prompt for AI agents

Extend the existing 5-minute `dispatch-notifications` cron scheduler to evaluate
and place due missed-sit calls, preserving idempotency, per-user error
isolation, and existing timezone handling.

1. Pure due-evaluation helper:
- In `src/lib/notification-scheduler.ts`, add a pure helper mirroring
`isWithinCronWindow`/`evaluateReminderDispatchWindow` that, given the user's
local time parts (from `getLocalParts`) and `callWindowStart`/`callWindowStop`,
determines whether the current tick falls within the inclusive 5-minute window
after an hourly slot (slots at start, start+60, start+120, ... while ≤ stop).
- Compute an hour-granular `windowKey` for the intended slot (e.g.
`YYYY-MM-DD-HHMM` in local time), reusing the existing midnight
`dayOffset`/`addCalendarDays` anchoring logic so boundary slots dedup against
the correct intended local date.
- Ensure the helper never emits a due slot outside `[start, stop]` and never
emits one when the window fields are unset.

2. Integrate into `dispatchDueNotifications`:
- Extend the candidate query to also select rows where `callOptIn = true`. If
needed for query efficiency, add a follow-up migration updating the
`idx_notification_preferences_dispatch` index (`DROP INDEX`/`CREATE INDEX`) to
include the new call fields.
- Inside the existing per-user try/catch block, when a call slot is due: first
check `userCompletedSessionOnDate(userId, localDateKey)` and skip (cancel
remaining calls for the day) if true.
- Otherwise call `claimNotificationDispatch` using a new `notificationType`
value (e.g. `"missed_sit_call"`) and the hourly `windowKey`.
- On successful claim: gather user context (name via user lookup,
`loadUserStreak`, and days-missed derived from the last completed session date),
call `initiateMissedSitCall`, and write a `callAttempts` row recording the
outcome.
- On failure (`ok: false` result or thrown error): log via structured
`console.error`/`console.warn`, write a `failed` `callAttempts` row, and release
the claim so a subsequent tick can retry, matching the existing
release-on-failure pattern.
- Add a `callsInitiated` counter to the returned summary object. Ensure Vapi
failures never abort the per-user loop.

3. Cron route:
- In `src/app/api/cron/dispatch-notifications/route.ts`, include the new
`callsInitiated` field in the JSON response, without changing the existing
`isAuthorizedCron` gating or the `*/5 * * * *` schedule.

Phase 4: iOS settings UI

Give the product-owner test user a way to opt in, provide a phone number, record consent, and set the [X, Y] window, mirroring existing controls.

Task 1: Extend shared DTOs

Add the new fields to the wire contract with backward-compatible decoding.

• Update ios/StillPointShared/Sources/StillPointShared/DTOs/DTOs.swift: add callOptIn, callPhoneNumber (String?), callConsentAt (String?), callWindowStart/callWindowStop (String?) to NotificationPreferencesDTO using decodeIfPresent + defaults; add matching fields to NotificationPreferencesPatch, using the double-optional (String??) pattern for the clearable phone number and window fields.

Task 2: Extend the view model and settings view

Add the opt-in, phone entry, consent, and time-window controls.

• Update ios/StillPointApp/ViewModels/NotificationPreferencesViewModel.swift to mirror new DTO fields as VM state (opt-in Bool, phone String, window start/stop as Date via formatHHMM/parseHHMM), with dedicated persist* methods building minimal patches and reusing the shared persist(patch:) flow.
• Update ios/StillPointApp/Views/NotificationsSettingsView.swift to add a "Missed-sit call" section: opt-in Toggle (with brief consent copy so enabling it records consent), a phone-number TextField (validate E.164 client-side before enabling opt-in), and two .hourAndMinute DatePickers for start/stop mirroring the quiet-hours section, each with accessibility identifiers and disabled-while-saving behavior.

🤖 Prompt for AI agents

Add iOS UI controls so users can opt in to missed-sit calls, provide a phone
number, record consent, and configure the [X, Y] call window, mirroring existing
preference controls.

1. Shared DTOs:
- In `ios/StillPointShared/Sources/StillPointShared/DTOs/DTOs.swift`, add
`callOptIn`, `callPhoneNumber` (`String?`), `callConsentAt` (`String?`), and
`callWindowStart`/`callWindowStop` (`String?`) to `NotificationPreferencesDTO`,
decoding with `decodeIfPresent` plus sensible defaults for backward
compatibility.
- Add matching fields to `NotificationPreferencesPatch`, using the
double-optional (`String??`) pattern already used for clearable fields, for the
phone number and window fields.

2. View model and view:
- In `ios/StillPointApp/ViewModels/NotificationPreferencesViewModel.swift`, add
VM state mirroring the new DTO fields: opt-in as `Bool`, phone as `String`, and
window start/stop as `Date` (converted via the existing `formatHHMM`/`parseHHMM`
helpers). Add dedicated `persist*` methods that build minimal patches and reuse
the existing `persist(patch:)` flow.
- In `ios/StillPointApp/Views/NotificationsSettingsView.swift`, add a new
"Missed-sit call" section containing: an opt-in `Toggle` with brief consent copy
indicating that enabling it records consent; a phone-number `TextField` that
validates E.164 format client-side before allowing opt-in; and two
`.hourAndMinute` `DatePicker` controls for window start/stop, mirroring the
existing quiet-hours section's structure, each with accessibility identifiers
and disabled-while-saving behavior.

Phase 5: Tests and documentation

Validate the logic tiers and document the new type, including its non-standard hourly window semantics.

Task 1: Add backend tests

Cover due-evaluation, cancellation, gating, timezone, and API/route contracts.

• Add scheduler unit tests (mirroring src/lib/notification-scheduler.test.ts's mocked-@/db/drizzle-orm pattern): hourly slot due at boundary minute, no calls outside [X, Y], cancellation once a qualifying session exists, opt-in gating, hourly-slot idempotency across adjacent ticks, timezone/DST correctness via America/New_York, and claim-release when the Vapi call fails.
• Add a Vapi client test that mocks the outbound HTTP call and asserts the payload shape (assistant/phone IDs, E.164 customer.number, assistantOverrides.variableValues with name/streak/days-missed) and result mapping.
• Extend src/app/api/notifications/preferences/route.test.ts for the new validation paths (invalid phone → 400, partial window → 400, opt-in without phone/window → 400, consent timestamp set on opt-in) and dispatch-notifications/route.test.ts to assert the new callsInitiated field passes through.

Task 2: Update documentation

Record the new notification type and its hourly-window deviation from existing daily semantics.

• Update docs/notifications.md: add the missed_sit_call type to the types table, document the hour-granular windowKey (a deliberate deviation from the daily YYYY-MM-DD convention), the opt-in/consent/phone requirements, and how the call window interacts with #561 timezone handling and DST transitions.

🤖 Prompt for AI agents

Add automated test coverage across all changed logic tiers and update
documentation to reflect the new notification type and its non-standard hourly
window semantics.

1. Backend tests:
- Add scheduler unit tests mirroring the mocked-`@/db`/`drizzle-orm` pattern in
`src/lib/notification-scheduler.test.ts`, covering: hourly slot due exactly at
the boundary minute; no calls emitted outside [X, Y]; cancellation of remaining
calls once a qualifying session exists; opt-in gating; hourly-slot idempotency
across adjacent ticks; timezone/DST correctness using `America/New_York`; and
claim-release behavior when the Vapi call fails.
- Add a Vapi client test that mocks the outbound HTTP call and asserts: correct
payload shape (assistant ID, phone number ID, E.164 `customer.number`,
`assistantOverrides.variableValues` containing name/streak/days-missed) and
correct result mapping for success/failure cases.
- Extend `src/app/api/notifications/preferences/route.test.ts` to cover new
validation paths: invalid phone number returns 400; partial window (only start
or only stop) returns 400; opt-in without phone/window returns 400; consent
timestamp is set when opting in.
- Extend `dispatch-notifications/route.test.ts` to assert the new
`callsInitiated` field is present and passed through correctly in the JSON
response.

2. Documentation:
- Update `docs/notifications.md` to add the `missed_sit_call` type to the
notification types table, document the hour-granular `windowKey` format as a
deliberate deviation from the daily `YYYY-MM-DD` convention used by other types,
describe the opt-in/consent/phone requirements, and explain how the call window
interacts with the existing timezone handling (`#561`) and DST transitions.

Research

The backend is a Next.js app with Drizzle/Postgres. Scheduled re-engagement runs through a single Vercel cron (/api/cron/dispatch-notifications, every 5 minutes) that calls dispatchDueNotifications() in src/lib/notification-scheduler.ts. That scheduler resolves each user's local wall-clock time from notification_preferences.tz via Intl.DateTimeFormat (the #561 timezone approach), evaluates per-type due windows, and uses a "claim → send → release-on-failure" idempotency pattern against notification_dispatches (unique on userId, notificationType, windowKey). Preferences live in notification_preferences (booleans + HH:MM varchar(5) fields such as dailyReminderTime, quietHoursStart/End), exposed via GET/PATCH /api/notifications/preferences with hand-rolled validation from src/lib/notification-preferences.ts, and mirrored on iOS through NotificationPreferencesDTO/NotificationPreferencesPatch and NotificationsSettingsView.swift. External API clients (e.g. src/lib/daily.ts, src/lib/apns.ts) follow a server-only, env-guarded fetch-wrapper pattern with typed errors and caller-side logging. "Qualifying session completed today" is determined by userCompletedSessionOnDate() in src/lib/notifications/daily-reminder.ts (any completed session, any type/track), and loadUserStreak() provides the consecutive-day streak. There is no prior Vapi, phone-number, or voice-call code anywhere.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the persistence and API layer for the new missed-sit-call opt-in
feature by extending the existing `notification_preferences` table and its
API/validation layer, mirroring the existing quiet-hours/reminder-time patterns.

1. Schema and migration:
- In `src/db/schema.ts`, add to `notificationPreferences`: `callOptIn` boolean
(default `false`, not null), `callPhoneNumber` nullable `varchar` sized for
E.164 (e.g. length 20), `callConsentAt` nullable timestamp with timezone, and
`callWindowStart`/`callWindowStop` nullable `varchar(5)` in `HH:MM` format
mirroring quiet hours.
- Decide whether to enforce the "opt-in requires phone + window" rule via a DB
CHECK constraint or leave it to API validation (prefer API validation for
simplicity).
- Add a new additive migration file
`drizzle/notification_preferences_call_window_<issue#>_incremental.sql` using
`ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...`, matching the style of existing
`notification_preferences_*_incremental.sql` files.

2. Typed helpers:
- In `src/lib/notification-preferences.ts`, extend `NotificationPreferencesRow`,
`DEFAULT_NOTIFICATION_PREFERENCES` (opt-in `false`; phone/consent/window
`null`), and `serializeNotificationPreferences` (serialize `callConsentAt` as an
ISO string like `updatedAt`).
- Add an E.164 phone validator (mirroring the validation structure in
`src/lib/username.ts`) and reuse the existing `HH:MM` `timePattern` for
validating the window fields.

3. API route:
- In `src/app/api/notifications/preferences/route.ts`, extend the PATCH handler
to accept `callOptIn` (boolean), `callPhoneNumber` (validated E.164, or explicit
`null` to clear using the existing double-optional clear semantics), and
`callWindowStart`/`callWindowStop` (validated `HH:MM`, required together, 400 on
partial).
- Enforce gating logic: if `callOptIn` transitions to `true`, require a valid
phone number and both window fields (either in the current patch or already
persisted); otherwise return 400.
- When `callOptIn` becomes `true`, set `callConsentAt` to the current timestamp;
when opting out, clear `callConsentAt`.
===============================================================================

Task: 2

Build the outbound-call integration boundary (Vapi client) and its outcome
logging table, kept separate from scheduler orchestration.

1. Vapi client (`src/lib/vapi.ts`):
- Add `import "server-only"` at the top.
- Add an env guard function (e.g. `requireVapiApiKey()`) that reads
`VAPI_API_KEY`, plus reads `VAPI_ASSISTANT_ID` and `VAPI_PHONE_NUMBER_ID`,
mirroring the pattern in `src/lib/daily.ts`.
- Implement `initiateMissedSitCall({ phoneNumber, variableValues })` that POSTs
to Vapi's `/call` endpoint with `assistantId`, `phoneNumberId`,
`customer.number` (E.164 formatted), and `assistantOverrides.variableValues`
containing `name`, `streak`, `daysMissed`.
- Follow the `apns.ts` result-object approach: return a discriminated union `{
ok: true, callId } | { ok: false, status, reason }` for expected provider
failures; only throw for unexpected transport errors. Add a request timeout via
`AbortSignal.timeout(...)`. Add a typed `VapiApiError` class analogous to
`DailyApiError`.
- Update `.env.example` to add the new `VAPI_*` variables, commented out,
grouped together, with a "server-only / never commit" style comment, following
existing convention.

2. Call attempt log table:
- In `src/db/schema.ts`, add a `callAttempts` table mirroring the shape of
`buddySessionCalendarEvents`: columns `id`, `userId` (FK with cascade delete), a
`windowKey`/slot identifier column, `status` as `varchar(20)` with a CHECK
constraint limiting values (e.g. `'initiated' | 'failed'`), nullable `error`
text, nullable external `callId`, and `createdAt` timestamp with timezone.
- Add a new additive migration `drizzle/call_attempts_<issue#>_incremental.sql`
using `CREATE TABLE IF NOT EXISTS` plus a guarded CHECK constraint, matching the
existing migration style in the repo.
===============================================================================

Task: 3

Extend the existing 5-minute `dispatch-notifications` cron scheduler to evaluate
and place due missed-sit calls, preserving idempotency, per-user error
isolation, and existing timezone handling.

1. Pure due-evaluation helper:
- In `src/lib/notification-scheduler.ts`, add a pure helper mirroring
`isWithinCronWindow`/`evaluateReminderDispatchWindow` that, given the user's
local time parts (from `getLocalParts`) and `callWindowStart`/`callWindowStop`,
determines whether the current tick falls within the inclusive 5-minute window
after an hourly slot (slots at start, start+60, start+120, ... while ≤ stop).
- Compute an hour-granular `windowKey` for the intended slot (e.g.
`YYYY-MM-DD-HHMM` in local time), reusing the existing midnight
`dayOffset`/`addCalendarDays` anchoring logic so boundary slots dedup against
the correct intended local date.
- Ensure the helper never emits a due slot outside `[start, stop]` and never
emits one when the window fields are unset.

2. Integrate into `dispatchDueNotifications`:
- Extend the candidate query to also select rows where `callOptIn = true`. If
needed for query efficiency, add a follow-up migration updating the
`idx_notification_preferences_dispatch` index (`DROP INDEX`/`CREATE INDEX`) to
include the new call fields.
- Inside the existing per-user try/catch block, when a call slot is due: first
check `userCompletedSessionOnDate(userId, localDateKey)` and skip (cancel
remaining calls for the day) if true.
- Otherwise call `claimNotificationDispatch` using a new `notificationType`
value (e.g. `"missed_sit_call"`) and the hourly `windowKey`.
- On successful claim: gather user context (name via user lookup,
`loadUserStreak`, and days-missed derived from the last completed session date),
call `initiateMissedSitCall`, and write a `callAttempts` row recording the
outcome.
- On failure (`ok: false` result or thrown error): log via structured
`console.error`/`console.warn`, write a `failed` `callAttempts` row, and release
the claim so a subsequent tick can retry, matching the existing
release-on-failure pattern.
- Add a `callsInitiated` counter to the returned summary object. Ensure Vapi
failures never abort the per-user loop.

3. Cron route:
- In `src/app/api/cron/dispatch-notifications/route.ts`, include the new
`callsInitiated` field in the JSON response, without changing the existing
`isAuthorizedCron` gating or the `*/5 * * * *` schedule.
===============================================================================

Task: 4

Add iOS UI controls so users can opt in to missed-sit calls, provide a phone
number, record consent, and configure the [X, Y] call window, mirroring existing
preference controls.

1. Shared DTOs:
- In `ios/StillPointShared/Sources/StillPointShared/DTOs/DTOs.swift`, add
`callOptIn`, `callPhoneNumber` (`String?`), `callConsentAt` (`String?`), and
`callWindowStart`/`callWindowStop` (`String?`) to `NotificationPreferencesDTO`,
decoding with `decodeIfPresent` plus sensible defaults for backward
compatibility.
- Add matching fields to `NotificationPreferencesPatch`, using the
double-optional (`String??`) pattern already used for clearable fields, for the
phone number and window fields.

2. View model and view:
- In `ios/StillPointApp/ViewModels/NotificationPreferencesViewModel.swift`, add
VM state mirroring the new DTO fields: opt-in as `Bool`, phone as `String`, and
window start/stop as `Date` (converted via the existing `formatHHMM`/`parseHHMM`
helpers). Add dedicated `persist*` methods that build minimal patches and reuse
the existing `persist(patch:)` flow.
- In `ios/StillPointApp/Views/NotificationsSettingsView.swift`, add a new
"Missed-sit call" section containing: an opt-in `Toggle` with brief consent copy
indicating that enabling it records consent; a phone-number `TextField` that
validates E.164 format client-side before allowing opt-in; and two
`.hourAndMinute` `DatePicker` controls for window start/stop, mirroring the
existing quiet-hours section's structure, each with accessibility identifiers
and disabled-while-saving behavior.
===============================================================================

Task: 5

Add automated test coverage across all changed logic tiers and update
documentation to reflect the new notification type and its non-standard hourly
window semantics.

1. Backend tests:
- Add scheduler unit tests mirroring the mocked-`@/db`/`drizzle-orm` pattern in
`src/lib/notification-scheduler.test.ts`, covering: hourly slot due exactly at
the boundary minute; no calls emitted outside [X, Y]; cancellation of remaining
calls once a qualifying session exists; opt-in gating; hourly-slot idempotency
across adjacent ticks; timezone/DST correctness using `America/New_York`; and
claim-release behavior when the Vapi call fails.
- Add a Vapi client test that mocks the outbound HTTP call and asserts: correct
payload shape (assistant ID, phone number ID, E.164 `customer.number`,
`assistantOverrides.variableValues` containing name/streak/days-missed) and
correct result mapping for success/failure cases.
- Extend `src/app/api/notifications/preferences/route.test.ts` to cover new
validation paths: invalid phone number returns 400; partial window (only start
or only stop) returns 400; opt-in without phone/window returns 400; consent
timestamp is set when opting in.
- Extend `dispatch-notifications/route.test.ts` to assert the new
`callsInitiated` field is present and passed through correctly in the JSON
response.

2. Documentation:
- Update `docs/notifications.md` to add the `missed_sit_call` type to the
notification types table, document the hour-granular `windowKey` format as a
deliberate deviation from the daily `YYYY-MM-DD` convention used by other types,
describe the opt-in/consent/phone requirements, and explain how the call window
interacts with the existing timezone handling (`#561`) and DST transitions.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[auerbachb]

⚠️ Prerequisite — no Vapi account yet. Before implementation can start, we need to create a Vapi account and provision: API key/secret, an outbound phone number, and the motivational-interviewing assistant config. That's a manual account-setup step (owner) and implementation is blocked on it. Vapi + telephony are paid — fine for single-user testing now; multi-user cost/pricing is deferred per the issue.

[auerbachb]

Consolidated implementation plan (#599)

Status: Implementation is blocked on Vapi account provisioning (owner action). Most backend/iOS scaffolding can proceed without live Vapi credentials; end-to-end outbound calls require secrets in Production (and any Preview that runs the dispatch cron).

This consolidates the issue spec, the @coderabbitai plan, repo conventions, and Vapi docs.

---

Blocker: Vapi account setup (owner — manual)

Complete these steps before live call testing. Record the three IDs/keys below; do not commit them.

Step	Action	Output to save
1	Sign up at dashboard.vapi.ai	Account + billing (telephony is paid; fine for single-user MVP)
2	API key: Dashboard → API Keys → Create private key	VAPI_API_KEY
3	Assistant: Dashboard → Assistants → Create	VAPI_ASSISTANT_ID
4	Outbound number: Dashboard → Phone Numbers → Create (US free Vapi number) or import (Twilio etc.)	VAPI_PHONE_NUMBER_ID
5	Smoke test: Dashboard → Outbound → call your own phone with the assistant	Confirms assistant + number work
6	Deploy secrets: Add the three vars to Vercel Production (and Preview only if that env runs /api/cron/dispatch-notifications)	Cron can initiate calls

MI assistant configuration (Vapi dashboard)

Configure the assistant on Vapi’s side (not in Still Point code for MVP):

• System prompt: Motivational interviewing for meditation re-engagement — explore ambivalence, affirm past practice, elicit change talk; avoid lecturing; keep responses concise for voice (~30 words).
• First message: Warm check-in referencing missed practice (use template variables).
• Template variables (Liquid syntax in prompt/firstMessage): reference {{ name }}, {{ streak }}, {{ daysMissed }} — our backend passes these via assistantOverrides.variableValues on each outbound call (Vapi Create Call API).
• Voice/model: Pick a calm, natural voice; GPT-4o or similar is fine for MVP.
• Outbound caller ID: Uses the provisioned phone number; inbound assignment to the same assistant is optional for MVP.

Example outbound API payload (what src/lib/vapi.ts will send):

POST https://api.vapi.ai/call
Authorization: Bearer <VAPI_API_KEY>

{
  "assistantId": "<VAPI_ASSISTANT_ID>",
  "phoneNumberId": "<VAPI_PHONE_NUMBER_ID>",
  "customer": { "number": "+1XXXXXXXXXX" },
  "assistantOverrides": {
    "variableValues": {
      "name": "Brett",
      "streak": "12",
      "daysMissed": "2"
    }
  }
}

---

Environment variables (placeholders only — never commit)

Add to .env.local / Vercel server env (same pattern as DAILY_API_KEY, APNS_*):

Variable	Purpose	Where set
VAPI_API_KEY	Private API key (Authorization: Bearer …)	Vercel Production (+ Preview if cron runs there)
VAPI_ASSISTANT_ID	MI assistant UUID from dashboard	Same
VAPI_PHONE_NUMBER_ID	Outbound caller ID resource UUID	Same

Also update .env.example (commented placeholders) when implementation lands — no real values.

Existing vars unchanged: CRON_SECRET (cron auth), DATABASE_URL, APNs/Web Push vars for other notification types.

---

Architecture (aligned with repo)

Concern	Decision
Storage	notification_preferences — callOptIn, callPhoneNumber (E.164), callConsentAt, callWindowStart/callWindowStop (HH:MM) — mirrors quiet hours
Scheduler	Extend existing 5-min /api/cron/dispatch-notifications + notification-scheduler.ts (reuse #561 timezone + claim/release)
Call window	If no qualifying sit by X, call at X, then hourly until Y or sit completed — windowKey = YYYY-MM-DD-HHMM (hour-granular dedup)
Cancellation	Any qualifying sit today → skip remaining slots (userCompletedSessionOnDate)
Opt-in	Off by default; enabling records callConsentAt; requires phone + window
Logging	call_attempts table for outcomes; notification_dispatches for slot dedup only
Vapi client	src/lib/vapi.ts — server-only, env-guarded, result-object pattern like apns.ts / daily.ts
UI	iOS-first settings section; web parity later

Qualifying session: any completed sit (standard/quick/breath) per #589/#590.

---

Implementation phases

Phase	Scope	Blocked on Vapi?
1	Schema + migration, notification-preferences.ts, PATCH/GET API, consent semantics	No
2	src/lib/vapi.ts + call_attempts table + .env.example placeholders	No (mock HTTP in tests)
3	Hourly slot evaluation + scheduler integration + callsInitiated cron field	No (Vapi mocked; live calls no-op/fail gracefully if env unset)
4	iOS DTOs + Notifications settings UI	No
5	Tests + docs/notifications.md	No
E2E	Product-owner test: opt in → miss sit → receive MI call	Yes — needs all three VAPI_* vars

---

What can start now

• Phases 1–5 can land on issue-599-* with full unit/route tests (mocked Vapi).
• Scheduler should skip call dispatch (or return { ok: false } without crashing) when VAPI_* vars are missing — same visibility pattern as #621 APNs guard.
• Do not place real outbound calls until owner completes Vapi setup + Vercel secrets.

Sub-issues will be linked below for parallel/agent work.

---

Test plan (from issue)

• Opt in, set X/Y, don't sit → call at X, hourly until Y
• Sit before X → no call; sit after first call → remaining cancelled
• Opt out → no calls
• Unit: hourly due evaluation, timezone, opt-in gating, cancel-on-completion, Vapi mock
• Live smoke (owner): one outbound call with context variables

---

Related

#247, #527, #238 (re-engagement), #561 (timezone), #441 (failure-reason reminder pattern)

[auerbachb]

Implementation sub-issues

Parallel work breakdown (none require Vapi secrets except live E2E on #599):

• 599-1: Schema + preferences API for missed-sit calls #638 — Phase 1: Schema + preferences API + consent
• 599-2: Vapi client + call_attempts logging #639 — Phase 2: Vapi client + call_attempts logging
• 599-3: Scheduler hourly missed-sit call dispatch #640 — Phase 3: Scheduler hourly dispatch
• 599-4: iOS missed-sit call settings UI #641 — Phase 4: iOS settings UI
• 599-5: Tests + docs for missed-sit calls #642 — Phase 5: Tests + docs

Next step after Vapi setup: set VAPI_* in Vercel Production, then run owner E2E test plan on #599.

[coderabbitai]

@auerbachb, acknowledged. The consolidated plan is aligned and makes the operational boundary clear:

• Phases 1–5 can proceed with mocked Vapi integration and complete automated coverage.
• Live outbound calls and E2E validation remain blocked until the owner provisions the Vapi account, assistant, caller ID, and server-side VAPI_* secrets.
• Missing Vapi configuration must degrade safely—no scheduler crash and no real outbound attempt.
• Secrets remain server-only and must never be committed.

🐇📋

---

✏️ Learnings added

Learnt from: auerbachb
URL: https://github.com/auerbachb/still-point/issues/599

Timestamp: 2026-07-23T19:27:39.370Z
Learning: For GitHub Issue `#599` in the still-point repository, Vapi account provisioning is an owner-managed prerequisite only for live outbound-call E2E testing. Backend and iOS phases 1–5 can be implemented and tested with mocked Vapi HTTP responses before `VAPI_API_KEY`, `VAPI_ASSISTANT_ID`, and `VAPI_PHONE_NUMBER_ID` exist.

---

Learnt from: auerbachb
URL: https://github.com/auerbachb/still-point/issues/599

Timestamp: 2026-07-23T19:27:39.370Z
Learning: For GitHub Issue `#599` in the still-point repository, `src/lib/vapi.ts` and scheduler integration must safely skip or return a non-throwing failure result when required `VAPI_*` server environment variables are absent; missing Vapi configuration must not crash `dispatchDueNotifications()` or place real calls.

---

Learnt from: auerbachb
URL: https://github.com/auerbachb/still-point/issues/599

Timestamp: 2026-07-23T19:27:39.370Z
Learning: For GitHub Issue `#599` in the still-point repository, missed-sit call preferences belong in `notification_preferences`: opt-in defaults off, E.164 phone number, consent timestamp, and `HH:MM` call window. Calls use hourly `YYYY-MM-DD-HHMM` dispatch keys, stop after any qualifying completed sit on that local date, and write outcomes to a dedicated `call_attempts` table.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.