chore: create new notification plan

2 weeks ago · 5110c17fba
1 changed files with 603 additions and 0 deletions
--- a/doc/notification-system-implementation-plan.md
+++ b/doc/notification-system-implementation-plan.md
@ -0,0 +1,603 @@
+# TimeSafari Notification System — Feature-First Execution Pack
+
+**Author**: Matthew Raymer  
+**Date**: 2025-01-27T15:00Z (UTC)  
+**Status**: 🚀 **ACTIVE** - Surgical PR implementation for Capacitor platforms
+
+## What we'll ship (v1 in-app)
+
+- Multi-daily **one-shot local notifications** (rolling window)
+- **Online-first** (ETag, 10–15s timeout) with **offline-first** fallback
+- **SQLite** persistence + **14-day** retention
+- **Templating**: `{title, body}` with `{{var}}`
+- **Event queue**: delivery/error/heartbeat (drained on foreground)
+- Same TS API that we can swap to native (v2) later
+
+---
+
+## Minimal PR layout
+
+```
+/src/services/notifs/
+  types.ts
+  NotificationOrchestrator.ts
+  adapters/
+    DataStoreSqlite.ts
+    SchedulerCapacitor.ts
+    CallbacksHttp.ts
+/migrations/
+  00XX_notifs.sql
+/sw_scripts/
+  notification-click.js   # (or merge into sw_scripts-combined.js)
+/app/bootstrap/
+  notifications.ts        # init + feature flags
+```
+
+---
+
+## Changes (surgical)
+
+### 1) Dependencies
+
+```bash
+npm i @capacitor/local-notifications
+npx cap sync
+```
+
+### 2) Capacitor setup
+
+```typescript
+// capacitor.config.ts
+plugins: {
+  LocalNotifications: {
+    smallIcon: 'ic_stat_name',
+    iconColor: '#4a90e2'
+  }
+}
+```
+
+### 3) Android channel + iOS category (once at app start)
+
+```typescript
+import { LocalNotifications } from '@capacitor/local-notifications';
+
+export async function initNotifChannels() {
+  await LocalNotifications.createChannel({
+    id: 'timesafari.daily',
+    name: 'TimeSafari Daily',
+    description: 'Daily briefings',
+    importance: 4, // high
+  });
+
+  await LocalNotifications.registerActionTypes({
+    types: [{
+      id: 'TS_DAILY',
+      actions: [{ id: 'OPEN', title: 'Open' }]
+    }]
+  });
+}
+```
+
+### 4) SQLite migration
+
+```sql
+-- /migrations/00XX_notifs.sql
+CREATE TABLE IF NOT EXISTS notif_contents(
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  slot_id TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  fetched_at INTEGER NOT NULL,
+  etag TEXT,
+  UNIQUE(slot_id, fetched_at)
+);
+
+CREATE INDEX IF NOT EXISTS notif_idx_contents_slot_time
+  ON notif_contents(slot_id, fetched_at DESC);
+
+CREATE TABLE IF NOT EXISTS notif_deliveries(
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  slot_id TEXT NOT NULL,
+  fire_at INTEGER NOT NULL,
+  delivered_at INTEGER,
+  status TEXT NOT NULL,
+  error_code TEXT,
+  error_message TEXT
+);
+
+CREATE TABLE IF NOT EXISTS notif_config(
+  k TEXT PRIMARY KEY,
+  v TEXT NOT NULL
+);
+```
+
+*Retention job (daily):*
+
+```sql
+DELETE FROM notif_contents
+WHERE fetched_at < strftime('%s','now','-14 days');
+
+DELETE FROM notif_deliveries
+WHERE fire_at < strftime('%s','now','-14 days');
+```
+
+### 5) Types (shared API)
+
+```typescript
+// src/services/notifs/types.ts
+export type NotificationTime = { hour: number; minute: number };
+export type SlotId = string;
+
+export type FetchSpec = {
+  method: 'GET'|'POST';
+  url: string;
+  headers?: Record<string,string>;
+  bodyJson?: Record<string,unknown>;
+  timeoutMs?: number;
+};
+
+export type CallbackProfile = {
+  fetchContent: FetchSpec;
+  ackDelivery?: Omit<FetchSpec,'bodyJson'|'timeoutMs'>;
+  reportError?: Omit<FetchSpec,'bodyJson'|'timeoutMs'>;
+  heartbeat?: Omit<FetchSpec,'bodyJson'> & { intervalMinutes?: number };
+};
+
+export type ConfigureOptions = {
+  times: NotificationTime[];
+  ttlSeconds?: number;
+  prefetchLeadMinutes?: number;
+  storage: 'shared'|'plugin';
+  dbPath?: string;
+  contentTemplate?: { title: string; body: string };
+  callbackProfile?: CallbackProfile;
+};
+
+export interface DataStore {
+  saveContent(slotId: SlotId, payload: unknown, etag?: string): Promise<void>;
+  getLatestContent(slotId: SlotId): Promise<{
+    payload: unknown;
+    fetchedAt: number;
+    etag?: string
+  }|null>;
+  recordDelivery(
+    slotId: SlotId,
+    fireAt: number,
+    status: 'scheduled'|'shown'|'error',
+    error?: { code?: string; message?: string }
+  ): Promise<void>;
+  enqueueEvent(e: unknown): Promise<void>;
+  drainEvents(): Promise<unknown[]>;
+}
+
+export interface Scheduler {
+  capabilities(): Promise<{ exactAlarms: boolean; maxPending?: number }>;
+  scheduleExact(slotId: SlotId, whenMs: number, payloadRef: string): Promise<void>;
+  scheduleWindow(
+    slotId: SlotId,
+    windowStartMs: number,
+    windowLenMs: number,
+    payloadRef: string
+  ): Promise<void>;
+  cancelBySlot(slotId: SlotId): Promise<void>;
+  rescheduleAll(next: Array<{ slotId: SlotId; whenMs: number }>): Promise<void>;
+}
+```
+
+### 6) Adapters (thin)
+
+```typescript
+// src/services/notifs/adapters/DataStoreSqlite.ts
+import type { DataStore, SlotId } from '../types';
+import { PlatformServiceMixin } from '@/utils/PlatformServiceMixin';
+
+export class DataStoreSqlite implements DataStore {
+  constructor(private platformService: PlatformServiceMixin) {}
+
+  async saveContent(slotId: SlotId, payload: unknown, etag?: string): Promise<void> {
+    const fetchedAt = Date.now();
+    const payloadJson = JSON.stringify(payload);
+    
+    await this.platformService.$exec(
+      `INSERT OR REPLACE INTO notif_contents (slot_id, payload_json, fetched_at, etag)
+       VALUES (?, ?, ?, ?)`,
+      [slotId, payloadJson, fetchedAt, etag]
+    );
+  }
+
+  async getLatestContent(slotId: SlotId): Promise<{
+    payload: unknown;
+    fetchedAt: number;
+    etag?: string
+  }|null> {
+    const result = await this.platformService.$db(
+      `SELECT payload_json, fetched_at, etag
+       FROM notif_contents
+       WHERE slot_id = ?
+       ORDER BY fetched_at DESC
+       LIMIT 1`,
+      [slotId]
+    );
+
+    if (!result || result.length === 0) {
+      return null;
+    }
+
+    const row = result[0];
+    return {
+      payload: JSON.parse(row.payload_json),
+      fetchedAt: row.fetched_at,
+      etag: row.etag
+    };
+  }
+
+  async recordDelivery(
+    slotId: SlotId,
+    fireAt: number,
+    status: 'scheduled'|'shown'|'error',
+    error?: { code?: string; message?: string }
+  ): Promise<void> {
+    const deliveredAt = status === 'shown' ? Date.now() : null;
+    
+    await this.platformService.$exec(
+      `INSERT INTO notif_deliveries (slot_id, fire_at, delivered_at, status, error_code, error_message)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [slotId, fireAt, deliveredAt, status, error?.code, error?.message]
+    );
+  }
+
+  async enqueueEvent(e: unknown): Promise<void> {
+    // Simple in-memory queue for now, can be enhanced with SQLite
+    // This will be drained when app comes to foreground
+  }
+
+  async drainEvents(): Promise<unknown[]> {
+    // Return and clear queued events
+    return [];
+  }
+}
+
+// src/services/notifs/adapters/SchedulerCapacitor.ts
+import { LocalNotifications } from '@capacitor/local-notifications';
+import type { Scheduler, SlotId } from '../types';
+
+export class SchedulerCapacitor implements Scheduler {
+  async capabilities(): Promise<{ exactAlarms: boolean; maxPending?: number }> {
+    // iOS: ~64 pending notifications
+    // Android: depends on exact alarm permissions
+    return {
+      exactAlarms: true, // Assume we have permissions
+      maxPending: 64
+    };
+  }
+
+  async scheduleExact(slotId: SlotId, whenMs: number, payloadRef: string): Promise<void> {
+    await LocalNotifications.schedule({
+      notifications: [{
+        id: this.generateNotificationId(slotId),
+        title: 'TimeSafari',
+        body: 'Your daily update is ready',
+        schedule: { at: new Date(whenMs) },
+        extra: { slotId, payloadRef }
+      }]
+    });
+  }
+
+  async scheduleWindow(
+    slotId: SlotId,
+    windowStartMs: number,
+    windowLenMs: number,
+    payloadRef: string
+  ): Promise<void> {
+    // For platforms that don't support exact alarms
+    await LocalNotifications.schedule({
+      notifications: [{
+        id: this.generateNotificationId(slotId),
+        title: 'TimeSafari',
+        body: 'Your daily update is ready',
+        schedule: {
+          at: new Date(windowStartMs),
+          repeats: false
+        },
+        extra: { slotId, payloadRef }
+      }]
+    });
+  }
+
+  async cancelBySlot(slotId: SlotId): Promise<void> {
+    const id = this.generateNotificationId(slotId);
+    await LocalNotifications.cancel({ notifications: [{ id }] });
+  }
+
+  async rescheduleAll(next: Array<{ slotId: SlotId; whenMs: number }>): Promise<void> {
+    // Cancel all existing notifications
+    await LocalNotifications.cancel({ notifications: [] });
+    
+    // Schedule new ones
+    const notifications = next.map(({ slotId, whenMs }) => ({
+      id: this.generateNotificationId(slotId),
+      title: 'TimeSafari',
+      body: 'Your daily update is ready',
+      schedule: { at: new Date(whenMs) },
+      extra: { slotId }
+    }));
+
+    await LocalNotifications.schedule({ notifications });
+  }
+
+  private generateNotificationId(slotId: SlotId): number {
+    // Simple hash of slotId to generate unique notification ID
+    let hash = 0;
+    for (let i = 0; i < slotId.length; i++) {
+      const char = slotId.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash = hash & hash; // Convert to 32-bit integer
+    }
+    return Math.abs(hash);
+  }
+}
+```
+
+### 7) Orchestrator (lean core)
+
+```typescript
+// src/services/notifs/NotificationOrchestrator.ts
+import type { ConfigureOptions, SlotId, DataStore, Scheduler } from './types';
+import { logger } from '@/utils/logger';
+
+export class NotificationOrchestrator {
+  constructor(private store: DataStore, private sched: Scheduler) {}
+
+  private opts!: ConfigureOptions;
+
+  async configure(o: ConfigureOptions): Promise<void> {
+    this.opts = o;
+    
+    // Persist configuration to SQLite
+    await this.store.enqueueEvent({
+      type: 'config_updated',
+      config: o,
+      timestamp: Date.now()
+    });
+  }
+
+  async runFullPipelineNow(): Promise<void> {
+    try {
+      // 1) For each upcoming slot, attempt online-first fetch
+      const upcomingSlots = this.getUpcomingSlots();
+      
+      for (const slot of upcomingSlots) {
+        await this.fetchAndScheduleSlot(slot);
+      }
+      
+      logger.log('[NotificationOrchestrator] Full pipeline completed');
+    } catch (error) {
+      logger.error('[NotificationOrchestrator] Pipeline failed:', error);
+      throw error;
+    }
+  }
+
+  async deliverStoredNow(slotId?: SlotId): Promise<void> {
+    const targetSlots = slotId ? [slotId] : this.getUpcomingSlots();
+    
+    for (const slot of targetSlots) {
+      const content = await this.store.getLatestContent(slot);
+      if (content) {
+        const payloadRef = this.createPayloadRef(content.payload);
+        await this.sched.scheduleExact(slot, Date.now() + 5000, payloadRef);
+      }
+    }
+  }
+
+  async reschedule(): Promise<void> {
+    const nextOccurrences = this.getUpcomingSlots().map(slotId => ({
+      slotId,
+      whenMs: this.getNextSlotTime(slotId)
+    }));
+    
+    await this.sched.rescheduleAll(nextOccurrences);
+  }
+
+  async getState(): Promise<{
+    pendingCount: number;
+    nextOccurrences: Array<{slotId: string; when: string}>
+  }> {
+    const capabilities = await this.sched.capabilities();
+    const upcomingSlots = this.getUpcomingSlots();
+    
+    return {
+      pendingCount: Math.min(upcomingSlots.length, capabilities.maxPending || 64),
+      nextOccurrences: upcomingSlots.map(slotId => ({
+        slotId,
+        when: new Date(this.getNextSlotTime(slotId)).toISOString()
+      }))
+    };
+  }
+
+  private async fetchAndScheduleSlot(slotId: SlotId): Promise<void> {
+    try {
+      // Attempt online-first fetch
+      if (this.opts.callbackProfile?.fetchContent) {
+        const content = await this.fetchContent(slotId);
+        if (content) {
+          await this.store.saveContent(slotId, content.payload, content.etag);
+          await this.scheduleSlot(slotId, content.payload);
+          return;
+        }
+      }
+      
+      // Fallback to offline-first
+      const storedContent = await this.store.getLatestContent(slotId);
+      if (storedContent && this.isWithinTTL(storedContent.fetchedAt)) {
+        await this.scheduleSlot(slotId, storedContent.payload);
+      }
+    } catch (error) {
+      logger.error(`[NotificationOrchestrator] Failed to fetch/schedule ${slotId}:`, error);
+      await this.store.recordDelivery(slotId, Date.now(), 'error', {
+        code: 'fetch_failed',
+        message: error instanceof Error ? error.message : 'Unknown error'
+      });
+    }
+  }
+
+  private async fetchContent(slotId: SlotId): Promise<{
+    payload: unknown;
+    etag?: string
+  }|null> {
+    const spec = this.opts.callbackProfile!.fetchContent;
+    const response = await fetch(spec.url, {
+      method: spec.method,
+      headers: spec.headers,
+      body: spec.bodyJson ? JSON.stringify(spec.bodyJson) : undefined,
+      signal: AbortSignal.timeout(spec.timeoutMs || 15000)
+    });
+
+    if (response.status === 304) {
+      return null; // Not modified
+    }
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const payload = await response.json();
+    const etag = response.headers.get('etag') || undefined;
+
+    return { payload, etag };
+  }
+
+  private async scheduleSlot(slotId: SlotId, payload: unknown): Promise<void> {
+    const whenMs = this.getNextSlotTime(slotId);
+    const payloadRef = this.createPayloadRef(payload);
+    
+    await this.sched.scheduleExact(slotId, whenMs, payloadRef);
+    await this.store.recordDelivery(slotId, whenMs, 'scheduled');
+  }
+
+  private getUpcomingSlots(): SlotId[] {
+    const now = new Date();
+    const slots: SlotId[] = [];
+    
+    for (const time of this.opts.times) {
+      const slotId = `slot-${time.hour.toString().padStart(2, '0')}-${time.minute.toString().padStart(2, '0')}`;
+      const nextTime = this.getNextSlotTime(slotId);
+      
+      // Include slots for today and tomorrow (within rolling window)
+      if (nextTime <= now.getTime() + (2 * 24 * 60 * 60 * 1000)) {
+        slots.push(slotId);
+      }
+    }
+    
+    return slots;
+  }
+
+  private getNextSlotTime(slotId: SlotId): number {
+    const [_, hourStr, minuteStr] = slotId.match(/slot-(\d{2})-(\d{2})/) || [];
+    const hour = parseInt(hourStr, 10);
+    const minute = parseInt(minuteStr, 10);
+    
+    const now = new Date();
+    const next = new Date(now);
+    next.setHours(hour, minute, 0, 0);
+    
+    // If time has passed today, schedule for tomorrow
+    if (next <= now) {
+      next.setDate(next.getDate() + 1);
+    }
+    
+    return next.getTime();
+  }
+
+  private createPayloadRef(payload: unknown): string {
+    return `payload-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  private isWithinTTL(fetchedAt: number): boolean {
+    const ttlMs = (this.opts.ttlSeconds || 86400) * 1000;
+    return Date.now() - fetchedAt < ttlMs;
+  }
+}
+```
+
+### 8) Bootstrap + feature flags
+
+```typescript
+// /app/bootstrap/notifications.ts
+import { initNotifChannels } from './initNotifChannels';
+import { NotificationOrchestrator } from '@/services/notifs/NotificationOrchestrator';
+import { DataStoreSqlite } from '@/services/notifs/adapters/DataStoreSqlite';
+import { SchedulerCapacitor } from '@/services/notifs/adapters/SchedulerCapacitor';
+import { PlatformServiceMixin } from '@/utils/PlatformServiceMixin';
+import { Capacitor } from '@capacitor/core';
+
+let orchestrator: NotificationOrchestrator | null = null;
+
+export async function initNotifications(): Promise<void> {
+  // Only initialize on Capacitor platforms
+  if (!Capacitor.isNativePlatform()) {
+    return;
+  }
+
+  try {
+    await initNotifChannels();
+    
+    const platformService = new PlatformServiceMixin();
+    const store = new DataStoreSqlite(platformService);
+    const scheduler = new SchedulerCapacitor();
+    
+    orchestrator = new NotificationOrchestrator(store, scheduler);
+    
+    // Run pipeline on app start
+    await orchestrator.runFullPipelineNow();
+    await orchestrator.reschedule();
+    
+    logger.log('[Notifications] Initialized successfully');
+  } catch (error) {
+    logger.error('[Notifications] Initialization failed:', error);
+  }
+}
+
+export function getNotificationOrchestrator(): NotificationOrchestrator | null {
+  return orchestrator;
+}
+```
+
+### 9) Service Worker click handler (web)
+
+```javascript
+// sw_scripts/notification-click.js (or inside combined file)
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close();
+  
+  // Extract slotId from notification data
+  const slotId = event.notification.data?.slotId;
+  
+  // Open appropriate route based on notification type
+  const route = slotId ? '/#/daily' : '/#/notifications';
+  
+  event.waitUntil(
+    clients.openWindow(route).catch(() => {
+      // Fallback if openWindow fails
+      return clients.openWindow('/');
+    })
+  );
+});
+```
+
+---
+
+## Acceptance (v1)
+
+- Locals fire at configured slots with app **killed**
+- Online-first w/ **ETag** + **timeout**; falls back to offline-first (TTL respected)
+- DB retains 14 days; retention job prunes
+- Foreground drains queued events
+- One-line adapter swap path ready for v2
+
+---
+
+## Platform Notes
+
+- **Capacitor Only**: This implementation is designed for iOS/Android via Capacitor
+- **Web Fallback**: Web platform will use existing service worker + push notifications
+- **Electron**: Will need separate implementation using native notification APIs
+- **Feature Flags**: Can be toggled per platform in bootstrap configuration