daily-notification-plugin/docs/INTEGRATION_REFACTOR_CONTEXT.md

Integration Point Refactor - Implementation Context

Author: Matthew Raymer
Date: 2025-10-29
Status: 🎯 CONTEXT - Pre-implementation analysis and mapping

Purpose

This document maps the current codebase to the Integration Point Refactor plan, identifies what exists, what needs to be created, and where gaps exist before starting implementation (PR1).

---

Current State Analysis

✅ What Already Exists

1. TypeScript Type Definitions (src/types/content-fetcher.ts)

• ✅ NotificationContent interface (matches directive spec)
• ✅ FetchContext interface (matches directive spec)
• ✅ JsNotificationContentFetcher interface (matches directive spec)
• ✅ FetchTrigger type (matches directive spec)
• ✅ SchedulingPolicy interface (matches directive spec)

Status: Complete and ready for PR1. No changes needed.

2. Example Implementations

• ✅ examples/native-fetcher-android.kt - Kotlin native fetcher skeleton
• ✅ examples/js-fetcher-typescript.ts - TypeScript JS fetcher skeleton

Status: Examples exist as reference. These are for host app, not plugin.

3. Test Contract (tests/fixtures/test-contract.json)

• ✅ Golden contract fixture with expected outputs
• ✅ Failure scenarios defined

Status: Ready for contract tests. Will be used in PR2+ for validation.

4. Current TimeSafari Integration (To Be Replaced)

Location: android/plugin/src/main/java/com/timesafari/dailynotification/

• ✅ TimeSafariIntegrationManager.java - Current TimeSafari orchestration
• ✅ EnhancedDailyNotificationFetcher.java - TimeSafari API client
• ✅ DailyNotificationJWTManager.java - JWT generation for TimeSafari
• ✅ DailyNotificationETagManager.java - ETag caching for TimeSafari

Status: These will be moved to host app OR deprecated behind feature flag (PR7).

Current Integration Flow:

DailyNotificationPlugin.load()
  → TimeSafariIntegrationManager (created in plugin)
    → EnhancedDailyNotificationFetcher
      → JWTManager + ETagManager
        → TimeSafari API endpoints

Target Flow (after refactor):

DailyNotificationPlugin.load()
  → NativeNotificationContentFetcher (registered by host app)
    → Host app's TimeSafari integration
      → TimeSafari API endpoints

---

What Needs to Be Created

PR1: SPI Shell (First Implementation)

1. Android Native SPI Interface

Location: android/plugin/src/main/java/com/timesafari/dailynotification/

File to Create: NativeNotificationContentFetcher.java

package com.timesafari.dailynotification;

public interface NativeNotificationContentFetcher {
    java.util.concurrent.CompletableFuture<java.util.List<NotificationContent>> 
        fetchContent(FetchContext context);
}

public class FetchContext {
    public final String trigger; // "background_work" | "prefetch" | "manual" | "scheduled"
    public final Long scheduledTime; // Optional: epoch ms
    public final long fetchTime; // Required: epoch ms
    public final Map<String, Object> metadata; // Optional
    
    // Constructor, getters...
}

Status: ❌ Not created yet - PR1 task

2. Fetcher Registry in Plugin

Location: android/plugin/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.java

What to Add:

• Field: private NativeNotificationContentFetcher nativeFetcher;
• Method: public void setNativeFetcher(NativeNotificationContentFetcher fetcher)
• Storage: Store in static registry or application-level singleton

Status: ❌ Not implemented yet - PR1 task

3. SchedulingPolicy Implementation (Android)

Location: android/plugin/src/main/java/com/timesafari/dailynotification/

File to Create: SchedulingPolicy.java

public class SchedulingPolicy {
    public Long prefetchWindowMs;
    public RetryBackoff retryBackoff;
    public Integer maxBatchSize;
    public Long dedupeHorizonMs;
    public Integer cacheTtlSeconds;
    public Boolean exactAlarmsAllowed;
    
    public static class RetryBackoff {
        public long minMs;
        public long maxMs;
        public double factor;
        public int jitterPct;
    }
}

Status: ❌ Not created yet - PR1 task

Where Used:

• DailyNotificationFetchWorker - backoff policy
• DailyNotificationScheduler - prefetch timing
• Deduplication logic (new, PR4)
• TTL enforcement (existing DailyNotificationTTLEnforcer)

4. Plugin API Methods (TypeScript Bridge)

Location: android/plugin/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.java

Methods to Add:

@PluginMethod
public void setJsContentFetcher(PluginCall call) {
    // Store JS fetcher for foreground use
    // Will be called from TypeScript
}

