@mpgd/game-services 0.25.1 → 0.27.0

package/dist/notifications/client.js

@@ -0,0 +1,432 @@
+import { assertNotificationConsentRecord, assertNotificationDeliveryProviderEntry, assertNotificationNotice, isNotificationErrorCode, NotificationError, } from '@mpgd/platform/notifications';
+import { GameServicesHeaderResolutionError, resolveGameServicesRequestHeaders, } from '../request-headers.js';
+/**
+ * The game-services notifications client: the notifications runtime's
+ * backend (`NotificationRuntimeBackend` from
+ * `@mpgd/platform/notifications-runtime`) over the game-services Worker's
+ * session routes under `/game-services/notifications` (see
+ * docs/CLOUDFLARE_WORKER_DEPLOY.md, "Sessions" and "Client routes").
+ *
+ * The Worker learns the player, the session, and the installation from the
+ * `Authorization` header alone, through its `GAME_SERVICES_NOTIFICATIONS_AUTH`
+ * binding (the identity Worker's `authenticateNotificationSession`); no
+ * request carries a player or an installation. The client learns which
+ * session is current from the game's identity, which also supplies the
+ * header through the same resolver the game gives its commerce client.
+ *
+ * No platform SDK, DOM, or Phaser import: only `fetch`.
+ */
+/** The Worker's route prefix for notifications. */
+export const gameServicesNotificationsRoutePrefix = '/game-services/notifications';
+/** The default `timeoutMs`: a request still unanswered after this is aborted. */
+export const defaultGameServicesNotificationsTimeoutMs = 15_000;
+/**
+ * A failed notifications request, with the `NotificationError` code the
+ * runtime acts on and what the Worker answered.
+ *
+ * - 401: the session is not authenticated (signed out, token expired, or
+ *   the session ended): `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`, retryable
+ *   once the game has a session again.
+ * - 404 on a session route: the Worker serves no notifications for sessions
+ *   (no catalog, or no `GAME_SERVICES_NOTIFICATIONS_AUTH` binding), and 405:
+ *   the Worker does not serve this client's routes;
+ *   `NOTIFICATIONS_CONFIGURATION_REQUIRED`, not retryable.
+ * - 400 and 413: `NOTIFICATIONS_INVALID_INPUT` (or the code the Worker names).
+ * - 408, 425, 429, and 503: `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`. The
+ *   runtime retries at its next trigger (a read, a start, a sign-in), not
+ *   on the Worker's `Retry-After`, which the client does not read.
+ * - Another status names the code the Worker answered when it is a
+ *   notifications code (a Worker whose notifications configuration is
+ *   broken answers 500 with `NOTIFICATIONS_CONFIGURATION_REQUIRED`, not
+ *   retryable); otherwise a 5xx is `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`
+ *   and a 4xx `NOTIFICATIONS_CONFIGURATION_REQUIRED`.
+ * - A 2xx whose body is not JSON, or is empty (a captive portal or proxy
+ *   answered): `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` with that status. A
+ *   2xx with JSON outside the route's contract:
+ *   `NOTIFICATIONS_CONFIGURATION_REQUIRED`.
+ * - `status` 0, `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`, nothing sent: no
+ *   signed-in player with a session id, the header resolver failed or did
+ *   not settle within `timeoutMs`, or the player signed out or changed
+ *   while the headers were resolved.
+ * - `status` 0, `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`, no answer read: the
+ *   request failed in transit, timed out (`timeoutMs`), or its body could
+ *   not be read, so the Worker may have handled it. Retrying may repeat it: reminders and endpoints
+ *   replace by key, but an advertising or night consent record is written
+ *   again.
+ */
+export class GameServicesNotificationsRequestError extends NotificationError {
+    /** The HTTP status, or 0 when no answer arrived. */
+    status;
+    /** The route, such as `/consent`. */
+    route;
+    /** The `error` the Worker answered, such as `UNAUTHORIZED`. */
+    serverCode;
+    constructor(input) {
+        super(input.code, {
+            message: input.message,
+            ...(input.cause === undefined ? {} : { cause: input.cause }),
+        });
+        this.status = input.status;
+        this.route = input.route;
+        this.serverCode = input.serverCode;
+    }
+}
+/** The player changed while a request's headers were resolved; nothing was sent. */
+class NotificationsPlayerChangedError extends GameServicesNotificationsRequestError {
+}
+const reminderSetStatuses = [
+    'scheduled',
+    'replaced',
+    'permission-required',
+    'request-missing',
+    'preference-off',
+    'advertising-consent-missing',
+    'capacity-exceeded',
+    'unavailable',
+];
+/**
+ * Creates the client. Every session call needs a current session and sends
+ * the headers the resolver gives for it; without a session it throws
+ * `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` and sends nothing.
+ */
+export function createGameServicesNotificationsClient(input) {
+    const baseUrl = input.baseUrl.trim().replace(/\/+$/u, '');
+    if (baseUrl.length === 0) {
+        throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+            message: 'The game-services notifications client needs a baseUrl.',
+        });
+    }
+    const { identity } = input;
+    const timeoutMs = input.timeoutMs ?? defaultGameServicesNotificationsTimeoutMs;
+    // setTimeout takes at most 2^31 - 1 ms; a longer delay would fire at once.
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+            message: 'The notifications client timeoutMs must be a positive number of milliseconds, at most 2147483647.',
+        });
+    }
+    if (input.target !== undefined && (typeof input.target !== 'string' || input.target.length === 0)) {
+        throw new NotificationError('NOTIFICATIONS_INVALID_INPUT', {
+            message: 'The notifications client target must be a non-empty string.',
+        });
+    }
+    const sessionOf = (session) => session !== undefined
+        && typeof session.playerId === 'string'
+        && session.playerId.length > 0
+        && typeof session.sessionId === 'string'
+        && session.sessionId.length > 0
+        ? { id: session.sessionId, player: session.playerId }
+        : undefined;
+    const requireSession = (route) => {
+        const session = sessionOf(identity.current());
+        if (session === undefined) {
+            throw new GameServicesNotificationsRequestError({
+                code: 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE',
+                route,
+                status: 0,
+                message: `${route} needs a signed-in player; no request was sent.`,
+            });
+        }
+        return session;
+    };
+    /**
+     * Sends one request. For a session route, `session` is the session the call
+     * began for: if another player is signed in once the headers are resolved
+     * (an account switch during a token refresh), nothing is sent, so one
+     * player's call never goes out with the next player's credentials. The
+     * same player under a new session id (an identity whose id rotates on
+     * refresh) still sends: the Worker reads the session from the header.
+     */
+    const request = async (route, method, body, session) => {
+        const fetcher = input.fetch ?? globalFetch();
+        // One deadline for the whole request, from resolving its headers to
+        // reading its answer: at the deadline the fetch is aborted and the call
+        // answers, even when a header resolver or a fetch never settles, so no
+        // runtime queue waits on it.
+        const controller = typeof AbortController === 'function' ? new AbortController() : undefined;
+        let timer;
+        let timedOut = false;
+        const deadline = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                timedOut = true;
+                reject(new Error(`no answer within ${timeoutMs} ms`));
+                try {
+                    controller?.abort();
+                }
+                catch {
+                    // The call has answered already.
+                }
+            }, timeoutMs);
+        });
+        deadline.catch(() => undefined);
+        try {
+            let headers;
+            try {
+                headers = await Promise.race([
+                    resolveGameServicesRequestHeaders({
+                        headers: input.headers,
+                        // The public registry read needs no credentials, so it works signed out.
+                        getHeaders: session === undefined ? undefined : input.getHeaders,
+                    }),
+                    deadline,
+                ]);
+            }
+            catch (error) {
+                throw new GameServicesNotificationsRequestError({
+                    code: 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE',
+                    route,
+                    status: 0,
+                    message: timedOut
+                        ? `${route}: the session's request headers were not resolved within ${timeoutMs} ms; no request was sent.`
+                        : `${route}: the session's request headers could not be resolved; no request was sent.`,
+                    cause: error instanceof GameServicesHeaderResolutionError ? error : undefined,
+                });
+            }
+            if (session !== undefined) {
+                const now = sessionOf(identity.current());
+                if (now === undefined || now.player !== session.player) {
+                    throw new NotificationsPlayerChangedError({
+                        code: 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE',
+                        route,
+                        status: 0,
+                        message: `${route}: the player signed out or changed while the request headers were resolved; `
+                            + 'no request was sent.',
+                    });
+                }
+            }
+            try {
+                const response = await Promise.race([
+                    fetcher(`${baseUrl}${gameServicesNotificationsRoutePrefix}${route}`, {
+                        method,
+                        headers: method === 'POST'
+                            ? { ...headers, 'content-type': 'application/json' }
+                            : { ...headers },
+                        ...(method === 'POST' ? { body: JSON.stringify(body) } : {}),
+                        ...(controller === undefined ? {} : { signal: controller.signal }),
+                    }),
+                    deadline,
+                ]);
+                return { response, text: await Promise.race([response.text(), deadline]) };
+            }
+            catch (error) {
+                throw new GameServicesNotificationsRequestError({
+                    code: 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE',
+                    route,
+                    status: 0,
+                    message: timedOut
+                        ? `${route}: the game-services Worker did not answer within ${timeoutMs} ms; the client stopped waiting `
+                            + '(and aborted the fetch, where it takes a signal).'
+                        : `${route}: the game-services Worker could not be reached.`,
+                    cause: error,
+                });
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    /** Sends one request and reads its answer as the route's JSON object. */
+    const call = async (route, method, body, session) => {
+        const { response, text } = await request(route, method, body, session);
+        const parsed = parseJson(text);
+        if (response.status >= 200 && response.status < 300) {
+            if (parsed === 'not-json') {
+                // A success page that is not JSON, or an empty one (a 204), came from
+                // something in between (a captive portal, a proxy), not from the
+                // Worker, which always answers a JSON object: try again later.
+                throw new GameServicesNotificationsRequestError({
+                    code: 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE',
+                    route,
+                    status: response.status,
+                    message: `${route}: the answer was not JSON; something between the game and the Worker answered.`,
+                });
+            }
+            if (parsed === undefined) {
+                throw contractBroken(route, response.status, 'the answer is not a JSON object');
+            }
+            return parsed;
+        }
+        throw errorOf(route, response, parsed === 'not-json' ? undefined : parsed);
+    };
+    return {
+        session: () => sessionOf(identity.current()),
+        onAuthenticated(listener) {
+            // The session already current when the runtime subscribes is not a new
+            // authentication; a later refresh of it is not either.
+            let announced = sessionOf(identity.current());
+            return identity.onAuthenticated((session) => {
+                const next = sessionOf(session);
+                if (next === undefined || (announced?.id === next.id && announced.player === next.player)) {
+                    return;
+                }
+                announced = next;
+                listener(next);
+            });
+        },
+        async recordConsent(record) {
+            const session = requireSession('/consent');
+            const answer = await call('/consent', 'POST', { record }, session);
+            checked('/consent', () => assertNotificationConsentRecord(answer['record']));
+        },
+        async listConsent() {
+            const session = requireSession('/consent');
+            const answer = await call('/consent', 'GET', undefined, session);
+            const records = answer['records'];
+            if (!Array.isArray(records)) {
+                throw contractBroken('/consent', 200, 'records is not a list');
+            }
+            return records.map((record) => checked('/consent', () => assertNotificationConsentRecord(record)));
+        },
+        async registerEndpoint(registration) {
+            const session = requireSession('/endpoints');
+            await call('/endpoints', 'POST', { registration, ...(input.target === undefined ? {} : { target: input.target }) }, session);
+        },
+        async unregisterEndpoint({ provider, player }) {
+            const session = sessionOf(identity.current());
+            if (session === undefined || session.player !== player) {
+                // The Worker unbinds the session's installation from the session's
+                // player. Another player's session must not send it: the leaving
+                // player's session already ended, and its end unbound what it registered.
+                return;
+            }
+            try {
+                await call('/endpoints/unregister', 'POST', { provider }, session);
+            }
+            catch (error) {
+                // The player left while the headers were resolved, so nothing was
+                // sent: as above, the session's end unbinds what it registered. A
+                // request that went out and failed is the caller's to see.
+                if (error instanceof NotificationsPlayerChangedError) {
+                    return;
+                }
+                throw error;
+            }
+        },
+        async setReminder(reminder) {
+            const session = requireSession('/reminders');
+            const answer = await call('/reminders', 'POST', { reminder }, session);
+            const status = answer['status'];
+            if (!reminderSetStatuses.includes(status)) {
+                throw contractBroken('/reminders', 200, `status ${JSON.stringify(status)} is not a reminder status`);
+            }
+            return status;
+        },
+        async cancelReminder({ key }) {
+            const session = requireSession('/reminders/cancel');
+            const answer = await call('/reminders/cancel', 'POST', { key }, session);
+            if (typeof answer['cancelled'] !== 'boolean') {
+                throw contractBroken('/reminders/cancel', 200, 'cancelled is not a boolean');
+            }
+            return answer['cancelled'];
+        },
+        async listNotices() {
+            const session = requireSession('/notices');
+            const answer = await call('/notices', 'GET', undefined, session);
+            const notices = answer['notices'];
+            if (!Array.isArray(notices)) {
+                throw contractBroken('/notices', 200, 'notices is not a list');
+            }
+            return notices.map((notice) => checked('/notices', () => assertNotificationNotice(notice)));
+        },
+        async recordNotice({ channel, kind, record, dueBy }) {
+            const session = requireSession('/notices/shown');
+            await call('/notices/shown', 'POST', { notice: { kind, record, dueBy }, channel }, session);
+        },
+        async getProviders() {
+            const answer = await call('/providers', 'GET', undefined, undefined);
+            const { protocolVersion, providers, targets } = answer;
+            if (typeof protocolVersion !== 'string'
+                || !Array.isArray(providers)
+                || typeof targets !== 'object'
+                || targets === null
+                || Array.isArray(targets)
+                || !Object.values(targets).every((provider) => typeof provider === 'string')) {
+                throw contractBroken('/providers', 200, 'the registry is not { protocolVersion, providers, targets }');
+            }
+            return {
+                protocolVersion,
+                providers: providers.map((entry) => checked('/providers', () => assertNotificationDeliveryProviderEntry(entry))),
+                targets: { ...targets },
+            };
+        },
+    };
+}
+function globalFetch() {
+    const fetcher = globalThis.fetch;
+    if (fetcher === undefined) {
+        throw new NotificationError('NOTIFICATIONS_CONFIGURATION_REQUIRED', {
+            message: 'globalThis.fetch is unavailable; give the notifications client a fetch.',
+        });
+    }
+    return fetcher;
+}
+/** The JSON object an answer holds, `undefined` for other JSON, or `'not-json'`. */
+function parseJson(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return 'not-json';
+    }
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+        ? parsed
+        : undefined;
+}
+/** An answer that breaks the route's contract: the Worker, not the game, is wrong. */
+function contractBroken(route, status, issue) {
+    return new GameServicesNotificationsRequestError({
+        code: 'NOTIFICATIONS_CONFIGURATION_REQUIRED',
+        route,
+        status,
+        message: `${route}: the game-services Worker answered outside the notifications contract: ${issue}.`,
+    });
+}
+function checked(route, read) {
+    try {
+        return read();
+    }
+    catch (error) {
+        throw contractBroken(route, 200, error instanceof Error ? error.message : String(error));
+    }
+}
+function errorOf(route, response, body) {
+    const { status } = response;
+    const serverCode = typeof body?.['error'] === 'string' ? body['error'] : undefined;
+    const serverMessage = typeof body?.['message'] === 'string' ? body['message'] : undefined;
+    let code;
+    let message;
+    if (status === 401) {
+        code = 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE';
+        message = `${route}: the game-services session is not authenticated (signed out, expired, or ended).`;
+    }
+    else if (status === 404 || status === 405) {
+        code = 'NOTIFICATIONS_CONFIGURATION_REQUIRED';
+        message = route === '/providers'
+            ? `${route}: the game-services Worker serves no notifications (no MPGD_NOTIFICATIONS_CATALOG).`
+            : `${route}: the game-services Worker serves no notifications for sessions `
+                + '(no MPGD_NOTIFICATIONS_CATALOG or no GAME_SERVICES_NOTIFICATIONS_AUTH binding).';
+    }
+    else if (status === 400 || status === 413) {
+        code = serverCode !== undefined && isNotificationErrorCode(serverCode) ? serverCode : 'NOTIFICATIONS_INVALID_INPUT';
+        message = `${route}: ${serverMessage ?? 'the game-services Worker refused the request as invalid.'}`;
+    }
+    else if (status === 408 || status === 425 || status === 429 || status === 503) {
+        code = 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE';
+        message = `${route}: ${serverMessage ?? 'the game-services Worker is busy; retry later.'}`;
+    }
+    else if (serverCode !== undefined && isNotificationErrorCode(serverCode)) {
+        code = serverCode;
+        message = `${route}: ${serverMessage ?? `the game-services Worker answered ${serverCode}.`}`;
+    }
+    else {
+        code = status >= 500 ? 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE' : 'NOTIFICATIONS_CONFIGURATION_REQUIRED';
+        message = `${route}: the game-services Worker answered ${status}${serverCode === undefined ? '' : ` ${serverCode}`}.`;
+    }
+    return new GameServicesNotificationsRequestError({
+        code,
+        route,
+        status,
+        message,
+        ...(serverCode === undefined ? {} : { serverCode }),
+    });
+}

