@mpgd/game-services 0.21.1 → 0.23.0

package/dist/commerce-ledger.d.ts

@@ -0,0 +1,64 @@
+import type { GameServicesStore } from './server.js';
+import { type EntitlementLedgerRevocation, type EntitlementRevocationTransaction, type ProductGrantTransaction, type PurchaseLedgerStatusRequest, type PurchaseLedgerStatusResponse } from './types.js';
+/**
+* Ledger reads and the revocation write path over any `GameServicesStore`
+* (RFC "Revocation and expiry entries"). Kept apart from the transport module
+* so a notification handler can import it without the HTTP and oRPC
+* machinery.
+*/
+/** The D1 bound-parameter cap: every ledger read is issued in chunks of at most this many ids. */
+export declare const ledgerReadChunkSize = 100;
+export declare function chunkLedgerEntryIds(ledgerEntryIds: readonly string[], size?: number): readonly (readonly string[])[];
+/** The revocations reversing any of the given grants, read in chunks the store accepts. */
+export declare function findEntitlementRevocationsChunked(store: GameServicesStore, ledgerEntryIds: readonly string[]): Promise<readonly EntitlementRevocationTransaction[]>;
+/** The grants with the given ids, through the store's batched read when it has one. */
+export declare function getEntitlementTransactionsChunked(store: GameServicesStore, ledgerEntryIds: readonly string[]): Promise<ReadonlyMap<string, ProductGrantTransaction>>;
+/**
+* Whether each grant is still active or which `revoke` entry reversed it
+* (RFC "Revocation and expiry entries"): one status per requested id, in
+* request order, for the grants of `playerId`. A store without revocation
+* support answers `active` for every grant it holds; an id that names no
+* grant, or a grant of another player, is `unknown`.
+*/
+export declare function readPurchaseLedgerStatuses(store: GameServicesStore, input: PurchaseLedgerStatusRequest): Promise<PurchaseLedgerStatusResponse>;
+/** A revocation key reused for another grant than the one it first reversed. */
+export declare class RevocationKeyConflictError extends Error {
+  constructor();
+}
+export type RevokeEntitlementGrantResult = {
+  readonly status: 'revoked';
+  readonly ledgerEntryId: string;
+  readonly alreadyProcessed: boolean;
+} | {
+  readonly status: 'grant_not_found';
+} | {
+  readonly status: 'grant_mismatch';
+}
+/** The notification key already reversed another grant. */
+| {
+  readonly status: 'key_conflict';
+}
+/** The notification's authority identity already reversed another grant. */
+| {
+  readonly status: 'evidence_already_processed';
+};
+/**
+* Appends a `revoke` entry for an earlier grant: the write path of store
+* notification handlers (a Play voided purchase, an App Store refund, an Apps
+* in Toss or Devvit refunded order). The grant must exist and belong to the
+* revocation's player; a store without `recordEntitlementRevocation` throws.
+* Replays of the same notification key, and a second revocation of one
+* grant, answer the first entry with `alreadyProcessed: true`; a key or
+* authority identity reused for another grant is a conflict, not a success.
+*/
+export declare function revokeEntitlementGrant(store: GameServicesStore, input: EntitlementLedgerRevocation): Promise<RevokeEntitlementGrantResult>;
+/** Whether a grant was reversed by a `revoke` entry; false on a store without revocations. */
+export declare function isEntitlementGrantReversed(store: GameServicesStore, ledgerEntryId: string): Promise<boolean>;
+/**
+* The ledger's grants minus those a `revoke` entry reversed: the read an
+* entitlement or balance computation starts from (RFC "Revocation and expiry
+* entries": entitlement reads subtract reversed grants).
+*/
+export declare function listActiveEntitlementTransactions(store: GameServicesStore, options?: {
+  readonly playerId?: string;
+}): Promise<readonly ProductGrantTransaction[]>;

package/dist/commerce-ledger.js

