@mpgd/game-services 0.21.1 → 0.22.0

package/README.md

@@ -20,6 +20,36 @@ installed by game clients, and no other subpath imports it. It moved here from
 `@mpgd/adapter-capacitor/app-store-server`, which stays as a deprecated
 re-export for one release.
 
+## Commerce v2 reconciler
+
+`createCommerceReconciler` from `@mpgd/game-services/commerce-reconciler` is
+the RFC "Reconciler" over any commerce v2 `CommerceProvider`: it journals every
+purchase as a `commerce-purchase` record of the `MonetizationOperationStore`,
+sends the saved verify request to the backend, finishes a purchase only after
+the ledger grant, and never grants on the client. `createGameServicesClient`
+purchases through it whenever `gateway.commerceV2` exists and exposes it as
+`commerceReconciler`; `createRecoverableMonetizationClient` and
+`createGameServicesRuntime` run it from `monetizationRecovery.reconcile()` and
+`restorePurchases()` over the durable journal. See
+[docs/MONETIZATION_RECOVERY.md](../../docs/MONETIZATION_RECOVERY.md).
+
+## Commerce evidence registry
+
+`createCommerceEvidenceRegistry` from
+`@mpgd/game-services/commerce-evidence-registry` is the RFC "Evidence
+registry": the backend routes every verify request by `evidence.schema` to the
+registered verifier and finalizer, publishes the stores it accepts through
+`getCommerceCapabilities` (`CommerceServiceCapabilities`), and rejects an
+unknown schema (`EVIDENCE_SCHEMA_UNSUPPORTED`) or one registered for another
+store (`EVIDENCE_SCHEMA_STORE_MISMATCH`) before any verifier runs. Reference
+entries wrap the Play, App Store, Microsoft Store, and Apps in Toss verifiers,
+and the server-push stores (`devvit.order.v1`, `verse8.agent8-event.v1`) get
+lookup verifiers that answer the grant the host's fulfillment path already
+wrote, never the client envelope. `@mpgd/game-services/commerce-ledger` adds
+the `revoke` entry write path (`revokeEntitlementGrant`), the ledger status
+read behind `getPurchaseLedgerStatus`, and `listActiveEntitlementTransactions`.
+See [docs/GAME_SERVICES_BACKEND.md](../../docs/GAME_SERVICES_BACKEND.md).
+
 ## Registered rewarded-ad evidence
 
 `createGameServicesClient`, `createRecoverableMonetizationClient`, and

package/dist/admob-ssv-conformance.js

