Miss-a-day push notification with shortened-session follow-up

[auerbachb]

Problem

Users who miss a day or do a shortened session aren't given a feedback loop to surface why. We're missing signal on why people drop off or shorten sessions, and an opportunity to re-engage.

Proposal

• If a user misses a day, send a push notification asking why they couldn't find one minute to meditate.
• If a user completes a shortened session, prompt them at the end of it asking why they shortened it.

Scope notes

• Push notification copy needs to be empathetic, not guilt-trippy.
• Response capture: free-text and/or multiple choice — TBD.
• Frequency cap: don't send miss-a-day pushes on consecutive days indefinitely.

Acceptance criteria

• Miss-a-day push fires after a missed day with appropriate copy
• Shortened-session prompt appears at end-of-session when session was below the user's normal length
• User responses are captured and stored
• Frequency cap prevents repeated nag pushes

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Builds complete push notification infrastructure from scratch: database tables for tokens and notification history, APNs server integration, and iOS push registration
• Implements shortened-session feedback as an inline overlay prompt (following existing ThoughtCaptureView pattern) that captures responses before session completion
• Uses Vercel cron jobs for daily miss-a-day detection with a rolling frequency cap (max 3 per 7 days, 2-day minimum gap) to prevent notification fatigue
• Stores all feedback in a unified user_feedback table enabling future analysis of drop-off and session-shortening patterns

Design Choices

Design Choice 1: Push notification provider selection

Options Considered:

1. Direct APNs integration — minimal dependencies, native iOS approach
2. Firebase Cloud Messaging (FCM) — more abstraction, supports Android if needed later
3. Expo Push — requires Expo SDK integration

Chosen Option: 1

Rationale: The app is iOS-native without Expo, and APNs is the simplest path with no additional SDK dependencies.

Design Choice 2: Feedback capture format

Options Considered:

1. Multiple choice only — easier to analyze, less friction
2. Free-text only — richer signal, more user effort
3. Multiple choice with optional free-text — balanced approach

Chosen Option: 3

Rationale: Predefined options with an optional free-text field. This enables quick responses while preserving the ability to capture detailed feedback when users want to share more.

Design Choice 3: Frequency cap strategy

Options Considered:

1. Simple consecutive-day block — stop after N consecutive missed days
2. Rolling window cap — max N notifications per time period
3. Exponential backoff — increasing gaps between notifications

Chosen Option: 2

Rationale: Rolling window with max 3 notifications per 7-day period and minimum 2-day gap between notifications. This prevents spam while allowing periodic re-engagement.

💡 User Tips

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

Implementation Steps

Phase 1: Database Schema and API Foundation

Establish the data layer for device tokens, notification tracking, and feedback storage, plus the API endpoints that iOS will call for registration and feedback submission.

Task 1: Create Database Tables for Push Notifications and Feedback

Add three new tables to support the notification and feedback system.

• Add push_tokens table to src/db/schema.ts with fields: id, user_id (FK to users), device_token (varchar, unique), platform (varchar, default 'ios'), created_at, updated_at
• Add notification_log table to track sent notifications: id, user_id, notification_type (varchar: 'missed_day'), sent_at, opened_at (nullable), responded_at (nullable)
• Add user_feedback table for responses: id, user_id, feedback_type (varchar: 'missed_day' | 'shortened_session'), session_id (nullable FK), selected_option (varchar, nullable), free_text (text, nullable), created_at
• Create corresponding Drizzle relations for user associations
• Add SQL migration file in drizzle/ for the new tables

Task 2: Build Device Token Registration API

Create endpoint for iOS to register/update push tokens.

• Create POST /api/push/register route in src/app/api/push/register/
• Accept { deviceToken: string } in request body
• Upsert token for authenticated user (update if exists, insert if new)
• Return success confirmation
• Add DELETE /api/push/register to allow token removal on logout

Task 3: Build Feedback Submission API

Create endpoint to capture user feedback from both shortened sessions and push notification responses.

• Create POST /api/feedback route in src/app/api/feedback/
• Accept { feedbackType: 'missed_day' | 'shortened_session', sessionId?: string, selectedOption?: string, freeText?: string }
• Validate that sessionId (if provided) belongs to the authenticated user
• Insert into user_feedback table
• If feedbackType is 'missed_day', update corresponding notification_log row's responded_at
• Return created feedback record

Task 4: Add Feedback Option Constants

Define the predefined response options that will be shared between backend validation and iOS UI.

• Create src/lib/feedbackOptions.ts with exported constants for shortened session reasons (e.g., "Not enough time", "Feeling restless", "Interrupted", "Other") and missed day reasons (e.g., "Too busy", "Forgot", "Didn't feel like it", "Other")
• Export TypeScript types for feedback types and option values
• Design for easy extension of options without breaking existing data

🤖 Prompt for AI agents

Implement the database schema and API foundation for the push notification and
feedback system. The goal is to create all necessary data tables, migration
files, API routes, and shared constants before any iOS or notification logic is
built.

**Database Schema (`src/db/schema.ts`)**
- Add `push_tokens` table with fields: `id`, `user_id` (FK to users),
`device_token` (varchar, unique), `platform` (varchar, default `'ios'`),
`created_at`, `updated_at`
- Add `notification_log` table with fields: `id`, `user_id`, `notification_type`
(varchar: `'missed_day'`), `sent_at`, `opened_at` (nullable), `responded_at`
(nullable)
- Add `user_feedback` table with fields: `id`, `user_id`, `feedback_type`
(varchar: `'missed_day'` | `'shortened_session'`), `session_id` (nullable FK),
`selected_option` (varchar, nullable), `free_text` (text, nullable),
`created_at`
- Add Drizzle relations for all user associations
- Create a SQL migration file in `drizzle/` covering all three new tables

