@mpgd/game-services 0.24.1 → 0.25.1

package/dist/notifications/registry.d.ts

@@ -0,0 +1,86 @@
+import { type NotificationDeliveryProviderEntry, type NotificationDeployment, type NotificationNoticeSettings, type NotificationProviderRegistryEntry, type NotificationTopicDeclaration } from '@mpgd/platform/notifications';
+import type { NotificationDeviceAddress, NotificationRemoteDeliveryProvider } from './delivery-provider.js';
+/**
+* The server-side provider registry (notifications v2 RFC, "Provider
+* registry"): each delivery provider's registry entry, which is the policy
+* gate's only capability input, the provider that sends for it, and the
+* catalog targets whose mappings it reads.
+*/
+/** Days a delivery stays in the gate's history; no provider limit may count further back. */
+export declare const notificationHistoryRetentionDays = 30;
+export interface NotificationProviderRegistration {
+  /**
+  * The registry entry, as the backend publishes it. A
+  * `NotificationProviderRegistryEntry` also carries the mapping rules the
+  * catalog validator checks.
+  */
+  readonly entry: NotificationDeliveryProviderEntry | NotificationProviderRegistryEntry;
+  readonly delivery: NotificationRemoteDeliveryProvider;
+  /**
+  * The catalog targets this provider serves, in preference order. Each
+  * target's mapping is what the gate reads for a recipient on that target;
+  * two targets may share one provider (FCM on `android` and `ios`). Defaults
+  * to the reference targets of the entry's provider id
+  * (`referenceNotificationTargetProviders`).
+  */
+  readonly targets?: readonly string[];
+  /** For a device provider: the address kinds it can send to. Defaults to both FCM kinds. */
+  readonly addressKinds?: readonly NotificationDeviceAddress['kind'][];
+}
+export interface RegisteredNotificationProvider {
+  readonly entry: NotificationDeliveryProviderEntry;
+  readonly delivery: NotificationRemoteDeliveryProvider;
+  readonly targets: readonly string[];
+  readonly addressKinds: readonly NotificationDeviceAddress['kind'][];
+  /** The entry with mapping rules, for the catalog validator; empty rules when none were given. */
+  readonly validation: NotificationProviderRegistryEntry;
+}
+/** What the backend publishes, so a runtime can compare its provider's capabilities at start. */
+export interface NotificationProviderRegistrySnapshot {
+  readonly providers: readonly NotificationDeliveryProviderEntry[];
+  /** Each served target and the provider id that delivers to it. */
+  readonly targets: Readonly<Record<string, string>>;
+}
+export interface NotificationProviderRegistry {
+  readonly providers: readonly RegisteredNotificationProvider[];
+  provider(id: string): RegisteredNotificationProvider | undefined;
+  /** The provider a catalog target enables, if this backend serves the target. */
+  providerForTarget(target: string): RegisteredNotificationProvider | undefined;
+  /** A fresh copy of the published entries and targets. */
+  snapshot(): NotificationProviderRegistrySnapshot;
+}
+/**
+* Builds the registry and checks it once: one registration per provider id
+* and per target, an entry that passes `assertNotificationDeliveryProviderEntry`,
+* a delivery provider whose `id` equals the entry's `provider`, a
+* `readPermission` for a server-readable entry, provider limits no longer
+* than the delivery history keeps, and no `per-send` entry.
+*
+* Per-send providers (WeChat one-time subscriptions, not planned) need the
+* acceptance reserved in the same atomic step that claims the delivery, which
+* this backend does not implement, so they are refused rather than served
+* without the reservation.
+*/
+export declare function createNotificationProviderRegistry(registrations: readonly NotificationProviderRegistration[]): NotificationProviderRegistry;
+/**
+* The catalog as the notifications service reads it: the topics resolved for
+* one target, with that target's mapping, the default locale, and the
+* catalog's `notices` block taken as is.
+*/
+export interface NotificationServiceCatalog {
+  readonly defaultLocale: string;
+  readonly notices?: NotificationNoticeSettings;
+  topicsFor(target: string): readonly NotificationTopicDeclaration[];
+}
+/**
+* Validates a topic catalog against the registry's providers and the
+* deployment (`assertNotificationTopicCatalog` from `@mpgd/catalog`, with
+* each served target checked against its provider's mapping rules), and
+* resolves it per target. An invalid catalog throws one error listing every
+* issue, so a deployment never starts on a catalog the release validator
+* would refuse.
+*/
+export declare function createNotificationServiceCatalog(catalog: unknown, options: {
+  readonly registry: NotificationProviderRegistry;
+  readonly deployment?: NotificationDeployment;
+}): NotificationServiceCatalog;

