analysis: TimeSafari host application integration patterns

- Documented active_identity table structure and access methods - Analyzed TimeSafari's PlatformServiceMixin patterns - Created three integration options: 1. Host-managed activeDid (plugin receives from host) 2. Plugin-lookup activeDid (plugin queries active_identity table) 3. Hybrid approach (recommended combination) - Detailed service layer integration points - Cross-platform considerations for Android/Capacitor/Web/iOS/Electron - Security isolation recommendations for plugin/host database access This analysis provides clear guidance for hosting the plugin within TimeSafari applications.
18 hours ago · 1fabcf1fe9
1 changed files with 343 additions and 0 deletions
--- a/doc/TIMESAFARI_INTEGRATION_ANALYSIS.md
+++ b/doc/TIMESAFARI_INTEGRATION_ANALYSIS.md
@ -0,0 +1,343 @@
 # TimeSafari Daily Notification Plugin Integration Analysis
 **Author**: Matthew Raymer  
 **Version**: 1.0.0  
 **Created**: 2025-10-02 11:00:00 UTC  
 **Last Updated**: 2025-10-02 11:00:00 UTC  
 ## Overview
 This document analyzes how the Daily Notification Plugin would integrate with TimeSafari, focusing on `activeDid` access and plugin hosting architecture.
 ## ActiveDid Management in TimeSafari
 ### Database Schema: `active_identity` Table
 **Table Structure:**
 ```sql
 CREATE TABLE active_identity (
  id INTEGER PRIMARY KEY DEFAULT 1,
  activeDid TEXT NOT NULL,
  lastUpdated DATETIME DEFAULT (datetime('now'))
 );
 ```
 **Key Characteristics:**
 - Single row table with `id = 1` always
 - `activeDid` contains the currently active user's DID
 - `lastUpdated` tracks when the active identity was switched
 - Single source of truth for current user identity
 ### Access Methods
 **1. Platform Service Level:**
 ```typescript
 // In CapacitorPlatformService, WebPlatformService, ElectronPlatformService
 async updateActiveDid(did: string): Promise<void> {
  await this.dbExec(
    "INSERT OR REPLACE INTO active_identity (id, activeDid, lastUpdated) VALUES (1, ?, ?)",
    [did, new Date().toISOString()]
  );
 }
 async getActiveIdentity(): Promise<{ activeDid: string }> {
  const result = await this.dbQuery(
    "SELECT activeDid FROM active_identity WHERE id = 1"
  );
  return {
    activeDid: (result?.values?.[0]?.[0] as string) || ""
  };
 }
 ```
 **2. Vue Mixin Level:**
 ```typescript
 // In PlatformServiceMixin.ts
 async $updateActiveDid(newDid: string | null): Promise<void> {
  await this.$dbExec(
    "UPDATE active_identity SET activeDid = ?, lastUpdated = datetime('now') WHERE id = 1",
    [newDid || ""]
  );
 }
 async $getActiveIdentity(): Promise<{ activeDid: string }> {
  const result = await this.$dbExec(
    "SELECT activeDid FROM active_identity WHERE id = 1"
  );
  return { activeDid: result.activeDid || "" };
 }
 ```
 **3. Component Level Usage:**
 ```typescript
 // In Vue components
 const activeIdentity = await this.$getActiveIdentity();
 const activeDid = activeIdentity.activeDid || "";
 ```
 ## Plugin Integration Options
 ### Option 1: Host Application Manages activeDid
 **Pros:**
 - Simple integration
 - Plugin doesn't need database access
 - Clear separation of concerns
 **Implementation:**
 ```typescript
 // In TimeSafari application
 import { DailyNotification } from '@timesafari/daily-notification-plugin';
 // On app initialization or user switch
 async function initializeNotifications() {
  const activeIdentity = await this.$getActiveIdentity();
  const activeDid = activeIdentity.activeDid;
  if (activeDid) {
    await DailyNotification.setActiveDid(activeDid);
    await DailyNotification.configure({
      apiServer: 'https://endorser.ch',
      activeDid: activeDid,
      // ... other config
    });
  }
 }
 ```
 **When to Use:**
 - Host application already has database access
 - Plugin should be stateless regarding identity
 - Simple notification scheduling only
 ### Option 2: Plugin Looks Up activeDid
 **Pros:**
 - Plugin manages its own identity context
 - Automatic activeDid synchronization
 - Background tasks have direct access
 **Implementation:**
 ```typescript
 // Plugin has database access via @capacitor-community/sqlite
 interface EnhancedDailyNotificationPlugin {
  async initializeFromTimeSafari(): Promise<void> {
    // Plugin accesses TimeSafari's active_identity table
    const result = await this.dbQuery(
      "SELECT activeDid FROM active_identity WHERE id = 1"
    );
    const activeDid = result?.values?.[0]?.[0] as string;
    await this.setActiveDid(activeDid);
    await this.scheduleBackgroundTasks();
  }
 }
 ```
 **When to Use:**
 - Plugin needs autonomous background operation
 - Host application integration should be minimal
 - Plugin operates independently of app lifecycle
 ### Option 3: Hybrid Approach (Recommended)
 **Implementation:**
 ```typescript
 // Host provides activeDid when app is active
 // Plugin looks up activeDid for background operations
 interface HybridDailyNotificationPlugin {
  // Host-initiated activeDid setting
  async setActiveDidFromHost(activeDid: string): Promise<void>;
  // Plugin-initiated activeDid lookup for background
  async refreshActiveDidFromDatabase(): Promise<string>;
  // Automatic mode that uses both approaches
  async enableAutoActiveDidMode(): Promise<void>;
 }
 // In TimeSafari app
 async function initializeNotifications() {
  const activeIdentity = await this.$getActiveIdentity();
  const activeDid = activeIdentity.activeDid;
  if (activeDid) {
    await DailyNotification.setActiveDidFromHost(activeDid);
    await DailyNotification.enableAutoActiveDidMode();
  }
 }
 ```
 ## Recommended Plugin Hosting Architecture
 ### Service Layer Integration
 **Location**: `src/services/DailyNotificationService.ts`
 ```typescript
 // src/services/DailyNotificationService.ts
 import { DailyNotification } from '@timesafari/daily-notification-plugin';
 import { PlatformServiceFactory } from './PlatformServiceFactory';
 export class DailyNotificationService {
  private plugin: DailyNotification;
  private platform = PlatformServiceFactory.getInstance();
  private currentActiveDid: string | null = null;
  async initialize(): Promise<void> {
    // Initialize plugin with current active identity
    const activeIdentity = await this.platform.getActiveIdentity();
    this.currentActiveDid = activeIdentity.activeDid;
    if (this.currentActiveDid) {
      await this.plugin.setActiveDid(this.currentActiveDid);
      await this.plugin.configure({
        apiServer: import.meta.env.VITE_ENDORSER_API_SERVER,
        storageType: 'plugin-managed',
        notifications: {
          offers: true,
          projects: true,
          people: true,
          items: true
        }
      });
      // Listen for identity changes
      this.setupIdentityChangeListener();
    }
  }
  private setupIdentityChangeListener(): void {
    // Subscribe to identity changes in TimeSafari
    document.addEventListener('activeDidChanged', (event: CustomEvent) => {
      this.handleActiveDidChange(event.detail.activeDid);
    });
  }
  private async handleActiveDidChange(newActiveDid: string): Promise<void> {
    if (newActiveDid !== this.currentActiveDid) {
      this.currentActiveDid = newActiveDid;
      await this.plugin.setActiveDid(newActiveDid);
      logger.info(`[DailyNotificationService] ActiveDid updated to: ${newActiveDid}`);
 ```
 ### PlatformServiceMixin Integration
 **Location**: `src/utils/PlatformServiceMixin.ts`
 ```typescript
 // Add to PlatformServiceMixin.ts
 async $notifyDailyNotificationService(): Promise<void> {
  // Trigger notification service update when activeDid changes
  const event = new CustomEvent('activeDidChanged', {
    detail: { activeDid: this.currentActiveDid }
  });
  document.dispatchEvent(event);
 }
 // Modify existing $updateActiveDid method
 async $updateActiveDid(newDid: string | null): Promise<void> {
  // ... existing logic ...
  // Notify DailyNotification service
  await this.$notifyDailyNotificationService();
 }
 ```
 ### App Initialization Integration
 **Location**: `src/main.ts` or App component
 ```typescript
 // src/main.ts
 import { DailyNotificationService } from '@/services/DailyNotificationService';
 async function initializeNotifications() {
  try {
    const notificationService = new DailyNotificationService();
    await notificationService.initialize();
    logger.info('[App] Daily notification service initialized successfully');
  } catch (error) {
    logger.error('[App] Failed to initialize notification service:', error);
  }
 }
 // Call after platform service initialization
 initializePlatform().then(async () => {
  await initializeNotifications();
  // ... rest of app initialization
 });
 ```
 ## Cross-Platform Considerations
 ### Android (Capacitor)
 - **Database Access**: Plugin uses `@capacitor-community/sqlite`
 - **identity Access**: Can read TimeSafari's active_identity table directly
 - **Background Tasks**: WorkManager can query active_identity independently
 ### Web (absurd-sql)
 - **Database Access**: Plugin delegates to host application
 - **identity Access**: Host provides activeDid, plugin doesn't access database
 - **Background Tasks**: Service Worker coordination with host database
 ### iOS (Capacitor)
 - **Database Access**: Plugin uses CapacitorSQLite
 - **identity Access**: Can read TimeSafari's active_identity table
 - **Background Tasks**: BGTaskScheduler coordination
 ### Electron
 - **Database Access**: Plugin uses `@capacitor-community/sqlite` + filesystem
 - **identity Access**: Direct file-based database access
 - **Background Tasks**: Electron main process coordination
 ## Security Considerations
 ### activeDid Isolation
 - Plugin should not modify active_identity table
 - Plugin should only read current activeDid
 - Identity changes should be initiated by TimeSafari host application
 ### Token Management
 - JWT tokens should use activeDid for both `iss` and `sub`
 - Token generation should happen in plugin context
 - Host application should not handle authentication tokens
 ### Background Execution
 - Background tasks should validate activeDid hasn't changed
 - Implement cache invalidation when activeDid changes
 - Handle edge cases where activeDid becomes empty/invalid
 ## Implementation Priority
 ### Phase 1: Basic Integration
 1. Host-managed activeDid (Option 1)
 2. Service layer integration
 3. Basic notification scheduling
 ### Phase 2: Enhanced Integration
 1. Hybrid activeDid management (Option 3)
 2. Background database access
 3. Automatic identity synchronization
 ### Phase 3: Advanced Features
 1. Cross-platform optimization
 2. Advanced background task coordination
 3. Performance monitoring and analytics
 ## Success Criteria
 - [ ] Plugin correctly receives activeDid from TimeSafari host
 - [ ] Background notifications work across identity changes
 - [] Cross-platform consistency maintained
 - [ ] Minimal impact on TimeSafari performance
 - [ ] Secure isolation between plugin and host database operations
 ---
 **Status**: Architectural analysis complete - Ready for implementation planning  
 **Next Steps**: Choose integration approach and begin Phase 1 implementation  
 **Dependencies**: TimeSafari active_identity table access, PlatformServiceMixin integration