**Device Token Registration API**
- Create `POST /api/push/register` in `src/app/api/push/register/`
  - Accept `{ deviceToken: string }` in request body
- Upsert the token for the authenticated user (insert or update if already
exists)
  - Return success confirmation
- Add `DELETE /api/push/register` to remove the token on user logout

**Feedback Submission API**
- Create `POST /api/feedback` in `src/app/api/feedback/`
- Accept `{ feedbackType: 'missed_day' | 'shortened_session', sessionId?:
string, selectedOption?: string, freeText?: string }`
  - Validate that `sessionId` (if provided) belongs to the authenticated user
  - Insert a record into `user_feedback`
- If `feedbackType` is `'missed_day'`, update the corresponding
`notification_log` row's `responded_at` field
  - Return the created feedback record

**Feedback Option Constants (`src/lib/feedbackOptions.ts`)**
- Export constants for shortened session reasons (e.g., `"Not enough time"`,
`"Feeling restless"`, `"Interrupted"`, `"Other"`) and missed day reasons (e.g.,
`"Too busy"`, `"Forgot"`, `"Didn't feel like it"`, `"Other"`)
- Export TypeScript types for feedback types and option values
- Design the structure to allow easy extension without breaking existing stored
data

Phase 2: iOS Client Features

Implement push notification registration and the shortened-session feedback prompt in the iOS app.

Task 1: Add Push Notification Capability and Registration

Configure iOS app for push notifications and register device tokens with the backend.

• Add push notification entitlement to the Xcode project (update project.yml with push capability)
• Add aps-environment entitlement to Info.plist
• Create PushNotificationManager.swift in ios/StillPointApp/Services/ to handle UNUserNotificationCenter setup
• Request notification permissions on first app launch (or after onboarding)
• Implement didRegisterForRemoteNotificationsWithDeviceToken in the app delegate or scene delegate to capture the token
• Call POST /api/push/register with the device token after successful registration
• Handle token refresh — re-register if token changes

Task 2: Handle Incoming Push Notifications

Process received notifications and navigate users appropriately.

• Implement UNUserNotificationCenterDelegate methods in PushNotificationManager
• When a missed-day notification is tapped, navigate to home screen (or a feedback capture screen if implementing in-app response)
• Track notification opens by calling a lightweight API endpoint or including in next feedback submission
• Handle notifications received while app is in foreground (show banner or suppress based on context)

Task 3: Build Shortened Session Feedback Prompt UI

Create an overlay prompt that appears when users end a session early.

• Create ShortenedSessionPromptView.swift in ios/StillPointApp/Components/ following the ThoughtCaptureView pattern
• Display predefined reason options as tappable buttons/chips
• Include optional free-text field for "Other" or additional context
• Add "Skip" option to dismiss without feedback
• Style consistently with existing amber/green design language

Task 4: Integrate Feedback Prompt into Session End Flow

Wire the prompt into the existing end-early flow in SessionView.

• Add @State private var showShortenedPrompt = false to SessionView
• Modify "End Early" button action: set showShortenedPrompt = true instead of directly calling vm.endEarly()
• Render ShortenedSessionPromptView as a ZStack overlay (same pattern as ThoughtCaptureView)
• On prompt submission: call vm.endEarly(), then handleCompletion(), then submit feedback to POST /api/feedback asynchronously
• On skip: proceed with vm.endEarly() and handleCompletion() without feedback submission
• Feedback submission should be fire-and-forget (non-blocking) — failure should not prevent session completion

Task 5: Add API Client Methods for Push and Feedback

Extend the iOS API client with methods for the new endpoints.

• Add registerPushToken(_ token: String) method to APIClient calling POST /api/push/register
• Add submitFeedback(type:sessionId:selectedOption:freeText:) method calling POST /api/feedback
• Handle authentication headers consistently with existing API methods

🤖 Prompt for AI agents

Implement all iOS client features for push notification registration and the
shortened-session feedback prompt. The goal is to configure the app for APNs,
register tokens with the backend, handle incoming notifications, and surface a
feedback overlay when a user ends a session early.

**Push Notification Setup**
- Update `project.yml` to add the push notification capability and add the
`aps-environment` entitlement to `Info.plist`
- Create `PushNotificationManager.swift` in `ios/StillPointApp/Services/`:
  - Set up `UNUserNotificationCenter`
  - Request notification permissions on first launch or after onboarding
- Implement `UNUserNotificationCenterDelegate` for handling foreground
notifications and notification taps
- On missed-day notification tap, navigate to the home screen (or feedback
capture screen)
  - Track opens via API call or include in next feedback submission
- Implement `didRegisterForRemoteNotificationsWithDeviceToken` in the app/scene
delegate:
  - Call `registerPushToken` on `APIClient` with the new token
  - Re-register on token refresh

**API Client Extensions**
- Add `registerPushToken(_ token: String)` method to `APIClient` calling `POST
/api/push/register`
- Add `submitFeedback(type:sessionId:selectedOption:freeText:)` method calling
`POST /api/feedback`
- Follow existing authentication header patterns

**Shortened Session Feedback UI**
- Create `ShortenedSessionPromptView.swift` in `ios/StillPointApp/Components/`
modeled after `ThoughtCaptureView`:
- Display predefined reason options (from shared constants) as tappable
buttons/chips
  - Include an optional free-text field for "Other" or additional context
  - Include a "Skip" button to dismiss without submitting feedback
  - Style consistently with the existing amber/green design language

