daily-notification-plugin/docs/architecture/DATABASE_INTERFACES.md

# Database Interfaces Documentation

**Author**: Matthew Raymer  
**Version**: 1.0.0  
**Last Updated**: 2025-01-21

## Overview

The Daily Notification Plugin owns its own SQLite database for storing schedules, cached content, configuration, and execution history. Since the plugin's database is isolated from the host app, the webview accesses this data through TypeScript/Capacitor interfaces.

This document explains how to use these interfaces from TypeScript/JavaScript code in your Capacitor app.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Host App (TypeScript)                     │
│  import { DailyNotification } from '@capacitor-community/...'│
│                                                              │
│  const schedules = await DailyNotification.getSchedules()  │
└──────────────────────┬──────────────────────────────────────┘
                       │ Capacitor Bridge
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Plugin (Native Android/Kotlin)                 │
│                                                              │
│  @PluginMethod                                              │
│  getSchedules() → Room Database → SQLite                    │
└─────────────────────────────────────────────────────────────┘
```

## Quick Start

```typescript
import { DailyNotification } from '@capacitor-community/daily-notification';

// Get all enabled notification schedules
const schedules = await DailyNotification.getSchedules({ 
  kind: 'notify', 
  enabled: true 
});

// Get latest cached content
const content = await DailyNotification.getLatestContentCache();

// Create a new schedule
const newSchedule = await DailyNotification.createSchedule({
  kind: 'notify',
  cron: '0 9 * * *',  // Daily at 9 AM
  enabled: true
});
```

## Interface Categories

### 1. Schedules Management

Schedules represent recurring patterns for fetching content or displaying notifications. These are critical for reboot recovery - Android doesn't persist AlarmManager/WorkManager schedules, so they must be restored from the database.

#### Get All Schedules

```typescript
// Get all schedules
const result = await DailyNotification.getSchedules();
const allSchedules = result.schedules;

// Get only enabled notification schedules
const notifyResult = await DailyNotification.getSchedules({ 
  kind: 'notify', 
  enabled: true 
});
const enabledNotify = notifyResult.schedules;

// Get only fetch schedules
const fetchResult = await DailyNotification.getSchedules({ 
  kind: 'fetch' 
});
const fetchSchedules = fetchResult.schedules;
```

**Returns**: `Promise<{ schedules: Schedule[] }>` - Note: Array is wrapped in object due to Capacitor serialization

#### Get Single Schedule

```typescript
const schedule = await DailyNotification.getSchedule('notify_1234567890');
if (schedule) {
  console.log(`Next run: ${new Date(schedule.nextRunAt)}`);
}
```

**Returns**: `Promise<Schedule | null>`

#### Create Schedule

```typescript
const schedule = await DailyNotification.createSchedule({
  kind: 'notify',
  cron: '0 9 * * *',  // Daily at 9 AM (cron format)
  // OR
  clockTime: '09:00',  // Simple HH:mm format
  enabled: true,
  jitterMs: 60000,  // 1 minute jitter
  backoffPolicy: 'exp'
});
```

**Returns**: `Promise<Schedule>`

#### Update Schedule

```typescript
// Update schedule enable state
await DailyNotification.updateSchedule('notify_1234567890', {
  enabled: false
});

// Update next run time
await DailyNotification.updateSchedule('notify_1234567890', {
  nextRunAt: Date.now() + 86400000  // Tomorrow
});
```

**Returns**: `Promise<Schedule>`

#### Delete Schedule

```typescript
await DailyNotification.deleteSchedule('notify_1234567890');
```

**Returns**: `Promise<void>`

#### Enable/Disable Schedule

```typescript
// Disable schedule
await DailyNotification.enableSchedule('notify_1234567890', false);

// Enable schedule
await DailyNotification.enableSchedule('notify_1234567890', true);
```

**Returns**: `Promise<void>`

#### Calculate Next Run Time

```typescript
// Calculate next run from cron expression
const nextRun = await DailyNotification.calculateNextRunTime('0 9 * * *');