package/dist/notifications/fcm.d.ts

@@ -14,9 +14,12 @@ import type { NotificationProviderRegistration } from './registry.js';
 * Android posts to the mapping's `channelId`, else to `mpgd-service`,
 * `mpgd-requested`, or `mpgd-advertising` by purpose. An advertising send
 * names the iOS category `mpgd-advertising`, whose opt-out action the app
-* registers; an Android FCM notification message cannot carry actions, so
-* the shell renders advertising natively (C1). An expiry becomes
-* `android.ttl` and the `apns-expiration` header.
+* registers; an Android FCM notification message cannot carry actions, and
+* the Capacitor shell does not render advertising natively yet. An expiry
+* becomes `android.ttl` and the `apns-expiration` header. A replay of the
+* same send key sets `android.collapse_key` and `apns-collapse-id` so a
+* crash after HTTP 200, before the ledger write, does not show a second
+* notification.
 */
 export declare const fcmMessagingScope = "https://www.googleapis.com/auth/firebase.messaging";
 export declare const fcmTokenEndpoint = "https://oauth2.googleapis.com/token";
@@ -31,6 +34,11 @@ export declare const fcmAddressKinds: readonly ["fcm-token"];
 export declare const fcmReservedDataKeys: readonly ["topic", "route"];
 /** The iOS notification category of advertising, which carries the opt-out action. */
 export declare const fcmAdvertisingCategory = "mpgd-advertising";