**Session End Flow Integration (in `SessionView`)**
- Add `@State private var showShortenedPrompt = false`
- Change the "End Early" button to set `showShortenedPrompt = true` instead of
calling `vm.endEarly()` directly
- Overlay `ShortenedSessionPromptView` using a `ZStack` (same pattern as
`ThoughtCaptureView`)
- On submission: call `vm.endEarly()`, then `handleCompletion()`, then
fire-and-forget `submitFeedback` to `POST /api/feedback`
- On skip: call `vm.endEarly()` and `handleCompletion()` with no feedback
submission
- Feedback failure must never block session completion

Phase 3: Miss-a-Day Notification System

Implement the server-side scheduled job that detects missed days and dispatches push notifications with appropriate frequency capping.

Task 1: Implement APNs Integration

Add server-side capability to send push notifications via Apple Push Notification service.

• Create src/lib/apns.ts with APNs HTTP/2 client using APNS_KEY_ID, APNS_TEAM_ID, APNS_KEY (p8 file contents) environment variables
• Implement JWT token generation for APNs authentication
• Create sendPushNotification(deviceToken: string, payload: APNsPayload) function
• Handle APNs error responses (invalid tokens, etc.) — mark invalid tokens for cleanup
• Use production vs sandbox APNs endpoint based on environment

Task 2: Build Miss-a-Day Detection Logic

Create the core logic to identify users who missed a day and are eligible for notification.

• Create src/lib/missedDayDetection.ts with query logic
• Find users whose most recent session.session_date is before yesterday (UTC-adjusted)
• Filter to users who have at least one registered push token
• Apply frequency cap: exclude users who received a missed-day notification within the last 2 days
• Apply rolling cap: exclude users who received 3+ missed-day notifications in the last 7 days
• Return list of eligible users with their device tokens

Task 3: Create Cron Job API Route

Set up a Vercel cron-triggered endpoint that runs the miss-a-day notification job.

• Create GET /api/cron/missed-day-notifications route in src/app/api/cron/missed-day-notifications/
• Verify cron authorization header (Vercel sets CRON_SECRET for security)
• Call missed-day detection logic to get eligible users
• For each eligible user: send notification via APNs, log to notification_log
• Add crons configuration to vercel.json scheduling the route (e.g., daily at 14:00 UTC)
• Handle partial failures gracefully — continue processing remaining users if one fails

Task 4: Craft Notification Copy

Define empathetic, non-guilt-trippy notification content.

• Create notification copy constants in src/lib/notificationCopy.ts
• Primary message: empathetic check-in tone (e.g., "We missed you yesterday. Even one minute can help maintain your practice.")
• Consider 2-3 variations to rotate for users who receive multiple notifications
• Include appropriate APNs payload structure (alert, sound, badge settings)

🤖 Prompt for AI agents

Implement the server-side miss-a-day notification system including APNs
integration, detection logic, the cron job route, and notification copy. The
goal is to have a daily scheduled job that identifies eligible users and sends
empathetic push notifications while respecting frequency caps.

**APNs Integration (`src/lib/apns.ts`)**
- Implement an APNs HTTP/2 client using environment variables: `APNS_KEY_ID`,
`APNS_TEAM_ID`, `APNS_KEY` (p8 file contents)
- Implement JWT token generation for APNs authentication
- Create a `sendPushNotification(deviceToken: string, payload: APNsPayload)`
function
- Handle APNs error responses (e.g., invalid tokens) — mark invalid tokens for
cleanup
- Switch between production and sandbox APNs endpoints based on the current
environment

**Miss-a-Day Detection Logic (`src/lib/missedDayDetection.ts`)**
- Query for users whose most recent `session.session_date` is before yesterday
(UTC-adjusted)
- Filter to users who have at least one registered push token
- Exclude users who received a missed-day notification within the last 2 days
(minimum gap cap)
- Exclude users who received 3 or more missed-day notifications in the last 7
days (rolling window cap)
- Return the list of eligible users along with their device tokens

**Cron Job API Route (`src/app/api/cron/missed-day-notifications/`)**
- Implement `GET /api/cron/missed-day-notifications`
- Verify the Vercel `CRON_SECRET` authorization header before proceeding
- Call the missed-day detection logic to retrieve eligible users
- For each eligible user: send notification via `sendPushNotification`, then
insert a record into `notification_log`
- Process users sequentially or in batches, continuing on individual failures
(partial failure tolerance)
- Add the `crons` entry to `vercel.json` to schedule the route (e.g., daily at
14:00 UTC)

**Notification Copy (`src/lib/notificationCopy.ts`)**
- Define 2-3 empathetic, non-guilt-trippy message variations to rotate across
notifications (e.g., `"We missed you yesterday. Even one minute can help
maintain your practice."`)
- Include the full APNs payload structure per variation (alert title/body,
sound, badge settings)

Research

The project is a meditation app with a Next.js backend (Vercel-deployed, Drizzle ORM with Neon Postgres) and a native iOS frontend. The database tracks users, sessions (with completed, duration, actual_time, and session_date fields), and buddy co-meditation sessions. Currently, there is no push notification infrastructure — no APNs integration, no device token storage, no scheduled jobs, and no notification-related code on either backend or iOS. The iOS app does have established patterns for inline overlay prompts (ThoughtCaptureView) and session state management that can be extended for the shortened-session feedback feature.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the database schema and API foundation for the push notification and
feedback system. The goal is to create all necessary data tables, migration
files, API routes, and shared constants before any iOS or notification logic is
built.