@@ -0,0 +1,146 @@
+import { assertEntitlementLedgerRevocation, assertPurchaseLedgerStatusRequest, assertPurchaseLedgerStatusResponse, } from './types.js';
+/**
+ * Ledger reads and the revocation write path over any `GameServicesStore`
+ * (RFC "Revocation and expiry entries"). Kept apart from the transport module
+ * so a notification handler can import it without the HTTP and oRPC
+ * machinery.
+ */
+/** The D1 bound-parameter cap: every ledger read is issued in chunks of at most this many ids. */
+export const ledgerReadChunkSize = 100;
+export function chunkLedgerEntryIds(ledgerEntryIds, size = ledgerReadChunkSize) {
+    if (!Number.isSafeInteger(size) || size <= 0) {
+        throw new RangeError('Ledger read chunk size must be a positive integer.');
+    }
+    const chunks = [];
+    for (let index = 0; index < ledgerEntryIds.length; index += size) {
+        chunks.push(ledgerEntryIds.slice(index, index + size));
+    }
+    return chunks;
+}
+/** The revocations reversing any of the given grants, read in chunks the store accepts. */
+export async function findEntitlementRevocationsChunked(store, ledgerEntryIds) {
+    const read = store.findEntitlementRevocations;
+    if (read === undefined || ledgerEntryIds.length === 0) {
+        return [];
+    }
+    const revocations = [];
+    for (const chunk of chunkLedgerEntryIds([...new Set(ledgerEntryIds)])) {
+        revocations.push(...await read.call(store, { ledgerEntryIds: chunk }));
+    }
+    return revocations;
+}
+/** The grants with the given ids, through the store's batched read when it has one. */
+export async function getEntitlementTransactionsChunked(store, ledgerEntryIds) {
+    const found = new Map();
+    const unique = [...new Set(ledgerEntryIds)];
+    const batched = store.getEntitlementTransactions;
+    if (batched !== undefined) {
+        for (const chunk of chunkLedgerEntryIds(unique)) {
+            for (const transaction of await batched.call(store, chunk)) {
+                found.set(transaction.ledgerEntryId, transaction);
+            }
+        }
+        return found;
+    }
+    for (const ledgerEntryId of unique) {
+        const transaction = await store.getEntitlementTransaction(ledgerEntryId);
+        if (transaction !== undefined) {
+            found.set(ledgerEntryId, transaction);
+        }
+    }
+    return found;
+}
+/**
+ * Whether each grant is still active or which `revoke` entry reversed it
+ * (RFC "Revocation and expiry entries"): one status per requested id, in
+ * request order, for the grants of `playerId`. A store without revocation
+ * support answers `active` for every grant it holds; an id that names no
+ * grant, or a grant of another player, is `unknown`.
+ */
+export async function readPurchaseLedgerStatuses(store, input) {
+    const request = assertPurchaseLedgerStatusRequest(input);
+    const grants = await getEntitlementTransactionsChunked(store, request.ledgerEntryIds);
+    const owned = [...grants.values()]
+        .filter((grant) => grant.playerId === request.playerId)
+        .map((grant) => grant.ledgerEntryId);
+    const reversedBy = new Map();
+    for (const revocation of await findEntitlementRevocationsChunked(store, owned)) {
+        if (!reversedBy.has(revocation.revokesLedgerEntryId)) {
+            reversedBy.set(revocation.revokesLedgerEntryId, revocation.ledgerEntryId);
+        }
+    }
+    const ownedSet = new Set(owned);
+    const statuses = request.ledgerEntryIds.map((ledgerEntryId) => {
+        const by = reversedBy.get(ledgerEntryId);
+        if (by !== undefined) {
+            return { ledgerEntryId, status: 'reversed', reversedBy: by };
+        }
+        return { ledgerEntryId, status: ownedSet.has(ledgerEntryId) ? 'active' : 'unknown' };
+    });
+    return assertPurchaseLedgerStatusResponse({ statuses });
+}
+/** A revocation key reused for another grant than the one it first reversed. */
+export class RevocationKeyConflictError extends Error {
+    constructor() {
+        super('Entitlement revocation idempotency key is bound to another grant.');
+        this.name = 'RevocationKeyConflictError';
+    }
+}
+/**
+ * Appends a `revoke` entry for an earlier grant: the write path of store
+ * notification handlers (a Play voided purchase, an App Store refund, an Apps
+ * in Toss or Devvit refunded order). The grant must exist and belong to the
+ * revocation's player; a store without `recordEntitlementRevocation` throws.
+ * Replays of the same notification key, and a second revocation of one
+ * grant, answer the first entry with `alreadyProcessed: true`; a key or
+ * authority identity reused for another grant is a conflict, not a success.
+ */
+export async function revokeEntitlementGrant(store, input) {
+    const revocation = assertEntitlementLedgerRevocation(input);
+    if (store.recordEntitlementRevocation === undefined) {
+        throw new Error('This GameServicesStore does not record entitlement revocations.');
+    }
+    const grant = await store.getEntitlementTransaction(revocation.revokesLedgerEntryId);
+    if (grant === undefined) {
+        return { status: 'grant_not_found' };
+    }
+    if (grant.playerId !== revocation.playerId) {
+        return { status: 'grant_mismatch' };
+    }
+    try {
+        const result = await store.recordEntitlementRevocation(revocation);
+        return {
+            status: 'revoked',
+            ledgerEntryId: result.ledgerEntryId,
+            alreadyProcessed: result.alreadyProcessed,
+        };
+    }
+    catch (error) {
+        if (error instanceof RevocationKeyConflictError) {
+            return { status: 'key_conflict' };
+        }
+        if (error instanceof Error && error.name === 'EvidenceAlreadyProcessedError') {
+            return { status: 'evidence_already_processed' };
+        }
+        throw error;
+    }
+}
+/** Whether a grant was reversed by a `revoke` entry; false on a store without revocations. */
+export async function isEntitlementGrantReversed(store, ledgerEntryId) {
+    const revocations = await findEntitlementRevocationsChunked(store, [ledgerEntryId]);
+    return revocations.length > 0;
+}
+/**
+ * The ledger's grants minus those a `revoke` entry reversed: the read an
+ * entitlement or balance computation starts from (RFC "Revocation and expiry
+ * entries": entitlement reads subtract reversed grants).
+ */
+export async function listActiveEntitlementTransactions(store, options = {}) {
+    const transactions = (await store.listEntitlementTransactions()).filter((transaction) => options.playerId === undefined || transaction.playerId === options.playerId);
+    if (store.findEntitlementRevocations === undefined || transactions.length === 0) {
+        return transactions;
+    }
+    const revocations = await findEntitlementRevocationsChunked(store, transactions.map((transaction) => transaction.ledgerEntryId));
+    const reversed = new Set(revocations.map((revocation) => revocation.revokesLedgerEntryId));
+    return transactions.filter((transaction) => !reversed.has(transaction.ledgerEntryId));
+}

