daily-notification-plugin/docs/host-request-configuration.md

TimeSafari Daily Notification Plugin - Host Request Configuration Guide

Author: Matthew Raymer
Version: 1.0.0
Created: 2025-10-08 06:24:57 UTC

Overview

This guide explains how the TimeSafari PWA host application should configure HTTP requests and network settings for the Daily Notification Plugin. The plugin uses a host-managed request pattern where the host provides network configuration and the plugin handles the actual requests.

Request Configuration Architecture

Plugin Request Pattern

Host Application (TimeSafari PWA)
    ↓ (provides configuration)
Plugin Network Layer
    ↓ (executes requests)
External APIs (Endorser.ch, etc.)

Key Principles

1. Host-Managed Configuration: Host provides all network settings
2. Plugin Execution: Plugin handles actual HTTP requests
3. Structured Logging: All requests are logged with event IDs
4. Circuit Breaker: Built-in failure handling and retry logic
5. ETag Support: Conditional requests for efficient caching

Host Configuration Options

1. Basic Network Configuration

// In TimeSafari PWA main configuration
import { DailyNotification } from '@timesafari/daily-notification-plugin';

await DailyNotification.configure({
  // Basic network settings
  networkConfig: {
    timeout: 30000,           // 30 second timeout
    retryAttempts: 3,         // 3 retry attempts
    retryDelay: 1000,         // 1 second initial delay
    maxConcurrent: 5,         // Max 5 concurrent requests
    userAgent: 'TimeSafari-PWA/1.0.0'
  },
  
  // Request headers
  headers: {
    'Accept': 'application/json',
    'Accept-Language': 'en-US,en;q=0.9',
    'Cache-Control': 'no-cache'
  }
});

2. TimeSafari-Specific Configuration

// TimeSafari Endorser.ch API configuration
await DailyNotification.configure({
  timesafariConfig: {
    // Required: Active DID for authentication
    activeDid: userDid,
    
    // API endpoints (optional - defaults provided)
    endpoints: {
      offersToPerson: 'https://endorser.ch/api/v1/offers/person',
      offersToPlans: 'https://endorser.ch/api/v1/offers/plans',
      projectsLastUpdated: 'https://endorser.ch/api/v1/projects/last-updated'
    },
    
    // Sync configuration
    syncConfig: {
      enableParallel: true,     // Enable parallel API requests
      maxConcurrent: 3,         // Max 3 concurrent requests
      batchSize: 10             // Batch size for requests
    },
    
    // Credential configuration
    credentialConfig: {
      jwtSecret: process.env.JWT_SECRET,
      tokenExpirationMinutes: 60,
      refreshThresholdMinutes: 10
    },
    
    // Error handling policy
    errorPolicy: {
      maxRetries: 3,
      backoffMultiplier: 2,
      activeDidChangeRetries: 5  // Special retry for DID changes
    }
  }
});

3. Content Fetch Configuration

// Configure content fetching
await DailyNotification.configure({
  contentFetch: {
    enabled: true,
    schedule: '0 8 * * *',  // Daily at 8 AM
    
    // Request configuration
    url: 'https://endorser.ch/api/v1/community/updates',
    headers: {
      'Authorization': `Bearer ${authToken}`,
      'X-User-DID': userDid,
      'X-Client-Version': '1.0.0'
    },
    timeout: 15000,
    retryAttempts: 2,
    retryDelay: 2000,
    
    // Callback configuration
    callbacks: {
      apiService: 'https://api.timesafari.com/notifications/callback',
      database: 'local://notification-storage',
      reporting: 'https://analytics.timesafari.com/events'
    },
    
    // Cache policy
    cachePolicy: {
      maxAge: 3600,           // 1 hour cache
      staleWhileRevalidate: 1800,  // 30 minutes stale
      etagSupport: true
    }
  }
});

Platform-Specific Request Configuration

Android Configuration

// Android-specific network configuration
await DailyNotification.configure({
  platform: 'android',
  
  // Android network settings
  androidConfig: {
    // WorkManager constraints
    workManagerConstraints: {
      requiresNetworkType: 'CONNECTED',
      requiresBatteryNotLow: false,
      requiresCharging: false,
      requiresDeviceIdle: false,
      requiresStorageNotLow: false
    },
    
    // Network security
    networkSecurityConfig: {
      cleartextTrafficPermitted: false,
      certificatePinning: true,
      trustedCertificates: ['endorser.ch', 'api.timesafari.com']
    },
    
    // Request configuration
    requestConfig: {
      connectTimeout: 30000,
      readTimeout: 30000,
      writeTimeout: 30000,
      followRedirects: true,
      followSslRedirects: true
    }
  }
});