+/**
+* `android.collapse_key` and `apns-collapse-id` are at most 64 bytes. The
+* id is the SHA-256 of the send key, which is 64 hex characters.
+*/
+export declare const fcmCollapseIdBytes = 64;
 /** The fields of a Google service-account key this provider reads. */
 export interface FcmServiceAccount {
   readonly projectId: string;
@@ -135,4 +143,10 @@ export declare function createFcmDeliveryProvider(input: CreateFcmDeliveryProvid
 export declare function createFcmProviderRegistration(input: CreateFcmDeliveryProviderInput & {
   readonly targets?: readonly string[];
 }): NotificationProviderRegistration;
+/**
+* Collapse id for one send key: SHA-256 hex, exactly 64 bytes, so it fits
+* `android.collapse_key` and `apns-collapse-id`. Sync because
+* `buildFcmMessage` is sync; Workers have no sync WebCrypto digest.
+*/
+export declare function fcmCollapseId(sendKey: string): string;
 export {};

package/dist/notifications/fcm.js

@@ -14,9 +14,12 @@ import { fcmInstallationIdRefusal, } from './delivery-provider.js';
  * Android posts to the mapping's `channelId`, else to `mpgd-service`,
  * `mpgd-requested`, or `mpgd-advertising` by purpose. An advertising send
  * names the iOS category `mpgd-advertising`, whose opt-out action the app
- * registers; an Android FCM notification message cannot carry actions, so
- * the shell renders advertising natively (C1). An expiry becomes
- * `android.ttl` and the `apns-expiration` header.
+ * registers; an Android FCM notification message cannot carry actions, and
+ * the Capacitor shell does not render advertising natively yet. An expiry
+ * becomes `android.ttl` and the `apns-expiration` header. A replay of the
+ * same send key sets `android.collapse_key` and `apns-collapse-id` so a
+ * crash after HTTP 200, before the ledger write, does not show a second
+ * notification.
  */
 export const fcmMessagingScope = 'https://www.googleapis.com/auth/firebase.messaging';
 export const fcmTokenEndpoint = 'https://oauth2.googleapis.com/token';
@@ -37,6 +40,11 @@ export const fcmAdvertisingCategory = 'mpgd-advertising';
  * not refused for its size.
  */
 const maxPayloadBytes = 3840;
+/**
+ * `android.collapse_key` and `apns-collapse-id` are at most 64 bytes. The
+ * id is the SHA-256 of the send key, which is 64 hex characters.
+ */
+export const fcmCollapseIdBytes = 64;
 /** The longest `Retry-After` this provider passes on; the service gives up after a day anyway. */
 const maxRetryAfterSeconds = 86_400;
 /** How long a refused grant or an unusable key answers without asking Google again. */
@@ -307,22 +315,28 @@ export function buildFcmMessage(request) {
             code: 'MESSAGE_EXPIRED',
         };
     }
+    // Same id on both transports: a replay of this send replaces the first
+    // instead of showing beside it. Collapse is per token, so two devices of
+    // one send do not hide each other.
+    const collapseId = fcmCollapseId(request.sendKey);
     const android = {
+        collapse_key: collapseId,
         ...(expiresAt === undefined ? {} : { ttl: `${Math.floor((expiresAt - at) / 1000)}s` }),
         notification: { channel_id: channelId },
     };
     const category = request.topic.purpose === 'advertising' ? fcmAdvertisingCategory : undefined;
     const apns = {
-        ...(expiresAt === undefined
-            ? {}
-            : { headers: { 'apns-expiration': String(Math.floor(expiresAt / 1000)) } }),
+        headers: {
+            'apns-collapse-id': collapseId,
+            ...(expiresAt === undefined ? {} : { 'apns-expiration': String(Math.floor(expiresAt / 1000)) }),
+        },
         ...(category === undefined ? {} : { payload: { aps: { category } } }),
     };
     const payload = {
         notification,
         data: { ...data },
         android,
-        ...(Object.keys(apns).length === 0 ? {} : { apns }),
+        apns,
     };
     // Everything but the token counts toward the size FCM and APNs carry.
     const payloadBytes = new TextEncoder().encode(JSON.stringify(payload)).length;
@@ -600,3 +614,91 @@ function retryAfterOf(response, now) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Collapse id for one send key: SHA-256 hex, exactly 64 bytes, so it fits
+ * `android.collapse_key` and `apns-collapse-id`. Sync because
+ * `buildFcmMessage` is sync; Workers have no sync WebCrypto digest.
+ */
+export function fcmCollapseId(sendKey) {
+    const hex = sha256Hex(new TextEncoder().encode(sendKey));
+    return hex.length === fcmCollapseIdBytes ? hex : hex.slice(0, fcmCollapseIdBytes);
+}
+const sha256K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+function rotr(value, bits) {
+    return (value >>> bits) | (value << (32 - bits));
+}
+function sha256Hex(data) {
+    const bitLength = data.length * 8;
+    const paddedLength = (Math.floor((data.length + 8) / 64) + 1) * 64;
+    const padded = new Uint8Array(paddedLength);
+    padded.set(data);
+    padded[data.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x100000000));
+    view.setUint32(paddedLength - 4, bitLength >>> 0);
+    let h0 = 0x6a09e667;
+    let h1 = 0xbb67ae85;
+    let h2 = 0x3c6ef372;
+    let h3 = 0xa54ff53a;
+    let h4 = 0x510e527f;
+    let h5 = 0x9b05688c;
+    let h6 = 0x1f83d9ab;
+    let h7 = 0x5be0cd19;
+    const words = new Uint32Array(64);
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let index = 0; index < 16; index += 1) {
+            words[index] = view.getUint32(offset + index * 4);
+        }
+        for (let index = 16; index < 64; index += 1) {
+            const earlier = words[index - 15] ?? 0;
+            const recent = words[index - 2] ?? 0;
+            const s0 = rotr(earlier, 7) ^ rotr(earlier, 18) ^ (earlier >>> 3);
+            const s1 = rotr(recent, 17) ^ rotr(recent, 19) ^ (recent >>> 10);
+            words[index] = ((words[index - 16] ?? 0) + s0 + (words[index - 7] ?? 0) + s1) >>> 0;
+        }
+        let a = h0;
+        let b = h1;
+        let c = h2;
+        let d = h3;
+        let e = h4;
+        let f = h5;
+        let g = h6;
+        let h = h7;
+        for (let index = 0; index < 64; index += 1) {
+            const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const temp1 = (h + s1 + ch + (sha256K[index] ?? 0) + (words[index] ?? 0)) >>> 0;
+            const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const temp2 = (s0 + maj) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + temp1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (temp1 + temp2) >>> 0;
+        }
+        h0 = (h0 + a) >>> 0;
+        h1 = (h1 + b) >>> 0;
+        h2 = (h2 + c) >>> 0;
+        h3 = (h3 + d) >>> 0;
+        h4 = (h4 + e) >>> 0;
+        h5 = (h5 + f) >>> 0;
+        h6 = (h6 + g) >>> 0;
+        h7 = (h7 + h) >>> 0;
+    }
+    return [h0, h1, h2, h3, h4, h5, h6, h7]
+        .map((word) => word.toString(16).padStart(8, '0'))
+        .join('');
+}

package/dist/notifications/service.d.ts

@@ -179,7 +179,10 @@ export interface NotificationService {
   * 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.
+  * still waits (deferred, or in flight with no live claim) is stopped. A
+  * row a holder has claimed is left so an acceptance the provider already
+  * took can be recorded; that holder does not call the provider if the
+  * reminder was cancelled or replaced before the call.
   */
   setReminder(session: NotificationSession, input: unknown): Promise<{
     readonly status: NotificationReminderSetStatus;