**Database Schema (`src/db/schema.ts`)**
- Add `push_tokens` table with fields: `id`, `user_id` (FK to users),
`device_token` (varchar, unique), `platform` (varchar, default `'ios'`),
`created_at`, `updated_at`
- Add `notification_log` table with fields: `id`, `user_id`, `notification_type`
(varchar: `'missed_day'`), `sent_at`, `opened_at` (nullable), `responded_at`
(nullable)
- Add `user_feedback` table with fields: `id`, `user_id`, `feedback_type`
(varchar: `'missed_day'` | `'shortened_session'`), `session_id` (nullable FK),
`selected_option` (varchar, nullable), `free_text` (text, nullable),
`created_at`
- Add Drizzle relations for all user associations
- Create a SQL migration file in `drizzle/` covering all three new tables

**Device Token Registration API**
- Create `POST /api/push/register` in `src/app/api/push/register/`
  - Accept `{ deviceToken: string }` in request body
- Upsert the token for the authenticated user (insert or update if already
exists)
  - Return success confirmation
- Add `DELETE /api/push/register` to remove the token on user logout

**Feedback Submission API**
- Create `POST /api/feedback` in `src/app/api/feedback/`
- Accept `{ feedbackType: 'missed_day' | 'shortened_session', sessionId?:
string, selectedOption?: string, freeText?: string }`
  - Validate that `sessionId` (if provided) belongs to the authenticated user
  - Insert a record into `user_feedback`
- If `feedbackType` is `'missed_day'`, update the corresponding
`notification_log` row's `responded_at` field
  - Return the created feedback record

**Feedback Option Constants (`src/lib/feedbackOptions.ts`)**
- Export constants for shortened session reasons (e.g., `"Not enough time"`,
`"Feeling restless"`, `"Interrupted"`, `"Other"`) and missed day reasons (e.g.,
`"Too busy"`, `"Forgot"`, `"Didn't feel like it"`, `"Other"`)
- Export TypeScript types for feedback types and option values
- Design the structure to allow easy extension without breaking existing stored
data
===============================================================================

Task: 2

Implement all iOS client features for push notification registration and the
shortened-session feedback prompt. The goal is to configure the app for APNs,
register tokens with the backend, handle incoming notifications, and surface a
feedback overlay when a user ends a session early.

**Push Notification Setup**
- Update `project.yml` to add the push notification capability and add the
`aps-environment` entitlement to `Info.plist`
- Create `PushNotificationManager.swift` in `ios/StillPointApp/Services/`:
  - Set up `UNUserNotificationCenter`
  - Request notification permissions on first launch or after onboarding
- Implement `UNUserNotificationCenterDelegate` for handling foreground
notifications and notification taps
- On missed-day notification tap, navigate to the home screen (or feedback
capture screen)
  - Track opens via API call or include in next feedback submission
- Implement `didRegisterForRemoteNotificationsWithDeviceToken` in the app/scene
delegate:
  - Call `registerPushToken` on `APIClient` with the new token
  - Re-register on token refresh

**API Client Extensions**
- Add `registerPushToken(_ token: String)` method to `APIClient` calling `POST
/api/push/register`
- Add `submitFeedback(type:sessionId:selectedOption:freeText:)` method calling
`POST /api/feedback`
- Follow existing authentication header patterns

**Shortened Session Feedback UI**
- Create `ShortenedSessionPromptView.swift` in `ios/StillPointApp/Components/`
modeled after `ThoughtCaptureView`:
- Display predefined reason options (from shared constants) as tappable
buttons/chips
  - Include an optional free-text field for "Other" or additional context
  - Include a "Skip" button to dismiss without submitting feedback
  - Style consistently with the existing amber/green design language

**Session End Flow Integration (in `SessionView`)**
- Add `@State private var showShortenedPrompt = false`
- Change the "End Early" button to set `showShortenedPrompt = true` instead of
calling `vm.endEarly()` directly
- Overlay `ShortenedSessionPromptView` using a `ZStack` (same pattern as
`ThoughtCaptureView`)
- On submission: call `vm.endEarly()`, then `handleCompletion()`, then
fire-and-forget `submitFeedback` to `POST /api/feedback`
- On skip: call `vm.endEarly()` and `handleCompletion()` with no feedback
submission
- Feedback failure must never block session completion
===============================================================================

Task: 3

Implement the server-side miss-a-day notification system including APNs
integration, detection logic, the cron job route, and notification copy. The
goal is to have a daily scheduled job that identifies eligible users and sends
empathetic push notifications while respecting frequency caps.

**APNs Integration (`src/lib/apns.ts`)**
- Implement an APNs HTTP/2 client using environment variables: `APNS_KEY_ID`,
`APNS_TEAM_ID`, `APNS_KEY` (p8 file contents)
- Implement JWT token generation for APNs authentication
- Create a `sendPushNotification(deviceToken: string, payload: APNsPayload)`
function
- Handle APNs error responses (e.g., invalid tokens) — mark invalid tokens for
cleanup
- Switch between production and sandbox APNs endpoints based on the current
environment

**Miss-a-Day Detection Logic (`src/lib/missedDayDetection.ts`)**
- Query for users whose most recent `session.session_date` is before yesterday
(UTC-adjusted)
- Filter to users who have at least one registered push token
- Exclude users who received a missed-day notification within the last 2 days
(minimum gap cap)
- Exclude users who received 3 or more missed-day notifications in the last 7
days (rolling window cap)
- Return the list of eligible users along with their device tokens

**Cron Job API Route (`src/app/api/cron/missed-day-notifications/`)**
- Implement `GET /api/cron/missed-day-notifications`
- Verify the Vercel `CRON_SECRET` authorization header before proceeding
- Call the missed-day detection logic to retrieve eligible users
- For each eligible user: send notification via `sendPushNotification`, then
insert a record into `notification_log`
- Process users sequentially or in batches, continuing on individual failures
(partial failure tolerance)
- Add the `crons` entry to `vercel.json` to schedule the route (e.g., daily at
14:00 UTC)