@PluginMethod  
public void enableNativeFetcher(PluginCall call) {
    // Toggle native fetcher on/off
    // Default: true (native required for background)
}

@PluginMethod
public void setPolicy(PluginCall call) {
    // Update SchedulingPolicy
    // Parse JSON from call, create SchedulingPolicy instance
}

Status: ❌ Not implemented yet - PR1 task

5. TypeScript Plugin Interface Extensions

Location: src/definitions.ts

What to Add:

export interface DailyNotificationPlugin {
  // ... existing methods ...
  
  setJsContentFetcher(fetcher: JsNotificationContentFetcher): void;
  enableNativeFetcher(enable: boolean): Promise<void>;
  setPolicy(policy: SchedulingPolicy): Promise<void>;
}

Status: ❌ Partially exists in src/types/content-fetcher.ts but not wired to DailyNotificationPlugin interface in src/definitions.ts - PR1 task

---

PR2: Background Workers

Current Worker: DailyNotificationFetchWorker.java

Location: android/plugin/src/main/java/com/timesafari/dailynotification/DailyNotificationFetchWorker.java

Current Behavior:

• Uses DailyNotificationFetcher (generic, no TimeSafari)
• Called from DailyNotificationFetcher.scheduleFetch()
• Runs via WorkManager

What Needs to Change:

1. Remove TimeSafari-Specific Coordination:

   // Remove these lines (79-92):
   boolean timesafariCoordination = inputData.getBoolean("timesafari_coordination", false);
   // ... coordination checks ...
   

2. Add Native Fetcher Call:

   private NotificationContent fetchContentWithTimeout() {
       if (nativeFetcher == null) {
           Log.w(TAG, "Native fetcher not registered, falling back to cache");
           return getCachedContent();
       }
   
       FetchContext context = new FetchContext(
           "background_work",
           scheduledTime,
           System.currentTimeMillis(),
           metadata
       );
   
       try {
           List<NotificationContent> results = 
               nativeFetcher.fetchContent(context)
                   .get(30, TimeUnit.SECONDS);
           return results.isEmpty() ? null : results.get(0);
       } catch (Exception e) {
           // Handle timeout, errors
           return null;
       }
   }
   

3. Add SchedulingPolicy Backoff:

   • Use SchedulingPolicy.retryBackoff for retry delays
   • Replace hardcoded retry logic

Status: ❌ Not modified yet - PR2 task

---

PR3: JS Fetcher Path

Plugin Side: Bridge JS Fetcher to Workers

Location: android/plugin/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.java

What Needs to Change:

1. Store JS Fetcher Reference:

   private JsNotificationContentFetcher jsFetcher; // Wrapper object needed
   
   @PluginMethod
   public void setJsContentFetcher(PluginCall call) {
       // Extract callback from JS
       // Store for foreground use only
       // Log warning if used in background worker
   }
   

2. Foreground Fetch Method:

   @PluginMethod
   public void refreshNow(PluginCall call) {
       if (jsFetcher != null) {
           // Call JS fetcher (foreground only)
           // Must bridge JS callback to Java
       } else if (nativeFetcher != null) {
           // Fall back to native fetcher
       }
   }
   

Challenge: JavaScript → Java callback bridge. Options:

• Option A: Use Capacitor's bridge to call JS function
• Option B: Use event system (plugin emits event, JS responds)
• Option C: Store fetcher config, not callback (requires HTTP endpoint)

Status: ❌ Not implemented yet - PR3 task

---

PR4: Deduplication

New Component: Deduplication Store

Location: android/plugin/src/main/java/com/timesafari/dailynotification/

File to Create: NotificationDeduplicationStore.java

Responsibilities:

• Maintain bloom filter or LRU cache of recent dedupeKey values
• Check dedupeHorizonMs window
• Prevent duplicate notifications within horizon
• Use dedupeKey (fallback to id)

Integration Points:

• DailyNotificationScheduler.scheduleNotification() - check before scheduling
• DailyNotificationFetchWorker.doWork() - check after fetch

Status: ❌ Not created yet - PR4 task

---

PR5: Failure Policy

Enhance Existing Components

Location: Multiple files

1. Retry Logic (DailyNotificationFetchWorker.java):

• Replace hardcoded retry with SchedulingPolicy.retryBackoff
• Implement exponential backoff with jitter
• Distinguish retryable vs unretryable errors

2. Cache Fallback (new or enhance DailyNotificationStorage.java):

• Check TTL using SchedulingPolicy.cacheTtlSeconds or item ttlSeconds
• Fallback to cached content if fetch fails and cache valid

3. Error Classification:

