@mpgd/game-services 0.30.4 → 0.31.0

package/README.md

@@ -183,6 +183,37 @@ and retry policy are not redesigned by this observer API.
 The root `pnpm test` pipeline includes compiled client JS and public declaration
 consumption checks alongside the client and target conformance suites.
 
+## oRPC version and error compatibility
+
+The oRPC transport (`createGameServicesOrpcClient`, `createGameServicesRouter`,
+`createGameServicesRpcFetchHandler`) is built on oRPC `2.0.0-beta.46`, pinned
+exactly. Pin the same exact version if a game or Worker also uses oRPC directly.
+
+oRPC 2.0.0-beta.34 removed the `inferable` flag from RPC error bodies, and each
+side rejects the other's shape: an older client would see a malformed response
+instead of `BAD_REQUEST` or `NOT_FOUND`, and so would a newer client talking to
+an older Worker. Games and Workers deploy separately, so this package bridges
+the change in `src/orpc-error-compat.ts`:
+
+- `createGameServicesRpcFetchHandler` adds `inferable: false` to oRPC error
+  bodies, so clients from `@mpgd/game-services` 0.30.5 or older (oRPC
+  2.0.0-beta.14) still decode error codes;
+- `createGameServicesOrpcClient` (0.31.0 or later) removes a boolean `inferable`
+  from error bodies before oRPC validates them, so it still decodes errors from
+  Workers on 0.30.5 or older.
+
+Success responses are unchanged. Any other oRPC 2.0.0-beta.34+ client that calls
+a game-services Worker's `/rpc` route (for example a plain `RPCLink` in a game)
+must wrap its fetch with `withLegacyOrpcErrorCompat` from
+`@mpgd/game-services/client`, or it sees the legacy flag as a malformed error. A
+Worker that no longer serves clients from 0.30.5 or older can pass
+`legacyOrpcErrorFlag: false` to `createGameServicesRpcFetchHandler`. The shim is
+removed once the oldest supported game client and every supported Worker come
+from `@mpgd/game-services` 0.31.0 or later (oRPC 2.0.0-beta.46). Other oRPC changes picked up with it: RPC routes accept
+only POST, PUT, PATCH, and DELETE (a GET answers 404, and the kit clients always
+POST), and `Infinity` inputs are encoded with their own meta marker, which a Worker
+on 0.30.5 or older (oRPC 2.0.0-beta.14) cannot decode.
+
 ## Runtime backend transport
 
 `createGameServicesRuntime` accepts `httpTransport` for its HTTP JSON backend
@@ -233,6 +264,71 @@ them into analytics or logs.
 All published entrypoints use explicit internal ESM module paths and are smoke-tested
 with native Node imports, without a bundler or TypeScript runtime loader.
 
