@mpgd/platform 0.26.0 → 0.27.0

package/dist/notifications-conformance.d.ts

@@ -1,4 +1,5 @@
-import { type CancelNotificationReminderInput, type LocalNotificationEntry, type LocalNotificationRequest, type NotificationCapabilities, type NotificationConsentRecord, type NotificationDeliveryContent, type NotificationDeliveryOutcome, type NotificationDeliveryProviderEntry, type NotificationDeployment, type NotificationEndpointRegistration, type NotificationNotice, type NotificationNoticeIdentity, type NotificationNoticeSettings, type NotificationPermissionState, type NotificationProvider, type NotificationRuntime, type NotificationTemplateData, type NotificationTopicDeclaration, type NotificationTopicMapping, type SetNotificationReminderInput } from './notifications.js';
+import { type LocalNotificationEntry, type LocalNotificationRequest, type NotificationCapabilities, type NotificationConsentRecord, type NotificationDeliveryContent, type NotificationDeliveryOutcome, type NotificationDeliveryProviderEntry, type NotificationDeployment, type NotificationNotice, type NotificationNoticeIdentity, type NotificationNoticeSettings, type NotificationPermissionState, type NotificationProvider, type NotificationTemplateData, type NotificationTopicDeclaration, type NotificationTopicMapping } from './notifications.js';
+import { type NotificationRuntimeBackend, type NotificationRuntimeController, type NotificationRuntimePersistedRegistration, type NotificationRuntimeReminderSetStatus, type NotificationRuntimeSession } from './notifications-runtime.js';
 import { notificationConformanceDefaultLocale, type NotificationConformanceDeliverInput, type NotificationConformanceEndpointFixture, type NotificationConformanceHostFixture, type NotificationConformanceInstallationFixture, type NotificationConformanceProfile, type NotificationConformanceProfileLimits, type NotificationConformancePromptResult, type NotificationConformanceRejectionReason, type NotificationConformanceTapInput, type NotificationConformanceVector } from './notifications-vectors.js';
 /**
 * Notifications v2 conformance runner (RFC "Conformance vectors") with the
@@ -6,7 +7,8 @@ import { notificationConformanceDefaultLocale, type NotificationConformanceDeliv
 * with its fixture `NotificationProvider`; a fake backend that keeps sessions,
 * consent records, endpoints, server reminders, notices, and an idempotency
 * ledger, and applies the pure policy gate before every provider call; and the
-* reference notifications runtime the runner drives as the `game` actor. Pure
+* notifications runtime the runner drives as the `game` actor, which is the
+* production one from `@mpgd/platform/notifications-runtime`. Pure
 * in-process code: no Phaser, DOM, network, or SDK imports. Nothing here sends
 * a real notification or grants anything.
 *
@@ -121,49 +123,25 @@ export declare function notificationConformanceRegistryEntry(input: {
   readonly limits?: NotificationConformanceProfileLimits;
 }): NotificationDeliveryProviderEntry | undefined;
 /** An authenticated game-services session; its installation id is the session's, never a request's. */
