@mpgd/game-services 0.24.1 → 0.25.0

package/dist/notifications/store.d.ts

@@ -0,0 +1,423 @@
+import { type NotificationConsentRecord, type NotificationDeferralReason, type NotificationDeliveryOutcome, type NotificationNoticeIdentity, type NotificationNoticeVariant, type NotificationPermissionState, type NotificationTemplateData } from '@mpgd/platform/notifications';
+import type { NotificationDeviceAddress } from './delivery-provider.js';
+/**
+* Persistence for the notifications service (notifications v2 RFC, "Server"):
+* consent records, the endpoint registry, platform-user registrations, the
+* notices given, the send ledger with its per-recipient rows, the delivery
+* history the gate's limits count, and the scheduler's entries (server
+* reminders and each player's notice check). The service owns every rule; a
+* store only keeps rows and answers the few atomic steps listed on each
+* method. `createInMemoryNotificationStore` is the reference implementation;
+* the game-services Worker ships a D1 one.
+*/
+/** Each member of a union without `key`. */
+type OmitEach<Union, Key extends PropertyKey> = Union extends unknown ? Omit<Union, Key> : never;
+/** A consent record before the backend dates it. */
+export type NotificationConsentRecordInput = OmitEach<NotificationConsentRecord, 'at'>;
+/** A device endpoint, keyed by provider and installation. */
+export interface NotificationStoredEndpoint {
+  readonly provider: string;
+  /** The registering session's installation id, never a request field. */
+  readonly installationId: string;
+  readonly player: string;
+  readonly address: NotificationDeviceAddress;
+  /** The device permission the latest registration reported. */
+  readonly permission: NotificationPermissionState;
+  readonly status: 'valid' | 'invalid';
+  readonly locale?: string;
+  readonly timeZone?: string;
+  /** The catalog target whose mapping applies to this device (`android`, `ios`). */
+  readonly target?: string;
+  /** The session that registered the endpoint; its end unbinds it. */
+  readonly sessionId: string;
+  /** When that session ends on its own; the endpoint counts as unbound from then. */
+  readonly sessionExpiresAt?: string;
+  readonly lastRegisteredAt: string;
+  readonly invalidatedAt?: string;
+}
+/** What a registration writes; the store decides `status`. */
+export type NotificationEndpointWrite = Omit<NotificationStoredEndpoint, 'status' | 'invalidatedAt'>;
+/** A platform-user registration: only the locale and zone; the recipient comes from the identity. */
+export interface NotificationPlatformRegistration {
+  readonly player: string;
+  readonly provider: string;
+  readonly locale?: string;
+  readonly timeZone?: string;
+  readonly registeredAt: string;
+}
+export type NotificationNoticeChannel = 'in-game' | 'push' | 'other';
+/** A notice given to a player: which notice (its name), how, and when. */
+export interface NotificationNoticeGiven extends NotificationNoticeIdentity {
+  readonly player: string;
+  readonly channel: NotificationNoticeChannel;
+  readonly at: string;
+}
+/** One delivered send, which the gate's frequency caps and provider limits count. */
+export interface NotificationHistoryEntry {
+  readonly sendKey: string;
+  readonly provider: string;
+  readonly player: string;
+  readonly topic: string;
+  readonly at: string;
+}
+/** The request a send key is bound to (`notificationSendFingerprint`). */
+export interface NotificationStoredSendRequest {
+  readonly idempotencyKey: string;
+  readonly player: string;
+  readonly provider?: string;
+  readonly topic: string;
+  readonly templateData?: NotificationTemplateData;
+  readonly data?: Readonly<Record<string, string>>;
+  readonly locale?: string;
+  readonly link?: string;
+}
+/** Why the send exists: a direct send, or a scheduler item (a server reminder or a consent notice). */
+export type NotificationSendOrigin = {
+  readonly kind: 'send';
+} | {
+  readonly kind: 'reminder';
+  readonly key: string;
+} | {
+  readonly kind: 'notice';
+  readonly notice: NotificationNoticeIdentity;
+  readonly variant: NotificationNoticeVariant;
+};
+/** Rate-limit backoff of one recipient, from its first `rate-limited` answer. */
+export interface NotificationRateLimitState {
+  readonly since: string;
+  readonly delaySeconds: number;
+  readonly attempts: number;
+}
+export type NotificationSendRowState = {
+  readonly status: 'delivered';
+} | {
+  readonly status: 'deferred';
+  readonly reason: NotificationDeferralReason;
+  readonly until: string;
+} | {
+  /**
+  * Claimed or waiting to be claimed. `claim` names the holder; a row
+  * without one is queued and was never sent. `attempted` turns true when
+  * a holder claimed it to call the provider, so an expired lease means
+  * the provider may have sent it.
+  */
+  readonly status: 'in-flight';
+  readonly leaseUntil: string;
+  readonly claim?: string;
+  readonly attempted: boolean;
+  /** When the latest holder claimed it to call the provider. */
+  readonly attemptedAt?: string;
+};
+/** One recipient's ledger delivery of a send. */
+export interface NotificationSendRow {
+  /** The ledger key: the send key, or `<send key>:<encodeURIComponent(installationId)>`. */
+  readonly key: string;
+  readonly provider: string;
+  /** The endpoint's installation, for device addressing. */
+  readonly installationId?: string;
+  readonly state: NotificationSendRowState;
+  readonly rateLimit?: NotificationRateLimitState;
+  /**
+  * When a claim that may have reached the provider first took the row. A
+  * deferral or a rate-limit answer, which prove nothing was sent, keep the
+  * earlier value, so ambiguous replays stop 24 hours after a real attempt.
+  */
+  readonly firstAttemptedAt?: string;
+  /** Ambiguous answers so far; each doubles the lease before the next replay. */
+  readonly ambiguousAttempts?: number;
+}
+/** A send key's stored state. */
+export interface NotificationStoredSend {
+  readonly key: string;
+  readonly fingerprint: string;
+  readonly request: NotificationStoredSendRequest;
+  readonly origin: NotificationSendOrigin;
+  /**
+  * Whether a scheduler item (a reminder or a notice) or a due replay owns
+  * the send. Every in-flight row whose lease ended is due either way, so no
+  * rule reads it; it tells an operator who made the send.
+  */
+  readonly scheduled: boolean;
+  readonly rows: readonly NotificationSendRow[];
+  /** Held while the first evaluation runs, before any row exists. */
+  readonly claim?: {
+    readonly token: string;
+    readonly leaseUntil: string;
+  };
+  readonly changedAt: string;
+}
+/** A stored send with the version a conditional write must name. */
+export interface NotificationVersionedSend {
+  readonly send: NotificationStoredSend;
+  readonly version: string;
+}
+export interface NotificationPurgeCutoffs {
+  /** Sends whose last change is older than this are forgotten (key retention). */
+  readonly sendsChangedBefore: string;
+  readonly historyBefore: string;
+  /** Endpoints invalidated before this are deleted. */
+  readonly invalidEndpointsBefore: string;
+  /** Endpoints last registered before this are deleted. */
+  readonly staleEndpointsBefore: string;
+  /** Endpoints whose session ended before this are deleted. */
+  readonly sessionEndpointsBefore: string;
+}
+export interface NotificationPurgeCounts {
+  readonly sends: number;
+  readonly history: number;
+  readonly endpoints: number;
+}
+/**
+* A server reminder a player set (RFC "Reminders"): one per player and key.
+* Once the scheduler turned it into its `reminder:` send it is `firedAt`,
+* no longer pending, and kept only so a later set or cancel can stop that
+* send while it still waits.
+*/
+export interface NotificationStoredReminder {
+  readonly kind: 'reminder';
+  readonly key: string;
+  readonly topic: string;
+  /** Canonical RFC 3339. */
+  readonly fireAt: string;
+  readonly templateData?: NotificationTemplateData;
+  readonly link?: string;
+  readonly firedAt?: string;
+  /** A fired reminder's send fingerprint (its content), which names the send it made. */
+  readonly fingerprint?: string;
+}
+/** When the scheduler next looks at a player's consent notices, with the backoff of refused pushes. */
+export interface NotificationNoticeCheck {
+  readonly kind: 'notices';
+  /** Notice pushes refused in a row; each refusal doubles the wait before the next try. */
+  readonly attempts: number;
+  /** Notice send keys whose push could not render; each fails once and is not tried again. */
+  readonly failed?: readonly string[];
+  /**
+  * Notice send keys the last check pushed: one that is gone at the next
+  * check while its notice is still owed was refused when it was sent.
+  */
+  readonly pushed?: readonly string[];
+}
+export type NotificationScheduleItem = NotificationStoredReminder | NotificationNoticeCheck;
+/**
+* One scheduler item of a player, named by `id` (`reminder:<key>` for a
+* reminder, `notices` for the notice check). The store keeps the item as
+* given and indexes `dueAt`; the service decides what it means.
+*/
+export interface NotificationScheduleEntry {
+  readonly player: string;
+  readonly id: string;
+  /** When the scheduler takes the entry next; an entry without one is never listed as due. */
+  readonly dueAt?: string;
+  readonly item: NotificationScheduleItem;
+}
+/** A schedule entry with the version a conditional write must name. */
+export interface NotificationVersionedScheduleEntry {
+  readonly entry: NotificationScheduleEntry;
+  readonly version: string;
+}
+export interface NotificationStore {
+  /**
+  * Appends a consent record for `player`, dated `at` or, when the player's
+  * latest record is not earlier, 1 ms after it, so a record's kind and time
+  * name it. Answers the stored record. Must be atomic per player.
+  */
+  appendConsent(input: {
+    readonly player: string;
+    readonly record: NotificationConsentRecordInput;
+    readonly at: string;
+  }): Promise<NotificationConsentRecord>;
+  /** The player's consent records, oldest first. */
+  listConsent(player: string): Promise<readonly NotificationConsentRecord[]>;
+  /**
+  * Deletes the player's consent records dated at these instants (each of a
+  * player's records has its own millisecond, so the instant names it), and
+  * the notices given that report on them, in one atomic step. Answers how
+  * many records it deleted. Callers never prune a player's latest record:
+  * `appendConsent` dates a new record after the latest one that is left, so
+  * an instant names one record for good only while the latest one stays.
+  */
+  pruneConsent(input: {
+    readonly player: string;
+    readonly at: readonly string[];
+  }): Promise<number>;
+  /**
+  * Binds a device endpoint, atomically: another installation's endpoint
+  * with the same provider and address value is removed (an address is
+  * unique per provider), and the endpoint stays `invalid` when its
+  * installation re-registers the same dead address; any other write is
+  * `valid`.
+  */
+  putEndpoint(endpoint: NotificationEndpointWrite): Promise<NotificationStoredEndpoint>;
+  listEndpoints(input: {
+    readonly player: string;
+    readonly provider: string;
+  }): Promise<readonly NotificationStoredEndpoint[]>;
+  getEndpoint(input: {
+    readonly provider: string;
+    readonly installationId: string;
+  }): Promise<NotificationStoredEndpoint | undefined>;
+  /** Marks the endpoint invalid while it still holds `value`. */
+  invalidateEndpoint(input: {
+    readonly provider: string;
+    readonly installationId: string;
+    readonly value: string;
+    readonly at: string;
+  }): Promise<void>;
+  /** Removes the installation's endpoints (of one provider, or all) that `player` holds. */
+  removeEndpoints(input: {
+    readonly installationId: string;
+    readonly player: string;
+    readonly provider?: string;
+  }): Promise<void>;
+  /** Removes every endpoint `sessionId` registered; answers how many. */
+  removeSessionEndpoints(input: {
+    readonly sessionId: string;
+  }): Promise<number>;
+  /**
+  * Moves the end of every endpoint `sessionId` registered to `expiresAt`
+  * where the stored end is earlier, or clears it when the session no longer
+  * ends on its own (`expiresAt` absent). An endpoint without an end keeps
+  * none, and no end moves earlier. Answers how many changed.
+  */
+  extendSessionEndpoints(input: {
+    readonly sessionId: string;
+    readonly expiresAt?: string;
+  }): Promise<number>;
+  putPlatformRegistration(registration: NotificationPlatformRegistration): Promise<void>;
+  getPlatformRegistration(input: {
+    readonly player: string;
+    readonly provider: string;
+  }): Promise<NotificationPlatformRegistration | undefined>;
+  /** Records a notice given; a notice already recorded for the player stays as it was. */
+  addNoticeGiven(notice: NotificationNoticeGiven): Promise<void>;
+  listNoticesGiven(player: string): Promise<readonly NotificationNoticeGiven[]>;
+  getSend(key: string): Promise<NotificationVersionedSend | undefined>;
+  /** Stores a new send; answers its version, or `undefined` when the key exists. */
+  createSend(send: NotificationStoredSend): Promise<string | undefined>;
+  /**
+  * Replaces (or, with `send: undefined`, deletes) the send while it still
+  * has `version`; answers whether it did. Every write gets a new version.
+  */
+  updateSend(input: {
+    readonly key: string;
+    readonly version: string;
+    readonly send: NotificationStoredSend | undefined;
+  }): Promise<boolean>;
+  /** The player's sends with at least one `in-flight` row. */
+  listInFlightSends(player: string): Promise<readonly NotificationStoredSend[]>;
+  /** Up to `limit` send keys with a row due at `at` (`notificationSendDueAt`), earliest first. */
+  listDueSends(input: {
+    readonly at: string;
+    readonly limit: number;
+  }): Promise<readonly string[]>;
+  /** Records a delivered send for one provider; a second record of the same pair is ignored. */
+  addHistory(entry: NotificationHistoryEntry): Promise<void>;
+  /** The player's deliveries at or after `since`, oldest first. */
+  listHistory(input: {
+    readonly player: string;
+    readonly since: string;
+  }): Promise<readonly NotificationHistoryEntry[]>;
+  /**
+  * How many deliveries every player received through `provider` at or
+  * after `since` and at or before `until`, for the scheduler's pacing. The
+  * upper bound leaves out deliveries dated after the run's time (the clock
+  * went back). It counts delivered sends only, so pacing is approximate
+  * while other sends are in flight.
+  */
+  countHistory(input: {
+    readonly provider: string;
+    readonly since: string;
+    readonly until: string;
+  }): Promise<number>;
+  getScheduleEntry(input: {
+    readonly player: string;
+    readonly id: string;
+  }): Promise<NotificationVersionedScheduleEntry | undefined>;
+  /**
+  * Stores a new entry; answers its version, or `undefined` when the player
+  * already has one with its id. A version is never reused, also after the
+  * entry is deleted and created again. The store deletes no entry on its
+  * own: the service removes a reminder or a notice check it is done with.
+  */
+  createScheduleEntry(entry: NotificationScheduleEntry): Promise<string | undefined>;
+  /**
+  * Replaces (or, with `entry: undefined`, deletes) the entry while it still
+  * has `version`; answers whether it did. Every write gets a new version.
+  * The entry is stored under `player` and `id`, whatever it names.
+  */
+  updateScheduleEntry(input: {
+    readonly player: string;
+    readonly id: string;
+    readonly version: string;
+    readonly entry: NotificationScheduleEntry | undefined;
+  }): Promise<boolean>;
+  /**
+  * How many of the player's entries are pending server reminders: an id
+  * that starts with `reminder:` and an item of kind `reminder` without
+  * `firedAt`. The service caps a player's pending reminders with it.
+  */
+  countPendingReminders(player: string): Promise<number>;
+  /**
+  * Up to `limit` entries whose `dueAt` is at or before `at`: earliest
+  * first, then by player and id.
+  */
+  listDueScheduleEntries(input: {
+    readonly at: string;
+    readonly limit: number;
+  }): Promise<readonly {
+    readonly player: string;
+    readonly id: string;
+  }[]>;
+  purge(cutoffs: NotificationPurgeCutoffs): Promise<NotificationPurgeCounts>;
+}
+type StoredOutcome = Extract<NotificationDeliveryOutcome, {
+  readonly status: 'delivered' | 'deferred' | 'in-flight';
+}>;
+export declare function notificationRowOutcome(row: NotificationSendRow): StoredOutcome;
+/** The highest-ranked outcome, the earliest among deferred ones, the first among equals. */
+export declare function bestNotificationOutcome<Outcome extends NotificationDeliveryOutcome>(outcomes: readonly Outcome[]): Outcome | undefined;
+/** A send's stored outcome: its best row, or `in-flight` while its first evaluation holds the claim. */
+export declare function notificationSendOutcome(send: NotificationStoredSend): StoredOutcome | undefined;
+/** How long an ambiguous delivery is replayed before it is left in flight. */
+export declare const notificationAmbiguousReplayHours = 24;
+/**
+* Whether an attempted row is past its replays: its lease would end a day
+* or more after its first attempt.
+*/
+export declare function isNotificationRowAbandoned(row: NotificationSendRow, leaseUntil: number): boolean;
+/**
+* Whether the scheduler may take a row at `at`: a deferred row once `until`
+* passed, and an in-flight row once its lease expired. That covers a queued
+* delivery whose message was lost, a claim whose holder failed before the
+* provider call, and an ambiguous answer, for a device endpoint, a scheduled
+* send, or a direct platform send whose caller never retries. Ambiguous
+* replays stop 24 hours after the first attempt.
+*/
+export declare function isNotificationRowDue(row: NotificationSendRow, at: number): boolean;
+/** When the scheduler may first take one of the send's rows, or `undefined` when none waits for it. */
+export declare function notificationSendDueAt(send: NotificationStoredSend): string | undefined;
+export declare function formatNotificationInstant(millis: number): string;
+/** The in-memory store's rows, for tests and conformance adapters. */
+export interface InMemoryNotificationStoreState {
+  readonly consent: readonly (NotificationConsentRecord & {
+    readonly player: string;
+  })[];
+  readonly endpoints: readonly NotificationStoredEndpoint[];
+  readonly platformRegistrations: readonly NotificationPlatformRegistration[];
+  readonly noticesGiven: readonly NotificationNoticeGiven[];
+  readonly sends: readonly NotificationStoredSend[];
+  readonly history: readonly NotificationHistoryEntry[];
+  readonly schedule: readonly NotificationScheduleEntry[];
+}
+export interface InMemoryNotificationStore extends NotificationStore {
+  /** A deep copy of every row, read synchronously. */
+  inspect(): InMemoryNotificationStoreState;
+}
+/**
+* A process-local store for tests, conformance runs, and local development.
+* Every method finishes its change before its first await, so concurrent
+* callers see each change whole. Production deployments use a durable store.
+*/
+export declare function createInMemoryNotificationStore(): InMemoryNotificationStore;
+export {};