daily-notification-plugin/docs/integration/REFACTOR_NOTES_QUICK_START.md

Integration Point Refactor - Quick Start Guide

Author: Matthew Raymer
Date: 2025-10-29
Status: 🎯 REFERENCE - Quick start for implementation on any machine

See also: REFACTOR_ANALYSIS.md for complete analysis | REFACTOR_NOTES.md for implementation context

Overview

This guide helps you get started implementing the Integration Point Refactor on any machine. All planning and specifications are documented in the codebase.

Key Documents

1. docs/integration-point-refactor-analysis.md - Complete analysis + improvement directive

   • Architecture decisions (ADR-001)
   • Public interfaces (TypeScript + Kotlin)
   • Migration plan (7 PRs)
   • Acceptance criteria
   • Risk register

2. src/types/content-fetcher.ts - TypeScript type definitions

   • NotificationContent interface
   • JsNotificationContentFetcher interface
   • SchedulingPolicy interface
   • FetchContext interface

3. examples/native-fetcher-android.kt - Kotlin native fetcher skeleton

   • Complete example implementation
   • Registration pattern
   • Error handling

4. examples/js-fetcher-typescript.ts - TypeScript JS fetcher skeleton

   • Foreground fetcher implementation
   • Policy configuration example

5. tests/fixtures/test-contract.json - Golden test contract

   • Shared fixture for both JS and Native fetchers
   • Failure scenarios

Implementation Roadmap (7 PRs)

PR1 — SPI Shell

Status: Ready to start Files to create:

• Kotlin/Swift interface definitions
• TypeScript types (already in src/types/content-fetcher.ts)
• SchedulingPolicy implementation (plugin side)
• No behavior change yet

Reference: Section B in analysis doc

PR2 — Background Workers

Status: After PR1 Tasks:

• Wire Native SPI in WorkManager/BGTasks
• Metrics skeleton
• Cache store

Reference: Section C1 (Background Reliability)

PR3 — JS Fetcher Path

Status: After PR2 Tasks:

• Foreground bridge
• Event bus
• Dev harness screen

Reference: Section B1 (TypeScript interfaces)

PR4 — Dedupe/Idempotency

Status: After PR3 Tasks:

• Bloom/filter store
• dedupeKey enforcement
• Tests

Reference: Section C3 (Idempotency & De-duplication)

PR5 — Failure Policy

Status: After PR4 Tasks:

• Retry taxonomy (Section E)
• Backoff implementation
• Cache fallback
• Structured errors

PR6 — Docs & Samples

Status: After PR5 Tasks:

• INTEGRATION_GUIDE.md (when to use which fetcher)
• SCHEDULING_POLICY.md (all configuration knobs)
• Copy-paste snippets

PR7 — Feature Flag Legacy

Status: After PR6 Tasks:

• Guard legacy TimeSafari code behind flag
• Regression tests
• Changelog for major removal

Reference: Section H (Migration Plan)

Architecture Decisions

ADR-001: Dual-Path SPI

• Native Fetcher (Kotlin/Swift) - Required for background
• JS Fetcher (TypeScript) - Optional, foreground only
• Legacy code behind feature flag for one minor release

See: Section A in analysis doc

Interface Contracts

TypeScript (Host App)

// From src/types/content-fetcher.ts
interface JsNotificationContentFetcher {
  fetchContent(context: FetchContext): Promise<NotificationContent[]>;
}

// Plugin API additions
interface DailyNotificationPlugin {
  setJsContentFetcher(fetcher: JsNotificationContentFetcher): void;
  enableNativeFetcher(enable: boolean): Promise<void>;
  setPolicy(policy: SchedulingPolicy): Promise<void>;
}

Android SPI (Native)

interface NativeNotificationContentFetcher {
    suspend fun fetchContent(context: FetchContext): List<NotificationContent>
}

See: Section B in analysis doc

Key Constraints

Background Workers

• Android: WorkManager - NO JS bridging, native SPI only
• iOS: BGAppRefreshTask/BGProcessingTask - native SPI only
• Tasks: Keep < 30s, respect backoff

Security

• JWT generation in host app only
• No TimeSafari DTOs in plugin
• Tokens never serialized through JS in background

Deduplication

• Use dedupeKey (fallback id)
• Bloom/filter for recent keys
• Horizon: dedupeHorizonMs (default 24h)

See: Sections C, D in analysis doc

Failure Handling

Class	Examples	Behavior
Retryable	5xx, network, timeout	Backoff per policy
Unretryable	4xx auth, schema error	Log, skip batch
Partial	Some items bad	Enqueue valid subset
Over-quota	429	Honor Retry-After

See: Section E in analysis doc

Testing Requirements

Golden Contract

• Single JSON fixture (tests/fixtures/test-contract.json)
• Run through both JS and Native fetchers
• Compare normalized outputs
• Contract tests must pass

Failure Scenarios

• Network chaos (drop, latency)
• 401 → refresh → 200
• 429 with Retry-After
• Malformed items (skip, don't crash)

See: Section G in analysis doc

Acceptance Criteria

Before considering this complete:

• ✅ Native fetcher runs with app killed
• ✅ JS fetcher never required for background
• ✅ Same inputs → same outputs (parity tests green)
• ✅ No TimeSafari imports/types in plugin
• ✅ No duplicate notifications within dedupeHorizonMs
• ✅ Metrics visible, error classes distinguished
• ✅ Docs include copy-paste snippets
• ✅ Battery/quotas respected

See: Section J in analysis doc

Open Questions (Resolve Before PR3)

1. iOS capabilities: Which BG task identifiers/intervals acceptable?
2. Token hardening: DPoP or JWE now or later?
3. User controls: Per-plan snooze/mute in metadata?

See: Section K in analysis doc

Getting Started Checklist

When starting on a new machine:

• Read docs/integration-point-refactor-analysis.md (full context)
• Review src/types/content-fetcher.ts (TypeScript interfaces)
• Review examples/native-fetcher-android.kt (Kotlin pattern)
• Review examples/js-fetcher-typescript.ts (JS pattern)
• Review tests/fixtures/test-contract.json (test contract)
• Start with PR1 - SPI Shell (no behavior change)
• Follow 7-PR plan sequentially
• Run contract tests after each PR

File Locations

docs/
  integration-point-refactor-analysis.md  # Complete spec
  INTEGRATION_REFACTOR_QUICK_START.md     # This file

src/types/
  content-fetcher.ts                       # TypeScript interfaces

examples/
  native-fetcher-android.kt                # Kotlin example
  js-fetcher-typescript.ts                 # TypeScript example

tests/fixtures/
  test-contract.json                       # Golden contract

Next Actions

1. Start PR1 (SPI Shell)

   • Create Kotlin interface in plugin
   • Create Swift interface (if iOS support needed)
   • Wire up TypeScript types (already done)
   • Add SchedulingPolicy to plugin

2. Review examples before implementing

   • Understand data flow
   • See error handling patterns
   • Note registration points

3. Plan testing early

   • Set up contract test infrastructure
   • Prepare mock fetchers for testing

Questions?

All specifications are in docs/integration-point-refactor-analysis.md. Refer to:

• Section B for interfaces
• Section C for policies
• Section E for failure handling
• Section I for PR breakdown
• Section J for acceptance criteria

---

Status: Reference guide Last Updated: 2025-10-29 Maintainer: Plugin development team