iOS Configuration

// iOS-specific network configuration
await DailyNotification.configure({
  platform: 'ios',
  
  // iOS network settings
  iosConfig: {
    // Background task configuration
    backgroundTasks: {
      'com.timesafari.daily-notification-fetch': {
        identifier: 'com.timesafari.daily-notification-fetch',
        requiresNetworkConnectivity: true,
        requiresExternalPower: false,
        requiresDeviceIdle: false
      }
    },
    
    // URL session configuration
    urlSessionConfig: {
      timeoutIntervalForRequest: 30,
      timeoutIntervalForResource: 60,
      allowsCellularAccess: true,
      allowsConstrainedNetworkAccess: true,
      allowsExpensiveNetworkAccess: true
    },
    
    // App transport security
    atsConfig: {
      allowsArbitraryLoads: false,
      allowsLocalNetworking: false,
      exceptionDomains: {
        'endorser.ch': {
          nstExceptionAllowsInsecureHTTPLoads: false,
          nstExceptionMinimumTLSVersion: 'TLSv1.2'
        }
      }
    }
  }
});

Electron Configuration

// Electron-specific network configuration
await DailyNotification.configure({
  platform: 'electron',
  
  // Electron network settings
  electronConfig: {
    // Session configuration
    sessionConfig: {
      userAgent: 'TimeSafari-Desktop/1.0.0',
      acceptLanguages: ['en-US', 'en'],
      cacheEnabled: true,
      cacheSize: 100 * 1024 * 1024  // 100MB cache
    },
    
    // Request configuration
    requestConfig: {
      timeout: 30000,
      maxRedirects: 5,
      followRedirects: true,
      validateSSL: true
    },
    
    // Proxy configuration (if needed)
    proxyConfig: {
      enabled: false,
      type: 'http',
      host: '',
      port: 0,
      username: '',
      password: ''
    }
  }
});

Advanced Request Configuration

1. Circuit Breaker Configuration

// Circuit breaker for fault tolerance
await DailyNotification.configure({
  circuitBreaker: {
    failureThreshold: 5,        // Open after 5 failures
    recoveryTimeout: 30000,     // 30 second recovery timeout
    monitoringPeriod: 60000     // 1 minute monitoring period
  }
});

2. Rate Limiting Configuration

// Rate limiting configuration
await DailyNotification.configure({
  rateLimiting: {
    maxRequestsPerMinute: 30,
    maxRequestsPerHour: 1000,
    burstLimit: 10,
    backoffStrategy: 'exponential',
    jitterEnabled: true
  }
});

3. Authentication Configuration

// Authentication configuration
await DailyNotification.configure({
  authentication: {
    // JWT configuration
    jwt: {
      secret: process.env.JWT_SECRET,
      algorithm: 'HS256',
      expirationMinutes: 60,
      refreshThresholdMinutes: 10
    },
    
    // API key configuration
    apiKey: {
      header: 'X-API-Key',
      value: process.env.API_KEY
    },
    
    // OAuth configuration
    oauth: {
      clientId: process.env.OAUTH_CLIENT_ID,
      clientSecret: process.env.OAUTH_CLIENT_SECRET,
      tokenEndpoint: 'https://auth.timesafari.com/oauth/token',
      scope: 'notifications:read notifications:write'
    }
  }
});

Request Monitoring and Observability

1. Structured Logging Configuration

// Configure structured logging
await DailyNotification.configure({
  logging: {
    level: 'INFO',
    enableRequestLogging: true,
    enableResponseLogging: true,
    enableErrorLogging: true,
    enablePerformanceLogging: true,
    
    // Log formatting
    logFormat: 'json',
    includeHeaders: false,      // Don't log sensitive headers
    includeBody: false,         // Don't log request/response bodies
    redactSensitiveData: true
  }
});

2. Metrics Configuration