// Calculate next run from clockTime
const nextRun2 = await DailyNotification.calculateNextRunTime('09:00');

console.log(`Next run: ${new Date(nextRun)}`);
```

**Returns**: `Promise<number>` (timestamp in milliseconds)

### 2. Content Cache Management

Content cache stores prefetched content for offline-first display. Each entry has a TTL (time-to-live) for freshness validation.

#### Get Latest Content Cache

```typescript
const latest = await DailyNotification.getLatestContentCache();
if (latest) {
  const content = JSON.parse(latest.payload);
  const age = Date.now() - latest.fetchedAt;
  const isFresh = age < (latest.ttlSeconds * 1000);
  
  console.log(`Content age: ${age}ms, Fresh: ${isFresh}`);
}
```

**Returns**: `Promise<ContentCache | null>`

#### Get Content Cache by ID

```typescript
const cache = await DailyNotification.getContentCacheById({ 
  id: 'cache_1234567890' 
});
```

**Returns**: `Promise<ContentCache | null>`

#### Get Content Cache History

```typescript
// Get last 10 cache entries
const result = await DailyNotification.getContentCacheHistory(10);
const history = result.history;

history.forEach(cache => {
  console.log(`Cache ${cache.id}: ${new Date(cache.fetchedAt)}`);
});
```

**Returns**: `Promise<{ history: ContentCache[] }>`

#### Save Content Cache

```typescript
const cached = await DailyNotification.saveContentCache({
  payload: JSON.stringify({
    title: 'Daily Update',
    body: 'Your daily content is ready!',
    data: { /* ... */ }
  }),
  ttlSeconds: 3600,  // 1 hour TTL
  meta: 'fetched_from_api'
});

console.log(`Cached content with ID: ${cached.id}`);
```

**Returns**: `Promise<ContentCache>`

#### Clear Content Cache

```typescript
// Clear all cache entries
await DailyNotification.clearContentCacheEntries();

// Clear entries older than 24 hours
const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);
await DailyNotification.clearContentCacheEntries({ 
  olderThan: oneDayAgo 
});
```

**Returns**: `Promise<void>`

### 3. Configuration Management

**Note**: Configuration management methods (`getConfig`, `setConfig`, etc.) are currently not implemented in the Kotlin database schema. These will be available once the database consolidation is complete (see `android/DATABASE_CONSOLIDATION_PLAN.md`). For now, use the Java-based `DailyNotificationStorageRoom` for configuration storage if needed.

When implemented, these methods will store plugin settings and user preferences with optional TimeSafari DID scoping.

#### Get Configuration

```typescript
// Get config by key
const config = await DailyNotification.getConfig('notification_sound_enabled');

if (config) {
  const value = config.configDataType === 'boolean' 
    ? config.configValue === 'true'
    : config.configValue;
  console.log(`Sound enabled: ${value}`);
}
```

**Returns**: `Promise<Config | null>`

#### Get All Configurations

```typescript
// Get all configs
const allConfigs = await DailyNotification.getAllConfigs();

// Get configs for specific user
const userConfigs = await DailyNotification.getAllConfigs({
  timesafariDid: 'did:ethr:0x...'
});

// Get configs by type
const pluginConfigs = await DailyNotification.getAllConfigs({
  configType: 'plugin_setting'
});
```

**Returns**: `Promise<Config[]>`

#### Set Configuration

```typescript
await DailyNotification.setConfig({
  configType: 'user_preference',
  configKey: 'notification_sound_enabled',
  configValue: 'true',
  configDataType: 'boolean',
  timesafariDid: 'did:ethr:0x...'  // Optional: user-specific
});
```

**Returns**: `Promise<Config>`

#### Update Configuration

```typescript
await DailyNotification.updateConfig(
  'notification_sound_enabled',
  'false',
  { timesafariDid: 'did:ethr:0x...' }
);
```

**Returns**: `Promise<Config>`

#### Delete Configuration

```typescript
await DailyNotification.deleteConfig('notification_sound_enabled', {
  timesafariDid: 'did:ethr:0x...'
});
```

**Returns**: `Promise<void>`

### 4. Callbacks Management

Callbacks are executed after fetch/notify events. They can be HTTP endpoints, local handlers, or queue destinations.

#### Get All Callbacks

```typescript
// Get all callbacks
const result = await DailyNotification.getCallbacks();
const allCallbacks = result.callbacks;

