trent_larson/daily-notification-plugin
4
0
Fork 0
Code Issues Pull Requests 2 Projects Releases Wiki Activity

docs(refactor): add integration point refactor analysis and implementation plan

Browse Source 
Add comprehensive documentation and implementation artifacts for refactoring
the plugin to use app-provided content fetchers instead of hardcoded TimeSafari
integration.

Changes:
- Add integration-point-refactor-analysis.md with complete ADR, interfaces,
  migration plan, and 7-PR breakdown
- Add INTEGRATION_REFACTOR_QUICK_START.md for quick reference on new machines
- Add src/types/content-fetcher.ts with TypeScript SPI interfaces
- Add examples/native-fetcher-android.kt with Kotlin implementation skeleton
- Add examples/js-fetcher-typescript.ts with TypeScript implementation skeleton
- Add tests/fixtures/test-contract.json for golden contract testing

Architecture Decisions:
- Dual-path SPI: Native Fetcher (background) + JS Fetcher (foreground only)
- Background reliability: Native SPI only, no JS bridging in workers
- Reversibility: Legacy code behind feature flag for one minor release
- Test contract: Single JSON fixture for both fetcher paths

This provides complete specification for implementing the refactor in 7 PRs,
starting with SPI shell and progressing through background workers, deduplication,
failure policies, and finally legacy code removal.

All documentation is self-contained and ready for implementation on any machine.
This commit is contained in:
Matthew Raymer
2025-10-29 13:04:49 +00:00
parent ed5dcfbbd1
commit e83b1518d7
6 changed files with 1635 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
docs/INTEGRATION_REFACTOR_QUICK_START.md Normal file
View File

@@ -0,0 +1,268 @@
# Integration Point Refactor - Quick Start Guide
**Author**: Matthew Raymer
**Date**: 2025-10-29
**Status**: 🎯 **REFERENCE** - Quick start for implementation on any machine
## 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)
```typescript
// 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)
```kotlin
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

853
docs/integration-point-refactor-analysis.md Normal file
View File