+## One player per runtime
+
+A runtime, its purchase journal records, and its reconciler belong to
+`playerId` for their whole life, while `getHeaders` and a store provider's
+account binding follow the live session. When the session can change player
+within a run (an account switch), pass `sessionPlayerId: () => session.current()?.playerId`:
+
+- It is read before every backend request and again once that request's
+  headers are resolved, and by the commerce reconciler before each pass,
+  queued event, record step, store read, restore, and finish, and right
+  before a store UI opens.
+- Another player closes the runtime for good: nothing more is verified,
+  restored, or finished for this player with the other player's credentials
+  (a backend answers that with a permanent account-mismatch rejection), and
+  no store UI opens for a purchase journaled here once the session names
+  someone else. The provider resolves its account binding a few steps after
+  that last check, so the binding resolver must follow the runtime's player
+  too (bind nothing for anyone else, as the generated game's
+  `pinStarterCommercePlayer` does) for a purchase never to be
+  journaled here and bound to the other account; a binding refused while the
+  session changed keeps the attempt retryable. Purchases
+  answer `failed` with the retryable diagnostic `GAME_SERVICES_PLAYER_CHANGED`
+  before any store UI, rewarded-ad claims answer `unavailable` before any
+  ad, recovery runs nothing, and Restore Purchases rejects with
+  `GameServicesRuntimeClosedError`.
+- No player (signed out) refuses the same way with
+  `GAME_SERVICES_SESSION_REQUIRED` and leaves the runtime open for its player.
+
+Refusals end no journal record: a runtime created for the player later
+resumes them. `runtime.dispose()` closes a runtime the same way
+(`GAME_SERVICES_RUNTIME_DISPOSED`) and resolves once a purchase whose store
+sheet is open has journaled its answer, a recovery pass under way
+(`monetizationRecovery.reconcile()`) has finished, and the reconciler has
+stopped (each wait bounded by `gameServicesDisposeWaitMs`, 3 minutes); call
+it, and wait, before creating the runtime for another player or reloading.
+A recovery pass that outlives that wait starts no store subscription
+afterwards. A custom
+`httpTransport` must send only the headers the runtime resolved for each
+request, or the after-resolution check cannot cover it. A refusal keeps its
+`GameServicesRuntimeClosedError` through header resolution and the HTTP
+transport (it is not turned into `GameServicesHeaderResolutionError` or
+`GameServicesBackendTransportError`). A reconciler started while the session
+is signed out still subscribes to the store; its work waits for the session.
+
+Pass `commerceAccountBinding` too: this player's store account binding,
+derived from `playerId` the way the store provider binds the player's new
+purchases (Google Play's obfuscated account id, StoreKit's app account
+token). The reconciler then leaves a store purchase bound to another account
+alone (reported, never journaled or verified for this player). After a
+restart as another player, Google Play still lists the previous player's
+unacknowledged purchases; sending one with this player's session would be
+rejected for good, and its derived key would then block the other player's
+own recovery. The player's explicit Restore Purchases still takes a durable
+bound to another account (restore sharing). StoreKit's provider already
+filters transactions by app account token the same way.
+
+`dispose()` is a required member of `GameServicesRuntime`: a runtime built by
+hand (a test fake, a custom wrapper) adds `dispose: async () => undefined`.
+
+A game adopting this creates its runtime from its server session's player
+(never a platform placeholder), passes `sessionPlayerId` and
+`commerceAccountBinding`, keeps its store account binding resolver on the
+same player (bind nothing for anyone else), and disposes the runtime (and
+waits) before it creates one for another player.
+
 ## Guest session and account binding foundation
 
 `createGuestSessionCoordinator` from `@mpgd/game-services/guest-session`

package/dist/client.d.ts

@@ -2,11 +2,12 @@ import { type AnalyticsSink } from '@mpgd/analytics';
 import type { LeaderboardScoreInput, PlatformGateway, PlatformTarget } from '@mpgd/platform';
 import type { CommerceServiceCapabilities } from '@mpgd/platform/commerce';
 import { type ClientRewardEvidenceRegistry } from './client-reward-evidence.js';
-import { type CommerceReconciler, type CommerceReconcilerEvent, type CommerceReconcilerProduct } from './commerce-reconciler.js';
+import { type CommerceReconciler, type CommerceReconcilerEvent, type CommerceReconcilerProduct, type CreateCommerceReconcilerInput } from './commerce-reconciler.js';
 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';