package/dist/notifications/registry.js

@@ -0,0 +1,131 @@
+import { assertNotificationTopicCatalog, resolveNotificationTopicsForTarget, } from '@mpgd/catalog';
+import { assertNotificationDeliveryProviderEntry, assertNotificationDeployment, referenceNotificationTargetProviders, } from '@mpgd/platform/notifications';
+import { describeError as describe } from './text.js';
+/**
+ * The server-side provider registry (notifications v2 RFC, "Provider
+ * registry"): each delivery provider's registry entry, which is the policy
+ * gate's only capability input, the provider that sends for it, and the
+ * catalog targets whose mappings it reads.
+ */
+/** Days a delivery stays in the gate's history; no provider limit may count further back. */
+export const notificationHistoryRetentionDays = 30;
+const deviceAddressKinds = ['fcm-token', 'fcm-installation'];
+const maxHistoryWindowSeconds = notificationHistoryRetentionDays * 86_400;
+/**
+ * Builds the registry and checks it once: one registration per provider id
+ * and per target, an entry that passes `assertNotificationDeliveryProviderEntry`,
+ * a delivery provider whose `id` equals the entry's `provider`, a
+ * `readPermission` for a server-readable entry, provider limits no longer
+ * than the delivery history keeps, and no `per-send` entry.
+ *
+ * Per-send providers (WeChat one-time subscriptions, not planned) need the
+ * acceptance reserved in the same atomic step that claims the delivery, which
+ * this backend does not implement, so they are refused rather than served
+ * without the reservation.
+ */
+export function createNotificationProviderRegistry(registrations) {
+    const byId = new Map();
+    const byTarget = new Map();
+    for (const [index, registration] of registrations.entries()) {
+        const at = `providers[${index}]`;
+        const { mapping, ...plain } = registration.entry;
+        let entry;
+        try {
+            entry = structuredClone(assertNotificationDeliveryProviderEntry(plain));
+        }
+        catch (error) {
+            throw new TypeError(`${at}.entry is not a provider registry entry: ${describe(error)}`, {
+                cause: error,
+            });
+        }
+        if (registration.delivery.id !== entry.provider) {
+            throw new TypeError(`${at}: the delivery provider ${registration.delivery.id} is registered for entry ${entry.provider}.`);
+        }
+        if (byId.has(entry.provider)) {
+            throw new TypeError(`${at}: provider ${entry.provider} is registered twice.`);
+        }
+        if (entry.permission.allowance === 'per-send') {
+            throw new TypeError(`${at}: provider ${entry.provider} is per-send; this backend cannot reserve an acceptance atomically with the delivery claim.`);
+        }
+        if (entry.permission.serverReadable && registration.delivery.readPermission === undefined) {
+            throw new TypeError(`${at}: provider ${entry.provider} is server-readable but its delivery provider has no readPermission.`);
+        }
+        for (const limit of entry.limits ?? []) {
+            if (limit.windowSeconds > maxHistoryWindowSeconds) {
+                throw new TypeError(`${at}: a limit window of ${limit.windowSeconds} seconds is longer than the ${notificationHistoryRetentionDays}-day delivery history.`);
+            }
+        }
+        const targets = registration.targets
+            ?? Object.entries(referenceNotificationTargetProviders)
+                .filter(([, provider]) => provider === entry.provider)
+                .map(([target]) => target);
+        if (targets.length === 0 || new Set(targets).size !== targets.length) {
+            throw new TypeError(`${at}: provider ${entry.provider} needs its catalog targets, each once (no reference targets name it).`);
+        }
+        const addressKinds = registration.addressKinds ?? deviceAddressKinds;
+        if (entry.addressing === 'device' && addressKinds.length === 0) {
+            throw new TypeError(`${at}: device provider ${entry.provider} accepts no address kind.`);
+        }
+        const registered = {
+            entry,
+            delivery: registration.delivery,
+            targets: [...targets],
+            addressKinds: [...addressKinds],
+            validation: { ...structuredClone(entry), mapping: structuredClone(mapping ?? {}) },
+        };
+        for (const target of targets) {
+            const other = byTarget.get(target);
+            if (other !== undefined) {
+                throw new TypeError(`${at}: target ${target} is served by both ${other.entry.provider} and ${entry.provider}.`);
+            }
+            byTarget.set(target, registered);
+        }
+        byId.set(entry.provider, registered);
+    }
+    const providers = [...byId.values()];
+    return {
+        providers,
+        provider: (id) => byId.get(id),
+        providerForTarget: (target) => byTarget.get(target),
+        snapshot: () => ({
+            providers: providers.map((provider) => structuredClone(provider.entry)),
+            targets: Object.fromEntries([...byTarget].map(([target, provider]) => [target, provider.entry.provider])),
+        }),
+    };
+}
+/**
+ * Validates a topic catalog against the registry's providers and the
+ * deployment (`assertNotificationTopicCatalog` from `@mpgd/catalog`, with
+ * each served target checked against its provider's mapping rules), and
+ * resolves it per target. An invalid catalog throws one error listing every
+ * issue, so a deployment never starts on a catalog the release validator
+ * would refuse.
+ */
+export function createNotificationServiceCatalog(catalog, options) {
+    const deployment = options.deployment === undefined
+        ? undefined
+        : assertNotificationDeployment(options.deployment);
+    const targetProviders = {};
+    for (const provider of options.registry.providers) {
+        for (const target of provider.targets) {
+            targetProviders[target] = provider.validation;
+        }
+    }
+    const validated = assertNotificationTopicCatalog(catalog, {
+        targetProviders,
+        ...(deployment === undefined ? {} : { deployment }),
+    });
+    const resolved = new Map();
+    return {
+        defaultLocale: validated.defaultLocale,
+        ...(validated.notices === undefined ? {} : { notices: validated.notices }),
+        topicsFor(target) {
+            let topics = resolved.get(target);
+            if (topics === undefined) {
+                topics = resolveNotificationTopicsForTarget(validated, target);
+                resolved.set(target, topics);
+            }
+            return topics;
+        },
+    };
+}