// Configure metrics collection
await DailyNotification.configure({
  metrics: {
    enabled: true,
    collectionInterval: 60000,  // 1 minute
    
    // Metrics to collect
    requestMetrics: {
      count: true,
      duration: true,
      statusCodes: true,
      errorRates: true
    },
    
    // Performance metrics
    performanceMetrics: {
      cacheHitRate: true,
      networkLatency: true,
      retryCount: true,
      circuitBreakerState: true
    }
  }
});

Error Handling Configuration

1. Retry Configuration

// Retry configuration
await DailyNotification.configure({
  retry: {
    // Exponential backoff
    strategy: 'exponential',
    initialDelay: 1000,        // 1 second
    maxDelay: 30000,           // 30 seconds
    multiplier: 2,
    jitter: true,
    
    // Retry conditions
    retryOn: {
      networkErrors: true,
      timeoutErrors: true,
      serverErrors: true,      // 5xx errors
      clientErrors: false      // Don't retry 4xx errors
    },
    
    // Max retries per request type
    maxRetries: {
      contentFetch: 3,
      notificationDelivery: 2,
      callbackDelivery: 1
    }
  }
});

2. Fallback Configuration

// Fallback configuration
await DailyNotification.configure({
  fallback: {
    // Content fallbacks
    contentFallbacks: [
      {
        condition: 'network_unavailable',
        action: 'use_cached_content',
        maxAge: 3600  // 1 hour
      },
      {
        condition: 'api_error',
        action: 'use_emergency_content',
        content: {
          title: 'TimeSafari Community Update',
          body: 'Check back later for the latest updates!'
        }
      }
    ],
    
    // Notification fallbacks
    notificationFallbacks: [
      {
        condition: 'permission_denied',
        action: 'show_in_app_notification'
      },
      {
        condition: 'platform_unsupported',
        action: 'log_warning'
      }
    ]
  }
});

Security Configuration

1. SSL/TLS Configuration

// SSL/TLS configuration
await DailyNotification.configure({
  security: {
    // Certificate pinning
    certificatePinning: {
      enabled: true,
      pins: [
        {
          hostname: 'endorser.ch',
          pins: [
            'sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=',
            'sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB='
          ]
        }
      ]
    },
    
    // TLS configuration
    tls: {
      minVersion: '1.2',
      maxVersion: '1.3',
      cipherSuites: [
        'TLS_AES_256_GCM_SHA384',
        'TLS_CHACHA20_POLY1305_SHA256',
        'TLS_AES_128_GCM_SHA256'
      ]
    }
  }
});

2. Data Protection Configuration

// Data protection configuration
await DailyNotification.configure({
  dataProtection: {
    // Encryption at rest
    encryption: {
      enabled: true,
      algorithm: 'AES-256-GCM',
      keyDerivation: 'PBKDF2'
    },
    
    // Data redaction
    redaction: {
      enabled: true,
      patterns: [
        'password',
        'token',
        'secret',
        'key',
        'authorization'
      ]
    },
    
    // Data retention
    retention: {
      maxAge: 30 * 24 * 60 * 60 * 1000,  // 30 days
      autoCleanup: true
    }
  }
});

Integration Examples

1. TimeSafari PWA Integration

// In TimeSafari PWA main.ts
import { DailyNotification } from '@timesafari/daily-notification-plugin';
import { TimeSafariIntegrationService } from '@timesafari/daily-notification-plugin';

// Initialize with TimeSafari configuration
const initializeDailyNotifications = async () => {
  try {
    // Configure plugin with TimeSafari settings
    await DailyNotification.configure({
      // Basic configuration
      storage: 'tiered',
      ttlSeconds: 1800,
      enableETagSupport: true,
      
      // TimeSafari-specific configuration
      timesafariConfig: {
        activeDid: userDid,
        endpoints: {
          offersToPerson: 'https://endorser.ch/api/v1/offers/person',
          offersToPlans: 'https://endorser.ch/api/v1/offers/plans'
        },
        syncConfig: {
          enableParallel: true,
          maxConcurrent: 3,
          batchSize: 10
        }
      },
      
      // Network configuration
      networkConfig: {
        timeout: 30000,
        retryAttempts: 3,
        retryDelay: 1000,
        maxConcurrent: 5
      },
      
      // Authentication
      authentication: {
        jwt: {
          secret: process.env.JWT_SECRET,
          algorithm: 'HS256',
          expirationMinutes: 60
        }
      },
      
      // Observability
      logging: {
        level: 'INFO',
        enableRequestLogging: true,
        redactSensitiveData: true
      },
      
      // Security
      security: {
        certificatePinning: {
          enabled: true,
          pins: [
            {
              hostname: 'endorser.ch',
              pins: ['sha256/...']
            }
          ]
        }
      }
    });
    
    // Initialize TimeSafari integration
    const integrationService = TimeSafariIntegrationService.getInstance();
    await integrationService.initialize({
      activeDid: userDid,
      storageAdapter: timeSafariStorageAdapter,
      endorserApiBaseUrl: 'https://endorser.ch/api/v1'
    });
    
    console.log('Daily notifications configured successfully');
    
  } catch (error) {
    console.error('Failed to configure daily notifications:', error);
  }
};

