@mpgd/platform 0.26.0 → 0.27.1

package/dist/notifications-runtime-support.d.ts

@@ -0,0 +1,20 @@
+import { type NotificationEvent, type NotificationNoticeIdentity, type RecordNotificationNoticeInput, type SetNotificationReminderInput } from './notifications.js';
+/**
+* Buffers an event for the first listener, keeping at most
+* `eventBufferLimit`: past it the oldest event that is not an open goes first,
+* so a cold-start open is not lost to later events.
+*/
+export declare function bufferEvent(buffer: NotificationEvent[], event: NotificationEvent): void;
+/** Calls every listener with every event, in order; returns the errors they threw. */
+export declare function deliverEach(listeners: readonly ((event: NotificationEvent) => void)[], events: readonly NotificationEvent[]): unknown[];
+/** A well-formed `notices.recordShown` input, or `NOTIFICATIONS_INVALID_INPUT`. */
+export declare function recordNoticeInputOf(input: unknown): RecordNotificationNoticeInput;
+/**
+* Only the fields that name a notice, with the record time in the canonical
+* form; a listed notice's `record.state` and `textVersion` are left out.
+*/
+export declare function noticeIdentityOf(notice: NotificationNoticeIdentity): NotificationNoticeIdentity;
+/** Why a reminder's input breaks the RFC bounds, or `undefined`. */
+export declare function reminderInputIssue(input: SetNotificationReminderInput): string | undefined;
+export declare function isBoundedText(value: unknown): boolean;
+export declare function describeError(error: unknown): string;

package/dist/notifications-runtime-support.js