@@ -0,0 +1,853 @@
# Integration Point Refactor Analysis
**Author**: Matthew Raymer
**Date**: 2025-10-29
**Status**: 🎯 **ANALYSIS** - Architectural refactoring proposal
## Objective
Refactor the Daily Notification Plugin architecture so that **TimeSafari-specific integration logic is implemented by the Capacitor host app** rather than hardcoded in the plugin. This makes the plugin generic and reusable for other applications.
## Current Architecture
### Plugin-Side Integration (Current State)
The plugin currently contains TimeSafari-specific code:
1. **`TimeSafariIntegrationManager.java`**
- Manages API server URL and DID lifecycle
- Coordinates fetching and scheduling
- Converts TimeSafari data to `NotificationContent`
2. **`EnhancedDailyNotificationFetcher.java`**
- Makes HTTP calls to TimeSafari API endpoints:
- `POST /api/v2/offers/person`
- `POST /api/v2/offers/plans`
- `POST /api/v2/report/plansLastUpdatedBetween`
- Handles JWT authentication
- Parses TimeSafari response formats
3. **`DailyNotificationJWTManager.java`**
- Generates JWT tokens for TimeSafari API authentication
- Manages JWT expiration and refresh
4. **TimeSafari Data Models**
- Plugin imports `PlanSummary`, `OffersResponse`, `TimeSafariNotificationBundle`
- Converts TimeSafari data structures to `NotificationContent[]`
### Current Data Flow
```
Host App (Capacitor)
↓ configure() with activeDidIntegration config
Plugin (DailyNotificationPlugin)
↓ initializes TimeSafariIntegrationManager
TimeSafariIntegrationManager
↓ creates EnhancedDailyNotificationFetcher
EnhancedDailyNotificationFetcher
↓ makes HTTP calls with JWT
TimeSafari API Server
↓ returns TimeSafariNotificationBundle
EnhancedDailyNotificationFetcher
↓ converts to NotificationContent[]
TimeSafariIntegrationManager
↓ saves & schedules
Plugin Storage & Scheduler
```
## Proposed Architecture
### App-Side Integration (Target State)
The plugin becomes a **generic notification scheduler** that accepts a **content fetcher callback** from the host app:
1. **Plugin exposes interface** for content fetching
2. **Host app implements** the TimeSafari API integration
3. **Plugin calls app's implementation** when fetching is needed
4. **Plugin remains generic** - no TimeSafari-specific code
### Proposed Data Flow
```
Host App (Capacitor)
↓ implements ContentFetcher interface
↓ provides fetcher callback to plugin
Plugin (DailyNotificationPlugin)
↓ calls app's fetcher callback
Host App's TimeSafari Integration
↓ makes HTTP calls, handles JWT, parses responses
TimeSafari API Server
↓ returns TimeSafariNotificationBundle
Host App's Integration
↓ converts to NotificationContent[]
↓ returns to plugin
Plugin
↓ saves & schedules (no TimeSafari knowledge)
Plugin Storage & Scheduler
```
## What Needs to Change
### 1. Plugin Interface Changes
#### New TypeScript Interface
```typescript
/**
* Content fetcher callback that host app must implement
*/
export interface NotificationContentFetcher {
/**
* Fetch notification content from external source
*
* This is called by the plugin when:
* - Background fetch work is triggered
* - Prefetch is scheduled before notification time
* - Manual refresh is requested
*
* @param context Context about why fetch was triggered
* @returns Promise with notification content array
*/
fetchContent(context: FetchContext): Promise<NotificationContent[]>;
}
export interface FetchContext {
/**
* Why the fetch was triggered
*/
trigger: 'background_work' | 'prefetch' | 'manual' | 'scheduled';
/**
* Scheduled notification time (millis since epoch)
*/
scheduledTime?: number;
/**
* When fetch was triggered (millis since epoch)
*/
fetchTime: number;
/**
* Any additional context from plugin
*/
metadata?: Record<string, unknown>;
}
```
#### New Plugin Method
```typescript
export interface DailyNotificationPlugin {
// ... existing methods ...
/**
* Register content fetcher callback from host app
*
* @param fetcher Implementation provided by host app
*/
setContentFetcher(fetcher: NotificationContentFetcher): void;
}
```
### 2. Android Plugin Changes
#### New Java Interface
```java
/**
* Content fetcher interface for host app to implement
*/
public interface NotificationContentFetcher {
/**
* Fetch notification content from external source
*
* Called by plugin when background fetch is needed.
* Host app implements TimeSafari API calls here.
*
* @param context Fetch context with trigger info
* @return Future with list of notification content
*/
CompletableFuture<List<NotificationContent>> fetchContent(
FetchContext context
);
}
public class FetchContext {
public final String trigger; // "background_work", "prefetch", "manual", "scheduled"
public final Long scheduledTime; // Optional: when notification is scheduled
public final long fetchTime; // When fetch was triggered
public final Map<String, Object> metadata; // Additional context
// Constructor, getters...
}
```
#### Plugin Implementation
```java
public class DailyNotificationPlugin extends Plugin {
private @Nullable NotificationContentFetcher contentFetcher;
@PluginMethod
public void setContentFetcher(PluginCall call) {
// Receive callback reference from JavaScript
// Store for use in background workers
// Implementation depends on how to bridge JS -> Java callback
}
// In DailyNotificationFetchWorker:
private NotificationContent fetchContentWithTimeout() {
if (contentFetcher == null) {
// Fallback: return null, use cached content
return null;
}
FetchContext context = new FetchContext(
"background_work",
scheduledTime,
System.currentTimeMillis(),
metadata
);
try {
List<NotificationContent> results =
contentFetcher.fetchContent(context).get(30, TimeUnit.SECONDS);
return results.isEmpty() ? null : results.get(0);
} catch (Exception e) {
// Handle timeout, errors
return null;
}
}
}
```
### 3. What Gets Removed from Plugin
#### Delete These Classes:
- `TimeSafariIntegrationManager.java` - Move logic to host app
- `EnhancedDailyNotificationFetcher.java` - Move to host app
- TimeSafari-specific data model imports
#### Keep These (Generic):
- `DailyNotificationStorage` - Generic storage
- `DailyNotificationScheduler` - Generic scheduling
- `DailyNotificationPlugin` - Core plugin (modified)
- `DailyNotificationFetchWorker` - Modified to call callback
- `NotificationContent` - Generic data model
### 4. Host App Implementation
#### TypeScript Implementation
```typescript
import { DailyNotification, NotificationContentFetcher, FetchContext }
from '@timesafari/daily-notification-plugin';
import { TimeSafariAPI } from './timesafari-api'; // Host app's API client
class TimeSafariContentFetcher implements NotificationContentFetcher {
constructor(
private api: TimeSafariAPI,
private activeDid: string
) {}
async fetchContent(context: FetchContext): Promise<NotificationContent[]> {
// 1. Generate JWT for authentication
const jwt = await this.api.generateJWT(this.activeDid);
// 2. Fetch TimeSafari data
const [offersToPerson, offersToProjects, projectUpdates] =
await Promise.all([
this.api.fetchOffersToPerson(jwt),
this.api.fetchOffersToProjects(jwt),
this.api.fetchProjectsLastUpdated(this.starredPlanIds, jwt)
]);
// 3. Convert TimeSafari data to NotificationContent[]
const contents: NotificationContent[] = [];
// Convert offers to person
if (offersToPerson?.data) {
for (const offer of offersToPerson.data) {
contents.push({
id: `offer_${offer.id}`,
title: `New Offer: ${offer.title}`,
body: offer.description || '',
scheduledTime: context.scheduledTime || Date.now() + 3600000,
fetchTime: context.fetchTime,
mediaUrl: offer.imageUrl
});
}
}
// Convert project updates
if (projectUpdates?.data) {
for (const update of projectUpdates.data) {
contents.push({
id: `project_${update.planSummary.jwtId}`,
title: `${update.planSummary.name} Updated`,
body: `New updates for ${update.planSummary.name}`,
scheduledTime: context.scheduledTime || Date.now() + 3600000,
fetchTime: context.fetchTime,
mediaUrl: update.planSummary.image
});
}
}
return contents;
}
}
// In host app initialization:
const plugin = new DailyNotification();
const fetcher = new TimeSafariContentFetcher(apiClient, activeDid);
plugin.setContentFetcher(fetcher);
```
#### Android Implementation (if needed)
If you need native Android implementation (for WorkManager background tasks):
```kotlin
// In host app's native code
class TimeSafariContentFetcher : NotificationContentFetcher {
private val apiClient: TimeSafariAPIClient
private val activeDid: String
override fun fetchContent(context: FetchContext): CompletableFuture<List<NotificationContent>> {
return CompletableFuture.supplyAsync {
// Make TimeSafari API calls
// Convert to NotificationContent[]
// Return list
}
}
}
```
## Implementation Challenges
### Challenge 1: JavaScript → Java Callback Bridge
**Problem**: Capacitor plugins need to bridge JavaScript callbacks to Java for background workers.
**Solutions**:
1. **Bridge via Plugin Method** (Simplest)
- Host app calls plugin method with callback ID
- Plugin stores callback reference
- Plugin calls back via Capacitor bridge when needed
- Limitations: Callback must be serializable
2. **Bridge via Event System** (More Flexible)
- Plugin emits events when fetch needed
- Host app listens and responds
- Plugin waits for response
- More complex but more flexible
3. **Native Implementation** (Best Performance)
- Host app provides native Java/Kotlin implementation
- Direct Java interface (no JS bridge needed)
- Best for background work
- Requires host app to include native code
**Recommendation**: Start with Option 1 (Plugin Method), add Option 3 (Native) later if needed.
### Challenge 2: Background Worker Execution
**Problem**: Background WorkManager workers need to call host app's fetcher, but WorkManager runs in separate process.
**Solutions**:
1. **Store callback reference in SharedPreferences** (Limited)
- Serialize callback config, not actual callback
- Host app provides API endpoint URL + auth info
- Plugin makes HTTP call to host app's endpoint
- Host app handles TimeSafari logic server-side
2. **Use Capacitor Background Tasks** (Platform-specific)
- iOS: BGTaskScheduler
- Android: WorkManager with Capacitor bridge
- Bridge JS callback from background task
- Complex but works
3. **Native Background Implementation** (Recommended)
- Host app provides native Java/Kotlin fetcher
- No JS bridge needed in background
- Direct Java interface
- Best performance
**Recommendation**: Option 3 (Native) for background work, Option 1 for foreground.
### Challenge 3: Data Model Conversion
**Problem**: Plugin's generic `NotificationContent` vs TimeSafari's specific data structures.
**Solution**:
- Host app owns conversion logic
- Plugin never sees TimeSafari data structures
- Plugin only knows about `NotificationContent[]`
This is actually **simpler** than current architecture.
### Challenge 4: Configuration Management
**Problem**: Plugin currently manages TimeSafari config (apiServer, activeDid, starredPlanIds).
**Solution**:
- Host app manages all TimeSafari config
- Plugin receives only fetcher callback
- Host app provides config to fetcher, not plugin
- Plugin becomes stateless regarding TimeSafari
## Migration Path
### Phase 1: Add Callback Interface (Non-Breaking)
1. Add `setContentFetcher()` method to plugin
2. Add callback interface definitions
3. Keep existing TimeSafari integration as fallback
4. Allow host app to opt-in to callback approach
### Phase 2: Move TimeSafari Code to Host App
1. Create `TimeSafariContentFetcher` in host app
2. Migrate `EnhancedDailyNotificationFetcher` logic
3. Migrate JWT generation logic
4. Test with callback approach
### Phase 3: Remove Plugin Integration (Breaking)
1. Remove `TimeSafariIntegrationManager` from plugin
2. Remove `EnhancedDailyNotificationFetcher` from plugin
3. Remove TimeSafari data model imports
4. Make callback approach required
5. Update documentation
## Effort Estimation
### Plugin Changes
- **Add callback interface**: 4-8 hours
- **Modify fetch worker**: 4-8 hours
- **Update documentation**: 2-4 hours
- **Testing**: 8-16 hours
- **Total**: 18-36 hours
### Host App Changes
- **Create TimeSafariContentFetcher**: 8-16 hours
- **Migrate API client logic**: 8-16 hours
- **Migrate JWT logic**: 4-8 hours
- **Testing**: 8-16 hours
- **Total**: 28-56 hours
### Total Effort
**Estimated**: 46-92 hours (6-12 days) for complete migration
## Benefits
1. **Generic Plugin**: Plugin can be used by any app, not just TimeSafari
2. **Clear Separation**: Plugin handles scheduling, app handles fetching
3. **Easier Testing**: Mock fetcher for unit tests
4. **Better Maintainability**: TimeSafari changes don't require plugin updates
5. **Flexibility**: Host app controls all API integration details
## Risks
1. **Breaking Changes**: Requires migration of host app
2. **Complexity**: Callback bridge adds complexity
3. **Performance**: JavaScript bridge may be slower for background work
4. **Testing Burden**: More complex integration testing
## Recommendations
### Short Term (Keep Current Architecture)
**Recommendation**: Keep current architecture for now, add callback interface as optional enhancement.
**Rationale**:
- Current architecture works
- Migration is significant effort
- Benefits may not justify costs yet
- Can add callback interface without removing existing code
### Long Term (Full Refactor)
**Recommendation**: Plan for full refactor when:
- Plugin needs to support multiple apps
- TimeSafari API changes frequently
- Plugin team wants to decouple from TimeSafari
**Approach**:
1. Phase 1: Add callback interface alongside existing code
2. Migrate TimeSafari app to use callbacks
3. Phase 3: Remove old integration code
## Alternative: Hybrid Approach
Keep TimeSafari integration in plugin but make it **optional and pluggable**:
```typescript
interface DailyNotificationPlugin {
// Current approach (TimeSafari-specific)
configure(options: ConfigureOptions): void;
// New approach (generic callback)
setContentFetcher(fetcher: NotificationContentFetcher): void;
// Plugin uses callback if provided, falls back to TimeSafari integration
}
```
This allows:
- Existing apps continue working (no breaking changes)
- New apps can use callback approach
- Plugin gradually becomes generic
## Questions to Resolve
1. **Background Work**: How to call JS callback from background WorkManager?
- Native implementation required?
- Or HTTP callback to host app endpoint?
2. **Error Handling**: How does plugin handle fetcher errors?
- Retry logic?
- Fallback to cached content?
- Event notifications?
3. **Configuration**: Where does TimeSafari config live?
- Host app only?
- Or plugin still needs some config?
4. **Testing**: How to test plugin without TimeSafari integration?
- Mock fetcher interface?
- Test fixtures?
---
## Improvement Directive Integration
This analysis has been superseded by the **Improvement Directive — Daily Notification Plugin "Integration Point" Refactor** (see below). The directive provides concrete, implementable specifications with clear interfaces, test contracts, and migration paths.
### Key Directive Decisions
1. **Dual-Path SPI**: Native Fetcher (required for background) + Optional JS Fetcher (foreground only)
2. **Background Reliability**: Native SPI only; JS fetcher explicitly disabled in background workers
3. **Reversibility**: Legacy TimeSafari code behind feature flag for one minor release
4. **Test Contract**: Single JSON fixture contract used by both native and JS paths
See full directive below for complete specifications.
---
## Improvement Directive — Daily Notification Plugin "Integration Point" Refactor
**Audience:** Plugin & TimeSafari app teams
**Goal:** Convert the analysis into an implementable, low-risk refactor with crisp interfaces, background-compatibility, testability, and a reversible migration path.
**Source reviewed:** `docs/integration-point-refactor-analysis.md`
---
## A) Decision Record (ADR-001): Architecture Shape
**Decision:** Ship a **dual-path SPI** where the plugin exposes:
1. a **Native Fetcher SPI** (Android/Kotlin, iOS/Swift) for background reliability, and
2. an **Optional JS Fetcher** for foreground/manual refresh & prototyping.
**Why:** Your analysis correctly targets decoupling, but the **WorkManager/BGTaskScheduler reality** means **native fetchers are the only dependable background path**. The JS callback remains useful for manual refresh, prefetch while the app is foregrounded, or rapid iteration.
**Reversibility:** Keep the legacy TimeSafari path behind a feature flag for one minor release; remove in the next major.
**Exit Criteria:** Both fetcher paths produce identical `NotificationContent[]` and pass the same test contract.
---
## B) Public Interfaces (Final Form)
### B1. TypeScript (Host App)
```typescript
// core types
export interface NotificationContent {
id: string;
title: string;
body?: string;
scheduledTime?: number; // epoch ms
fetchTime: number; // epoch ms
mediaUrl?: string;
ttlSeconds?: number; // cache validity
dedupeKey?: string; // for idempotency
priority?: 'min'|'low'|'default'|'high'|'max';
metadata?: Record<string, unknown>;
}
export type FetchTrigger = 'background_work' | 'prefetch' | 'manual' | 'scheduled';
export interface FetchContext {
trigger: FetchTrigger;
scheduledTime?: number;
fetchTime: number;
metadata?: Record<string, unknown>;
}
export interface JsNotificationContentFetcher {
fetchContent(context: FetchContext): Promise<NotificationContent[]>;
}
```
**Plugin API Additions**
```typescript
export interface DailyNotificationPlugin {
setJsContentFetcher(fetcher: JsNotificationContentFetcher): void; // foreground-only
enableNativeFetcher(enable: boolean): Promise<void>; // default true
setPolicy(policy: SchedulingPolicy): Promise<void>; // see §C2
}
```
### B2. Android SPI (Host App native)
```kotlin
interface NativeNotificationContentFetcher {
suspend fun fetchContent(context: FetchContext): List<NotificationContent>
}
data class FetchContext(
val trigger: String, // enum mirror
val scheduledTime: Long?, // epoch ms
val fetchTime: Long, // epoch ms
val metadata: Map<String, Any?> = emptyMap()
)
```
**Registration:** Host app injects an implementation via a generated ServiceLoader or explicit setter in `Application.onCreate()`:
```kotlin
DailyNotification.setNativeFetcher(TimeSafariNativeFetcher())
```
> **Note:** JS fetcher remains available but **is not used** by background workers.
---
## C) Scheduling & Policy Guardrails
### C1. Background Reliability
* **Android:** WorkManager + `setRequiredNetworkType(CONNECTED)`, exponential backoff, content URI triggers optional, **no JS bridging** in background.
* **iOS:** `BGAppRefreshTask` + `BGProcessingTask` with earliestBeginDate windows; keep tasks short (< 30s), aggregate fetches.
### C2. `SchedulingPolicy`
```typescript
export interface SchedulingPolicy {
prefetchWindowMs?: number; // how early to prefetch before schedule
retryBackoff: { minMs: number; maxMs: number; factor: number; jitterPct: number };
maxBatchSize?: number; // upper bound per run
dedupeHorizonMs?: number; // window for dedupeKey suppression
cacheTtlSeconds?: number; // default if item.ttlSeconds absent
exactAlarmsAllowed?: boolean; // guarded by OS version & battery policy
}
```
### C3. Idempotency & De-duplication
* The plugin maintains a **recent keys bloom/filter** using `dedupeKey` (fallback `id`) for `dedupeHorizonMs`.
* No notification is enqueued if `(dedupeKey, title, body)` unchanged within horizon.
---
## D) Security & Config Partition
### D1. Secrets & Tokens
* **JWT generation lives in the host app**, not the plugin. For extra hardening consider **DPoP** or **JWE-wrapped access tokens** if your API supports it.
* Rotate keys; keep key refs in host app secure storage; never serialize tokens through JS bridges in background.
### D2. Least-Knowledge Plugin
* Plugin stores only generic `NotificationContent`.
* **No TimeSafari DTOs** in plugin artifacts. (As your analysis recommends.)
---
## E) Failure Taxonomy & Handling
| Class | Examples | Plugin Behavior |
| --------------- | ---------------------- | ------------------------------------------------- |
| **Retryable** | 5xx, network, timeouts | Backoff per policy; stop on `maxAttempts` |
| **Unretryable** | 4xx auth, schema error | Log & surface event; skip batch; keep schedule |
| **Partial** | Some items bad | Enqueue valid subset; metric + structured error |
| **Over-quota** | 429 | Honor `Retry-After` if present; otherwise backoff |
**Cache fallback:** If fetch fails, reuse **unexpired cached contents** (by item `ttlSeconds` or default policy).
---
## F) Metrics, Logs, Events
* **Metrics:** `fetch_duration_ms`, `fetch_success`, `fetch_fail_class`, `items_fetched`, `items_enqueued`, `deduped_count`, `cache_hits`.
* **Structured logs:** Correlate by `run_id`, include `trigger`, backoff stage, and per-item `dedupeKey`.
* **Event bus:** Emit `onFetchStart`, `onFetchEnd`, `onFetchError`, `onEnqueue` (debug UI can subscribe).
---
## G) Test Contract & Fixtures
### G1. Golden Contract
A **single JSON fixture contract** used by both native & JS fetchers:
```json
{
"context": {"trigger":"scheduled","scheduledTime":1730179200000,"fetchTime":1730175600000},
"output": [
{"id":"offer_123","title":"New Offer","body":"...","fetchTime":1730175600000,"dedupeKey":"offer_123","ttlSeconds":86400}
]
}
```
* CI runs the same contract through **(1) JS fetcher** (foreground test harness) and **(2) Native fetcher** (instrumented test) and compares normalized outputs.
### G2. Failure Sims
* Network chaos (drop, latency), 401→refresh→200, 429 with `Retry-After`, malformed item (should be skipped, not crash).
---
## H) Migration Plan (Minor → Major)
**Minor (X.Y):**
1. Add `setJsContentFetcher`, `enableNativeFetcher`, `setPolicy`.
2. Implement **Native Fetcher SPI** & plugin side registry.
3. Keep legacy TimeSafari code behind `useLegacyIntegration` flag (default **false**).
**Major (X+1.0):**
1. Remove legacy TimeSafari classes (`TimeSafariIntegrationManager`, `EnhancedDailyNotificationFetcher`, etc.).
2. Publish migration guide & codemod mapping old config → SPI registration.
---
## I) Pull-Request Breakdown (7 PRs)
1. **PR1 — SPI Shell:** Kotlin/Swift interfaces, TS types, `SchedulingPolicy`, no behavior change.
2. **PR2 — Background Workers:** Wire Native SPI in WorkManager/BGTasks; metrics skeleton; cache store.
3. **PR3 — JS Fetcher Path:** Foreground bridge, event bus, dev harness screen.
4. **PR4 — Dedupe/Idempotency:** Bloom/filter store + tests; `dedupeKey` enforcement.
5. **PR5 — Failure Policy:** Retry taxonomy, backoff, cache fallback; structured errors.
6. **PR6 — Docs & Samples:** Minimal host app examples (JS + Kotlin), migration notes.
7. **PR7 — Feature Flag Legacy:** Guard & regression tests; changelog for major removal.
---
## J) Acceptance Criteria (Definition of Done)
* **Background Reliability:** Native fetcher runs with app killed; JS fetcher **never** required for background.
* **Parity:** Same inputs → same `NotificationContent[]` via JS & Native paths (contract tests green).
* **No TimeSafari in Plugin:** No imports, types, or endpoints leak into plugin modules.
* **Safety:** No notifications emitted twice within `dedupeHorizonMs` for identical `dedupeKey`.
* **Observability:** Metrics visible; error classes distinguish retryable vs. not; logs correlated by run.
* **Docs:** Host app integration guide includes **copy-paste** Kotlin & TS skeletons; migration guide from legacy.
* **Battery & Quotas:** Backoff respected; tasks kept <30s; policy toggles documented; exact alarms gated.
---
## K) Open Questions (Resolve Before PR3)
1. **iOS capabilities:** Which BG task identifiers and permitted intervals will Product accept (refresh vs processing)?
2. **Token Hardening:** Do we want DPoP or short-lived JWE now or later?
3. **User Controls:** Should we surface a per-plan "snooze/mute" map inside `metadata` with plugin-side persistence?
---
## L) Example Skeletons
### L1. Android Native Fetcher (Host App)
```kotlin
class TimeSafariNativeFetcher(
private val api: TimeSafariApi,
private val tokenProvider: TokenProvider
) : NativeNotificationContentFetcher {
override suspend fun fetchContent(context: FetchContext): List<NotificationContent> {
val jwt = tokenProvider.freshToken()
val updates = api.updates(jwt) // domain-specific
val offers = api.offers(jwt)
return buildList {
for (o in offers) add(
NotificationContent(
id = "offer_${o.id}",
title = "New Offer: ${o.title}",
body = o.description ?: "",
scheduledTime = context.scheduledTime ?: (System.currentTimeMillis() + 3_600_000),
fetchTime = context.fetchTime,
mediaUrl = o.imageUrl,
ttlSeconds = 86_400,
dedupeKey = "offer_${o.id}"
)
)
// … map updates similarly …
}
}
}
```
### L2. JS Fetcher Registration (Foreground Only)
```typescript
const fetcher: JsNotificationContentFetcher = {
async fetchContent(ctx) {
const jwt = await api.generateJWT(activeDid);
const { offers, updates } = await api.fetchEverything(jwt);
return mapToNotificationContent(offers, updates, ctx);
}
};
DailyNotification.setJsContentFetcher(fetcher);
await DailyNotification.setPolicy({
retryBackoff: { minMs: 2000, maxMs: 600000, factor: 2, jitterPct: 20 },
dedupeHorizonMs: 24*60*60*1000,
cacheTtlSeconds: 6*60*60
});
```
---
## M) Docs to Produce
* **INTEGRATION_GUIDE.md** (host app: Native vs JS, when to use which, copy-paste snippets).
* **SCHEDULING_POLICY.md** (all knobs with OS caveats).
* **MIGRATION_GUIDE_X→X+1.md** (flag removal plan, old→new mapping).
* **TEST_CONTRACTS.md** (fixtures, CI commands).
---
## N) Risk Register & Mitigations
* **Risk:** JS callback used in background → fetch starves.
**Mitigation:** Disable in background by design; lint rule + runtime guard.
* **Risk:** Duplicate notifications.
**Mitigation:** `dedupeKey` + horizon filter; contract tests to assert no dupes.
* **Risk:** Token leakage through JS.
**Mitigation:** Tokens stay in native path for background; JS path only in foreground; redact logs.
* **Risk:** Major removal shocks dependents.
**Mitigation:** Two-release migration window + codemod and samples.
---
### Final Note
Your analysis nails the **separation of concerns** and enumerates the **callback bridge challenges**. This directive turns it into a concrete, staged plan with **native-first background fetch**, **JS optionality**, **clear policies**, and **verifiable acceptance criteria** while preserving a **rollback path**.
---
**Status**: Improvement Directive - Active Implementation Plan
**Next Steps**: Begin PR1 (SPI Shell) implementation
**Dependencies**: None
**Stakeholders**: Plugin developers, TimeSafari app developers