-export interface NotificationConformanceSession {
-  readonly id: string;
-  readonly player: string;
+export interface NotificationConformanceSession extends NotificationRuntimeSession {
   readonly installationId: string;
 }
 /**
-* What setting a server reminder answers: stored, the gate step 3 to 5
-* refusal, `capacity-exceeded` past a backend's cap on a player's pending
-* reminders, or `unavailable` when no provider the player can be reached on
-* maps the topic. The fake backend answers only the first six.
+* What setting a server reminder answers (`NotificationRuntimeReminderSetStatus`).
+* The fake backend answers only the first six.
 */
-export type NotificationConformanceReminderSetStatus = 'scheduled' | 'replaced' | 'permission-required' | 'request-missing' | 'preference-off' | 'advertising-consent-missing' | 'capacity-exceeded' | 'unavailable';
+export type NotificationConformanceReminderSetStatus = NotificationRuntimeReminderSetStatus;
 export type NotificationConformanceNoticeChannel = 'in-game' | 'push' | 'other';
-/** The backend surface the runtime calls for the authenticated session. */
-export interface NotificationConformanceBackendClient {
+/**
+* The backend surface the runtime calls for the authenticated session
+* (`NotificationRuntimeBackend`), with the fixture session's installation and
+* every notice channel a backend under test records.
+*/
+export interface NotificationConformanceBackendClient extends NotificationRuntimeBackend {
   /** The authenticated session; `undefined` before authentication and after the session ends. */
   session(): NotificationConformanceSession | undefined;
   /** Calls `listener` whenever a session starts; returns the unsubscribe. */
   onAuthenticated(listener: (session: NotificationConformanceSession) => void): () => void;
-  /** Appends a record for the session's player; the backend stamps `at` with its own clock. */
-  recordConsent(record: NotificationConsentRecord): Promise<void>;
-  /** The session player's consent records, oldest first. */
-  listConsent(): Promise<readonly NotificationConsentRecord[]>;
-  /**
-  * Binds a device registration to the session's installation and player, or
-  * keeps a platform-user registration's locale and zone for the player.
-  */
-  registerEndpoint(registration: NotificationEndpointRegistration): Promise<void>;
-  /**
-  * Unbinds the session's installation from `player`, the player whose
-  * session sent the unbind; an installation another player took over since
-  * stays bound.
-  */
-  unregisterEndpoint(input: {
-    readonly provider: string;
-    readonly player: string;
-  }): Promise<void>;
-  /** Checks gate steps 3 to 5, then stores or replaces the session player's reminder with this key. */
-  setReminder(input: SetNotificationReminderInput): Promise<NotificationConformanceReminderSetStatus>;
-  /** Whether a pending reminder with this key, or a waiting send of one, existed. */
-  cancelReminder(input: CancelNotificationReminderInput): Promise<boolean>;
-  /** The session player's listed notices; none unless the deployment applies the Korean rules. */
-  listNotices(): Promise<readonly NotificationNotice[]>;
   /**
   * Records a notice given to the session's player, named by its identity
   * fields, while that notice is listed; recording one that is not listed
@@ -368,31 +346,25 @@ export interface CreateNotificationConformanceBackendInput {
 *   is retried on the next run, and one failing item never stops the others.
 */
 export declare function createNotificationConformanceBackend(input: CreateNotificationConformanceBackendInput): NotificationConformanceFakeBackend;
-export interface NotificationConformanceRuntime extends NotificationRuntime {
-  /**
-  * Subscribes to the provider and to authentication, compares the provider
-  * with its registry entry, and reconciles pending local reminders. Provider
-  * events are buffered for the game's first listener.
-  */
-  start(): Promise<void>;
-  /** Drops listeners, buffered events, and both subscriptions. */
-  stop(): void;
-  /** Waits for event-driven work (records, registrations, local reminders) and rethrows its first failure. */
-  runUntilIdle(): Promise<void>;
-}
-/** What the runtime keeps across restarts. */
+/**
+* The reference runtime the runner drives as the `game` actor: the
+* production runtime (`createNotificationRuntime` in
+* `@mpgd/platform/notifications-runtime`), so every vector exercises it.
+*/
+export type NotificationConformanceRuntime = NotificationRuntimeController;
+/** What the runtime keeps across restarts; the runner passes the same object to each restart. */
 export interface NotificationConformanceRuntimeStorage {
   /** The last registration the backend acknowledged. */
   registration?: NotificationConformancePersistedRegistration;
   /** Set by `unregister()`; `register()` or the next authentication clears it. */
   unbound?: boolean;
+  /** With `unbound`: the session signed in when `unregister()` ran. */
+  unboundSession?: {
+    readonly player: string;
+    readonly session: string;
+  };
 }
-export interface NotificationConformancePersistedRegistration {
-  readonly registration: NotificationEndpointRegistration;
-  readonly player: string;
-  readonly session: string;
-  readonly at: string;
-}
+export type NotificationConformancePersistedRegistration = NotificationRuntimePersistedRegistration;
 export interface CreateNotificationConformanceRuntimeInput {
   readonly provider: NotificationProvider;
   readonly backend: NotificationConformanceBackendClient;
@@ -404,7 +376,7 @@ export interface CreateNotificationConformanceRuntimeInput {
   readonly defaultLocale: string;
   /** The device locale for local reminder copy; defaults to `defaultLocale`. */
   readonly locale?: string;
-  /** Survives restarts; a fresh object when absent. */
+  /** Survives restarts; a fresh object when absent. The runtime writes it after each change. */
   readonly storage?: NotificationConformanceRuntimeStorage;
   /**
   * The backend's registry entry for this provider. When the provider's
@@ -414,64 +386,9 @@ export interface CreateNotificationConformanceRuntimeInput {
   readonly registryEntry?: NotificationDeliveryProviderEntry;
 }
 /**
-* The reference notifications runtime (RFC "Runtime"): the provider composed
-* with the backend for the authenticated session.
-*
-* - Reads return the provider snapshot. A topic the host reads `unknown`
-*   takes the latest record, `sources` says which answered, and a
-*   game-rendered consent that is not opted in reads `prompt` until a
-*   decision is recorded and `denied` after it. A topic whose mapping needs no
-*   agreement reads `granted`. A read that observes a changed decided state
-*   records it, and every read still answers when the backend cannot.
-* - Reads, requests, and revocations take each topic once, however often it
-*   is listed.
-* - Requests throw `NOTIFICATIONS_USER_GESTURE_REQUIRED` without a gesture on
-*   a gesture-only provider. An unsupported provider answers `unavailable`, a
-*   provider in `action-required` answers that with its `requiredAction`, an
-*   undeclared or unmapped topic answers `unavailable`, a topic that needs no
-*   agreement answers `already-granted`, and a topic the host reads `blocked`
-*   answers `blocked`, all without reaching the host; every other topic
-*   reaches the prompt.
-* - Records: decided states that differ from the latest record of their kind
-*   and scope, never `dismissed` or `action-required` answers. Device
-*   providers write none (the endpoint holds the permission), other app-scope
-*   providers write `delivery-permission`, and topic-scope providers write
-*   `host-agreement` with the host evidence, plus a `topic-preference` of
-*   `granted` when the player accepts a `requested` topic's agreement.
-*   Per-send acceptances are appended every time. A record belongs to the
-*   player signed in when the call or event began: one observed before
-*   authentication waits for it (only the latest per kind and scope), and one
-*   observed for a player waits for that player's session. A player action
-*   (`setTopicPreference`, `setAdvertisingConsent`) needs an authenticated
-*   player and throws `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` without one, as
-*   does every other backend call (a server reminder, `reminders.cancel`'s
-*   server part, and `notices`). A backend call belongs to the player signed
-*   in when it began and is refused when another player signed in since. A
-*   record the backend would refuse is dropped and its error surfaces.
-* - Registrations: the provider's registration goes to the backend at
-*   authentication, on `register()`, on `endpoint-changed` (a rotated device
-*   address, or a platform user's changed locale or zone), and when a read
-*   or request, or a revocation, changes the device's decided permission; and
-*   at start and on reads once the last one the backend acknowledged is older
-*   than 7 days. An identical one for the same player and session is skipped
-*   for 7 days, except on `register()`. `unregister()` unbinds the
-*   installation from the player signed in when it was called and cancels the
-*   pending local reminders, even when the unbind fails, and nothing binds it
-*   again, across restarts, until `register()` or the next authentication.
-* - Reminders: one key across both routes, and `cancel` removes it from each
-*   route that has it. Local ones pass the client gate steps (permission,
-*   then the topic preference from the backend, then quiet hours, which move
-*   them or refuse a topic that is not deferrable, then the topic's daily
-*   cap); server ones are checked and stored by the backend. Turning a topic off cancels its local
-*   reminders, a known permission other than granted cancels them, and start,
-*   authentication, and every backend read reconcile them with the catalog
-*   (a topic that no longer takes the local route loses its reminders), the
-*   latest preference, and permission.
-* - Game listeners run after the runtime's own handling of an event; a
-*   listener that throws stops neither the others nor the runtime, and its
-*   error surfaces from `runUntilIdle`, as do failures of background work:
-*   the first one, or an `AggregateError` that counts them all. `stop()` and
-*   a later `start()` buffer events for the next first subscriber again.
+* The production runtime over the conformance inputs: `storage` is a plain
+* object the runtime reads when it is created and rewrites after each
+* change, so a restart that passes the same object resumes from it.
 */
 export declare function createNotificationConformanceRuntime(input: CreateNotificationConformanceRuntimeInput): NotificationConformanceRuntime;
 export interface NotificationConformanceHarness {