refactor(docs): split notification system docs into plan and implementation
Replace monolithic notification-system-implementation-plan.md with focused strategic plan (notification-system-plan.md) and detailed implementation guide (notification-system-implementation.md). Both documents now perfectly aligned with TimeSafari codebase patterns including: - Actual Settings type extension pattern (JSON strings for complex objects) - Real useNotifications composable stub signatures with eslint-disable - Verified logger exports and safeStringify usage - Confirmed PlatformServiceMixin.$saveSettings integration - Validated migration system registerMigration patterns Documents are production-ready with accurate code examples verified against actual TimeSafari infrastructure.
This commit is contained in:
Matthew Raymer
@@ -1,644 +0,0 @@
|
||||
# TimeSafari Notification System — Feature-First Execution Pack
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-01-27T15:00Z (UTC)
|
||||
**Status**: 🚀 **ACTIVE** - Surgical PR implementation for Capacitor platforms
|
||||
|
||||
## Purpose
|
||||
|
||||
We **will deliver** 1..M daily local notifications with content fetched beforehand so they **will display offline**. We **will support** online-first (API→DB→Schedule) with offline-first fallback. New v1 ships in-app; New v2 extracts to a native Capacitor plugin with the same API.
|
||||
|
||||
## What we'll ship (v1 in-app)
|
||||
|
||||
- **Multi-daily one-shot local notifications** (rolling window; today + tomorrow within iOS pending limits ~64)
|
||||
- **Online-first** content fetch (**ETag**, 10–15s timeout) with **offline-first** fallback and **TTL** handling ("(cached)" or skip)
|
||||
- **SQLite persistence** (contents, deliveries, config) with **14-day retention**
|
||||
- **Templating**: `{title, body}` with `{{var}}` substitution **before** scheduling
|
||||
- **Event queue** in SQLite: `delivery`, `error`, `heartbeat`; **drain on foreground**
|
||||
- **Resilience hooks**: re-arm on **app resume**, and when **timezone/offset** changes
|
||||
|
||||
---
|
||||
|
||||
## New v2 (Plugin) — What It Adds
|
||||
|
||||
- **Native schedulers** (WorkManager+AlarmManager / BGTask+UNUserNotificationCenter) incl. exact/inexact handling
|
||||
- **Native HTTP** + **native SQLite** for reliability/perf
|
||||
- **Server-assist (silent push)** to wake at T-lead and prefetch
|
||||
- **Same TS API**, adapters swapped
|
||||
|
||||
---
|
||||
|
||||
## Feature Flags
|
||||
|
||||
- `scheduler: 'capacitor'|'native'`
|
||||
- `mode: 'online-first'|'offline-first'|'auto'`
|
||||
- `prefetchLeadMinutes`, `ttlSeconds`
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
/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)
|
||||
|
||||
- Local notifications **fire at configured slots with the app killed** (iOS/Android)
|
||||
- **Online-first** → 304/ETag respected; **offline-first** fallback; **TTL** policy respected
|
||||
- **14-day retention** job prunes contents & deliveries
|
||||
- **TZ/DST** change triggers **reschedule()**; rolling window adheres to iOS pending cap
|
||||
- **Feature flags** present: `scheduler: 'capacitor'|'native'`, `mode: 'online-first'|'offline-first'|'auto'`
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
- **Android UX**: Settings deep-link to grant exact-alarm special access on API 31+
|
||||
- **DST/TZ Guardrail**: On app resume, if offset/TZ changed → `reschedule()` and re-arm today's slots
|
||||
1872
doc/notification-system-implementation.md
Normal file
1872
doc/notification-system-implementation.md
Normal file
File diff suppressed because it is too large
Load Diff
457
doc/notification-system-plan.md
Normal file
457
doc/notification-system-plan.md
Normal file
@@ -0,0 +1,457 @@
|
||||
# TimeSafari Notification System — Strategic Plan
|
||||
|
||||
**Status:** 🚀 Active plan
|
||||
**Date:** 2025-09-05T05:09Z (UTC)
|
||||
**Author:** Matthew Raymer
|
||||
**Scope:** v1 (in‑app orchestrator) now; path to v2 (native plugin) next
|
||||
**Goal:** We **will deliver** 1..M local notifications/day with content **prefetched** so messages **will display offline**. We **will support** online‑first (API→DB→Schedule) with offline‑first fallback. The system **will enhance** TimeSafari's community-building mission by keeping users connected to gratitude, gifts, and collaborative projects through timely, relevant notifications.
|
||||
|
||||
> **Implementation Details:** See `notification-system-implementation.md` for detailed code, database schemas, and integration specifics.
|
||||
> **Canonical Ownership:** This document owns Goals, Tenets, Platform behaviors, Acceptance criteria, and Test cases.
|
||||
|
||||
---
|
||||
|
||||
## 1) Versioning & Intent
|
||||
|
||||
- **v1 (In‑App Orchestrator):** We **will implement** multi‑daily local notifications, online/offline flows, templating, SQLite persistence, and eventing **inside the app** using Capacitor Local Notifications.
|
||||
- **v2 (Plugin):** We **will extract** adapters to a Capacitor/Native plugin to gain native schedulers (WorkManager/AlarmManager; BGTask+UNUserNotificationCenter), native HTTP, and native SQLite **with the same TypeScript API**.
|
||||
|
||||
> We **will retain** the existing web push + Service Worker foundation; the system **will add** reliable local scheduling on mobile and a unified API across platforms.
|
||||
|
||||
---
|
||||
|
||||
## 2) Design Tenets
|
||||
|
||||
- **Reliability:** OS‑level delivery once scheduled; no reliance on JS being alive at fire time.
|
||||
- **Freshness:** Prefer online‑first within a short prefetch window; degrade gracefully to cached content with TTL.
|
||||
- **Extractable:** Clean interfaces (Scheduler, DataStore, Callbacks) so v2 **will swap** adapters without API changes.
|
||||
- **Simplicity:** One‑shot notifications per slot; rolling window scheduling to respect platform caps.
|
||||
- **Observability:** Persist deliveries and errors; surface minimal metrics; enable ACKs.
|
||||
- **Privacy-First:** Follow TimeSafari's privacy-preserving architecture; user-controlled visibility and data sovereignty.
|
||||
- **Community-Focused:** Enhance TimeSafari's mission of connecting people through gratitude, gifts, and collaborative projects.
|
||||
|
||||
---
|
||||
|
||||
## 3) Architecture Overview
|
||||
|
||||
```
|
||||
Application (Vue/TS)
|
||||
├─ NotificationOrchestrator (core state)
|
||||
│ ├─ Scheduler (adapter)
|
||||
│ ├─ DataStore (adapter)
|
||||
│ └─ Callbacks (adapter)
|
||||
└─ UI (settings, status)
|
||||
|
||||
Adapters
|
||||
├─ V1: SchedulerCapacitor, DataStoreSqlite, CallbacksHttp
|
||||
└─ V2: SchedulerNative, DataStoreNativeSqlite, CallbacksNativeHttp
|
||||
|
||||
Platform
|
||||
├─ iOS/Android: LocalNotifications (+ native bridges later)
|
||||
├─ Web: Service Worker + Push (kept)
|
||||
└─ Electron: OS notifications (thin adapter)
|
||||
```
|
||||
|
||||
**Execution modes (concise):**
|
||||
- **Online‑First:** wake near slot → fetch (ETag, timeout) → persist → schedule; on failure → Offline‑First.
|
||||
- **Offline‑First:** read last good payload from SQLite; if beyond TTL → skip notification (no retry).
|
||||
|
||||
---
|
||||
|
||||
## 4) Public API (Shared by v1 & v2)
|
||||
|
||||
```ts
|
||||
export type NotificationTime = { hour: number; minute: number }; // local wall-clock
|
||||
export type SlotId = string; // Format: "HHmm" (e.g., "0800", "1200", "1800") - stable across TZ changes
|
||||
|
||||
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[]; // 1..M daily
|
||||
timezone?: string; // Default: system timezone
|
||||
ttlSeconds?: number; // Default: 86400 (24h)
|
||||
prefetchLeadMinutes?: number; // Default: 20
|
||||
storage: 'shared'|'private'; // Required
|
||||
contentTemplate: { title: string; body: string }; // Required
|
||||
callbackProfile?: CallbackProfile; // Optional
|
||||
};
|
||||
|
||||
export interface MultiDailyNotification {
|
||||
requestPermissions(): Promise<void>;
|
||||
configure(o: ConfigureOptions): Promise<void>;
|
||||
runFullPipelineNow(): Promise<void>; // API→DB→Schedule (today's remaining)
|
||||
deliverStoredNow(slotId?: SlotId): Promise<void>; // 60s cooldown guard
|
||||
reschedule(): Promise<void>;
|
||||
getState(): Promise<{
|
||||
nextOccurrences: Array<{ slotId: SlotId; when: string }>; // ISO
|
||||
lastFetchAt?: string; lastDeliveryAt?: string;
|
||||
pendingCount: number; exactAlarmCapable?: boolean;
|
||||
}>;
|
||||
}
|
||||
```
|
||||
|
||||
> **Storage semantics:** `'shared'` = app DB; `'private'` = plugin-owned/native DB (v2). (No functional difference in v1.)
|
||||
|
||||
> **Slot Identity & Scheduling Policy**
|
||||
> • **SlotId** uses canonical `HHmm` and remains stable across timezone changes.
|
||||
> • **Lead window:** default `prefetchLeadMinutes = 20`; no retries once inside the lead.
|
||||
> • **TTL policy:** When offline and content is beyond TTL, **we will skip** the notification (no "(cached)" suffix).
|
||||
> • **Idempotency:** Duplicate "scheduled" deliveries are prevented by a unique index on `(slot_id, fire_at, status='scheduled')`.
|
||||
> • **Time handling:** Slots will follow **local wall-clock** time across TZ/DST; `slotId=HHmm` stays constant and we will **recompute fire times** on offset change.
|
||||
|
||||
---
|
||||
|
||||
## 5) Data Model & Retention (SQLite)
|
||||
|
||||
**Tables:** `notif_contents`, `notif_deliveries`, `notif_config`
|
||||
|
||||
**Retention:** We **will keep** ~14 days of contents/deliveries (configurable) and **will prune** via a simple daily job that runs on app start/resume. We **will prune** daily but **will not** VACUUM by default on mobile; disk compaction is deferred.
|
||||
|
||||
**Payload handling:** We **will template** `{title, body}` **before** scheduling; we **will not** mutate at delivery time.
|
||||
|
||||
---
|
||||
|
||||
## 6) Scheduling Policy & Slot Math
|
||||
|
||||
- **One‑shot per slot** per day (non‑repeating).
|
||||
- **Rolling window:** today's remaining slots; seed tomorrow where platform limits allow. v1 will schedule **the next occurrence per slot** by default; a **configurable depth** (0=today, 1=today+tomorrow) may be enabled as long as the iOS pending cap is respected.
|
||||
- **TZ/DST safe:** We **will recompute** local wall‑times on app resume and whenever timezone/offset changes; then **reschedule**.
|
||||
- **Android exactness:** If exact alarms are unavailable or denied, we **will use** `setWindow` semantics via the scheduler adapter.
|
||||
- **iOS pending cap:** We **will keep** pending locals within typical caps (~64) by limiting the window and canceling/re‑arming as needed.
|
||||
- **Electron rolling window:** On Electron we **will schedule** the **next occurrence per slot** by default; depth (today+tomorrow) **will be** enabled only when auto-launch is on, to avoid drift while the app is closed.
|
||||
|
||||
---
|
||||
|
||||
## 7) Platform Essentials
|
||||
|
||||
**iOS**
|
||||
- Local notifications **will** fire without background runtime once scheduled. NSE **will not** mutate locals; delivery-time enrichment requires remote push (future).
|
||||
- **Category ID**: `TS_DAILY` with default `OPEN` action
|
||||
- **Background budget** is short and OS‑managed; any prefetch work **will complete** promptly.
|
||||
- **Mobile local notifications will route via action listeners (not the service worker)**.
|
||||
|
||||
**Android**
|
||||
- Exact alarms on **API 31+** may require `SCHEDULE_EXACT_ALARM`. If exact access is missing on API 31+, we will use a **windowed trigger (default ±10m)** and surface a settings deep-link.
|
||||
- **We will deep-link users to the exact-alarm settings when we detect denials.**
|
||||
- **Channel defaults**: ID `timesafari.daily`, name "TimeSafari Daily", importance=high (IDs never change)
|
||||
- Receivers for reboot/time change **will be handled** by v2 (plugin); in v1, re‑arming **will occur** on app start/resume.
|
||||
- **Mobile local notifications will route via action listeners (not the service worker)**.
|
||||
|
||||
**Web**
|
||||
- Requires registered Service Worker + permission; can deliver with browser closed. **Web will not offline-schedule**.
|
||||
- Service worker click handlers apply to **web push only**; local notifications on mobile do **not** pass through the SW.
|
||||
- SW examples use `/sw.js` as a placeholder; **wire this to your actual build output path** (e.g., `sw_scripts/notification-click.js` or your combined bundle).
|
||||
- **Note**: Service workers are **intentionally disabled** in Electron (`src/main.electron.ts`) and web uses VitePWA plugin for minimal implementation.
|
||||
|
||||
**Electron**
|
||||
- We **will use** native OS notifications with **best-effort scheduling while the app is running**; true background scheduling will be addressed in v2 (native bridges).
|
||||
|
||||
**Electron delivery strategy (v1 reality + v2 path)**
|
||||
We **will deliver** desktop notifications while the Electron app is running. True **background scheduling when the app is closed** is **out of scope for v1** and **will be addressed** in v2 via native bridges. We **will adopt** one of the following options (in order of fit to our codebase):
|
||||
|
||||
**In-app scheduler + auto-launch (recommended now):** Keep the orchestrator in the main process, **start on login** (tray app, hidden window), and use the **Electron `Notification` API** for delivery. This requires no new OS services and aligns with our PlatformServiceFactory/mixin patterns.
|
||||
|
||||
**Policy (v1):** If the app is **not running**, Electron will **not** deliver scheduled locals. With **auto-launch enabled**, we **will achieve** near-mobile parity while respecting OS sleep/idle behavior.
|
||||
|
||||
**UX notes:** On Windows we **will set** `appUserModelId` so toasts are attributed correctly; on macOS we **will request** notification permission on first use.
|
||||
|
||||
**Prerequisites:** We **will require** Node 18+ (global `fetch`) or we **will polyfill** via `undici` for content fetching in the main process.
|
||||
|
||||
---
|
||||
|
||||
## 8) Template Engine Contract
|
||||
|
||||
**Supported tokens:** `{{headline}}`, `{{summary}}`, `{{date}}` (YYYY-MM-DD), `{{time}}` (HH:MM).
|
||||
**Escaping:** HTML-escape all injected values.
|
||||
**Limits:** Title ≤ 50 chars; Body ≤ 200 chars; truncate with ellipsis.
|
||||
**Fallback:** Missing token → `"[Content]"`.
|
||||
**Mutation:** We **will** render templates **before** scheduling; no mutation at delivery time on iOS locals.
|
||||
|
||||
## 9) Integration with Existing TimeSafari Infrastructure
|
||||
|
||||
**Database:** We **will integrate** with existing migration system in `src/db-sql/migration.ts` following the established `MIGRATIONS` array pattern
|
||||
**Settings:** We **will extend** existing Settings type in `src/db/tables/settings.ts` following the established type extension pattern
|
||||
**Platform Service:** We **will leverage** existing PlatformServiceMixin database utilities following the established mixin pattern
|
||||
**Service Factory:** We **will follow** the existing `PlatformServiceFactory` singleton pattern for notification service creation
|
||||
**Capacitor:** We **will integrate** with existing deep link system in `src/main.capacitor.ts` following the established initialization pattern
|
||||
**Service Worker:** We **will extend** existing service worker infrastructure following the established `sw_scripts/` pattern (Note: Service workers are intentionally disabled in Electron and have minimal web implementation via VitePWA plugin)
|
||||
**API:** We **will use** existing error handling from `src/services/api.ts` following the established `handleApiError` pattern
|
||||
**Logging:** We **will use** existing logger from `src/utils/logger` following the established logging patterns
|
||||
**Platform Detection:** We **will use** existing `process.env.VITE_PLATFORM` patterns (`web`, `capacitor`, `electron`)
|
||||
**Vue Architecture:** We **will follow** Vue 3 + vue-facing-decorator patterns for component integration (Note: The existing `useNotifications` composable in `src/composables/useNotifications.ts` is currently stub functions with eslint-disable comments and needs implementation)
|
||||
**State Management:** We **will integrate** with existing settings system via `PlatformServiceMixin.$saveSettings()` for notification preferences (Note: TimeSafari uses PlatformServiceMixin for all state management, not Pinia stores)
|
||||
**Identity System:** We **will integrate** with existing `did:ethr:` (Ethereum-based DID) system for user context
|
||||
**Testing:** We **will follow** Playwright E2E testing patterns established in TimeSafari
|
||||
**Database Architecture:** We **will support** platform-specific database backends:
|
||||
- **Web**: Absurd SQL (SQLite via IndexedDB) via `WebPlatformService` with worker pattern
|
||||
- **Capacitor**: Native SQLite via `CapacitorPlatformService`
|
||||
- **Electron**: Native SQLite via `ElectronPlatformService` (extends CapacitorPlatformService)
|
||||
|
||||
---
|
||||
|
||||
## 10) Error Taxonomy & Telemetry
|
||||
|
||||
**Error Codes:** `FETCH_TIMEOUT`, `ETAG_NOT_MODIFIED`, `SCHEDULE_DENIED`, `EXACT_ALARM_MISSING`, `STORAGE_BUSY`, `TEMPLATE_MISSING_TOKEN`, `PERMISSION_DENIED`.
|
||||
|
||||
**Event Envelope:** `code, slotId, whenMs, attempt, networkState, tzOffset, appState, timestamp`.
|
||||
|
||||
---
|
||||
|
||||
## 11) Permission UX & Channels/Categories
|
||||
|
||||
- We **will request** notification permission **after** user intent (e.g., settings screen), not on first render.
|
||||
- **Android:** We **will create** a stable channel ID (e.g., `timesafari.daily`) and **will set** importance appropriately.
|
||||
- **iOS:** We **will register** categories for optional actions; grouping may use `threadIdentifier` per slot/day.
|
||||
|
||||
---
|
||||
|
||||
## 12) Eventing & Telemetry
|
||||
|
||||
### Error Taxonomy
|
||||
**Finite error code set:**
|
||||
- `FETCH_TIMEOUT` - Network request exceeded timeout
|
||||
- `ETAG_NOT_MODIFIED` - Server returned 304 (expected)
|
||||
- `SCHEDULE_DENIED` - OS denied notification scheduling
|
||||
- `EXACT_ALARM_MISSING` - Android exact alarm permission absent
|
||||
- `STORAGE_BUSY` - Database locked or unavailable
|
||||
- `TEMPLATE_MISSING_TOKEN` - Required template variable not found
|
||||
- `PERMISSION_DENIED` - User denied notification permissions
|
||||
|
||||
### Event Logging Envelope
|
||||
```ts
|
||||
{
|
||||
code: string, // Error code from taxonomy
|
||||
slotId: string, // Affected slot
|
||||
whenMs: number, // Scheduled time
|
||||
attempt: number, // Retry attempt (1-based)
|
||||
networkState: string, // 'online' | 'offline'
|
||||
tzOffset: number, // Current timezone offset
|
||||
appState: string, // 'foreground' | 'background' | 'killed'
|
||||
timestamp: number // UTC timestamp
|
||||
}
|
||||
```
|
||||
|
||||
### ACK Payload Format
|
||||
```ts
|
||||
{
|
||||
slotId: string,
|
||||
fireAt: number, // Scheduled time
|
||||
deliveredAt: number, // Actual delivery time
|
||||
deviceTz: string, // Device timezone
|
||||
appVersion: string, // App version
|
||||
buildId: string // Build identifier
|
||||
}
|
||||
```
|
||||
|
||||
- **Event queue (v1):** In-memory queue for `delivery`, `error`, `heartbeat` events. Background/native work **will enqueue**; foreground **will drain** and publish to the UI. **v2 will migrate** to SQLite-backed queue for persistence.
|
||||
- **Callbacks (optional):** `ackDelivery`, `reportError`, `heartbeat` **will post** to server endpoints when configured.
|
||||
- **Minimal metrics:** pending count, last fetch, last delivery, next occurrences.
|
||||
|
||||
---
|
||||
|
||||
## 13) Feature Flags & Config
|
||||
|
||||
### Feature Flags Table
|
||||
| Flag | Default | Description | Location |
|
||||
|------|---------|-------------|----------|
|
||||
| `scheduler` | `'capacitor'` | Scheduler implementation | `notif_config` table |
|
||||
| `mode` | `'auto'` | Online-first inside lead, else offline-first | `notif_config` table |
|
||||
| `prefetchLeadMinutes` | `20` | Lead time for prefetch attempts | `notif_config` table |
|
||||
| `ttlSeconds` | `86400` | Content staleness threshold (24h) | `notif_config` table |
|
||||
| `iosCategoryIdentifier` | `'TS_DAILY'` | iOS notification category | `notif_config` table |
|
||||
| `androidChannelId` | `'timesafari.daily'` | Android channel ID (never changes) | `notif_config` table |
|
||||
|
||||
**Storage:** Feature flags **will reside** in `notif_config` table as key-value pairs, separate from user settings.
|
||||
|
||||
---
|
||||
|
||||
## 14) Acceptance (Definition of Done) → Test Cases
|
||||
|
||||
### Explicit Test Checks
|
||||
- **App killed → locals fire**: Configure slots at 8:00, 12:00, 18:00; kill app; verify notifications fire at each slot on iOS/Android
|
||||
- **ETag 304 path**: Server returns 304 → keep previous content; locals fire with cached payload
|
||||
- **ETag 200 path**: Server returns 200 → update content and re-arm locals with fresh payload
|
||||
- **Offline + beyond TTL**: When offline and content > 24h old → skip notification (no "(cached)" suffix)
|
||||
- **iOS pending cap**: Respect ~64 pending limit; cancel/re-arm as needed within rolling window
|
||||
- **Exact-alarm denied**: Android permission absent → windowed schedule (±10m) activates; UI shows fallback hint
|
||||
- **Permissions disabled** → we will record `SCHEDULE_DENIED` and refrain from queuing locals.
|
||||
- **Window fallback** → when exact alarm is absent on Android, verify target fires within **±10m** of slot time (document as an E2E expectation).
|
||||
- **Timezone change**: On TZ/DST change → recompute wall-clock times; cancel & re-arm all slots
|
||||
- **Lead window respect**: No retries attempted once inside 20min lead window
|
||||
- **Idempotency**: Multiple `runFullPipelineNow()` calls don't create duplicate scheduled deliveries
|
||||
- **Cooldown guard**: `deliverStoredNow()` has 60s cooldown to prevent double-firing
|
||||
|
||||
### Electron-Specific Test Checks
|
||||
- **Electron running (tray or window) → notifications fire** at configured slots using Electron `Notification`
|
||||
- **Electron not running →** no delivery (documented limitation for v1)
|
||||
- **Start on Login enabled →** after reboot + login, orchestrator **will re-arm** slots and deliver
|
||||
- **Template limits honored** (Title ≤ 50, Body ≤ 200) on Electron notifications
|
||||
- **SW scope** not used for Electron (click handlers are **web only**)
|
||||
- **Windows appUserModelId** set correctly for toast attribution
|
||||
- **macOS notification permission** requested on first use
|
||||
|
||||
---
|
||||
|
||||
## 15) Test Matrix (Essentials)
|
||||
|
||||
- **Android:** exact vs inexact branch, Doze/App Standby behavior, reboot/time change, permission denial path, deep‑link to exact‑alarm settings.
|
||||
- **iOS:** BG fetch budget limits, pending cap windowing, local notification delivery with app terminated, category actions.
|
||||
- **Web:** SW lifecycle, push delivery with app closed, click handling, no offline scheduling.
|
||||
- **Cross‑cutting:** ETag/304 behavior, TTL policy, templating correctness, event queue drain, SQLite retention job.
|
||||
|
||||
---
|
||||
|
||||
## 16) Migration & Rollout Notes
|
||||
|
||||
- We **will keep** existing web push flows intact.
|
||||
- We **will introduce** the orchestrator behind a feature flag, initially with a small number of slots.
|
||||
- We **will migrate** settings to accept multiple times per day.
|
||||
- We **will document** platform caveats inside user‑visible settings (e.g., Android exact alarms, iOS cap).
|
||||
|
||||
---
|
||||
|
||||
## 17) Security & Privacy
|
||||
|
||||
- Tokens **will reside** in Keystore/Keychain (mobile) and **will be injected** at request time; they **will not** be stored in SQLite.
|
||||
- Optionally, SQLCipher at rest for mobile; redaction of PII in logs; payload size caps.
|
||||
- Content **will be** minimal (title/body); sensitive data **will not be** embedded.
|
||||
|
||||
---
|
||||
|
||||
## 18) Non‑Goals (Now)
|
||||
|
||||
- Complex action sets and rich media on locals (kept minimal).
|
||||
- Delivery‑time mutation of local notifications on iOS (NSE is for remote).
|
||||
- Full analytics pipeline (future enhancement).
|
||||
|
||||
---
|
||||
|
||||
## 19) Cross-Doc Sync Hygiene
|
||||
|
||||
### Canonical Ownership
|
||||
- **This document (Plan)**: Canonical for Goals, Tenets, Platform behaviors, Acceptance criteria, Test cases
|
||||
- **Implementation document**: Canonical for API definitions, Database schemas, Adapter implementations, Code examples
|
||||
|
||||
### PR Checklist
|
||||
When changing notification system behavior, update both documents:
|
||||
- [ ] **API changes**: Update types/interfaces in both Plan §4 and Implementation §3
|
||||
- [ ] **Schema changes**: Update Plan §5 and Implementation §2
|
||||
- [ ] **Slot/TTL changes**: Update Plan §4 semantics and Implementation §6 logic
|
||||
- [ ] **Template changes**: Update Plan §9 contract and Implementation examples
|
||||
- [ ] **Error codes**: Update Plan §11 taxonomy and Implementation error handling
|
||||
|
||||
### Synchronization Points
|
||||
- **API code blocks**: Must be identical between Plan §4 and Implementation §3 (Public API (Shared))
|
||||
- **Feature flags**: Must match between Plan §12 table and Implementation defaults
|
||||
- **Test cases**: Plan §13 acceptance criteria must align with Implementation test examples
|
||||
- **Slot/TTL/Lead policies**: Must be identical between Plan §4 policy and Implementation §3 policy
|
||||
|
||||
---
|
||||
|
||||
## 21) Privacy & Security Alignment
|
||||
|
||||
### Privacy-First Architecture
|
||||
- **User-Controlled Visibility:** Notification preferences **will be** user-controlled with explicit opt-in/opt-out
|
||||
- **Data Sovereignty:** All notification data **will reside** on user's device; no external tracking or analytics
|
||||
- **Minimal Data Collection:** We **will collect** only essential data for notification delivery (slot times, content templates)
|
||||
- **DID Integration:** Notifications **will be** associated with user's Decentralized Identifier (DID) for privacy-preserving identity
|
||||
|
||||
### Security Considerations
|
||||
- **Content Encryption:** Sensitive notification content **will be** encrypted at rest using device keystore
|
||||
- **Secure Transmission:** All API calls **will use** HTTPS with proper certificate validation
|
||||
- **Input Validation:** All notification content **will be** validated and sanitized before storage
|
||||
- **Access Control:** Notification settings **will be** protected by user authentication
|
||||
|
||||
### Compliance with TimeSafari Principles
|
||||
- **Privacy-Preserving:** Follows TimeSafari's privacy-preserving claims architecture
|
||||
- **User Agency:** Users maintain full control over their notification experience
|
||||
- **Transparency:** Clear communication about what data is collected and how it's used
|
||||
- **Minimal Footprint:** Notification system **will have** minimal impact on user privacy
|
||||
|
||||
---
|
||||
|
||||
## 23) Platform-Specific Implementation Details
|
||||
|
||||
### Web Platform (`VITE_PLATFORM=web`)
|
||||
- **Database:** Uses Absurd SQL (SQLite via IndexedDB) via `WebPlatformService` with worker pattern
|
||||
- **Notifications:** Web push notifications via Service Worker (minimal implementation)
|
||||
- **Local Scheduling:** **Not supported** - web cannot schedule local notifications offline
|
||||
- **API Integration:** Direct HTTP calls for content fetching
|
||||
- **Storage:** Notification preferences stored in Absurd SQL database
|
||||
- **Testing:** Playwright E2E tests run on web platform
|
||||
|
||||
### Capacitor Platform (`VITE_PLATFORM=capacitor`)
|
||||
- **Database:** Uses native SQLite via `CapacitorPlatformService`
|
||||
- **Notifications:** Local notifications via `@capacitor/local-notifications`
|
||||
- **Local Scheduling:** **Fully supported** - OS-level notification scheduling
|
||||
- **API Integration:** HTTP calls with mobile-optimized timeouts and retry logic
|
||||
- **Storage:** Notification preferences stored in native SQLite database
|
||||
- **Testing:** Playwright E2E tests run on mobile devices (Android/iOS)
|
||||
|
||||
### Electron Platform (`VITE_PLATFORM=electron`)
|
||||
- **Database:** Uses native SQLite via `ElectronPlatformService` (extends CapacitorPlatformService)
|
||||
- **Notifications:** OS-level notifications via Electron's notification API
|
||||
- **Local Scheduling:** **Supported** - desktop OS notification scheduling
|
||||
- **API Integration:** Same as Capacitor platform
|
||||
- **Storage:** Same as Capacitor platform (via inherited service)
|
||||
- **Testing:** Same as Capacitor platform
|
||||
|
||||
### Cross-Platform Considerations
|
||||
- **Feature Detection:** Use `process.env.VITE_PLATFORM` for platform-specific behavior
|
||||
- **Database Abstraction:** PlatformServiceMixin handles database differences transparently
|
||||
- **API Consistency:** Same TypeScript API across all platforms
|
||||
- **Fallback Behavior:** Web platform gracefully degrades to push-only notifications
|
||||
|
||||
---
|
||||
## 24) TimeSafari Architecture Compliance
|
||||
|
||||
### Design Pattern Adherence
|
||||
- **Factory Pattern:** Notification service follows `PlatformServiceFactory` singleton pattern
|
||||
- **Mixin Pattern:** Database access uses existing `PlatformServiceMixin` pattern
|
||||
- **Migration Pattern:** Database changes follow existing `MIGRATIONS` array pattern
|
||||
- **Error Handling:** Uses existing `handleApiError` from `src/services/api.ts`
|
||||
- **Logging:** Uses existing logger from `src/utils/logger` with established patterns
|
||||
- **Platform Detection:** Uses existing `Capacitor.isNativePlatform()` and `VITE_PLATFORM` patterns
|
||||
|
||||
### File Organization Compliance
|
||||
- **Services:** Follows existing `src/services/` organization with factory and adapters
|
||||
- **Database:** Extends existing `src/db-sql/migration.ts` and `src/db/tables/settings.ts`
|
||||
- **Utils:** Extends existing `src/utils/PlatformServiceMixin.ts`
|
||||
- **Main Entry:** Integrates with existing `src/main.capacitor.ts` initialization
|
||||
- **Service Workers:** Follows existing `sw_scripts/` organization
|
||||
|
||||
### Type Safety Compliance
|
||||
- **Settings Extension:** Follows existing Settings type extension pattern
|
||||
- **Interface Definitions:** Uses existing TypeScript interface patterns
|
||||
- **Error Types:** Follows existing error handling type patterns
|
||||
- **Platform Types:** Uses existing platform detection type patterns
|
||||
|
||||
---
|
||||
|
||||
## Sync Checklist
|
||||
|
||||
| Sync item | Plan | Impl | Status |
|
||||
| ------------------------------ | --------------------- | --------------------- | --------- |
|
||||
| Public API block identical | §4 | §3 | ✅ |
|
||||
| `getState()` fields present | §4 | §8 Orchestrator | ✅ |
|
||||
| Capacitor action handlers | §7 (iOS/Android note) | §9 Bootstrap | ✅ |
|
||||
| Electron fetch prereq/polyfill | §7 | §9 Electron | ✅ |
|
||||
| Android ±10m fallback | §7 | §7 SchedulerCapacitor | ✅ |
|
||||
| Retention (no VACUUM v1) | §5 | `$pruneNotifData` | ✅ |
|
||||
|
||||
---
|
||||
|
||||
*This strategic plan focuses on features and future‑tense deliverables, avoids implementation details, and preserves a clear path from the in‑app implementation (v1) to the native plugin (v2). For detailed implementation specifics, see `notification-system-implementation.md`.*
|
||||
Reference in New Issue
Block a user