156
examples/js-fetcher-typescript.ts Normal file
View File

@@ -0,0 +1,156 @@
/**
* JavaScript Content Fetcher Implementation (TypeScript)
*
* Example implementation of JsNotificationContentFetcher for foreground/manual refresh.
*
* NOTE: This is used ONLY for foreground operations. Background workers use
* the Native Fetcher SPI (Kotlin/Swift) for reliability.
*
* @author Matthew Raymer
* @version 1.0.0
*/
import { DailyNotification } from '@timesafari/daily-notification-plugin';
import type {
JsNotificationContentFetcher,
FetchContext,
NotificationContent
} from '@timesafari/daily-notification-plugin';
import { TimeSafariAPI } from './timesafari-api'; // Host app's API client
/**
* TimeSafari JavaScript content fetcher
*
* Implements JsNotificationContentFetcher for foreground/manual refresh.
* Background workers use the native Kotlin/Swift implementation.
*/
class TimeSafariJsFetcher implements JsNotificationContentFetcher {
constructor(
private api: TimeSafariAPI,
private activeDid: string,
private starredPlanIds: string[]
) {}
async fetchContent(context: FetchContext): Promise<NotificationContent[]> {
try {
// 1. Generate JWT for authentication
const jwt = await this.api.generateJWT(this.activeDid);
// 2. Fetch TimeSafari data in parallel
const [offersToPerson, offersToPlans, projectUpdates] = await Promise.all([
this.api.fetchOffersToPerson(jwt),
this.api.fetchOffersToPlans(jwt),
this.starredPlanIds.length > 0
? this.api.fetchProjectsLastUpdated(this.starredPlanIds, jwt)
: Promise.resolve(null)
]);
// 3. Convert to NotificationContent array
const contents: NotificationContent[] = [];
// Convert offers to person
if (offersToPerson?.data) {
for (const offer of offersToPerson.data) {
contents.push({
id: `offer_person_${offer.id}`,
title: `New Offer: ${offer.title}`,
body: offer.description || '',
scheduledTime: context.scheduledTime || Date.now() + 3600000,
fetchTime: context.fetchTime,
mediaUrl: offer.imageUrl,
ttlSeconds: 86400, // 24 hours
dedupeKey: `offer_person_${offer.id}_${offer.updatedAt}`,
priority: 'default',
metadata: {
offerId: offer.id,
issuerDid: offer.issuerDid,
source: 'offers_to_person'
}
});
}
}
// Convert offers to plans
if (offersToPlans?.data) {
for (const offer of offersToPlans.data) {
contents.push({
id: `offer_plan_${offer.id}`,
title: `Offer for Your Project: ${offer.projectName}`,
body: offer.description || '',
scheduledTime: context.scheduledTime || Date.now() + 3600000,
fetchTime: context.fetchTime,
mediaUrl: offer.imageUrl,
ttlSeconds: 86400,
dedupeKey: `offer_plan_${offer.id}_${offer.updatedAt}`,
priority: 'default',
metadata: {
offerId: offer.id,
planHandleId: offer.planHandleId,
source: 'offers_to_plans'
}
});
}
}
// Convert project updates
if (projectUpdates?.data) {
for (const update of projectUpdates.data) {
contents.push({
id: `project_${update.planSummary.jwtId}`,
title: `${update.planSummary.name} Updated`,
body: `New updates for ${update.planSummary.name}`,
scheduledTime: context.scheduledTime || Date.now() + 3600000,
fetchTime: context.fetchTime,
mediaUrl: update.planSummary.image,
ttlSeconds: 86400,
dedupeKey: `project_${update.planSummary.handleId}_${update.planSummary.jwtId}`,
priority: 'default',
metadata: {
planHandleId: update.planSummary.handleId,
jwtId: update.planSummary.jwtId,
source: 'project_updates'
}
});
}
}
return contents;
} catch (error) {
console.error('TimeSafari fetch failed:', error);
// Return empty array - plugin will handle retry based on policy
return [];
}
}
}
/**
* Register fetcher and configure policy
*/
export async function setupDailyNotification(
api: TimeSafariAPI,
activeDid: string,
starredPlanIds: string[]
): Promise<void> {
// Create JS fetcher for foreground operations
const jsFetcher = new TimeSafariJsFetcher(api, activeDid, starredPlanIds);
DailyNotification.setJsContentFetcher(jsFetcher);
// Configure scheduling policy
await DailyNotification.setPolicy({
prefetchWindowMs: 5 * 60 * 1000, // 5 minutes before scheduled time
retryBackoff: {
minMs: 2000,
maxMs: 600000, // 10 minutes max
factor: 2,
jitterPct: 20
},
maxBatchSize: 50,
dedupeHorizonMs: 24 * 60 * 60 * 1000, // 24 hours
cacheTtlSeconds: 6 * 60 * 60, // 6 hours default
exactAlarmsAllowed: true // If app has permission
});
// Enable native fetcher (required for background workers)
await DailyNotification.enableNativeFetcher(true);
}