**Notification Copy (`src/lib/notificationCopy.ts`)**
- Define 2-3 empathetic, non-guilt-trippy message variations to rotate across
notifications (e.g., `"We missed you yesterday. Even one minute can help
maintain your practice."`)
- Include the full APNs payload structure per variation (alert title/body,
sound, badge settings)

💡 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!

[coderabbitai]

Coding Plan

Summary

• Builds complete push notification infrastructure from scratch: database tables for tokens and notification history, APNs server integration, and iOS push registration
• Implements shortened-session feedback as an inline overlay prompt (following existing ThoughtCaptureView pattern) that captures responses before session completion
• Uses Vercel cron jobs for daily miss-a-day detection with a rolling frequency cap (max 3 per 7 days, 2-day minimum gap) to prevent notification fatigue
• Stores all feedback in a unified user_feedback table enabling future analysis of drop-off and session-shortening patterns

Design Choices

Design Choice 1: Push notification provider selection

Options Considered:

1. Direct APNs integration — minimal dependencies, native iOS approach
2. Firebase Cloud Messaging (FCM) — more abstraction, supports Android if needed later
3. Expo Push — requires Expo SDK integration

Chosen Option: 1

Rationale: The app is iOS-native without Expo, and APNs is the simplest path with no additional SDK dependencies.

Design Choice 2: Feedback capture format

Options Considered:

1. Multiple choice only — easier to analyze, less friction
2. Free-text only — richer signal, more user effort
3. Multiple choice with optional free-text — balanced approach

Chosen Option: 3

Rationale: Predefined options with an optional free-text field. This enables quick responses while preserving the ability to capture detailed feedback when users want to share more.

Design Choice 3: Frequency cap strategy

Options Considered:

1. Simple consecutive-day block — stop after N consecutive missed days
2. Rolling window cap — max N notifications per time period
3. Exponential backoff — increasing gaps between notifications

Chosen Option: 2

Rationale: Rolling window with max 3 notifications per 7-day period and minimum 2-day gap between notifications. This prevents spam while allowing periodic re-engagement.

💡 User Tips

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

Implementation Steps

Phase 1: Database Schema and API Foundation

Establish the data layer for device tokens, notification tracking, and feedback storage, plus the API endpoints that iOS will call for registration and feedback submission.

Task 1: Create Database Tables for Push Notifications and Feedback

Add three new tables to support the notification and feedback system.

• Add push_tokens table to src/db/schema.ts with fields: id, user_id (FK to users), device_token (varchar, unique), platform (varchar, default 'ios'), created_at, updated_at
• Add notification_log table to track sent notifications: id, user_id, notification_type (varchar: 'missed_day'), sent_at, opened_at (nullable), responded_at (nullable)
• Add user_feedback table for responses: id, user_id, feedback_type (varchar: 'missed_day' | 'shortened_session'), session_id (nullable FK), selected_option (varchar, nullable), free_text (text, nullable), created_at
• Create corresponding Drizzle relations for user associations
• Add SQL migration file in drizzle/ for the new tables

Task 2: Build Device Token Registration API

Create endpoint for iOS to register/update push tokens.

• Create POST /api/push/register route in src/app/api/push/register/
• Accept { deviceToken: string } in request body
• Upsert token for authenticated user (update if exists, insert if new)
• Return success confirmation
• Add DELETE /api/push/register to allow token removal on logout

Task 3: Build Feedback Submission API

Create endpoint to capture user feedback from both shortened sessions and push notification responses.

• Create POST /api/feedback route in src/app/api/feedback/
• Accept { feedbackType: 'missed_day' | 'shortened_session', sessionId?: string, selectedOption?: string, freeText?: string }
• Validate that sessionId (if provided) belongs to the authenticated user
• Insert into user_feedback table
• If feedbackType is 'missed_day', update corresponding notification_log row's responded_at
• Return created feedback record

Task 4: Add Feedback Option Constants

Define the predefined response options that will be shared between backend validation and iOS UI.

• Create src/lib/feedbackOptions.ts with exported constants for shortened session reasons (e.g., "Not enough time", "Feeling restless", "Interrupted", "Other") and missed day reasons (e.g., "Too busy", "Forgot", "Didn't feel like it", "Other")
• Export TypeScript types for feedback types and option values
• Design for easy extension of options without breaking existing data

🤖 Prompt for AI agents

Implement the database schema and API foundation for the push notification and
feedback system. The goal is to create all necessary data tables, migration
files, API routes, and shared constants before any iOS or notification logic is
built.

**Database Schema (`src/db/schema.ts`)**
- Add `push_tokens` table with fields: `id`, `user_id` (FK to users),
`device_token` (varchar, unique), `platform` (varchar, default `'ios'`),
`created_at`, `updated_at`
- Add `notification_log` table with fields: `id`, `user_id`, `notification_type`
(varchar: `'missed_day'`), `sent_at`, `opened_at` (nullable), `responded_at`
(nullable)
- Add `user_feedback` table with fields: `id`, `user_id`, `feedback_type`
(varchar: `'missed_day'` | `'shortened_session'`), `session_id` (nullable FK),
`selected_option` (varchar, nullable), `free_text` (text, nullable),
`created_at`
- Add Drizzle relations for all user associations
- Create a SQL migration file in `drizzle/` covering all three new tables

**Device Token Registration API**
- Create `POST /api/push/register` in `src/app/api/push/register/`
  - Accept `{ deviceToken: string }` in request body
- Upsert the token for the authenticated user (insert or update if already
exists)
  - Return success confirmation
- Add `DELETE /api/push/register` to remove the token on user logout

**Feedback Submission API**
- Create `POST /api/feedback` in `src/app/api/feedback/`
- Accept `{ feedbackType: 'missed_day' | 'shortened_session', sessionId?:
string, selectedOption?: string, freeText?: string }`
  - Validate that `sessionId` (if provided) belongs to the authenticated user
  - Insert a record into `user_feedback`