package/dist/commerce-reconciler.d.ts

@@ -0,0 +1,191 @@
+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 type { PurchaseVerificationApi } from './client.js';
+import { type CommerceServiceAlignment } from './commerce-evidence-registry.js';
+import type { MonetizationOperationStore } from './monetization-recovery.js';
+import type { GameServicesPurchaseInput, GameServicesPurchaseResult } from './operations.js';
+import type { GameServicesLedgerTarget, VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.js';
+/**
+* Commerce v2 reconciler (RFC "Purchase lifecycle", "Reconciler", and
+* "Idempotency keys"). One reconciler per `CommerceProvider` replaces the
+* per-store recovery drivers: it journals every purchase the game starts or
+* the store reports as one record moving through the RFC states, sends the
+* saved verify request to the game backend, and finishes a purchase only after
+* the backend's ledger grant. Nothing here grants: only the backend response
+* moves a record to `granted`, and only the backend ledger moves it to
+* `revoked`.
+*/
+/** Journal record kind of a commerce v2 purchase. */
+export declare const commercePurchaseOperationKind: 'commerce-purchase';
+export type CommercePurchaseOrigin = 'game' | 'discovered';
+/**
+* One commerce v2 purchase in the `MonetizationOperationStore`. `key` is the
+* store's global key (`createCommercePurchaseOperationKey`); `idempotencyKey`
+* is the purchase key the backend sees: the game's key for a purchase the
+* game started, or the derived key of a purchase discovered from the store.
+* Every state change is its own revision; `request` is saved before the
+* first send and resent unchanged; `response` is the last backend answer.
+*/
+export interface CommercePurchaseOperationRecord {
+  readonly kind: typeof commercePurchaseOperationKind;
+  /** The store must enforce uniqueness across users, not just within one account. */
+  readonly key: string;
+  readonly playerId: string;
+  readonly target: string;
+  readonly deploymentTarget: string;
+  readonly revision: number;
+  readonly idempotencyKey: string;
+  readonly store: StoreId;
+  readonly logicalId: LogicalProductId;
+  /** Unknown while the catalog cannot be read; a client or host finish waits until it is. */
+  readonly productKind?: PurchaseKind;
+  readonly origin: CommercePurchaseOrigin;
+  readonly state: CommercePurchaseState;
+  readonly updatedAt: string;
+  /** The game's purchase input; absent for a purchase discovered from the store. */
+  readonly input?: GameServicesPurchaseInput;
+  readonly purchase?: StorePurchase;
+  /** Saved before the first send and resent unchanged on later passes. */
+  readonly request?: VerifyPurchaseRequest;
+  readonly response?: VerifyPurchaseResponse;
+  readonly ledgerEntryId?: string;
+  readonly error?: CommerceErrorInfo;
+  readonly revokedBy?: string;
+}
+/** The store key of a commerce v2 purchase record: one namespace per ledger target. */
+export declare function createCommercePurchaseOperationKey(target: string, idempotencyKey: string): string;
+export declare function isCommercePurchaseOperationRecord(record: unknown): record is CommercePurchaseOperationRecord;
+/** Summary status of a record: the RFC mapping, with `revoked` kept distinct. */
+export declare function summarizeCommercePurchaseOperation(record: CommercePurchaseOperationRecord): CommercePurchaseSummaryStatus;
+/**
+* Only `granted` and `finishing` records that hold the backend's ledger entry
+* id and a store transaction may be finished. The StoreKit v2 SDK keeps no
+* finish allow-list of its own (the v1 driver's `finishGrantedTransaction`
+* pairing), 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.
+*/
+export declare function assertCommerceFinishAllowed(record: CommercePurchaseOperationRecord): {
+  readonly transactionId: string;
+  readonly ledgerEntryId: string;
+};
+/** The `GameServicesPurchaseResult` a journal record stands for; `pending` allows no client-side grant. */
+export declare function toGameServicesPurchaseResult(record: CommercePurchaseOperationRecord): GameServicesPurchaseResult;
+/** A catalog entry the reconciler resolves kinds and SKUs from without a store read. */
+export interface CommerceReconcilerProduct {
+  readonly logicalId: LogicalProductId;
+  readonly kind: PurchaseKind;
+  readonly storeSku?: string;
+}
+export type CommerceReconcilerFailureStage = 'capabilities' | 'available' | 'catalog' | 'match' | 'journal' | 'verify' | 'finish' | 'ledger-status' | 'restore';
+export type CommerceReconcilerEvent = {
+  readonly type: 'transition';
+  readonly record: CommercePurchaseOperationRecord;
+  /** Undefined when the record was just reserved. */
+  readonly previous: CommercePurchaseState | undefined;
+} | {
+  readonly type: 'verify-requested';
+  readonly record: CommercePurchaseOperationRecord;
+} | {
+  readonly type: 'verify-result';
+  readonly record: CommercePurchaseOperationRecord;
+  readonly response: VerifyPurchaseResponse;
+} | {
+  readonly type: 'failure';
+  readonly stage: CommerceReconcilerFailureStage;
+  readonly idempotencyKey?: string;
+  readonly error: unknown;
+};
+export interface CreateCommerceReconcilerInput {
+  readonly provider: CommerceProvider;
+  /** The game backend; `getPurchaseLedgerStatus` enables the revocation pass once the server exposes it (C2). */
+  readonly backend: PurchaseVerificationApi;
+  /** Durable, compare-and-swap journal shared with the v1 recovery client. */
+  readonly store: MonetizationOperationStore;
+  readonly playerId: string;
+  /** Ledger target sent as `VerifyPurchaseRequest.target`. */
+  readonly target: GameServicesLedgerTarget;
+  readonly deploymentTarget?: string;
+  /**
+  * Catalog mapping consulted before `fetchProducts`; required for a provider
+  * whose product list cannot be read before the first purchase.
+  */
+  readonly products?: readonly CommerceReconcilerProduct[];
+  readonly now?: () => string;
+  readonly onEvent?: (event: CommerceReconcilerEvent) => void;
+  /**
+  * How long a `launched` record with no store purchase keeps serializing
+  * purchases of its product. After it the attempt is `failed` with
+  * `OUTCOME_UNKNOWN`; a purchase the store reports later is journaled under
+  * its derived key. Defaults to 24 hours; `Infinity` keeps the RFC rule
+  * without expiry.
+  */
+  readonly staleLaunchedAfterMs?: number;
+  /**
+  * Minimum time before an event-triggered pass retries a record's backend
+  * or store step: resending a backend-pending request, a verify or finish
+  * that failed in transport, a finalization re-read, or a catalog lookup.
+  * An explicit trigger (`start`, `reconcile`, `restorePurchases`) always
+  * retries. Defaults to one minute; `0` retries on every pass.
+  */
+  readonly retryIntervalMs?: number;
+  /**
+  * How long a running store call keeps its product serialized and its
+  * events waiting. A call that has not answered after this (a store sheet
+  * that never settles) stops deferring: events for the product are
+  * reconciled as they come and a new purchase of it may start. Defaults to
+  * ten minutes.
+  */
+  readonly inFlightTimeoutMs?: number;
+  /**
+  * How long the backend's `getCommerceCapabilities` read may take at start
+  * and on explicit passes before the last comparison is kept. Defaults to
+  * ten seconds.
+  */
+  readonly serviceCapabilitiesTimeoutMs?: number;
+}
+export declare const defaultStaleLaunchedAfterMs: number;
+/** How long one backend capabilities read may take before the last comparison is kept. */
+export declare const defaultServiceCapabilitiesTimeoutMs: number;
+/** `compareCommerceServiceCapabilities`'s answer, or `unpublished` for a backend without the read. */
+export type CommerceReconcilerServiceAlignment = CommerceServiceAlignment | {
+  readonly status: 'unpublished';
+  readonly store: StoreId;
+};
+export declare const defaultRetryIntervalMs: number;
+export declare const defaultInFlightTimeoutMs: number;
+export interface CommerceReconciler {
+  readonly provider: CommerceProvider;
+  readonly started: boolean;
+  /**
+  * The last comparison of the provider's capabilities with the backend's
+  * published ones (RFC "Provider capabilities endpoint"); undefined until
+  * the first read, or when the backend offers no `getCommerceCapabilities`
+  * (`unpublished` once a backend answered that it has no such read). While
+  * it is `configuration-required`, the capabilities this reconciler reports
+  * carry that availability and `requestPurchase` refuses with
+  * `CONFIGURATION_REQUIRED`; a purchase never opens the store before the
+  * comparison was attempted.
+  */
+  readonly serviceAlignment: CommerceReconcilerServiceAlignment | undefined;
+  /** The provider's capability block with the backend alignment applied to `availability`. */
+  getCapabilities(): Promise<CommerceCapabilities>;
+  /** Subscribe to the provider, read its available purchases when declared, then reconcile until idle. */
+  start(): Promise<void>;
+  /** Unsubscribe and drop in-memory state; the journal keeps every record. */
+  stop(): Promise<void>;
+  /** One reconcile pass (the app-resume trigger), then any passes that events arriving meanwhile trigger. */
+  reconcile(): Promise<void>;
+  /** Reconcile while a trigger is pending; a no-op when stopped. */
+  runUntilIdle(): Promise<void>;
+  /** The manual restore trigger: `provider.restorePurchases` when offered, then a pass over the available purchases. */
+  restorePurchases(): Promise<void>;
+  /** Journals the attempt, opens the store once per key, and reconciles the result. Never reopens the store UI for a journaled key. */
+  requestPurchase(input: RequestPurchaseInput): Promise<RequestPurchaseResult>;
+  fetchProducts(input?: FetchProductsInput): Promise<readonly StoreProduct[]>;
+  /** The record journaled under a purchase idempotency key. */
+  read(idempotencyKey: string): Promise<CommercePurchaseOperationRecord | undefined>;
+  /** The player's open records for this provider's store. */
+  listRecoverable(): Promise<readonly CommercePurchaseOperationRecord[]>;
+  subscribe(listener: (event: CommerceReconcilerEvent) => void): () => void;
+}
+export declare function createCommerceReconciler(input: CreateCommerceReconcilerInput): CommerceReconciler;