153
examples/native-fetcher-android.kt Normal file
View File

@@ -0,0 +1,153 @@
/**
* TimeSafari Native Fetcher Implementation (Android/Kotlin)
*
* Example implementation of NativeNotificationContentFetcher for Android.
* This runs in background workers and does NOT require JavaScript bridge.
*
* @author Matthew Raymer
* @version 1.0.0
*/
package com.timesafari.notification
import com.timesafari.dailynotification.*
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
/**
* TimeSafari native content fetcher
*
* Implements the NativeNotificationContentFetcher SPI to provide
* TimeSafari-specific notification content fetching for background workers.
*/
class TimeSafariNativeFetcher(
private val api: TimeSafariApi,
private val tokenProvider: TokenProvider,
private val starredPlanIds: List<String>
) : NativeNotificationContentFetcher {
override suspend fun fetchContent(context: FetchContext): List<NotificationContent> {
return withContext(Dispatchers.IO) {
try {
// 1. Get fresh authentication token
val jwt = tokenProvider.freshToken()
// 2. Fetch TimeSafari data in parallel
val offersToPerson = async { api.fetchOffersToPerson(jwt) }
val offersToPlans = async { api.fetchOffersToPlans(jwt) }
val projectUpdates = async {
if (starredPlanIds.isNotEmpty()) {
api.fetchProjectsLastUpdated(starredPlanIds, jwt)
} else {
null
}
}
// Wait for all requests
val offersPersonResult = offersToPerson.await()
val offersPlansResult = offersToPlans.await()
val updatesResult = projectUpdates.await()
// 3. Convert to NotificationContent list
buildList {
// Add offers to person
offersPersonResult?.data?.forEach { offer ->
add(
NotificationContent(
id = "offer_person_${offer.id}",
title = "New Offer: ${offer.title}",
body = offer.description ?: "",
scheduledTime = context.scheduledTime
?: (System.currentTimeMillis() + 3_600_000),
fetchTime = context.fetchTime,
mediaUrl = offer.imageUrl,
ttlSeconds = 86_400, // 24 hours
dedupeKey = "offer_person_${offer.id}_${offer.updatedAt}",
priority = "default",
metadata = mapOf(
"offerId" to offer.id,
"issuerDid" to offer.issuerDid,
"source" to "offers_to_person"
)
)
)
}
// Add offers to plans
offersPlansResult?.data?.forEach { offer ->
add(
NotificationContent(
id = "offer_plan_${offer.id}",
title = "Offer for Your Project: ${offer.projectName}",
body = offer.description ?: "",
scheduledTime = context.scheduledTime
?: (System.currentTimeMillis() + 3_600_000),
fetchTime = context.fetchTime,
mediaUrl = offer.imageUrl,
ttlSeconds = 86_400,
dedupeKey = "offer_plan_${offer.id}_${offer.updatedAt}",
priority = "default",
metadata = mapOf(
"offerId" to offer.id,
"planHandleId" to offer.planHandleId,
"source" to "offers_to_plans"
)
)
)
}
// Add project updates
updatesResult?.data?.forEach { update ->
add(
NotificationContent(
id = "project_${update.planSummary.jwtId}",
title = "${update.planSummary.name} Updated",
body = "New updates for ${update.planSummary.name}",
scheduledTime = context.scheduledTime
?: (System.currentTimeMillis() + 3_600_000),
fetchTime = context.fetchTime,
mediaUrl = update.planSummary.image,
ttlSeconds = 86_400,
dedupeKey = "project_${update.planSummary.handleId}_${update.planSummary.jwtId}",
priority = "default",
metadata = mapOf(
"planHandleId" to update.planSummary.handleId,
"jwtId" to update.planSummary.jwtId,
"source" to "project_updates"
)
)
)
}
}
} catch (e: Exception) {
// Log error and return empty list
// Plugin will handle retry based on SchedulingPolicy
android.util.Log.e("TimeSafariFetcher", "Fetch failed", e)
emptyList()
}
}
}
}
/**
* Registration in Application.onCreate()
*/
class TimeSafariApplication : Application() {
override fun onCreate() {
super.onCreate()
// Register native fetcher
val api = TimeSafariApiClient(context = this)
val tokenProvider = JWTokenProvider(activeDid = getActiveDid())
val starredPlanIds = getStarredPlanIds()
val fetcher = TimeSafariNativeFetcher(
api = api,
tokenProvider = tokenProvider,
starredPlanIds = starredPlanIds
)
DailyNotification.setNativeFetcher(fetcher)
}
}