- If `feedbackType` is `'missed_day'`, update the corresponding
`notification_log` row's `responded_at` field
  - Return the created feedback record

**Feedback Option Constants (`src/lib/feedbackOptions.ts`)**
- Export constants for shortened session reasons (e.g., `"Not enough time"`,
`"Feeling restless"`, `"Interrupted"`, `"Other"`) and missed day reasons (e.g.,
`"Too busy"`, `"Forgot"`, `"Didn't feel like it"`, `"Other"`)
- Export TypeScript types for feedback types and option values
- Design the structure to allow easy extension without breaking existing stored
data

Phase 2: iOS Client Features

Implement push notification registration and the shortened-session feedback prompt in the iOS app.

Task 1: Add Push Notification Capability and Registration

Configure iOS app for push notifications and register device tokens with the backend.

• Add push notification entitlement to the Xcode project (update project.yml with push capability)
• Add aps-environment entitlement to Info.plist
• Create PushNotificationManager.swift in ios/StillPointApp/Services/ to handle UNUserNotificationCenter setup
• Request notification permissions on first app launch (or after onboarding)
• Implement didRegisterForRemoteNotificationsWithDeviceToken in the app delegate or scene delegate to capture the token
• Call POST /api/push/register with the device token after successful registration
• Handle token refresh — re-register if token changes

Task 2: Handle Incoming Push Notifications

Process received notifications and navigate users appropriately.

• Implement UNUserNotificationCenterDelegate methods in PushNotificationManager
• When a missed-day notification is tapped, navigate to home screen (or a feedback capture screen if implementing in-app response)
• Track notification opens by calling a lightweight API endpoint or including in next feedback submission
• Handle notifications received while app is in foreground (show banner or suppress based on context)

Task 3: Build Shortened Session Feedback Prompt UI

Create an overlay prompt that appears when users end a session early.

• Create ShortenedSessionPromptView.swift in ios/StillPointApp/Components/ following the ThoughtCaptureView pattern
• Display predefined reason options as tappable buttons/chips
• Include optional free-text field for "Other" or additional context
• Add "Skip" option to dismiss without feedback
• Style consistently with existing amber/green design language

Task 4: Integrate Feedback Prompt into Session End Flow

Wire the prompt into the existing end-early flow in SessionView.

• Add @State private var showShortenedPrompt = false to SessionView
• Modify "End Early" button action: set showShortenedPrompt = true instead of directly calling vm.endEarly()
• Render ShortenedSessionPromptView as a ZStack overlay (same pattern as ThoughtCaptureView)
• On prompt submission: call vm.endEarly(), then handleCompletion(), then submit feedback to POST /api/feedback asynchronously
• On skip: proceed with vm.endEarly() and handleCompletion() without feedback submission
• Feedback submission should be fire-and-forget (non-blocking) — failure should not prevent session completion

Task 5: Add API Client Methods for Push and Feedback

Extend the iOS API client with methods for the new endpoints.

• Add registerPushToken(_ token: String) method to APIClient calling POST /api/push/register
• Add submitFeedback(type:sessionId:selectedOption:freeText:) method calling POST /api/feedback
• Handle authentication headers consistently with existing API methods

🤖 Prompt for AI agents

Implement all iOS client features for push notification registration and the
shortened-session feedback prompt. The goal is to configure the app for APNs,
register tokens with the backend, handle incoming notifications, and surface a
feedback overlay when a user ends a session early.

**Push Notification Setup**
- Update `project.yml` to add the push notification capability and add the
`aps-environment` entitlement to `Info.plist`
- Create `PushNotificationManager.swift` in `ios/StillPointApp/Services/`:
  - Set up `UNUserNotificationCenter`
  - Request notification permissions on first launch or after onboarding
- Implement `UNUserNotificationCenterDelegate` for handling foreground
notifications and notification taps
- On missed-day notification tap, navigate to the home screen (or feedback
capture screen)
  - Track opens via API call or include in next feedback submission
- Implement `didRegisterForRemoteNotificationsWithDeviceToken` in the app/scene
delegate:
  - Call `registerPushToken` on `APIClient` with the new token
  - Re-register on token refresh

**API Client Extensions**
- Add `registerPushToken(_ token: String)` method to `APIClient` calling `POST
/api/push/register`
- Add `submitFeedback(type:sessionId:selectedOption:freeText:)` method calling
`POST /api/feedback`
- Follow existing authentication header patterns

**Shortened Session Feedback UI**
- Create `ShortenedSessionPromptView.swift` in `ios/StillPointApp/Components/`
modeled after `ThoughtCaptureView`:
- Display predefined reason options (from shared constants) as tappable
buttons/chips
  - Include an optional free-text field for "Other" or additional context
  - Include a "Skip" button to dismiss without submitting feedback
  - Style consistently with the existing amber/green design language

**Session End Flow Integration (in `SessionView`)**
- Add `@State private var showShortenedPrompt = false`
- Change the "End Early" button to set `showShortenedPrompt = true` instead of
calling `vm.endEarly()` directly
- Overlay `ShortenedSessionPromptView` using a `ZStack` (same pattern as
`ThoughtCaptureView`)
- On submission: call `vm.endEarly()`, then `handleCompletion()`, then
fire-and-forget `submitFeedback` to `POST /api/feedback`
- On skip: call `vm.endEarly()` and `handleCompletion()` with no feedback
submission
- Feedback failure must never block session completion

Phase 3: Miss-a-Day Notification System

Implement the server-side scheduled job that detects missed days and dispatches push notifications with appropriate frequency capping.