// Get only enabled callbacks
const enabledResult = await DailyNotification.getCallbacks({ 
  enabled: true 
});
const enabledCallbacks = enabledResult.callbacks;
```

**Returns**: `Promise<{ callbacks: Callback[] }>`

#### Get Single Callback

```typescript
const callback = await DailyNotification.getCallback('on_notify_delivered');
```

**Returns**: `Promise<Callback | null>`

#### Register Callback

```typescript
await DailyNotification.registerCallbackConfig({
  id: 'on_notify_delivered',
  kind: 'http',
  target: 'https://api.example.com/webhooks/notify',
  headersJson: JSON.stringify({
    'Authorization': 'Bearer token123',
    'Content-Type': 'application/json'
  }),
  enabled: true
});
```

**Returns**: `Promise<Callback>`

#### Update Callback

```typescript
await DailyNotification.updateCallback('on_notify_delivered', {
  enabled: false,
  headersJson: JSON.stringify({ 'Authorization': 'Bearer newtoken' })
});
```

**Returns**: `Promise<Callback>`

#### Delete Callback

```typescript
await DailyNotification.deleteCallback('on_notify_delivered');
```

**Returns**: `Promise<void>`

#### Enable/Disable Callback

```typescript
await DailyNotification.enableCallback('on_notify_delivered', false);
```

**Returns**: `Promise<void>`

### 5. History/Analytics

History provides execution logs for debugging and analytics.

#### Get History

```typescript
// Get last 50 entries
const result = await DailyNotification.getHistory();
const history = result.history;

// Get entries since yesterday
const yesterday = Date.now() - (24 * 60 * 60 * 1000);
const recentResult = await DailyNotification.getHistory({
  since: yesterday,
  limit: 100
});
const recentHistory = recentResult.history;

// Get only fetch executions
const fetchResult = await DailyNotification.getHistory({
  kind: 'fetch',
  limit: 20
});
const fetchHistory = fetchResult.history;
```

**Returns**: `Promise<{ history: History[] }>`

#### Get History Statistics

```typescript
const stats = await DailyNotification.getHistoryStats();