package/dist/notifications/service.d.ts

@@ -0,0 +1,222 @@
+import { NotificationError, type NotificationConsentRecord, type NotificationDeliveryOutcome, type NotificationDeployment, type NotificationNotice, type NotificationTemplateData } from '@mpgd/platform/notifications';
+import { type NotificationProviderRegistry, type NotificationProviderRegistrySnapshot, type NotificationServiceCatalog } from './registry.js';
+import { type NotificationNoticeChannel, type NotificationPurgeCounts, type NotificationStore } from './store.js';
+/**
+* Client-written consent records a player may add per rolling day. It is
+* generous: it only stops a client that writes in a loop, since every send
+* reads the player's whole history. It is checked before the write, so
+* concurrent writes may pass it by a few.
+*/
+export declare const maxClientNotificationConsentRecordsPerDay = 200;
+/**
+* Pending server reminders a player may keep, as many as iOS keeps local
+* notifications. Replacing a pending one is always allowed; a new key past
+* it answers `capacity-exceeded`. The count is read before the write, so
+* sets that race may pass it by a few, as the daily consent cap may.
+*/
+export declare const maxPendingNotificationReminders = 64;
+/** How far ahead a server reminder may be set; a later `fireAt` is refused. */
+export declare const notificationReminderHorizonDays = 90;
+/** An authenticated game-services session, as the deployment's identity service resolves it. */
+export interface NotificationSession {
+  readonly player: string;
+  /** Stable for the session's life (its refresh family); its end unbinds what it registered. */
+  readonly sessionId: string;
+  /** The guest session's installation id. */
+  readonly installationId: string;
+  /**
+  * When the session ends on its own, RFC 3339; endpoints it registered
+  * count as unbound from then. Each call moves their stored end to a later
+  * one (or clears it when this is absent), never to an earlier one.
+  */
+  readonly expiresAt?: string;
+}
+/** A send request from the game's server (never from a client). */
+export interface NotificationDeliverInput {
+  readonly idempotencyKey: string;
+  readonly player: string;
+  readonly topic: string;
+  /** One provider; without it the send goes to every provider the player has a recipient on. */
+  readonly provider?: string;
+  readonly templateData?: Readonly<Record<string, string | number | boolean>>;
+  /** Untrusted routing data the open carries. */
+  readonly data?: Readonly<Record<string, string>>;
+  readonly locale?: string;
+  /** A post or comment id for providers whose sends need one (Devvit). */
+  readonly link?: string;
+}
+/** One recipient's delivery to run: a send key and its row. */
+export interface NotificationDispatchJob {
+  readonly sendKey: string;
+  readonly provider: string;
+  readonly rowKey: string;
+}
+/** A queue that runs each job later through `NotificationService.dispatch` (a Cloudflare Queue). */
+export interface NotificationDispatchQueue {
+  enqueue(jobs: readonly NotificationDispatchJob[]): Promise<void>;
+}
+export interface CreateNotificationServiceInput {
+  readonly store: NotificationStore;
+  readonly registry: NotificationProviderRegistry;
+  readonly catalog: NotificationServiceCatalog;
+  readonly deployment?: NotificationDeployment;
+  /**
+  * The recipient id of a platform-user provider for a player, from the
+  * player's authenticated identity on that platform; `undefined` when the
+  * player has none.
+  */
+  readonly resolvePlatformRecipient?: (input: {
+    readonly provider: string;
+    readonly player: string;
+  }) => string | undefined | Promise<string | undefined>;
+  /**
+  * Runs dispatch jobs later, so a fan-out never exceeds one invocation's
+  * subrequest limit. Without it every job runs inline before `deliver`
+  * answers.
+  */
+  readonly queue?: NotificationDispatchQueue;
+  readonly now?: () => string;
+  /**
+  * A monotonic clock in milliseconds that bounds one scheduler run's wall
+  * time (`runScheduler`'s `budgetMs`); `performance.now()` by default.
+  */
+  readonly elapsedMs?: () => number;
+  /** Jitter for repeated rate-limit backoff, in [0, 1). */
+  readonly random?: () => number;
+  /** How long a claim holds a delivery before another worker may replay it; 300 by default. */
+  readonly claimLeaseSeconds?: number;
+  /** Errors the service handles without failing the call, such as a queue that refused a job. */
+  readonly onError?: (error: unknown, context: {
+    readonly operation: string;
+    readonly sendKey?: string;
+    readonly provider?: string;
+    readonly rowKey?: string;
+    /**
+    * True when the error is a delivery provider's own failure, whose
+    * message may quote a device token or a credential: log its name only.
+    */
+    readonly fromProvider?: boolean;
+  }) => void;
+}
+export interface NotificationDueResult {
+  readonly sendKey: string;
+  /** The send's result after the replay. */
+  readonly outcome: NotificationDeliveryOutcome;
+}
+/** A server reminder as a game sets it (RFC `reminders.set`, with the time already in the request). */
+export interface NotificationReminderInput {
+  readonly key: string;
+  readonly topic: string;
+  /** RFC 3339 with an explicit offset. */
+  readonly fireAt: string;
+  readonly templateData?: NotificationTemplateData;
+  /** A post or comment id for providers whose sends need a link (Devvit). */
+  readonly link?: string;
+}
+/** What setting a server reminder answers: stored, or the refusal of gate steps 3 to 5. */
+export type NotificationReminderSetStatus = 'scheduled' | 'replaced' | 'permission-required' | 'request-missing' | 'preference-off' | 'advertising-consent-missing'
+/** The player keeps `maxPendingNotificationReminders` pending reminders already. */
+| 'capacity-exceeded'
+/** No provider the player can be reached on maps the topic for its target. */
+| 'unavailable';
+export interface NotificationService {
+  /** The registry entries and served targets the backend publishes. */
+  providers(): NotificationProviderRegistrySnapshot;
+  /**
+  * Appends a consent record for the session's player, dated by the backend.
+  * A repeat of the player's latest permission, agreement, or preference
+  * record for the same kind and topic answers that record unwritten; an
+  * `advertising` or `night` record is always written, even a repeat, and
+  * counts toward the cap. A player past
+  * `maxClientNotificationConsentRecordsPerDay` gets a
+  * `NotificationConsentRateLimitError`.
+  */
+  recordConsent(session: NotificationSession, record: unknown): Promise<NotificationConsentRecord>;
+  listConsent(session: NotificationSession): Promise<readonly NotificationConsentRecord[]>;
+  /**
+  * Binds a device registration to the session's installation and player, or
+  * keeps a platform-user registration's locale and zone. `target` names the
+  * catalog target whose mapping applies to the device when two targets share
+  * a provider (FCM on `android` and `ios`).
+  */
+  registerEndpoint(session: NotificationSession, input: {
+    readonly registration: unknown;
+    readonly target?: string;
+  }): Promise<void>;
+  /** Unbinds the session's installation from the session's player (one provider, or all). */
+  unregisterEndpoint(session: NotificationSession, input?: {
+    readonly provider?: string;
+  }): Promise<void>;
+  /** The session ended (logout, revocation): every endpoint it registered is unbound. */
+  endSession(input: {
+    readonly sessionId: string;
+  }): Promise<void>;
+  /** The session player's listed notices; none unless the deployment applies the Korean rules. */
+  listNotices(session: NotificationSession): Promise<readonly NotificationNotice[]>;
+  /** Records a listed notice the game showed; a notice that is not listed changes nothing. */
+  recordNoticeShown(session: NotificationSession, notice: unknown, input?: {
+    readonly channel?: Exclude<NotificationNoticeChannel, 'push'>;
+  }): Promise<void>;
+  /** One send through the ledger, the gate, and the providers. */
+  deliver(input: unknown): Promise<NotificationDeliveryOutcome>;
+  /** Runs one queued dispatch job; a job that is no longer due does nothing. */
+  dispatch(job: NotificationDispatchJob): Promise<void>;
+  /**
+  * Replays up to `limit` sends with a due row, at no more than each
+  * provider's registry `rate`: through the queue when one is bound (each
+  * row is taken for its lease and enqueued), inline otherwise. One failing
+  * send never stops the others.
+  */
+  dispatchDue(input?: {
+    readonly limit?: number;
+  }): Promise<{
+    readonly results: readonly NotificationDueResult[];
+    readonly failed: number;
+  }>;
+  /**
+  * Sets the session player's server reminder (RFC "Reminders"). Gate steps
+  * 3 to 5 run first against the backend's records, the device permission
+  * each endpoint reported, or the host read, for any provider the player
+  * can be reached on; a refusal stores nothing. Otherwise the reminder with
+  * this key is stored or replaced, and a send of the previous one that
+  * still waits (deferred or in flight) is stopped.
+  */
+  setReminder(session: NotificationSession, input: unknown): Promise<{
+    readonly status: NotificationReminderSetStatus;
+  }>;
+  /**
+  * Removes the session player's reminder with this key and stops a send of
+  * it that still waits; answers whether either existed.
+  */
+  cancelReminder(session: NotificationSession, input: unknown): Promise<{
+    readonly cancelled: boolean;
+  }>;
+  /**
+  * One scheduler run, in rounds: each takes up to `limit` due schedule
+  * entries (server reminders become `reminder:` sends; each player's notice
+  * check pushes the consent notices owed by now), then `dispatchDue` with
+  * the same `limit`. Rounds go on while a round filled a batch and got
+  * somewhere, until `budgetMs` of wall time (20 seconds by default) is used.
+  * Answers each send it touched with its result after the run, in the order
+  * it first touched them.
+  */
+  runScheduler(input?: {
+    readonly limit?: number;
+    readonly budgetMs?: number;
+  }): Promise<{
+    readonly results: readonly NotificationDueResult[];
+    readonly failed: number;
+  }>;
+  /** Forgets keys after 30 days, the history past the limit windows, and dead or stale endpoints. */
+  purge(): Promise<NotificationPurgeCounts>;
+}
+/**
+* A player wrote more consent records than one rolling day allows. It is
+* retryable after `retryAfterSeconds`, when the oldest counted record leaves
+* the window.
+*/
+export declare class NotificationConsentRateLimitError extends NotificationError {
+  readonly retryAfterSeconds: number;
+  constructor(retryAfterSeconds: number);
+}
+export declare function createNotificationService(input: CreateNotificationServiceInput): NotificationService;