Task 1: Implement APNs Integration

Add server-side capability to send push notifications via Apple Push Notification service.

• Create src/lib/apns.ts with APNs HTTP/2 client using APNS_KEY_ID, APNS_TEAM_ID, APNS_KEY (p8 file contents) environment variables
• Implement JWT token generation for APNs authentication
• Create sendPushNotification(deviceToken: string, payload: APNsPayload) function
• Handle APNs error responses (invalid tokens, etc.) — mark invalid tokens for cleanup
• Use production vs sandbox APNs endpoint based on environment

Task 2: Build Miss-a-Day Detection Logic

Create the core logic to identify users who missed a day and are eligible for notification.

• Create src/lib/missedDayDetection.ts with query logic
• Find users whose most recent session.session_date is before yesterday (UTC-adjusted)
• Filter to users who have at least one registered push token
• Apply frequency cap: exclude users who received a missed-day notification within the last 2 days
• Apply rolling cap: exclude users who received 3+ missed-day notifications in the last 7 days
• Return list of eligible users with their device tokens

Task 3: Create Cron Job API Route

Set up a Vercel cron-triggered endpoint that runs the miss-a-day notification job.

• Create GET /api/cron/missed-day-notifications route in src/app/api/cron/missed-day-notifications/
• Verify cron authorization header (Vercel sets CRON_SECRET for security)
• Call missed-day detection logic to get eligible users
• For each eligible user: send notification via APNs, log to notification_log
• Add crons configuration to vercel.json scheduling the route (e.g., daily at 14:00 UTC)
• Handle partial failures gracefully — continue processing remaining users if one fails

Task 4: Craft Notification Copy

Define empathetic, non-guilt-trippy notification content.

• Create notification copy constants in src/lib/notificationCopy.ts
• Primary message: empathetic check-in tone (e.g., "We missed you yesterday. Even one minute can help maintain your practice.")
• Consider 2-3 variations to rotate for users who receive multiple notifications
• Include appropriate APNs payload structure (alert, sound, badge settings)

🤖 Prompt for AI agents

Implement the server-side miss-a-day notification system including APNs
integration, detection logic, the cron job route, and notification copy. The
goal is to have a daily scheduled job that identifies eligible users and sends
empathetic push notifications while respecting frequency caps.

**APNs Integration (`src/lib/apns.ts`)**
- Implement an APNs HTTP/2 client using environment variables: `APNS_KEY_ID`,
`APNS_TEAM_ID`, `APNS_KEY` (p8 file contents)
- Implement JWT token generation for APNs authentication
- Create a `sendPushNotification(deviceToken: string, payload: APNsPayload)`
function
- Handle APNs error responses (e.g., invalid tokens) — mark invalid tokens for
cleanup
- Switch between production and sandbox APNs endpoints based on the current
environment

**Miss-a-Day Detection Logic (`src/lib/missedDayDetection.ts`)**
- Query for users whose most recent `session.session_date` is before yesterday
(UTC-adjusted)
- Filter to users who have at least one registered push token
- Exclude users who received a missed-day notification within the last 2 days
(minimum gap cap)
- Exclude users who received 3 or more missed-day notifications in the last 7
days (rolling window cap)
- Return the list of eligible users along with their device tokens

**Cron Job API Route (`src/app/api/cron/missed-day-notifications/`)**
- Implement `GET /api/cron/missed-day-notifications`
- Verify the Vercel `CRON_SECRET` authorization header before proceeding
- Call the missed-day detection logic to retrieve eligible users
- For each eligible user: send notification via `sendPushNotification`, then
insert a record into `notification_log`
- Process users sequentially or in batches, continuing on individual failures
(partial failure tolerance)
- Add the `crons` entry to `vercel.json` to schedule the route (e.g., daily at
14:00 UTC)

**Notification Copy (`src/lib/notificationCopy.ts`)**
- Define 2-3 empathetic, non-guilt-trippy message variations to rotate across
notifications (e.g., `"We missed you yesterday. Even one minute can help
maintain your practice."`)
- Include the full APNs payload structure per variation (alert title/body,
sound, badge settings)

Research

The project is a meditation app with a Next.js backend (Vercel-deployed, Drizzle ORM with Neon Postgres) and a native iOS frontend. The database tracks users, sessions (with completed, duration, actual_time, and session_date fields), and buddy co-meditation sessions. Currently, there is no push notification infrastructure — no APNs integration, no device token storage, no scheduled jobs, and no notification-related code on either backend or iOS. The iOS app does have established patterns for inline overlay prompts (ThoughtCaptureView) and session state management that can be extended for the shortened-session feedback feature.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the database schema and API foundation for the push notification and
feedback system. The goal is to create all necessary data tables, migration
files, API routes, and shared constants before any iOS or notification logic is
built.

**Database Schema (`src/db/schema.ts`)**
- Add `push_tokens` table with fields: `id`, `user_id` (FK to users),
`device_token` (varchar, unique), `platform` (varchar, default `'ios'`),
`created_at`, `updated_at`
- Add `notification_log` table with fields: `id`, `user_id`, `notification_type`
(varchar: `'missed_day'`), `sent_at`, `opened_at` (nullable), `responded_at`
(nullable)
- Add `user_feedback` table with fields: `id`, `user_id`, `feedback_type`
(varchar: `'missed_day'` | `'shortened_session'`), `session_id` (nullable FK),
`selected_option` (varchar, nullable), `free_text` (text, nullable),
`created_at`
- Add Drizzle relations for all user associations
- Create a SQL migration file in `drizzle/` covering all three new tables

**Device Token Registration API**
- Create `POST /api/push/register` in `src/app/api/push/register/`
  - Accept `{ deviceToken: string }` in request body
