@mpgd/game-services 0.26.0 → 0.27.0

package/dist/client.d.ts

@@ -7,8 +7,10 @@ import type { MonetizationOperationStore } from './monetization-recovery.js';
 import type { GameServicesOperationClient } from './operations.js';
 export type { GameServicesOperationClient, GameServicesPurchaseInput, GameServicesPurchaseResult, GameServicesRewardedAdInput, GameServicesRewardedAdResult, } from './operations.js';
 import type { GameServicesContractClient } from './contract.js';
+import { type GameServicesHeaderResolver } from './request-headers.js';
 import type { ClaimAdRewardRequest, ClaimAdRewardResponse, GameServicesLedgerTarget, PurchaseLedgerStatusRequest, PurchaseLedgerStatusResponse, RecordLeaderboardScoreRequest, RecordLeaderboardScoreResponse, VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.js';
 export type { GameServicesOperationKind, GameServicesOperationLocation, GameServicesOperationOptions, GameServicesOperationProgress, GameServicesPurchaseProgress, GameServicesRewardedAdProgress, } from './operation-progress.js';
+export { GameServicesHeaderResolutionError, resolveGameServicesRequestHeaders, type GameServicesHeaderResolver, } from './request-headers.js';
 export interface PurchaseVerificationApi {
   verifyPurchase(input: VerifyPurchaseRequest): Promise<VerifyPurchaseResponse>;
   /**
@@ -75,7 +77,6 @@ export interface CreateGameServicesOrpcClientInput {
   readonly headers?: Record<string, string>;
   readonly getHeaders?: GameServicesHeaderResolver;
 }
-export type GameServicesHeaderResolver = () => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
 export type GameServicesFetch = (url: string, init: {
   readonly method: 'POST';
   readonly headers: Record<string, string>;
@@ -96,16 +97,6 @@ export declare class GameServicesBackendTransportError extends Error {
   readonly endpoint: GameServicesBackendEndpoint;
   constructor(endpoint: GameServicesBackendEndpoint);
 }
-/** Credentials could not be resolved; no backend request was dispatched. */
-export declare class GameServicesHeaderResolutionError extends Error {
-  constructor();
-}
-/** Resolve rotating credentials once and preserve static → dynamic → request precedence. */
-export declare function resolveGameServicesRequestHeaders(input: {
-  readonly headers?: Readonly<Record<string, string>> | undefined;
-  readonly getHeaders?: GameServicesHeaderResolver | undefined;
-  readonly requestHeaders?: Readonly<Record<string, string>> | undefined;
-}): Promise<Readonly<Record<string, string>>>;
 export interface GameServicesClient extends GameServicesOperationClient {
   submitLeaderboardScore(input: GameServicesLeaderboardInput): Promise<GameServicesLeaderboardResult>;
   /**

package/dist/client.js

@@ -6,6 +6,8 @@ import { createCommerceReconciler, toGameServicesPurchaseResult, } from './comme
 import { createDefaultClientRewardEvidenceRegistry } from './default-client-reward-evidence.js';
 import { createInMemoryMonetizationOperationStore } from './monetization-operation-store.js';
 import { observeGameServicesOperation } from './operation-progress.js';
+import { GameServicesHeaderResolutionError, resolveGameServicesRequestHeaders, } from './request-headers.js';
+export { GameServicesHeaderResolutionError, resolveGameServicesRequestHeaders, } from './request-headers.js';
 export const gameServicesBackendEndpoints = {
     verifyPurchase: '/game-services/purchases/verify',
     getPurchaseLedgerStatus: '/game-services/purchases/ledger-status',
@@ -33,31 +35,6 @@ export class GameServicesBackendTransportError extends Error {
         this.endpoint = endpoint;
     }
 }
-/** Credentials could not be resolved; no backend request was dispatched. */
-export class GameServicesHeaderResolutionError extends Error {
-    constructor() {
-        super('Game Services request headers could not be resolved before dispatch.');
-        this.name = 'GameServicesHeaderResolutionError';
-    }
-}
-/** Resolve rotating credentials once and preserve static → dynamic → request precedence. */
-export async function resolveGameServicesRequestHeaders(input) {
-    let dynamicHeaders;
-    try {
-        dynamicHeaders = await input.getHeaders?.();
-    }
-    catch {
-        // Resolver exceptions can contain credentials; expose a stable outcome.
-        throw new GameServicesHeaderResolutionError();
-    }
-    const merged = new Map();
-    for (const layer of [input.headers, dynamicHeaders, input.requestHeaders]) {
-        for (const [name, value] of Object.entries(layer ?? {})) {
-            merged.set(name.toLowerCase(), value);
-        }
-    }
-    return Object.fromEntries(merged);
-}
 export function createGameServicesClient(input) {
     const now = input.now ?? (() => new Date().toISOString());
     const requestNow = input.requestNow ?? now;

package/dist/notifications/ait-functional-delivery.d.ts

@@ -31,7 +31,12 @@ import type { AppsInTossMutualTlsFetcher } from '../apps-in-toss-partner-api.js'
 *   recipient who has not agreed to the template. `agreementErrorCodes` and
 *   `agreementFailReasons` let a deployment name the ones it observes, so
 *   such an answer is `rejected` with reason `agreement` and records the
-*   denial; without them it is reason `recipient`.
+*   denial; without them it is reason `recipient`. A deployment list cannot
+*   override 4095, 5004, 4034, or 4010: those documented codes are classified
+*   first, so a rate limit is not stored as an agreement denial.
+* - `baseUrl` must be the partner API host (`apps-in-toss-api.toss.im`).
+*   The mTLS client certificate and the recipient key are not sent to any
+*   other host unless the caller sets `allowUnlistedHost` (tests only).
 * - Limits: 15,000 calls per minute per app and 10 per minute per user, the
 *   reference registry entry's `rate` and `limits`, which the scheduler and
 *   the gate apply.
@@ -39,6 +44,12 @@ import type { AppsInTossMutualTlsFetcher } from '../apps-in-toss-partner-api.js'
 export declare const aitFunctionalMessageProviderId: "apps-in-toss";
 export declare const aitFunctionalMessagePath = "api-partner/v1/apps-in-toss/messenger/send-message";
 export declare const defaultAitFunctionalMessageBaseUrl = "https://apps-in-toss-api.toss.im";
+/**
+* Hosts the partner certificate and the recipient key may be sent to.
+* `docs/APPS_IN_TOSS_PRODUCTION_EVIDENCE.md` names this production base and
+* no sandbox API host.
+*/
+export declare const aitFunctionalMessageAllowedHosts: readonly string[];
 export declare const defaultAitFunctionalMessageTimeoutMs = 10000;
 /** The longest `Retry-After` the provider passes on; the scheduler backs off from it. */
 export declare const maximumAitFunctionalMessageRetryAfterSeconds = 86400;
@@ -112,6 +123,12 @@ export interface CreateAitFunctionalMessageDeliveryProviderOptions {
   */
   readonly recipientKey: 'toss-user' | 'anonymous';
   readonly baseUrl?: string;
+  /**
+  * Send to a `baseUrl` whose host is not
+  * {@link aitFunctionalMessageAllowedHosts}. Tests only: a deployment that
+  * sets this can leak the partner certificate and the recipient key.
+  */
+  readonly allowUnlistedHost?: boolean;
   /** 1 to 60,000 ms, as the partner API client accepts. */
   readonly timeoutMs?: number;
   /** `FAIL` error codes that mean the recipient has not agreed to the template. */
@@ -135,13 +152,13 @@ export interface AitFunctionalMessageDeliveryProvider {
 *   With none sent, the per-channel `fail` lists decide: `rejected` with
 *   reason `agreement` when a failure's `reachedFailReason` is one of
 *   `agreementFailReasons`, otherwise `recipient`.
-* - `FAIL` with a code in `agreementErrorCodes` (first) or
-*   `recipientErrorCodes` is `rejected` with that reason, before any
-*   documented meaning of the code, on any status except HTTP 429, 5xx,
-*   408, and 425, which the status alone decides (see below);
-*   otherwise 4095 is `rate-limited` with `retryAfterSeconds` (at most a
-*   day), and 5004, 4034, and 4010 are `rejected` with reason
-*   `configuration`. Any other code is `rejected` with reason `recipient` on HTTP 200
+* - `FAIL` with a documented code is classified before any deployment list:
+*   4095 is `rate-limited` with `retryAfterSeconds` (at most a day), and
+*   5004, 4034, and 4010 are `rejected` with reason `configuration`. A
+*   deployment cannot store those as an agreement denial. Then a code in
+*   `agreementErrorCodes` or `recipientErrorCodes` is `rejected` with that
+*   reason, on any status except HTTP 429, 5xx, 408, and 425, which the
+*   status alone decides (see below). Any other code is `rejected` with reason `recipient` on HTTP 200
 *   and `configuration` when the HTTP status refused the request (400, 401,
 *   403, 404, 405, 413, 415, 422): a `FAIL` envelope reports a failed
 *   request, and answering `ambiguous` would replay a send that fails the

package/dist/notifications/ait-functional-delivery.js

@@ -30,7 +30,12 @@ import { notificationTemplateDataIssue, referenceNotificationProviders, } from '
  *   recipient who has not agreed to the template. `agreementErrorCodes` and
  *   `agreementFailReasons` let a deployment name the ones it observes, so
  *   such an answer is `rejected` with reason `agreement` and records the
- *   denial; without them it is reason `recipient`.
+ *   denial; without them it is reason `recipient`. A deployment list cannot
+ *   override 4095, 5004, 4034, or 4010: those documented codes are classified
+ *   first, so a rate limit is not stored as an agreement denial.
+ * - `baseUrl` must be the partner API host (`apps-in-toss-api.toss.im`).
+ *   The mTLS client certificate and the recipient key are not sent to any
+ *   other host unless the caller sets `allowUnlistedHost` (tests only).
  * - Limits: 15,000 calls per minute per app and 10 per minute per user, the
  *   reference registry entry's `rate` and `limits`, which the scheduler and
  *   the gate apply.
@@ -41,6 +46,12 @@ export const aitFunctionalMessagePath = 'api-partner/v1/apps-in-toss/messenger/s
 // `defaultAppsInTossPartnerApiTimeoutMs` (a test keeps them equal), kept here
 // so this module loads none of the partner client's code.
 export const defaultAitFunctionalMessageBaseUrl = 'https://apps-in-toss-api.toss.im';
+/**
+ * Hosts the partner certificate and the recipient key may be sent to.
+ * `docs/APPS_IN_TOSS_PRODUCTION_EVIDENCE.md` names this production base and
+ * no sandbox API host.
+ */
+export const aitFunctionalMessageAllowedHosts = Object.freeze(['apps-in-toss-api.toss.im']);
 export const defaultAitFunctionalMessageTimeoutMs = 10_000;
 /** The longest `Retry-After` the provider passes on; the scheduler backs off from it. */
 export const maximumAitFunctionalMessageRetryAfterSeconds = 86_400;
@@ -77,13 +88,13 @@ const maximumTimeoutMs = 60_000;
  *   With none sent, the per-channel `fail` lists decide: `rejected` with
  *   reason `agreement` when a failure's `reachedFailReason` is one of
  *   `agreementFailReasons`, otherwise `recipient`.
- * - `FAIL` with a code in `agreementErrorCodes` (first) or
- *   `recipientErrorCodes` is `rejected` with that reason, before any
- *   documented meaning of the code, on any status except HTTP 429, 5xx,
- *   408, and 425, which the status alone decides (see below);
- *   otherwise 4095 is `rate-limited` with `retryAfterSeconds` (at most a
- *   day), and 5004, 4034, and 4010 are `rejected` with reason
- *   `configuration`. Any other code is `rejected` with reason `recipient` on HTTP 200
+ * - `FAIL` with a documented code is classified before any deployment list:
+ *   4095 is `rate-limited` with `retryAfterSeconds` (at most a day), and
+ *   5004, 4034, and 4010 are `rejected` with reason `configuration`. A
+ *   deployment cannot store those as an agreement denial. Then a code in
+ *   `agreementErrorCodes` or `recipientErrorCodes` is `rejected` with that
+ *   reason, on any status except HTTP 429, 5xx, 408, and 425, which the
+ *   status alone decides (see below). Any other code is `rejected` with reason `recipient` on HTTP 200
  *   and `configuration` when the HTTP status refused the request (400, 401,
  *   403, 404, 405, 413, 415, 422): a `FAIL` envelope reports a failed
  *   request, and answering `ambiguous` would replay a send that fails the
@@ -109,24 +120,29 @@ export function createAitFunctionalMessageDeliveryProvider(options) {
         throw new TypeError("recipientKey must be 'toss-user' or 'anonymous'.");
     }
     const recipientHeader = options.recipientKey === 'anonymous' ? 'x-anon-key' : 'x-toss-user-key';
-    const url = new URL(aitFunctionalMessagePath, normalizeBaseUrl(options.baseUrl ?? defaultAitFunctionalMessageBaseUrl)).href;
+    const url = new URL(aitFunctionalMessagePath, normalizeBaseUrl(options.baseUrl ?? defaultAitFunctionalMessageBaseUrl, {
+        allowUnlistedHost: options.allowUnlistedHost === true,
+    })).href;
     const timeoutMs = normalizeTimeout(options.timeoutMs);
     const agreementErrorCodes = new Set(options.agreementErrorCodes ?? []);
     const recipientErrorCodes = new Set(options.recipientErrorCodes ?? []);
     const agreementFailReasons = new Set((options.agreementFailReasons ?? []).map((reason) => reason.trim()));
-    // The deployment's codes come first, then the documented ones (RFC
-    // "Delivery providers -> Apps in Toss").
+    // Documented codes come first (RFC "Delivery providers -> Apps in Toss"),
+    // then the deployment's. A list must not turn 4095 into an agreement denial.
     const classifyFailCode = (code, status) => {
+        if (code === rateLimitedErrorCode) {
+            return { status: 'rate-limited', providerCode: code };
+        }
+        if (configurationErrorCodes.has(code)) {
+            return { status: 'rejected', reason: 'configuration', providerCode: code };
+        }
         if (agreementErrorCodes.has(code)) {
             return { status: 'rejected', reason: 'agreement', providerCode: code };
         }
         if (recipientErrorCodes.has(code)) {
             return { status: 'rejected', reason: 'recipient', providerCode: code };
         }
-        if (code === rateLimitedErrorCode) {
-            return { status: 'rate-limited', providerCode: code };
-        }
-        if (configurationErrorCodes.has(code) || refusedRequestStatuses.has(status)) {
+        if (refusedRequestStatuses.has(status)) {
             return { status: 'rejected', reason: 'configuration', providerCode: code };
         }
         // An undocumented code on another status proves nothing either way.
@@ -421,8 +437,8 @@ function isCount(value) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** A credential-free HTTPS base URL ending in `/`, as the partner API client requires. */
-function normalizeBaseUrl(input) {
+/** A credential-free HTTPS base URL ending in `/`, on an allowlisted partner host. */
+function normalizeBaseUrl(input, options) {
     const url = new URL(input);
     if (url.protocol !== 'https:'
         || url.username.length > 0
@@ -431,6 +447,11 @@ function normalizeBaseUrl(input) {
         || url.hash.length > 0) {
         throw new TypeError('The Apps in Toss partner API baseUrl must be a credential-free HTTPS URL.');
     }
+    const allowedHost = aitFunctionalMessageAllowedHosts.includes(url.hostname)
+        && (url.port === '' || url.port === '443');
+    if (!allowedHost && !options.allowUnlistedHost) {
+        throw new TypeError(`The Apps in Toss partner API baseUrl host must be ${aitFunctionalMessageAllowedHosts.join(' or ')}.`);
+    }
     url.pathname = url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`;
     return url.href;
 }

package/dist/notifications/client.d.ts

@@ -0,0 +1,168 @@
+import { NotificationError, type NotificationDeliveryProviderEntry, type NotificationErrorCode } from '@mpgd/platform/notifications';
+import type { NotificationRuntimeBackend } from '@mpgd/platform/notifications-runtime';
+import { type GameServicesHeaderResolver } 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 declare const gameServicesNotificationsRoutePrefix = "/game-services/notifications";
+/** The server-backed session the game is signed in with. */
+export interface GameServicesNotificationSession {
+  readonly playerId: string;
+  /**
+  * The stable session-family id: the `sessionId` the identity service
+  * answers to the Worker's `authenticateNotificationSession` for this
+  * session's header, the same across token refreshes. A new sign-in starts
+  * a new one. A per-token or rotating id is not it (a
+  * `GuestSessionCoordinator` view's `sessionId` may rotate on refresh); with
+  * one, each rotation counts as a new session and sends the registration
+  * again.
+  */
+  readonly sessionId: string;
+}
+/**
+* The game's identity as the notifications client needs it. The game wires
+* it to its own session holder and identity service; the kit does not
+* create sessions.
+*/
+export interface GameServicesNotificationIdentity {
+  /** The current session, or `undefined` while signed out. */
+  current(): GameServicesNotificationSession | undefined;
+  /**
+  * Calls `listener` when a session becomes current after the subscription:
+  * a sign-in, a session restored after the runtime started, or an account
+  * switch. Returns the unsubscribe. A repeat for the session already
+  * announced (a token refresh) is ignored, and so is one for the session
+  * current when the runtime subscribed (at its `start()`); the runtime's
+  * start registers again on its own when that session is not the one its
+  * last registration was acknowledged for.
+  */
+  onAuthenticated(listener: (session: GameServicesNotificationSession) => void): () => void;
+}
+/** The part of the Fetch API the client uses; `globalThis.fetch` satisfies it. */
+export type GameServicesNotificationsFetch = (url: string, init: {
+  readonly method: 'GET' | 'POST';
+  readonly headers: Record<string, string>;
+  readonly body?: string;
+  /** Aborted when the request times out. */
+  readonly signal?: AbortSignal;
+}) => Promise<GameServicesNotificationsFetchResponse>;
+export interface GameServicesNotificationsFetchResponse {
+  readonly status: number;
+  text(): Promise<string>;
+}
+export interface CreateGameServicesNotificationsClientInput {
+  /**
+  * The game-services Worker's origin, as the commerce client takes it
+  * (`VITE_MPGD_GAME_SERVICES_URL`). The client sends the session's
+  * credentials to it as given: in a production build, check it with
+  * `isPublicGameServicesUrl` from `@mpgd/game-services` first.
+  */
+  readonly baseUrl: string;
+  readonly identity: GameServicesNotificationIdentity;
+  /** Defaults to `globalThis.fetch`. */
+  readonly fetch?: GameServicesNotificationsFetch;
+  /** Static headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Resolves the session's `Authorization` header at request time, as for the commerce client. */
+  readonly getHeaders?: GameServicesHeaderResolver;
+  /**
+  * The catalog target a device registration is for (`android`, `ios`): the
+  * Worker applies that target's topic mapping to the device and refuses a
+  * registration without it when one provider serves two targets.
+  */
+  readonly target?: string;
+  /**
+  * How long one request may take, from resolving its headers to reading
+  * its answer, before it is aborted and answers
+  * `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`; 15 seconds by default, at most
+  * 2147483647.
+  */
+  readonly timeoutMs?: number;
+}
+/** The default `timeoutMs`: a request still unanswered after this is aborted. */
+export declare const defaultGameServicesNotificationsTimeoutMs = 15000;
+/** The registry the Worker publishes at `GET /providers`. */
+export interface GameServicesNotificationProviders {
+  readonly protocolVersion: string;
+  readonly providers: readonly NotificationDeliveryProviderEntry[];
+  /** Each served target and the provider id that delivers to it. */
+  readonly targets: Readonly<Record<string, string>>;
+}
+export interface GameServicesNotificationsClient extends NotificationRuntimeBackend {
+  /**
+  * The registry the Worker publishes (`GET /providers`, no session needed):
+  * pass `providers.find((entry) => entry.provider === provider.provider)` as
+  * the runtime's `registryEntry`.
+  */
+  getProviders(): Promise<GameServicesNotificationProviders>;
+}
+/**
+* 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 declare class GameServicesNotificationsRequestError extends NotificationError {
+  /** The HTTP status, or 0 when no answer arrived. */
+  readonly status: number;
+  /** The route, such as `/consent`. */
+  readonly route: string;
+  /** The `error` the Worker answered, such as `UNAUTHORIZED`. */
+  readonly serverCode: string | undefined;
+  constructor(input: {
+    readonly code: NotificationErrorCode;
+    readonly route: string;
+    readonly status: number;
+    readonly message: string;
+    readonly serverCode?: string;
+    readonly cause?: unknown;
+  });
+}
+/**
+* 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 declare function createGameServicesNotificationsClient(input: CreateGameServicesNotificationsClientInput): GameServicesNotificationsClient;