public enum FetchErrorType {
    RETRYABLE,    // 5xx, network, timeout
    UNRETRYABLE,  // 4xx auth, schema error
    PARTIAL,      // Some items bad
    OVER_QUOTA    // 429 with Retry-After
}

Status: ❌ Partially implemented (basic retry exists), needs enhancement - PR5 task

---

Component Dependency Map

Current Dependencies

DailyNotificationPlugin
  ├── TimeSafariIntegrationManager (TO BE REMOVED in PR7)
  │   ├── EnhancedDailyNotificationFetcher (TO BE MOVED to host app)
  │   ├── DailyNotificationJWTManager (TO BE MOVED to host app)
  │   └── DailyNotificationETagManager (TO BE MOVED to host app)
  ├── DailyNotificationScheduler
  │   ├── DailyNotificationTTLEnforcer
  │   └── PendingIntentManager
  ├── DailyNotificationFetchWorker
  │   └── DailyNotificationFetcher (generic, keep)
  └── DailyNotificationStorage

Target Dependencies (After Refactor)

DailyNotificationPlugin
  ├── NativeNotificationContentFetcher (REGISTERED by host app)
  ├── JsNotificationContentFetcher (REGISTERED by host app, foreground only)
  ├── SchedulingPolicy (CONFIGURED by host app)
  ├── DailyNotificationScheduler
  │   ├── DailyNotificationTTLEnforcer
  │   ├── PendingIntentManager
  │   └── NotificationDeduplicationStore (NEW in PR4)
  ├── DailyNotificationFetchWorker
  │   ├── Calls NativeNotificationContentFetcher (native path)
  │   └── Uses SchedulingPolicy (backoff, TTL)
  └── DailyNotificationStorage

---

Integration Points to Identify

1. Worker Enqueue Points

Where Workers Are Scheduled:

1. DailyNotificationFetcher.scheduleFetch() (line ~77-116):

   • Enqueues DailyNotificationFetchWorker
   • Currently generic (no TimeSafari coupling)

2. TimeSafariIntegrationManager.fetchAndScheduleFromServer() (line ~258):

   • May enqueue workers with TimeSafari coordination flags
   • Needs to switch to native fetcher path

3. DailyNotificationPlugin.scheduleCoordinatedBackgroundJobs():

   • Phase 3 coordination code
   • Adds TimeSafari-specific flags to WorkManager Data
   • Needs refactor to remove TimeSafari flags

Action for PR2: Modify worker enqueue to use native fetcher, remove TimeSafari coordination flags.

---

2. Notification Content Flow

Current Flow:

EnhancedDailyNotificationFetcher.fetch()
  → Returns TimeSafariNotificationBundle
    → TimeSafariIntegrationManager.convertBundleToNotificationContent()
      → Returns List<NotificationContent>
        → DailyNotificationScheduler.scheduleNotification()

Target Flow:

NativeNotificationContentFetcher.fetchContent(context)
  → Returns List<NotificationContent> (already generic)
    → DailyNotificationScheduler.scheduleNotification()

Gap: convertBundleToNotificationContent() logic must move to host app (PR7).

---

3. TTL Enforcement Points

Current TTL Flow:

1. Hard-Fail at Arming: ->DailyNotificationScheduler.scheduleNotification()

   • Calls ttlEnforcer.validateBeforeArming(content)
   • ✅ Already generic (works with any NotificationContent)

2. Soft-Check at Fire: DailyNotificationReceiver.onReceive()

   • Checks freshness, may trigger refresh
   • ✅ Already generic

Status: ✅ TTL enforcement is already generic - no changes needed for SPI.

---

4. Metrics Collection Points

Current Metrics:

• src/observability.ts - TypeScript observability
• packages/polling-contracts/src/telemetry.ts - Telemetry manager

What to Add:

• fetch_duration_ms - Time for native fetcher to complete
• fetch_success - Boolean success/failure
• fetch_fail_class - Error classification (retryable/unretryable/partial/over-quota)
• items_fetched - Number of items from fetcher
• items_enqueued - Number successfully scheduled
• deduped_count - Items filtered by deduplication (PR4)
• cache_hits - Cached content used when fetch fails (PR5)

Action for PR2: Add metrics calls in DailyNotificationFetchWorker.doWork().

---

Migration Path Mapping

Feature Flag Implementation (PR7)

Location: DailyNotificationPlugin.java

What to Add:

private static final boolean USE_LEGACY_INTEGRATION = false; // Default false in new minor

private void fetchContent() {
    if (USE_LEGACY_INTEGRATION && timeSafariIntegration != null) {
        // Legacy path
        timeSafariIntegration.fetchAndScheduleFromServer(false);
    } else if (nativeFetcher != null) {
        // New SPI path
        // Call native fetcher
    } else {
        Log.w(TAG, "No fetcher available");
    }
}