@@ -0,0 +1,96 @@
+import { assertRecordNotificationNoticeInput, normalizeNotificationTimestamp, NotificationError, notificationKeyIssue, notificationTemplateDataIssue, } from './notifications.js';
+/**
+ * Helpers the notifications runtime and the conformance runner share. Not a
+ * package entry: `@mpgd/platform/notifications-runtime` and
+ * `@mpgd/platform/notifications-conformance` are.
+ */
+/** Events a provider or runtime keeps for its first listener. */
+const eventBufferLimit = 64;
+/**
+ * Buffers an event for the first listener, keeping at most
+ * `eventBufferLimit`: past it the oldest event that is not an open goes first,
+ * so a cold-start open is not lost to later events.
+ */
+export function bufferEvent(buffer, event) {
+    buffer.push(event);
+    if (buffer.length > eventBufferLimit) {
+        const evicted = buffer.findIndex((buffered) => buffered.type !== 'opened');
+        buffer.splice(evicted === -1 ? 0 : evicted, 1);
+    }
+}
+/** Calls every listener with every event, in order; returns the errors they threw. */
+export function deliverEach(listeners, events) {
+    const errors = [];
+    for (const event of events) {
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+    }
+    return errors;
+}
+/** A well-formed `notices.recordShown` input, or `NOTIFICATIONS_INVALID_INPUT`. */
+export function recordNoticeInputOf(input) {
+    try {
+        return assertRecordNotificationNoticeInput(input);
+    }
+    catch (error) {
+        throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+            message: 'A notice is a listed notice, or its kind, the kind and time of the record it reports '
+                + `on, and its dueBy: ${describeError(error)}`,
+            cause: error,
+        });
+    }
+}
+/**
+ * Only the fields that name a notice, with the record time in the canonical
+ * form; a listed notice's `record.state` and `textVersion` are left out.
+ */
+export function noticeIdentityOf(notice) {
+    return {
+        kind: notice.kind,
+        record: { kind: notice.record.kind, at: normalizeNotificationTimestamp(notice.record.at) },
+        dueBy: notice.dueBy,
+    };
+}
+/** Why a reminder's input breaks the RFC bounds, or `undefined`. */
+export function reminderInputIssue(input) {
+    const keyIssue = notificationKeyIssue(input.key);
+    if (keyIssue !== undefined) {
+        return `key: ${keyIssue}`;
+    }
+    if (timestampOrUndefined(input.fireAt) === undefined) {
+        return 'fireAt: expected RFC 3339 with an explicit offset';
+    }
+    if (input.templateData !== undefined) {
+        const issue = notificationTemplateDataIssue(input.templateData);
+        if (issue !== undefined) {
+            return `templateData: ${issue}`;
+        }
+    }
+    if (input.link !== undefined && !isBoundedText(input.link)) {
+        return 'link: expected a non-empty string';
+    }
+    return undefined;
+}
+export function isBoundedText(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 16_384;
+}
+function timestampOrUndefined(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    try {
+        return normalizeNotificationTimestamp(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function describeError(error) {
+    return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}

package/dist/notifications-runtime.d.ts

@@ -0,0 +1,262 @@
+import type { StorageAdapter } from './index.js';
+import { type CancelNotificationReminderInput, type NotificationConsentRecord, type NotificationDeliveryProviderEntry, type NotificationEndpointRegistration, type NotificationNotice, type NotificationNoticeIdentity, type NotificationProvider, type NotificationRuntime, type NotificationTopicDeclaration, type SetNotificationReminderInput } from './notifications.js';
+/** The authenticated session a backend serves; the backend binds the installation to it. */
+export interface NotificationRuntimeSession {
+  /** Stable for the session's life: refreshing the session keeps it. */
+  readonly id: string;
+  readonly player: 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.
+*/
+export type NotificationRuntimeReminderSetStatus = 'scheduled' | 'replaced' | 'permission-required' | 'request-missing' | 'preference-off' | 'advertising-consent-missing' | 'capacity-exceeded' | 'unavailable';
+/**
+* The backend surface the runtime calls for the authenticated session. Every
+* call acts for the session `session()` names when it is made; the backend
+* learns the session from its own authentication, never from a request field.
+* A call without a session, or for a session the backend no longer accepts,
+* throws `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`.
+*/
+export interface NotificationRuntimeBackend {
+  /** The authenticated session; `undefined` before authentication and after the session ends. */
+  session(): NotificationRuntimeSession | undefined;
+  /**
+  * Calls `listener` whenever a session starts, including a restored one and
+  * an account switch; returns the unsubscribe. Refreshing the same session
+  * (the same `id`) is not a start.
+  */
+  onAuthenticated(listener: (session: NotificationRuntimeSession) => 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. Unlike the other calls, it may answer without a request when
+  * `player` is no longer signed in: that session's end unbinds what it
+  * registered (the game-services client does).
+  */
+  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<NotificationRuntimeReminderSetStatus>;
+  /** 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 the game showed the session's player, named by its
+  * identity fields, while that notice is listed; recording one that is not
+  * listed changes nothing.
+  */
+  recordNotice(input: NotificationNoticeIdentity & {
+    readonly channel: 'in-game';
+  }): Promise<void>;
+}
+/** The last registration the backend acknowledged, with the player and session it was sent for. */
+export interface NotificationRuntimePersistedRegistration {
+  readonly registration: NotificationEndpointRegistration;
+  readonly player: string;
+  readonly session: string;
+  readonly at: string;
+}
+/** What the runtime keeps across restarts (RFC "Runtime", "Restarts"). */
+export interface NotificationRuntimeState {
+  /** The last registration the backend acknowledged. */
+  readonly registration?: NotificationRuntimePersistedRegistration;
+  /**
+  * Set by `unregister()`; `register()` or the next authentication clears it,
+  * including one the runtime did not observe (see `unboundSession`).
+  */
+  readonly unbound?: boolean;
+  /**
+  * With `unbound`: the session signed in when `unregister()` ran. Another
+  * session found at start or on a read, or any session when none was signed
+  * in then, is a sign-in the runtime did not observe, so it binds again.
+  */
+  readonly unboundSession?: {
+    readonly player: string;
+    readonly session: string;
+  };
+}
+/**
+* Where the runtime keeps its state across restarts. `load` runs once, when
+* the runtime is created, and again after a load that failed; a failed load
+* is reported by the call that needed the state. `save` runs after each
+* change, with the whole state. Either may answer synchronously. A value
+* `load` answers that is not a runtime state reads as an empty one. One
+* runtime owns a storage: a game with two runtimes gives each its own key.
+* The state holds the last registration as sent, push address included (an
+* FCM token): an address, not a credential, kept like other game data.
+*/
+export interface NotificationRuntimeStorage {
+  load(): unknown;
+  save(state: NotificationRuntimeState): void | Promise<void>;
+}
+/** The clock the runtime dates its records and registrations by (RFC 3339 instants). */
+export interface NotificationRuntimeClock {
+  now(): string;
+}
+export interface CreateNotificationRuntimeInput {
+  readonly provider: NotificationProvider;
+  readonly backend: NotificationRuntimeBackend;
+  /** The provider's topics, each with this target's mapping (`resolveNotificationTopicsForTarget`). */
+  readonly catalog: readonly NotificationTopicDeclaration[];
+  /** The catalog's default locale. */
+  readonly defaultLocale: string;
+  /** The device locale for local reminder copy; defaults to `defaultLocale`. */
+  readonly locale?: string;
+  /**
+  * The deployment's zone, for local quiet hours while the device has
+  * registered none; defaults to `notificationDefaultDeploymentTimeZone`.
+  */
+  readonly timeZone?: string;
+  /** Defaults to the system clock. */
+  readonly clock?: NotificationRuntimeClock;
+  /**
+  * Survives restarts. Without it the state lives in memory, so a restart
+  * re-sends the registration and forgets an `unregister()`; pass
+  * `createNotificationRuntimeStorage({ storage: gateway.storage })` or
+  * another durable port.
+  */
+  readonly storage?: NotificationRuntimeStorage;
+  /**
+  * The backend's registry entry for this provider. When the provider's
+  * capabilities disagree with it at start, every call throws
+  * `NOTIFICATIONS_CONFIGURATION_REQUIRED`, and nothing is registered, read,
+  * or recorded in the background either. `unregister()` is the exception:
+  * it still unbinds, since removing a device from a player is always safe. While a `loadRegistryEntry` is in
+  * flight, registrations (including `register()`, which then resolves
+  * before it is sent) and records that grant something wait without
+  * holding any queue, and go out when the load settles without a mismatch;
+  * withdrawals and refusals go out at once.
+  */
+  readonly registryEntry?: NotificationDeliveryProviderEntry;
+  /**
+  * Loads the registry entry when `start()` runs without `registryEntry`,
+  * for example from the game-services Worker's `GET /providers`. The load
+  * runs on its own: neither `start()` nor `runUntilIdle()` waits for it.
+  * Until it answers, reads, prompts, and local reminders run without the
+  * comparison, while registrations and granting records wait for it (see
+  * `registryEntry`). A load that fails is
+  * reported through `onError` and the next `runUntilIdle()`, and the runtime
+  * goes on without the entry, so a backend it cannot reach does not turn notifications off;
+  * the next `start()` loads it again. An entry once loaded is kept for the
+  * runtime's life.
+  */
+  readonly loadRegistryEntry?: () => Promise<NotificationDeliveryProviderEntry | undefined>;
+  /**
+  * Called with each failure of background work (records, registrations,
+  * local reminders, game listeners) as it happens; `runUntilIdle` still
+  * rethrows them. It runs synchronously: an error it throws, or a promise
+  * it returns, is ignored.
+  */
+  readonly onError?: (error: unknown) => void;
+}
+export interface NotificationRuntimeController 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>;
+}
+/** The storage key `createNotificationRuntimeStorage` uses by default. */
+export declare const defaultNotificationRuntimeStorageKey = "mpgd:notifications-runtime";
+/**
+* A `NotificationRuntimeStorage` over the platform storage adapter
+* (`gateway.storage`), one JSON value under `key`. The host owns its
+* durability; a failed load or save surfaces from the runtime call that
+* needed it as `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`.
+*/
+export declare function createNotificationRuntimeStorage(input: {
+  readonly storage: Pick<StorageAdapter, 'load' | 'save'>;
+  readonly key?: string;
+}): NotificationRuntimeStorage;
+/** A `NotificationRuntimeStorage` that lives in memory: nothing survives a restart. */
+export declare function createMemoryNotificationRuntimeStorage(): NotificationRuntimeStorage;
+/** A stored value as a runtime state; anything else reads as an empty state. */
+export declare function notificationRuntimeStateOf(value: unknown): NotificationRuntimeState;
+/**
+* Creates the notifications runtime (RFC "Runtime"): the provider composed
+* with the backend for the authenticated session. The conformance runner's
+* reference runtime is this one, so every vector exercises it.
+*
+* - 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, belongs to another session, or was never acknowledged (a
+*   first registration that failed). 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. A
+*   session found at start or on a read other than the one `unregister()`
+*   left (any session, when none was signed in then) is such an
+*   authentication even when the runtime did not observe it. While bound, a
+*   registration acknowledged for another session is sent again for this
+*   one, and so is, at start, one for a session with nothing acknowledged.
+* - 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.
+*/
+export declare function createNotificationRuntime(input: CreateNotificationRuntimeInput): NotificationRuntimeController;