+export { withLegacyOrpcErrorCompat } from './orpc-error-compat.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';
@@ -133,8 +134,21 @@ export interface CreateGameServicesClientInput {
   readonly warn?: (message: string) => void;
   /** Catalog kinds and SKUs the reconciler resolves without a store read. */
   readonly commerceProducts?: readonly CommerceReconcilerProduct[];
+  /** The reconciler's `staleLaunchedAfterMs` (24 hours by default). */
+  readonly commerceStaleLaunchedAfterMs?: number;
   readonly onCommerceEvent?: (event: CommerceReconcilerEvent) => void;
-}
+  /** The reconciler's `sessionCheck` (see `CreateCommerceReconcilerInput`). */
+  readonly commerceSessionCheck?: CreateCommerceReconcilerInput['sessionCheck'];
+  /** The reconciler's `closed` (see `CreateCommerceReconcilerInput`). */
+  readonly commerceClosed?: CreateCommerceReconcilerInput['closed'];
+  /** The reconciler's `accountBinding` (see `CreateCommerceReconcilerInput`). */
+  readonly commerceAccountBinding?: CreateCommerceReconcilerInput['accountBinding'];
+}
+/**
+* `commerceStaleLaunchedAfterMs` is checked where it enters, so a bad value
+* fails even when no reconciler is built (a gateway without `commerce`).
+*/
+export declare function assertCommerceStaleLaunchedAfterMs(value: number | undefined): void;
 export interface GameServicesLeaderboardInput extends LeaderboardScoreInput {
 }
 export interface GameServicesLeaderboardResult {

package/dist/client.js

@@ -6,7 +6,9 @@ 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';
+import { withLegacyOrpcErrorCompat } from './orpc-error-compat.js';
+export { withLegacyOrpcErrorCompat } from './orpc-error-compat.js';
+import { GameServicesHeaderResolutionError, GameServicesRuntimeClosedError, resolveGameServicesRequestHeaders, } from './request-headers.js';
 export { GameServicesHeaderResolutionError, resolveGameServicesRequestHeaders, } from './request-headers.js';
 export const gameServicesBackendEndpoints = {
     verifyPurchase: '/game-services/purchases/verify',
@@ -35,7 +37,17 @@ export class GameServicesBackendTransportError extends Error {
         this.endpoint = endpoint;
     }
 }
+/**
+ * `commerceStaleLaunchedAfterMs` is checked where it enters, so a bad value
+ * fails even when no reconciler is built (a gateway without `commerce`).
+ */
+export function assertCommerceStaleLaunchedAfterMs(value) {
+    if (value !== undefined && !(typeof value === 'number' && value > 0)) {
+        throw new RangeError('commerceStaleLaunchedAfterMs must be a positive duration in milliseconds, or Infinity.');
+    }
+}
 export function createGameServicesClient(input) {
+    assertCommerceStaleLaunchedAfterMs(input.commerceStaleLaunchedAfterMs);
     const now = input.now ?? (() => new Date().toISOString());
     const requestNow = input.requestNow ?? now;
     const rewardEvidenceRegistry = input.rewardEvidenceRegistry ?? createDefaultClientRewardEvidenceRegistry();
@@ -62,6 +74,12 @@ export function createGameServicesClient(input) {
             target: input.target,
             ...(input.deploymentTarget === undefined ? {} : { deploymentTarget: input.deploymentTarget }),
             ...(input.commerceProducts === undefined ? {} : { products: input.commerceProducts }),
+            ...(input.commerceSessionCheck === undefined ? {} : { sessionCheck: input.commerceSessionCheck }),
+            ...(input.commerceClosed === undefined ? {} : { closed: input.commerceClosed }),
+            ...(input.commerceAccountBinding === undefined ? {} : { accountBinding: input.commerceAccountBinding }),
+            ...(input.commerceStaleLaunchedAfterMs === undefined
+                ? {}
+                : { staleLaunchedAfterMs: input.commerceStaleLaunchedAfterMs }),
             now: requestNow,
         });
         if (input.onCommerceEvent !== undefined) {
@@ -424,9 +442,16 @@ export function createGameServicesFetchBackendTransport(input) {
     };
 }
 export function createGameServicesOrpcClient(input) {
+    const fetcher = input.fetch;
     const link = new RPCLink({
         origin: input.url,
-        ...(input.fetch === undefined ? {} : { fetch: input.fetch }),
+        // Every response passes the oRPC error-body compatibility shim so errors from a Worker on
+        // an older oRPC beta keep their codes; the default fetch is resolved per call, as oRPC does.
+        fetch: withLegacyOrpcErrorCompat((url, init, ...rest) => {
+            return fetcher === undefined
+                ? globalThis.fetch(url, init)
+                : fetcher(url, init, ...rest);
+        }),
         ...(input.headers === undefined && input.getHeaders === undefined
             ? {}
             : {
@@ -490,7 +515,7 @@ async function sendGameServicesBackendRequest(transport, endpoint, body) {
         });
     }
     catch (error) {
-        if (error instanceof GameServicesHeaderResolutionError) {
+        if (error instanceof GameServicesHeaderResolutionError || error instanceof GameServicesRuntimeClosedError) {
             throw error;
         }
         // Do not leak SDK or native transport exceptions (which can contain

package/dist/commerce-reconciler.d.ts

@@ -1,5 +1,5 @@
 import type { LogicalProductId } from '@mpgd/platform';
-import { type CommerceCapabilities, type CommerceErrorInfo, type CommerceProvider, type CommercePurchaseState, type CommercePurchaseSummaryStatus, type FetchProductsInput, type PurchaseKind, type RequestPurchaseInput, type RequestPurchaseResult, type StoreId, type StoreProduct, type StorePurchase } from '@mpgd/platform/commerce';
+import { CommerceError, type CommerceCapabilities, type CommerceErrorInfo, type CommerceProvider, type CommercePurchaseState, type CommercePurchaseSummaryStatus, type FetchProductsInput, type PurchaseKind, type RequestPurchaseInput, type RequestPurchaseResult, type StoreId, type StoreProduct, type StorePurchase, type StorePurchaseAccountBinding } from '@mpgd/platform/commerce';
 import type { PurchaseVerificationApi } from './client.js';
 import { type CommerceServiceAlignment } from './commerce-evidence-registry.js';
 import type { MonetizationOperationStore } from './monetization-recovery.js';
@@ -73,7 +73,9 @@ export declare function summarizeCommercePurchaseOperation(record: CommercePurch
 * finish allow-list of its own (the removed v1 driver paired transactions in
 * `finishGrantedTransaction`), so this is the finish gate for every `client`
 * and `host` owner: the ledger entry id comes from the journal revision the
-* backend grant wrote.
+* backend grant wrote. The one other finish call is a `finished` consumable a
+* `client` store reports again, finished with the same journaled ledger entry
+* (see `finishReportedAgain` in `createCommerceReconciler`).
 */
 export declare function assertCommerceFinishAllowed(record: CommercePurchaseOperationRecord): {
   readonly transactionId: string;
@@ -87,7 +89,9 @@ export interface CommerceReconcilerProduct {
   readonly kind: PurchaseKind;
   readonly storeSku?: string;
 }
-export type CommerceReconcilerFailureStage = 'capabilities' | 'available' | 'catalog' | 'match' | 'journal' | 'verify' | 'finish' | 'ledger-status' | 'restore';
+export type CommerceReconcilerFailureStage = 'capabilities' | 'available' | 'catalog' | 'match' | 'journal' | 'verify' | 'finish' | 'ledger-status' | 'restore'
+/** `sessionCheck` refused: the reconciler's player is not the session's now. */
+| 'session';
 export type CommerceReconcilerEvent = {
   readonly type: 'transition';
   readonly record: CommercePurchaseOperationRecord;
@@ -153,6 +157,52 @@ export interface CreateCommerceReconcilerInput {
   * ten seconds.
   */
   readonly serviceCapabilitiesTimeoutMs?: number;
+  /**
+  * Whether the reconciler may act for `playerId` right now; an error says
+  * why not (`createGameServicesRuntime` passes its session player check).
+  * It is read synchronously before every pass, before each queued event and
+  * each record a pass handles, before a store read, restore, or finish, and
+  * for a purchase at its start, right before its record is reserved, and
+  * right before the store UI opens. A refusal never ends a record: a pass stops with the
+  * journal as it is and the events still queued (a `failure` event with
+  * stage `session` reports it), a purchase answers the error with no store
+  * UI (a reserved attempt stays retryable), and `restorePurchases` rejects
+  * with it. So one player's journaled purchases are never verified,
+  * restored, or finished while another player's session headers or account
+  * binding are current. Return a retryable `CommerceError`.
+  */
+  readonly sessionCheck?: () => CommerceError | undefined;
+  /**
+  * Whether the reconciler's owner closed for good (`createGameServicesRuntime`
+  * passes its disposed or player-changed state). Read synchronously when
+  * `start()` is called and again right before it subscribes (after the
+  * journal read): while it answers true, `start()` subscribes nothing and
+  * starts nothing, and resolves without an error. So a caller that reaches
+  * `start()` after `stop()` (a recovery pass that outlived its owner's
+  * dispose), or a start that was still reading the journal when its owner
+  * stopped waiting for it, leaves no store subscription.
+  * Unlike `sessionCheck`, a signed-out session is not closed: the reconciler
+  * still subscribes then and its work waits for the session. Omitted, a
+  * stopped reconciler can be started again.
+  */
+  readonly closed?: () => boolean;
+  /**
+  * This player's store account binding: the value the store provider binds
+  * the player's new purchases to (Google Play's obfuscated account id,
+  * StoreKit's app account token). A store purchase the journal does not
+  * hold yet whose binding names another account is another player's: it is
+  * reported (stage `match`) and left alone, never journaled or verified for
+  * this player (a backend would reject it for good as an account mismatch,
+  * and its derived key would then block that player's own recovery). The
+  * player's explicit Restore Purchases pass still takes a durable bound to
+  * another account (restore sharing). A purchase without a binding, or with
+  * a binding of another kind, is not compared. Answer `undefined` (or
+  * throw) only transiently, while this player's binding cannot be read
+  * yet: a bound purchase reported then is kept and asked about again on
+  * the next pass (a resume, an event, an explicit trigger). A runtime for a store or target whose purchases this player's
+  * binding never covers must omit the input; omitted, nothing is compared.
+  */
+  readonly accountBinding?: () => StorePurchaseAccountBinding | undefined | Promise<StorePurchaseAccountBinding | undefined>;
 }
 export declare const defaultStaleLaunchedAfterMs: number;
 /** How long one backend capabilities read may take before the last comparison is kept. */