// Initialize on app startup
initializeDailyNotifications();

2. Vue.js Component Integration

// In TimeSafari PWA Vue component
import { defineComponent } from 'vue';
import { DailyNotification } from '@timesafari/daily-notification-plugin';

export default defineComponent({
  name: 'DailyNotificationSettings',
  
  async mounted() {
    // Configure notifications for this component
    await DailyNotification.configure({
      // Component-specific configuration
      contentFetch: {
        enabled: true,
        schedule: '0 9 * * *',  // 9 AM daily
        url: 'https://endorser.ch/api/v1/community/updates',
        headers: {
          'Authorization': `Bearer ${this.authToken}`,
          'X-User-DID': this.userDid
        },
        callbacks: {
          onSuccess: async (data) => {
            // Handle successful fetch
            this.updateNotificationContent(data);
          },
          onError: async (error) => {
            // Handle fetch error
            this.handleNotificationError(error);
          }
        }
      }
    });
  },
  
  methods: {
    async updateNotificationContent(data: Record<string, unknown>) {
      // Update UI with new content
      this.notificationData = data;
    },
    
    async handleNotificationError(error: Error) {
      // Handle error in UI
      this.showError(error.message);
    }
  }
});

Troubleshooting

Common Configuration Issues

1. Network Timeout Issues

// Increase timeout for slow networks
await DailyNotification.configure({
  networkConfig: {
    timeout: 60000,  // 60 seconds
    retryAttempts: 5,
    retryDelay: 2000
  }
});

2. Authentication Issues

// Debug authentication
await DailyNotification.configure({
  logging: {
    level: 'DEBUG',
    enableRequestLogging: true,
    includeHeaders: true  // Temporarily enable for debugging
  }
});

3. Certificate Issues

// Disable certificate pinning for development
await DailyNotification.configure({
  security: {
    certificatePinning: {
      enabled: false  // Only for development
    }
  }
});

Debugging Request Issues

1. Enable Debug Logging

// Enable comprehensive logging
await DailyNotification.configure({
  logging: {
    level: 'DEBUG',
    enableRequestLogging: true,
    enableResponseLogging: true,
    enableErrorLogging: true,
    enablePerformanceLogging: true
  }
});

2. Monitor Request Metrics

// Get request statistics
const stats = await DailyNotification.getRequestStats();
console.log('Request Statistics:', stats);

// Get error statistics
const errors = await DailyNotification.getErrorStats();
console.log('Error Statistics:', errors);

Best Practices

1. Configuration Management

• Environment Variables: Use environment variables for sensitive data
• Configuration Validation: Validate configuration on startup
• Graceful Degradation: Provide fallbacks for missing configuration
• Configuration Updates: Support runtime configuration updates

2. Security Best Practices

• Certificate Pinning: Enable for production environments
• Data Redaction: Always redact sensitive data in logs
• Token Management: Use secure token storage and rotation
• Network Security: Use HTTPS for all requests

3. Performance Best Practices

• Connection Pooling: Reuse HTTP connections
• Request Batching: Batch multiple requests when possible
• Caching: Use ETag support for efficient caching
• Rate Limiting: Implement appropriate rate limits

4. Monitoring Best Practices

• Structured Logging: Use structured logs with event IDs
• Metrics Collection: Collect relevant performance metrics
• Error Tracking: Track and analyze error patterns
• Health Checks: Implement health check endpoints

---

Note: This configuration guide should be updated as the plugin evolves. Regular review and updates are recommended to ensure accuracy and completeness.