@@ -241,7 +241,9 @@ function fixedPublicKeySource(publicKeys) {
     };
 }
 function assertDecision(decision, status, reason) {
-    const receivedReason = decision.status === 'verified' ? undefined : decision.reason;
+    const receivedReason = decision.status === 'verified' || decision.status === 'settled'
+        ? undefined
+        : decision.reason;
     assert(decision.status === status && receivedReason === reason, `expected ${status}/${reason}, received ${decision.status}/${String(receivedReason)}`);
 }
 function assert(condition, message) {

package/dist/app-store-recovery.js

@@ -177,6 +177,11 @@ async function verifyRestoredNonConsumable(input, request, options) {
     if (decision.status === 'rejected') {
         return rejected(decision.reason);
     }
+    if (decision.status === 'settled') {
+        // Restored non-consumables are re-verified against Apple, never settled
+        // by a ledger lookup.
+        return rejected('APP_STORE_RESTORE_EVIDENCE_MISMATCH');
+    }
     const originalTransactionId = decision.payload?.appStoreOriginalTransactionId;
     const environment = decision.payload?.appStoreEnvironment;
     const bundleId = decision.payload?.appStoreBundleId;

package/dist/client.d.ts

@@ -1,13 +1,30 @@
 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 { 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 { ClaimAdRewardRequest, ClaimAdRewardResponse, GameServicesLedgerTarget, RecordLeaderboardScoreRequest, RecordLeaderboardScoreResponse, VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.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 interface PurchaseVerificationApi {
   verifyPurchase(input: VerifyPurchaseRequest): Promise<VerifyPurchaseResponse>;
+  /**
+  * Whether earlier ledger grants are still active (RFC "Revocation and
+  * expiry entries"). The commerce reconciler runs its revocation pass only
+  * when a backend offers this read; the reference server offers it since C2.
+  */
+  getPurchaseLedgerStatus?(input: PurchaseLedgerStatusRequest): Promise<PurchaseLedgerStatusResponse>;
+  /**
+  * What the backend accepts (RFC "Provider capabilities endpoint"): the
+  * stores its commerce evidence registry serves, their schemas, and who
+  * finishes. The commerce reconciler compares it with its provider at start
+  * when a backend offers it; the reference server offers it when it was
+  * created with a `commerceEvidenceRegistry`.
+  */
+  getCommerceCapabilities?(): Promise<CommerceServiceCapabilities>;
 }
 export interface AdRewardClaimApi {
   claimAdReward(input: ClaimAdRewardRequest): Promise<ClaimAdRewardResponse>;
@@ -23,6 +40,8 @@ export interface GameServicesBackendApi {
 }
 export declare const gameServicesBackendEndpoints: {
   readonly verifyPurchase: '/game-services/purchases/verify';
+  readonly getPurchaseLedgerStatus: '/game-services/purchases/ledger-status';
+  readonly getCommerceCapabilities: '/game-services/purchases/capabilities';
   readonly claimAdReward: '/game-services/ad-rewards/claim';
   readonly recordLeaderboardScore: '/game-services/leaderboard/record';
 };
@@ -89,6 +108,12 @@ export declare function resolveGameServicesRequestHeaders(input: {
 }): Promise<Readonly<Record<string, string>>>;
 export interface GameServicesClient extends GameServicesOperationClient {
   submitLeaderboardScore(input: GameServicesLeaderboardInput): Promise<GameServicesLeaderboardResult>;
+  /**
+  * The commerce v2 reconciler behind `purchase` when the gateway exposes
+  * `commerceV2`. Call `start()` at runtime start and `reconcile()` on app
+  * resume; `purchase` starts it on first use.
+  */
+  readonly commerceReconciler?: CommerceReconciler;
 }
 export interface CreateGameServicesClientInput {
   readonly gateway: PlatformGateway;
@@ -103,6 +128,19 @@ export interface CreateGameServicesClientInput {
   readonly requestNow?: () => string;
   /** Explicit client decoders only; server verification is configured independently. */
   readonly rewardEvidenceRegistry?: ClientRewardEvidenceRegistry;
+  /**
+  * Journal of the commerce v2 reconciler used when `gateway.commerceV2`
+  * exists. Without one the journal lives in memory for this session only:
+  * duplicates are then caught by the backend ledger, not by the client.
+  */
+  readonly operationStore?: MonetizationOperationStore;
+  /** A reconciler shared with another client, for example the recovery client's. */
+  readonly commerceReconciler?: CommerceReconciler;
+  /** Receives the one-time warning about a session-only commerce journal; defaults to `console.warn`. */
+  readonly warn?: (message: string) => void;
+  /** Catalog kinds and SKUs the reconciler resolves without a store read. */
+  readonly commerceProducts?: readonly CommerceReconcilerProduct[];
+  readonly onCommerceEvent?: (event: CommerceReconcilerEvent) => void;
 }
 export interface GameServicesLeaderboardInput extends LeaderboardScoreInput {
 }

package/dist/client.js

@@ -3,10 +3,14 @@ import { RPCLink } from '@orpc/client/fetch';
 import { createAnalyticsReporter } from '@mpgd/analytics';
 import { findAdapterSettledGrant } from './authoritative-purchase.js';
 import { resolveClientRewardClaim, } from './client-reward-evidence.js';
+import { createCommerceReconciler, toGameServicesPurchaseResult, } from './commerce-reconciler.js';
 import { createDefaultClientRewardEvidenceRegistry } from './default-client-reward-evidence.js';
+import { createInMemoryMonetizationOperationStore } from './monetization-operation-store.js';
 import { observeGameServicesOperation } from './operation-progress.js';
 export const gameServicesBackendEndpoints = {
     verifyPurchase: '/game-services/purchases/verify',
+    getPurchaseLedgerStatus: '/game-services/purchases/ledger-status',
+    getCommerceCapabilities: '/game-services/purchases/capabilities',
     claimAdReward: '/game-services/ad-rewards/claim',
     recordLeaderboardScore: '/game-services/leaderboard/record',
 };
@@ -66,8 +70,190 @@ export function createGameServicesClient(input) {
         now,
         ...(input.analytics === undefined ? {} : { sink: input.analytics }),
     });
+    const commerceProvider = input.gateway.commerceV2;
+    let commerceReconciler;
+    if (commerceProvider !== undefined) {
+        if (input.commerceReconciler === undefined && input.operationStore === undefined) {
+            (input.warn ?? console.warn)('@mpgd/game-services: the commerce v2 reconciler is journaling in memory for this session '
+                + 'because no operationStore was given; purchases are not recoverable across restarts and '
+                + 'the backend ledger is the only duplicate backstop. Pass a durable MonetizationOperationStore.');
+        }
+        commerceReconciler = input.commerceReconciler ?? createCommerceReconciler({
+            provider: commerceProvider,
+            backend: input.backend.purchases,
+            store: input.operationStore ?? createInMemoryMonetizationOperationStore(),
+            playerId: input.playerId,
+            target: input.target,
+            ...(input.deploymentTarget === undefined ? {} : { deploymentTarget: input.deploymentTarget }),
+            ...(input.commerceProducts === undefined ? {} : { products: input.commerceProducts }),
+            now: requestNow,
+        });
+        if (input.onCommerceEvent !== undefined) {
+            commerceReconciler.subscribe(input.onCommerceEvent);
+        }
+    }
+    /** Keys of purchase calls in flight, and those whose backend verdict the observer tracked meanwhile. */
+    const inFlightKeys = new Set();
+    const trackedVerdicts = new Set();
+    const markTracked = (key) => {
+        if (inFlightKeys.has(key)) {
+            trackedVerdicts.add(key);
+        }
+    };
+    if (commerceReconciler !== undefined && input.commerceReconciler === undefined) {
+        // Verdicts arrive as events, inside or after a purchase call; each is tracked once.
+        commerceReconciler.subscribe((event) => {
+            if (event.type !== 'transition' || event.previous === undefined) {
+                return;
+            }
+            const { record } = event;
+            const productId = record.logicalId;
+            if (event.previous === 'verifying' && record.state === 'granted') {
+                markTracked(record.idempotencyKey);
+                analytics.track({
+                    name: 'purchase_granted',
+                    properties: {
+                        productId,
+                        status: 'granted',
+                        ledgerEntryId: record.ledgerEntryId,
+                        alreadyProcessed: record.response?.alreadyProcessed,
+                    },
+                }).catch(() => { });
+            }
+            else if (event.previous === 'verifying' && record.state === 'rejected') {
+                markTracked(record.idempotencyKey);
+                analytics.track({
+                    name: 'purchase_rejected',
+                    properties: { productId, status: 'rejected', reason: record.response?.reason },
+                }).catch(() => { });
+            }
+            else if (event.previous === 'verifying' && record.state === 'pending') {
+                markTracked(record.idempotencyKey);
+                analytics.track({
+                    name: 'purchase_pending',
+                    properties: {
+                        productId,
+                        status: 'pending',
+                        reason: record.response?.reason ?? 'purchase_pending',
+                    },
+                }).catch(() => { });
+            }
+            else if (record.state === 'cancelled' || record.state === 'failed') {
+                markTracked(record.idempotencyKey);
+                analytics.track({
+                    name: 'purchase_rejected',
+                    properties: { productId, status: record.state, reason: record.error?.code },
+                }).catch(() => { });
+            }
+        });
+    }
     return {
+        ...(commerceReconciler === undefined ? {} : { commerceReconciler }),
         async purchase(purchaseInput, options) {
+            const reconciler = commerceReconciler;
+            if (reconciler !== undefined) {
+                return observeGameServicesOperation('purchase', options, async (progress) => {
+                    const key = purchaseInput.idempotencyKey;
+                    trackedVerdicts.delete(key);
+                    inFlightKeys.add(key);
+                    if (!reconciler.started) {
+                        await reconciler.start();
+                    }
+                    // The store phase ends when the journal records what the store answered;
+                    // the reconcile pass inside requestPurchase then reports the server phases.
+                    let platformReported = false;
+                    let serverRequested = false;
+                    let serverResulted = false;
+                    const reportPlatform = (status) => {
+                        if (!platformReported) {
+                            platformReported = true;
+                            progress.platformResult(status);
+                        }
+                    };
+                    const unsubscribe = reconciler.subscribe((event) => {
+                        if (event.type === 'failure' || event.record.idempotencyKey !== key) {
+                            return;
+                        }
+                        if (event.type === 'transition') {
+                            const { state } = event.record;
+                            if (state === 'purchased') {
+                                reportPlatform('completed');
+                            }
+                            else if (state === 'pending' && event.previous === 'launched') {
+                                reportPlatform('pending');
+                            }
+                            else if ((state === 'cancelled' || state === 'failed') && event.previous !== 'verifying') {
+                                reportPlatform(state);
+                            }
+                        }
+                        else if (event.type === 'verify-requested') {
+                            reportPlatform('completed');
+                            // A server-owned finish may re-read finalization in the same
+                            // pass; the server phase is reported once per call.
+                            if (!serverRequested) {
+                                serverRequested = true;
+                                progress.serverRequested();
+                            }
+                        }
+                        else if (!serverResulted) {
+                            serverResulted = true;
+                            progress.serverResult(event.response.verified);
+                        }
+                    });
+                    try {
+                        progress.platformRequested();
+                        const outcome = await reconciler.requestPurchase({
+                            logicalId: purchaseInput.productId,
+                            idempotencyKey: key,
+                            source: purchaseInput.source,
+                        });
+                        reportPlatform(outcome.outcome === 'launched'
+                            ? 'pending'
+                            : outcome.outcome === 'purchased'
+                                ? (outcome.purchase.state === 'purchased' ? 'completed' : 'pending')
+                                : outcome.outcome);
+                        const record = await reconciler.read(key);
+                        const result = record === undefined
+                            ? {
+                                status: 'failed',
+                                purchase: {
+                                    status: 'failed',
+                                    entitlementIds: [],
+                                    ...(outcome.outcome === 'cancelled' || outcome.outcome === 'failed'
+                                        ? { diagnostic: { code: outcome.error.code, retryable: outcome.error.retryable } }
+                                        : {}),
+                                },
+                            }
+                            : toGameServicesPurchaseResult(record);
+                        if (!trackedVerdicts.has(key)) {
+                            // The call ended without a backend verdict (the store answers later,
+                            // or a journaled attempt was replayed); report the status it returns.
+                            await analytics.track({
+                                name: result.status === 'granted'
+                                    ? 'purchase_granted'
+                                    : result.status === 'pending'
+                                        ? 'purchase_pending'
+                                        : 'purchase_rejected',
+                                properties: {
+                                    productId: purchaseInput.productId,
+                                    status: result.status,
+                                    ledgerEntryId: result.ledgerEntryId,
+                                    alreadyProcessed: result.verification?.alreadyProcessed,
+                                    reason: result.status === 'pending'
+                                        ? 'purchase_pending'
+                                        : (result.verification?.reason ?? record?.error?.code),
+                                },
+                            });
+                        }
+                        return result;
+                    }
+                    finally {
+                        unsubscribe();
+                        inFlightKeys.delete(key);
+                        trackedVerdicts.delete(key);
+                    }
+                });
+            }
             return observeGameServicesOperation('purchase', options, async (progress) => {
                 const target = input.target;
                 if (!isGameServicesCommerceTarget(target)) {
@@ -313,6 +499,12 @@ export function createGameServicesHttpBackendApi(input) {
             async verifyPurchase(body) {
                 return sendGameServicesBackendRequest(input.transport, gameServicesBackendEndpoints.verifyPurchase, body);
             },
+            async getPurchaseLedgerStatus(body) {
+                return sendGameServicesBackendRequest(input.transport, gameServicesBackendEndpoints.getPurchaseLedgerStatus, body);
+            },
+            async getCommerceCapabilities() {
+                return sendGameServicesBackendRequest(input.transport, gameServicesBackendEndpoints.getCommerceCapabilities, {});
+            },
         },
         adRewards: {
             async claimAdReward(body) {
@@ -368,6 +560,12 @@ export function createGameServicesOrpcBackendApi(client) {
             verifyPurchase(input) {
                 return client.commerce.verifyPurchase(input);
             },
+            getPurchaseLedgerStatus(input) {
+                return client.commerce.getPurchaseLedgerStatus(input);
+            },
+            getCommerceCapabilities() {
+                return client.commerce.getCapabilities();
+            },
         },
         adRewards: {
             claimAdReward(input) {