135
src/types/content-fetcher.ts Normal file
View File

@@ -0,0 +1,135 @@
/**
* Content Fetcher SPI Types
*
* TypeScript definitions for the content fetcher Service Provider Interface
* that allows host apps to provide notification content fetching logic.
*
* @author Matthew Raymer
* @version 1.0.0
*/
/**
* Notification content item
*
* Core data structure for notifications that the plugin can schedule
* and display. All TimeSafari-specific data must be converted to this
* generic format by the host app's fetcher implementation.
*/
export interface NotificationContent {
/** Unique identifier for this notification */
id: string;
/** Notification title (required) */
title: string;
/** Notification body text (optional) */
body?: string;
/** When this notification should be displayed (epoch ms) */
scheduledTime?: number;
/** When this content was fetched (epoch ms, required) */
fetchTime: number;
/** Optional image URL for rich notifications */
mediaUrl?: string;
/** Cache TTL in seconds (how long this content is valid) */
ttlSeconds?: number;
/** Deduplication key (for idempotency) */
dedupeKey?: string;
/** Notification priority level */
priority?: 'min' | 'low' | 'default' | 'high' | 'max';
/** Additional metadata (opaque to plugin) */
metadata?: Record<string, unknown>;
}
/**
* Reason why content fetch was triggered
*/
export type FetchTrigger =
| 'background_work' // Background worker (WorkManager/BGTask)
| 'prefetch' // Prefetch before scheduled notification
| 'manual' // User-initiated refresh
| 'scheduled'; // Scheduled fetch
/**
* Context provided to fetcher about why fetch was triggered
*/
export interface FetchContext {
/** Why the fetch was triggered */
trigger: FetchTrigger;
/** When notification is scheduled (if applicable, epoch ms) */
scheduledTime?: number;
/** When fetch was triggered (epoch ms) */
fetchTime: number;
/** Additional context from plugin (opaque) */
metadata?: Record<string, unknown>;
}
/**
* JavaScript Content Fetcher Interface
*
* Host app implements this interface to provide notification content
* fetching logic. This is used ONLY for foreground/manual refresh.
*
* Background workers use Native Fetcher SPI (Kotlin/Swift) for reliability.
*/
export interface JsNotificationContentFetcher {
/**
* Fetch notification content from external source
*
* Called by plugin when:
* - Manual refresh is requested
* - Prefetch is needed while app is foregrounded
* - Testing/debugging
*
* NOT called from background workers (they use Native SPI)
*
* @param context Context about why fetch was triggered
* @returns Promise with array of notification content
*/
fetchContent(context: FetchContext): Promise<NotificationContent[]>;
}
/**
* Scheduling policy configuration
*
* Controls how the plugin schedules fetches, handles retries,
* and manages deduplication.
*/
export interface SchedulingPolicy {
/** How early to prefetch before scheduled notification (ms) */
prefetchWindowMs?: number;
/** Retry backoff configuration */
retryBackoff: {
/** Minimum delay between retries (ms) */
minMs: number;
/** Maximum delay between retries (ms) */
maxMs: number;
/** Exponential backoff multiplier */
factor: number;
/** Jitter percentage (0-100) */
jitterPct: number;
};
/** Maximum items to fetch per batch */
maxBatchSize?: number;
/** Deduplication window (ms) - prevents duplicate notifications */
dedupeHorizonMs?: number;
/** Default cache TTL if item doesn't specify (seconds) */
cacheTtlSeconds?: number;
/** Whether exact alarms are allowed (Android 12+) */
exactAlarmsAllowed?: boolean;
}