Files to Guard:

• TimeSafariIntegrationManager.java - Keep for one minor release
• EnhancedDailyNotificationFetcher.java - Keep for one minor release
• Legacy @PluginMethod wrappers - Deprecate, keep for compatibility

---

File Creation Checklist

PR1: SPI Shell

• android/plugin/src/main/java/com/timesafari/dailynotification/NativeNotificationContentFetcher.java
• android/plugin/src/main/java/com/timesafari/dailynotification/FetchContext.java (or inner class)
• android/plugin/src/main/java/com/timesafari/dailynotification/SchedulingPolicy.java
• Update DailyNotificationPlugin.java:
  • Add setNativeFetcher() method
  • Add setJsContentFetcher() method (stub, full in PR3)
  • Add enableNativeFetcher() method
  • Add setPolicy() method
• Update src/definitions.ts:
  • Wire SchedulingPolicy from content-fetcher.ts
  • Add new methods to DailyNotificationPlugin interface

PR2: Background Workers

• Modify DailyNotificationFetchWorker.java:
  • Remove TimeSafari coordination checks
  • Add native fetcher call
  • Add SchedulingPolicy backoff
  • Add metrics recording

PR3: JS Fetcher Path

• Modify DailyNotificationPlugin.java:
  • Implement setJsContentFetcher() (JS bridge)
  • Add foreground refresh method
  • Add event bus for JS communication
• Create TypeScript bridge utilities

PR4: Deduplication

• android/plugin/src/main/java/com/timesafari/dailynotification/NotificationDeduplicationStore.java
• Integrate into DailyNotificationScheduler
• Add metrics for deduped count

PR5: Failure Policy

• Create FetchErrorType enum
• Enhance retry logic with SchedulingPolicy
• Add cache fallback mechanism
• Add error classification helpers

PR6: Docs & Samples

• INTEGRATION_GUIDE.md - When to use native vs JS fetcher
• SCHEDULING_POLICY.md - All configuration knobs
• Update examples with real registration code

PR7: Feature Flag Legacy

• Add USE_LEGACY_INTEGRATION flag
• Guard all TimeSafari code paths
• Update migration guide
• Regression tests

---

Open Questions to Resolve

Before PR1

1. Fetcher Registration Pattern:

   • Should setNativeFetcher() be called from host app's Application.onCreate()?
   • Or should it be a static registry accessible from host app's native code?
   • Recommendation: Static registry in plugin, host app registers in Application.onCreate()

2. FetchContext Metadata:

   • What should plugin populate in metadata map?
   • Current activeDid? App state? Network state?
   • Recommendation: Start minimal (empty map), extend later

Before PR2

3. Background Worker Timeout:

   • Current: 30 seconds for fetch
   • Should this be configurable in SchedulingPolicy?
   • Recommendation: Add fetchTimeoutMs to SchedulingPolicy in PR1

4. Multiple NotificationContent Handling:

   • If native fetcher returns multiple items, should all be scheduled?
   • Should maxBatchSize apply here?
   • Recommendation: Schedule all valid items, maxBatchSize limits fetcher input/API calls

Before PR3

5. JS Fetcher Bridge Mechanism:

   • Which approach: Capacitor bridge callback, event system, or HTTP endpoint?
   • Recommendation: Start with event system (plugin emits fetch_needed, JS responds via setJsContentFetcher callback)

6. Foreground-Only Enforcement:

   • How to prevent JS fetcher from being called in background worker?
   • Recommendation: Runtime guard + lint rule (document in PR3)

---

Testing Strategy

Contract Tests (After PR2)

• Use tests/fixtures/test-contract.json
• Run native fetcher with fixture context
• Compare normalized output to expected output
• Location: Create android/plugin/src/test/java/com/timesafari/dailynotification/NativeFetcherContractTest.java

Integration Tests (After PR3)

• Test JS fetcher in foreground
• Test native fetcher in background worker
• Verify both produce identical results for same input

Regression Tests (Before PR7)

• Ensure legacy TimeSafari path still works behind feature flag
• Verify new SPI path works independently
• Test migration from legacy to SPI path

---

Next Steps

1. Review this context document - Verify completeness
2. Resolve open questions - Make decisions before PR1
3. Create PR1 branch - Start with SPI shell implementation
4. Reference examples - Use examples/native-fetcher-android.kt as pattern
5. Follow 7-PR plan - Sequential implementation with tests after each PR

---

Status: Context building complete - ready for PR1 implementation
Last Updated: 2025-10-29
Maintainer: Plugin development team