Skip to content

Frontend SDK notification implementation

The SDK provides TypeScript types, runtime selectors, event merge behavior, application notification polling, display ownership classification, and action execution helpers.

Maintainer entry points:

  • src/types/notifications.ts
  • src/types/applicationNotifications.ts
  • src/notifications/
  • src/plugins/displayPresentation.ts
  • src/plugins/actionDisplayPolicy.ts
  • src/plugins/actionRunner.ts
  • src/plugins/uiEffects.ts
  • src/plugins/applicationActionsInvalidation.ts
  • src/plugins/pluginsRegistry.ts
  • src/events/pollingEventSource.ts

Session selectors validate metadata and skip malformed records. Application notification controllers can hydrate an authoritative owner snapshot before polling from a cursor captured before that snapshot. Revision-aware merge prevents stale events from replacing newer snapshot records. Display envelopes classify connection and session ownership independently from presentation.

RestAgentBackend exposes application/session list and dismiss operations. Mobile enables snapshot hydration and uses NotificationDismissalCache over a host-provided KeyValueStore. The cache stores connection/scope/session/notification identity plus the exact dismissed revision, but no notification content.

Application notification controllers hide a cached exact revision, retry its unchanged dismissal during hydration or observation, and remove the cache after server convergence. A newer authoritative revision invalidates the older cache entry and is presented; the controller never rewrites the cached expected revision. Dismissal events remain in the event contract but are not forced onto another already-open presentation.

The SDK exposes the versioned retention type and a TTL deadline helper. Application notification controllers remember TTL lifecycle identities accepted before their deadline for the controller's lifetime. A reconstructed controller filters an elapsed record during snapshot hydration; no timer or TTL lifecycle event removes an already accepted record.

Direct action-display close remains transient and does not enter the notification dismissal cache. The cache is synchronization state, not the authoritative notification record.

NotificationUiEffectObserver deduplicates notification effects by scope, notification identity, and revision and ignores terminal revisions. uiEffects.ts stores backend-keyed pending session and session-list invalidations. Matching mobile and desktop consumers claim one invalidation and reload authoritative data. An invalidation is consumed after a single reload attempt regardless of outcome: a successful reload acknowledges it, and a failed or rejected reload also removes it so a persistently failing reload is never replayed. This matters because pending invalidations are replayed to new subscribers, and consumers routinely resubscribe when their reload callbacks change identity across renders; replaying failed invalidations turns any persistent reload failure (for example a message range that no longer selects messages after session compaction) into an infinite retry and error-alert loop.

Claims live in backend-scoped SDK state rather than component-local state. This prevents React rerender or resubscription from starting duplicate reloads while the first reload is still in flight. Revision comparison prevents a late completion from clearing a newer invalidation.

Application-action definition invalidation uses a parallel backend-keyed pending revision. PluginsRegistry invalidates its cache, refreshes actions and application UI schema, and acknowledges after successful refresh.

These runtime invalidations are not persisted independently. A reconstructed frontend can recreate notification invalidation by observing the latest persisted pending notification revision.

Tests should distinguish portable contract coverage from TypeScript-specific details such as backend-keyed subscriptions and controller ownership.