- Upsert the token for the authenticated user (insert or update if already
exists)
  - Return success confirmation
- Add `DELETE /api/push/register` to remove the token on user logout

**Feedback Submission API**
- Create `POST /api/feedback` in `src/app/api/feedback/`
- Accept `{ feedbackType: 'missed_day' | 'shortened_session', sessionId?:
string, selectedOption?: string, freeText?: string }`
  - Validate that `sessionId` (if provided) belongs to the authenticated user
  - Insert a record into `user_feedback`
- If `feedbackType` is `'missed_day'`, update the corresponding
`notification_log` row's `responded_at` field
  - Return the created feedback record

**Feedback Option Constants (`src/lib/feedbackOptions.ts`)**
- Export constants for shortened session reasons (e.g., `"Not enough time"`,
`"Feeling restless"`, `"Interrupted"`, `"Other"`) and missed day reasons (e.g.,
`"Too busy"`, `"Forgot"`, `"Didn't feel like it"`, `"Other"`)
- Export TypeScript types for feedback types and option values
- Design the structure to allow easy extension without breaking existing stored
data
===============================================================================

Task: 2

Implement all iOS client features for push notification registration and the
shortened-session feedback prompt. The goal is to configure the app for APNs,
register tokens with the backend, handle incoming notifications, and surface a
feedback overlay when a user ends a session early.

**Push Notification Setup**
- Update `project.yml` to add the push notification capability and add the
`aps-environment` entitlement to `Info.plist`
- Create `PushNotificationManager.swift` in `ios/StillPointApp/Services/`:
  - Set up `UNUserNotificationCenter`
  - Request notification permissions on first launch or after onboarding
- Implement `UNUserNotificationCenterDelegate` for handling foreground
notifications and notification taps
- On missed-day notification tap, navigate to the home screen (or feedback
capture screen)
  - Track opens via API call or include in next feedback submission
- Implement `didRegisterForRemoteNotificationsWithDeviceToken` in the app/scene
delegate:
  - Call `registerPushToken` on `APIClient` with the new token
  - Re-register on token refresh

**API Client Extensions**
- Add `registerPushToken(_ token: String)` method to `APIClient` calling `POST
/api/push/register`
- Add `submitFeedback(type:sessionId:selectedOption:freeText:)` method calling
`POST /api/feedback`
- Follow existing authentication header patterns

**Shortened Session Feedback UI**
- Create `ShortenedSessionPromptView.swift` in `ios/StillPointApp/Components/`
modeled after `ThoughtCaptureView`:
- Display predefined reason options (from shared constants) as tappable
buttons/chips
  - Include an optional free-text field for "Other" or additional context
  - Include a "Skip" button to dismiss without submitting feedback
  - Style consistently with the existing amber/green design language

**Session End Flow Integration (in `SessionView`)**
- Add `@State private var showShortenedPrompt = false`
- Change the "End Early" button to set `showShortenedPrompt = true` instead of
calling `vm.endEarly()` directly
- Overlay `ShortenedSessionPromptView` using a `ZStack` (same pattern as
`ThoughtCaptureView`)
- On submission: call `vm.endEarly()`, then `handleCompletion()`, then
fire-and-forget `submitFeedback` to `POST /api/feedback`
- On skip: call `vm.endEarly()` and `handleCompletion()` with no feedback
submission
- Feedback failure must never block session completion
===============================================================================

Task: 3

Implement the server-side miss-a-day notification system including APNs
integration, detection logic, the cron job route, and notification copy. The
goal is to have a daily scheduled job that identifies eligible users and sends
empathetic push notifications while respecting frequency caps.

**APNs Integration (`src/lib/apns.ts`)**
- Implement an APNs HTTP/2 client using environment variables: `APNS_KEY_ID`,
`APNS_TEAM_ID`, `APNS_KEY` (p8 file contents)
- Implement JWT token generation for APNs authentication
- Create a `sendPushNotification(deviceToken: string, payload: APNsPayload)`
function
- Handle APNs error responses (e.g., invalid tokens) — mark invalid tokens for
cleanup
- Switch between production and sandbox APNs endpoints based on the current
environment

**Miss-a-Day Detection Logic (`src/lib/missedDayDetection.ts`)**
- Query for users whose most recent `session.session_date` is before yesterday
(UTC-adjusted)
- Filter to users who have at least one registered push token
- Exclude users who received a missed-day notification within the last 2 days
(minimum gap cap)
- Exclude users who received 3 or more missed-day notifications in the last 7
days (rolling window cap)
- Return the list of eligible users along with their device tokens

**Cron Job API Route (`src/app/api/cron/missed-day-notifications/`)**
- Implement `GET /api/cron/missed-day-notifications`
- Verify the Vercel `CRON_SECRET` authorization header before proceeding
- Call the missed-day detection logic to retrieve eligible users
- For each eligible user: send notification via `sendPushNotification`, then
insert a record into `notification_log`
- Process users sequentially or in batches, continuing on individual failures
(partial failure tolerance)
- Add the `crons` entry to `vercel.json` to schedule the route (e.g., daily at
14:00 UTC)

**Notification Copy (`src/lib/notificationCopy.ts`)**
- Define 2-3 empathetic, non-guilt-trippy message variations to rotate across
notifications (e.g., `"We missed you yesterday. Even one minute can help
maintain your practice."`)
- Include the full APNs payload structure per variation (alert title/body,
sound, badge settings)

💡 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]

Backlog scan 2026-05-29: this issue now depends on the notification preferences + scheduling infrastructure being built in #345. Once #345 ships, the miss-a-day notification just plugs in as another notification type alongside the daily reminder. De-dup logic between miss-a-day and the daily reminder lives in the daily-reminder issue.