70
tests/fixtures/test-contract.json vendored Normal file
View File

@@ -0,0 +1,70 @@
{
"description": "Golden contract test fixture - used by both JS and Native fetcher tests",
"version": "1.0.0",
"context": {
"trigger": "scheduled",
"scheduledTime": 1730179200000,
"fetchTime": 1730175600000,
"metadata": {
"testRun": true,
"runId": "test-run-001"
}
},
"expectedOutput": [
{
"id": "offer_123",
"title": "New Offer: Community Garden Project",
"body": "A new volunteer opportunity is available",
"scheduledTime": 1730179200000,
"fetchTime": 1730175600000,
"mediaUrl": "https://example.com/images/garden.jpg",
"ttlSeconds": 86400,
"dedupeKey": "offer_123_2025-10-29T12:00:00Z",
"priority": "default",
"metadata": {
"offerId": "123",
"issuerDid": "did:key:test123",
"source": "offers_to_person"
}
},
{
"id": "project_456",
"title": "Community Center Project Updated",
"body": "New updates for Community Center Project",
"scheduledTime": 1730179200000,
"fetchTime": 1730175600000,
"mediaUrl": null,
"ttlSeconds": 86400,
"dedupeKey": "project_https://endorser.ch/entity/01ABC_789xyz",
"priority": "default",
"metadata": {
"planHandleId": "https://endorser.ch/entity/01ABC",
"jwtId": "789xyz",
"source": "project_updates"
}
}
],
"failureScenarios": [
{
"name": "network_timeout",
"simulate": "timeout_5000ms",
"expectedBehavior": "retry_with_backoff"
},
{
"name": "auth_401",
"simulate": "http_401",
"expectedBehavior": "unretryable_error_logged"
},
{
"name": "rate_limit_429",
"simulate": "http_429_retry_after_60",
"expectedBehavior": "honor_retry_after_header"
},
{
"name": "partial_failure",
"simulate": "malformed_item_in_array",
"expectedBehavior": "skip_bad_item_enqueue_valid"
}
]
}