crowd-funder-for-time-pwa/doc/plugin-feedback-daily-notification-configureNativeFetcher-jwt-pool.md

Plugin feedback: configureNativeFetcher — optional JWT pool for background API calls

Date: 2026-03-27 PST
Target repo: @timesafari/daily-notification-plugin (daily-notification-plugin)
Consuming app: crowd-funder-for-time-pwa (TimeSafari)
Related app plan: doc/plan-background-jwt-pool-and-expiry.md (Phase B, Option B1)

---

Summary

The host app’s NativeNotificationContentFetcher (TimeSafariNativeFetcher on Android) calls Endorser with a Bearer JWT set via configureNativeFetcher. For background prefetch, the token must stay valid until WorkManager runs (often minutes later); Endorser may also reject duplicate JWT strings across days.

The app will mint a pool of distinct JWTs (see app plan) and needs the plugin to accept and persist that pool so native code can select a token without JavaScript at prefetch time.

Requested change (plugin): extend configureNativeFetcher to accept an optional JWT pool alongside the existing jwtToken, persist it in the same storage the host already relies on (e.g. SharedPreferences / app group), and document how NativeNotificationContentFetcher implementations should read it.

---

Motivation

Issue	Why plugin support helps
Single short-lived jwtToken	Expires before background fetch
Server duplicate-JWT rules	Need many distinct bearer strings over time
No JS in WorkManager	Pool must be readable only from native

---

Proposed API (TypeScript / Capacitor)

Extend existing configureNativeFetcher options (names indicative — align with plugin naming conventions):

configureNativeFetcher(options: {
  apiBaseUrl: string;
  activeDid: string;
  /** Primary token; keep for backward compatibility and Phase A (single long-lived JWT). */
  jwtToken: string;
  /**
   * Optional. Distinct JWT strings for background use (e.g. one per day slot).
   * If omitted, behavior matches today (single jwtToken only).
   */
  jwtTokens?: string[];
});

Alternatives (if size limits matter for bridge payload):

• jwtTokenPoolJson: string — JSON array string of JWT strings (single string across the bridge).

Validation (plugin):

• If jwtTokens present: length ≤ a sane cap (host will use ~100; plugin may enforce max e.g. 128).
• Empty array: treat as “no pool” (same as omitting).

---

Android

1. Parse new fields in DailyNotificationPlugin.configureNativeFetcher (or equivalent).
2. Persist pool under the same prefs namespace used for other TimeSafari / dual-schedule data, or a documented key prefix (e.g. jwt_token_pool as JSON array string).
3. Document for host implementers: NativeNotificationContentFetcher should:
   • Prefer pool entry for fetchContent when pool is non-empty (selection policy is host responsibility — e.g. day index % length), or
   • Expose a small helper the host fetcher calls to resolve “current” bearer.
4. Clear pool when configureNativeFetcher is called with a new identity / empty pool / logout path (coordinate with host).
5. Backward compatibility: if only jwtToken is sent, behavior unchanged from current release.

---

iOS

When configureNativeFetcher exists on iOS, mirror Android: accept optional pool, persist, document read path for native fetcher.

---

Versioning & release

• Bump plugin semver (minor: new optional fields).
• Publish package; consuming app bumps @timesafari/daily-notification-plugin and updates nativeFetcherConfig.ts to pass jwtTokens when Phase B ships.

---

References (host app)

Topic	Location
End-to-end plan (Phase A/B, pool sizing)	doc/plan-background-jwt-pool-and-expiry.md
Android fetcher	android/.../TimeSafariNativeFetcher.java
Current configure call	src/services/notifications/nativeFetcherConfig.ts
JWT options (expired token context)	doc/endorser-jwt-background-prefetch-options.md

---

This document is intended to be copied or linked from PRs in daily-notification-plugin; keep app-specific details in the app plan.