console.log(`Total executions: ${stats.totalCount}`);
console.log(`Success rate: ${stats.outcomes.success / stats.totalCount * 100}%`);
console.log(`Fetch executions: ${stats.kinds.fetch}`);
console.log(`Most recent: ${new Date(stats.mostRecent)}`);
```

**Returns**: `Promise<HistoryStats>`

## Type Definitions

### Schedule

```typescript
interface Schedule {
  id: string;
  kind: 'fetch' | 'notify';
  cron?: string;              // Cron expression (e.g., "0 9 * * *")
  clockTime?: string;         // HH:mm format (e.g., "09:00")
  enabled: boolean;
  lastRunAt?: number;         // Timestamp (ms)
  nextRunAt?: number;        // Timestamp (ms)
  jitterMs: number;
  backoffPolicy: string;     // 'exp', etc.
  stateJson?: string;
}
```

### ContentCache

```typescript
interface ContentCache {
  id: string;
  fetchedAt: number;         // Timestamp (ms)
  ttlSeconds: number;
  payload: string;            // JSON string or base64
  meta?: string;
}
```

### Config

```typescript
interface Config {
  id: string;
  timesafariDid?: string;
  configType: string;
  configKey: string;
  configValue: string;
  configDataType: string;     // 'string' | 'boolean' | 'integer' | etc.
  isEncrypted: boolean;
  createdAt: number;         // Timestamp (ms)
  updatedAt: number;          // Timestamp (ms)
}
```

### Callback

```typescript
interface Callback {
  id: string;
  kind: 'http' | 'local' | 'queue';
  target: string;
  headersJson?: string;
  enabled: boolean;
  createdAt: number;         // Timestamp (ms)
}
```

### History

```typescript
interface History {
  id: number;
  refId: string;
  kind: 'fetch' | 'notify' | 'callback' | 'boot_recovery';
  occurredAt: number;        // Timestamp (ms)
  durationMs?: number;
  outcome: string;            // 'success' | 'failure' | etc.
  diagJson?: string;
}
```

## Common Patterns

### Pattern 1: Check Schedule Status

```typescript
async function checkScheduleStatus() {
  const result = await DailyNotification.getSchedules({ enabled: true });
  const schedules = result.schedules;
  
  for (const schedule of schedules) {
    if (schedule.nextRunAt) {
      const nextRun = new Date(schedule.nextRunAt);
      const now = new Date();
      const timeUntil = nextRun.getTime() - now.getTime();
      
      console.log(`${schedule.kind} schedule ${schedule.id}:`);
      console.log(`  Next run: ${nextRun}`);
      console.log(`  Time until: ${Math.round(timeUntil / 1000 / 60)} minutes`);
    }
  }
}
```

### Pattern 2: Verify Content Freshness

```typescript
async function isContentFresh(): Promise<boolean> {
  const cache = await DailyNotification.getLatestContentCache();
  
  if (!cache) {
    return false;  // No content available
  }
  
  const age = Date.now() - cache.fetchedAt;
  const ttlMs = cache.ttlSeconds * 1000;
  
  return age < ttlMs;
}
```

### Pattern 3: Update User Preferences

```typescript
async function updateUserPreferences(did: string, preferences: Record<string, any>) {
  for (const [key, value] of Object.entries(preferences)) {
    await DailyNotification.setConfig({
      timesafariDid: did,
      configType: 'user_preference',
      configKey: key,
      configValue: String(value),
      configDataType: typeof value === 'boolean' ? 'boolean' : 'string'
    });
  }
}
```

### Pattern 4: Monitor Execution Health

```typescript
async function checkExecutionHealth() {
  const stats = await DailyNotification.getHistoryStats();
  const recentResult = await DailyNotification.getHistory({ 
    since: Date.now() - (24 * 60 * 60 * 1000)  // Last 24 hours
  });
  const recent = recentResult.history;
  
  const successCount = recent.filter(h => h.outcome === 'success').length;
  const failureCount = recent.filter(h => h.outcome === 'failure').length;
  const successRate = successCount / recent.length;
  
  console.log(`24h Success Rate: ${(successRate * 100).toFixed(1)}%`);
  console.log(`Successes: ${successCount}, Failures: ${failureCount}`);
  
  return successRate > 0.9;  // Healthy if > 90% success rate
}
```

## Error Handling

All methods return Promises and can reject with errors:

```typescript
try {
  const schedule = await DailyNotification.getSchedule('invalid_id');
  if (!schedule) {
    console.log('Schedule not found');
  }
} catch (error) {
  console.error('Error accessing database:', error);
  // Handle error - database might be unavailable, etc.
}
```

## Thread Safety

All database operations are executed on background threads (Kotlin `Dispatchers.IO`). Methods are safe to call from any thread in your TypeScript code.

## Implementation Status

### ✅ Implemented
- Schedule management (CRUD operations)
- Content cache management (CRUD operations)
- Callback management (CRUD operations)
- History/analytics (read operations)

### ⚠️ Pending Database Consolidation
- Configuration management (Config table exists in Java DB, needs to be added to Kotlin schema)
- See `android/DATABASE_CONSOLIDATION_PLAN.md` for full consolidation plan

## Return Format Notes

**Important**: Capacitor serializes arrays wrapped in JSObject. Methods that return arrays will return them in this format:
- `getSchedules()` → `{ schedules: Schedule[] }`
- `getCallbacks()` → `{ callbacks: Callback[] }`
- `getHistory()` → `{ history: History[] }`
- `getContentCacheHistory()` → `{ history: ContentCache[] }`

This is due to Capacitor's serialization mechanism. Always access the array property from the returned object.