@mpgd/game-services 0.21.0 → 0.22.0

package/dist/commerce-evidence-registry.d.ts

@@ -0,0 +1,406 @@
+import type { ProductCatalog } from '@mpgd/catalog';
+import type { CommerceCapabilities, CommerceFinishOwner, PlatformEvidenceEnvelope } from '@mpgd/platform';
+import { type CommerceServiceCapabilities, type CommerceServiceStoreCapabilities, type StoreId } from '@mpgd/platform/commerce';
+import type { EvidenceVerificationDecision, GameServicesEvidenceVerifier, GameServicesPurchaseGrantFinalizer, VerifyPurchaseEvidenceInput } from './evidence-verification.js';
+import type { GameServicesStore } from './server.js';
+import { type EntitlementLedgerGrant, type EntitlementLedgerPayload, type ProductGrantTransaction, type VerifyPurchaseRequest } from './types.js';
+/**
+* Commerce v2 evidence registry (RFC "Server: commerce service protocol").
+* The game composes one registry from the reference entries below and its
+* own; the backend routes every verify request by `evidence.schema` to the
+* entry that claims it, publishes the stores it accepts through the
+* capabilities endpoint, and finalizes server-finish grants through the
+* entry's finalizer. Nothing here grants: an entry's verifier decides, and
+* the backend writes the ledger.
+*/
+/** Stable rejection reasons the registry answers before any verifier runs. */
+export type CommerceEvidenceRegistryErrorCode = 'EVIDENCE_SCHEMA_UNSUPPORTED' | 'EVIDENCE_SCHEMA_STORE_MISMATCH' | 'EVIDENCE_SCHEMA_TARGET_MISMATCH';
+/** The purchase kinds a store sells, as the capabilities endpoint publishes them. */
+export type CommerceServicePurchaseCapabilities = CommerceServiceStoreCapabilities['purchase'];
+export interface CommerceEvidenceRegistryEntry {
+  /** The evidence schema this entry verifies, for example `google-play.product-purchase.v2`. */
+  readonly schema: string;
+  readonly store: StoreId;
+  readonly verifier: Pick<GameServicesEvidenceVerifier, 'verifyPurchase'>;
+  /** Required when `finish` is `server`; registry construction fails otherwise. */
+  readonly finalizer?: GameServicesPurchaseGrantFinalizer;
+  readonly finish: CommerceFinishOwner;
+  /** Spend scope of credit lots bought through this store. Default 'title'. */
+  readonly creditScope?: 'title' | 'cross-title';
+  /**
+  * Route a request of this store that carries no evidence envelope to this
+  * entry (the App Store verifier keeps its Server API lookup for one). At
+  * most one entry per store may declare it.
+  */
+  readonly acceptsMissingEvidence?: boolean;
+  /**
+  * Route a request of this store whose schema no entry claims to this entry
+  * as well (a verifier binding that keeps its own schema list). At most one
+  * entry per store may declare it; without one such a request is rejected.
+  */
+  readonly acceptsUnclaimedSchemas?: boolean;
+  /**
+  * The ledger targets a request of this store may name (`request.target`).
+  * A request naming another target is rejected with
+  * `EVIDENCE_SCHEMA_TARGET_MISMATCH`; absent, any target is accepted.
+  */
+  readonly targets?: readonly string[];
+  /**
+  * What the store sells, published by the capabilities endpoint. Defaults to
+  * consumable and durable one-time products; every entry of one store is
+  * merged.
+  */
+  readonly purchase?: CommerceServicePurchaseCapabilities;
+}
+/** A store the `unregistered` fallback verifier serves, published by the capabilities endpoint. */
+export interface CommerceEvidenceFallbackStore {
+  readonly store: StoreId;
+  readonly finish: CommerceFinishOwner;
+  readonly purchase?: CommerceServicePurchaseCapabilities;
+  readonly targets?: readonly string[];
+}
+export interface CreateCommerceEvidenceRegistryOptions {
+  /**
+  * A deployment's v1 verifier (and finalizer) for requests whose schema no
+  * entry claims, so a registry can be introduced next to an existing
+  * aggregate verifier. Without it such a request is rejected with
+  * `EVIDENCE_SCHEMA_UNSUPPORTED`. A schema an entry claims never reaches it.
+  */
+  readonly unregistered?: {
+    readonly verifier: Pick<GameServicesEvidenceVerifier, 'verifyPurchase'>;
+    readonly finalizer?: GameServicesPurchaseGrantFinalizer;
+    /**
+    * The stores the fallback publishes through the capabilities endpoint
+    * (with no schemas), so a client of such a store is not told
+    * `configuration-required`. Absent, nothing is published for the
+    * fallback.
+    */
+    readonly stores?: readonly CommerceEvidenceFallbackStore[];
+    /**
+    * Whether the fallback also serves stores it did not declare (a v1
+    * aggregate verifier that served every target). Defaults to true when
+    * `stores` is absent and to false when it is given: a declared list is
+    * then also the list of served stores, and any other store is rejected.
+    */
+    readonly servesUndeclaredStores?: boolean;
+  };
+}
+export type CommerceEvidenceRoute = {
+  readonly status: 'routed';
+  readonly store: StoreId;
+  readonly entry: CommerceEvidenceRegistryEntry;
+} | {
+  /** No entry claims the request's schema (or its missing envelope). */
+  readonly status: 'unregistered';
+  readonly store: StoreId;
+} | {
+  readonly status: 'rejected';
+  readonly store: StoreId;
+  readonly reason: CommerceEvidenceRegistryErrorCode;
+};
+export interface CommerceEvidenceRegistry {
+  readonly entries: readonly CommerceEvidenceRegistryEntry[];
+  /** Every store the registry serves: the entries' stores and the fallback's declared ones. */
+  readonly stores: ReadonlySet<StoreId>;
+  /**
+  * Whether a request is served at all: a served store, or (with
+  * `servesUndeclaredStores`) an undeclared store whose target's v1 store is
+  * not itself served. The backend answers a 400 otherwise.
+  */
+  serves(request: Pick<VerifyPurchaseRequest, 'target' | 'store'>): boolean;
+  /** Whether the fallback serves stores it did not declare. */
+  readonly servesUndeclaredStores: boolean;
+  /**
+  * The ledger targets requests of a served store may name: the union of the
+  * store's entries' `targets` (or the declared fallback store's), or
+  * undefined when any target is accepted or the store is not served.
+  */
+  allowedTargets(store: StoreId): ReadonlySet<string> | undefined;
+  /** The store a request names: `store`, or the v1 mapping of its `target`. */
+  resolveStore(request: Pick<VerifyPurchaseRequest, 'target' | 'store'>): StoreId;
+  /** Where a request's evidence is routed, without running a verifier. */
+  route(request: Pick<VerifyPurchaseRequest, 'target' | 'store' | 'evidence'>): CommerceEvidenceRoute;
+  /** Routes the request and runs the entry's verifier; a `GameServicesEvidenceVerifier.verifyPurchase`. */
+  verifyPurchase(input: VerifyPurchaseEvidenceInput): Promise<EvidenceVerificationDecision>;
+  /** Routes a grant to the entry's finalizer; a `GameServicesPurchaseGrantFinalizer`. */
+  readonly finalizer: GameServicesPurchaseGrantFinalizer;
+  /** What the backend accepts, for the provider capabilities endpoint. */
+  getCapabilities(): CommerceServiceCapabilities;
+}
+/**
+* The v1 request mapping (RFC "Open store ids"): a request without `store`
+* names its store through its deployment target. `android` is `google-play`,
+* `ios` is `app-store`, `ait` is `apps-in-toss`, `reddit` is `devvit`, and
+* every other target is its own store id (`microsoft-store`, `verse8`,
+* `oneplay`, or a project store that reuses its target name).
+*/
+export declare function resolveLegacyCommerceStoreId(target: string): StoreId;
+/** The store a verify request names: its `store`, or the v1 mapping of its `target`. */
+export declare function resolveCommerceStoreId(request: Pick<VerifyPurchaseRequest, 'target' | 'store'>): StoreId;
+/**
+* Builds the registry. Construction fails when two entries claim one schema,
+* when a `finish: 'server'` entry has no finalizer, when two entries of one
+* store disagree on `finish`, or when more than one entry of a store accepts
+* a missing envelope.
+*/
+export declare function createCommerceEvidenceRegistry(entries: readonly CommerceEvidenceRegistryEntry[], options?: CreateCommerceEvidenceRegistryOptions): CommerceEvidenceRegistry;
+/** The ledger target each reference store's verify requests name (RFC "Open store ids"). */
+export declare const referenceCommerceLedgerTargets: Readonly<{
+  'google-play': readonly string[];
+  'app-store': readonly string[];
+  'microsoft-store': readonly string[];
+  'apps-in-toss': readonly string[];
+  devvit: readonly string[];
+  verse8: readonly string[];
+}>;
+/** The RFC profile purchase flags of the reference stores. */
+export declare const referenceCommercePurchaseCapabilities: Readonly<{
+  'google-play': Readonly<{
+    consumable: true;
+    durable: true;
+    subscription: false;
+  }>;
+  'app-store': Readonly<{
+    consumable: true;
+    durable: true;
+    subscription: false;
+  }>;
+  'microsoft-store': Readonly<{
+    consumable: true;
+    durable: false;
+    subscription: false;
+  }>;
+  'apps-in-toss': Readonly<{
+    consumable: true;
+    durable: true;
+    subscription: false;
+  }>;
+  devvit: Readonly<{
+    consumable: true;
+    durable: true;
+    subscription: false;
+  }>;
+  verse8: Readonly<{
+    consumable: true;
+    durable: true;
+    subscription: false;
+  }>;
+}>;
+export declare const googlePlayCommerceStoreId: 'google-play';
+export declare const appStoreCommerceStoreId: 'app-store';
+export declare const microsoftStoreCommerceStoreId: 'microsoft-store';
+export declare const appsInTossCommerceStoreId: 'apps-in-toss';
+export declare const devvitCommerceStoreId: 'devvit';
+export declare const verse8CommerceStoreId: 'verse8';
+export declare const googlePlayCommerceEvidenceSchema: 'google-play.product-purchase.v2';
+export declare const appStoreCommerceEvidenceSchema: 'app-store.signed-transaction.v1';
+export declare const microsoftStoreCommerceEvidenceSchema: 'mpgd.microsoft-store.digital-goods.v1';
+export declare const appsInTossCommerceEvidenceSchema: 'apps-in-toss.iap.callback.v1';
+export declare const devvitPaymentOrderEvidenceSchema: 'devvit.payment-order.v1';
+export declare const devvitOrderEvidenceSchema: 'devvit.order.v1';
+export declare const verse8Agent8EventEvidenceSchema: 'verse8.agent8-event.v1';
+/**
+* `google-play.product-purchase.v2`: the Play boundary verifies the purchase
+* token and, after the ledger grant, acknowledges or consumes it
+* (`finish: 'server'`). Pass `createGooglePlayProductPurchaseBoundary(...)`,
+* or a verifier binding plus a separate finalizer.
+*/
+export declare function createGooglePlayCommerceEvidenceEntry(input: {
+  readonly verifier: Pick<GameServicesEvidenceVerifier, 'verifyPurchase'>;
+  /** Required for `finish: 'server'` (the default). */
+  readonly finalizer?: GameServicesPurchaseGrantFinalizer;
+  /** Route a token-less request to the verifier too; the Play boundary rejects one itself. */
+  readonly acceptsMissingEvidence?: boolean;
+  /** Route any schema of the store to the verifier (a binding that keeps its own list). */
+  readonly acceptsUnclaimedSchemas?: boolean;
+  /** Who finishes; `client` only for a verifier that acknowledges the purchase itself. */
+  readonly finish?: Extract<CommerceFinishOwner, 'server' | 'client'>;
+  readonly targets?: readonly string[];
+}): CommerceEvidenceRegistryEntry;
+/**
+* `app-store.signed-transaction.v1`: the App Store verifier checks the
+* StoreKit JWS offline and decides on the Server API status; a request
+* without the envelope keeps the `Get Transaction Info` lookup, so the entry
+* accepts a missing envelope. The client finishes after the ledger grant.
+*/
+export declare function createAppStoreCommerceEvidenceEntry(input: {
+  readonly verifier: Pick<GameServicesEvidenceVerifier, 'verifyPurchase'>;
+  /** Defaults to true: a request without the JWS keeps the Server API lookup. */
+  readonly acceptsMissingEvidence?: boolean;
+  readonly acceptsUnclaimedSchemas?: boolean;
+  readonly targets?: readonly string[];
+}): CommerceEvidenceRegistryEntry;
+/**
+* `mpgd.microsoft-store.digital-goods.v1`: the Collections verifier before
+* the grant and the consume finalizer after it (`finish: 'server'`), always
+* configured together.
+*/
+export declare function createMicrosoftStoreCommerceEvidenceEntry(input: {
+  readonly verifier: Pick<GameServicesEvidenceVerifier, 'verifyPurchase'>;
+  readonly finalizer: GameServicesPurchaseGrantFinalizer;
+  readonly acceptsMissingEvidence?: boolean;
+  readonly acceptsUnclaimedSchemas?: boolean;
+  readonly targets?: readonly string[];
+}): CommerceEvidenceRegistryEntry;
+/**
+* `apps-in-toss.iap.callback.v1`: the production evidence verifier binds the
+* order through the partner API; the host finishes (`completeProductGrant`)
+* after the ledger grant.
+*/
+export declare function createAppsInTossCommerceEvidenceEntry(input: {
+  readonly verifier: Pick<GameServicesEvidenceVerifier, 'verifyPurchase'>;
+  readonly acceptsMissingEvidence?: boolean;
+  readonly acceptsUnclaimedSchemas?: boolean;
+  readonly targets?: readonly string[];
+}): CommerceEvidenceRegistryEntry;
+export interface DevvitPaymentOrderAuthorityInput {
+  readonly orderId: string;
+  readonly playerId: string;
+  readonly platformSku: string;
+  readonly signal: AbortSignal;
+}
+/** A Reddit order as the deployment's payments authority reports it. */
+export interface DevvitPaymentOrderRecord {
+  readonly orderId: string;
+  /** The purchasing Reddit account as the payments authority knows it. */
+  readonly playerId: string;
+  readonly sku: string;
+  readonly status: 'PAID' | 'DELIVERED' | 'REVERTED' | string;
+  /** ISO timestamp of the status change. */
+  readonly occurredAt?: string;
+}
+export type DevvitPaymentOrderAuthorityResult = {
+  readonly decision: 'resolved';
+  readonly order: DevvitPaymentOrderRecord;
+} | {
+  readonly decision: 'pending';
+  readonly reason?: string;
+} | {
+  readonly decision: 'rejected';
+  readonly reason: string;
+};
+/**
+* Game-owned port the `devvit.payment-order.v1` verifier binds an order
+* through: the Devvit `payments` plugin's order read on the Devvit server, or
+* the fulfillment handler's own order when the backend runs in that process.
+* It is the authority; the envelope only names the order.
+*/
+export interface DevvitPaymentOrderAuthority {
+  getOrder(input: DevvitPaymentOrderAuthorityInput): Promise<DevvitPaymentOrderAuthorityResult>;
+}
+/**
+* The `devvit.payment-order.v1` verifier: the envelope
+* `normalizeDevvitFulfillmentOrder` produced names the order, and the grant
+* is decided by the deployment's payments authority (`PAID` or `DELIVERED`
+* for the requesting player and SKU). Replay identity is the order id, so a
+* second fulfillment of one order meets the first grant.
+*/
+export declare function createDevvitPaymentOrderEvidenceVerifier(input: {
+  readonly authority: DevvitPaymentOrderAuthority;
+  readonly now?: () => string;
+}): Pick<GameServicesEvidenceVerifier, 'verifyPurchase'>;
+/** `devvit.payment-order.v1`: the fulfillment handler's own record, bound through the payments authority. */
+export declare function createDevvitPaymentOrderCommerceEvidenceEntry(input: {
+  readonly authority: DevvitPaymentOrderAuthority;
+  readonly now?: () => string;
+  readonly targets?: readonly string[];
+}): CommerceEvidenceRegistryEntry;
+export interface CreateCommerceLedgerLookupVerifierInput {
+  readonly schema: string;
+  readonly store: StoreId;
+  /** The ledger the host's fulfillment path writes. */
+  readonly ledger: GameServicesStore;
+  /** The store transaction id the envelope names; `undefined` rejects the envelope. */
+  readonly readTransactionId: (payload: EntitlementLedgerPayload) => string | undefined;
+  /** The store SKU the envelope names, compared with the catalog's platform product id when present. */
+  readonly readStoreSku?: (payload: EntitlementLedgerPayload) => string | undefined;
+  /** The ledger target the fulfillment path wrote the grant under; defaults to the request's target. */
+  readonly ledgerTarget?: string;
+}
+/**
+* A server-push lookup verifier (RFC "Evidence registry"): it never grants
+* from the client envelope. It answers `settled` with the ledger entry the
+* host's fulfillment path already wrote for the same store and transaction
+* id, when that entry belongs to the requesting player and product and is
+* not reversed; `pending` while no such entry exists; and `rejected` when the
+* envelope names another transaction or product than the request, or the
+* entry belongs to someone else.
+*/
+export declare function createCommerceLedgerLookupVerifier(input: CreateCommerceLedgerLookupVerifierInput): Pick<GameServicesEvidenceVerifier, 'verifyPurchase'>;
+/** The purchase grant written under a ledger target and store transaction id, through the store's index or a list scan. */
+export declare function findPurchaseGrantByPlatformEvidence(ledger: GameServicesStore, identity: {
+  readonly target: string;
+  readonly platformEvidenceId: string;
+}): Promise<ProductGrantTransaction | undefined>;
+/**
+* `devvit.order.v1`: the client's order envelope (a checkout result or the
+* paid-order list) looked up against the ledger the fulfillment handler
+* wrote under target `reddit` (`createPlatformOrderLedgerGrant`).
+*/
+export declare function createDevvitOrderLookupCommerceEvidenceEntry(input: {
+  readonly ledger: GameServicesStore;
+  /** Defaults to the request target, which `targets` pins to `reddit`. */
+  readonly ledgerTarget?: string;
+  readonly targets?: readonly string[];
+}): CommerceEvidenceRegistryEntry;
+/**
+* `verse8.agent8-event.v1`: the client's Agent8 purchase envelope looked up
+* against the ledger the `$onItemPurchased` event wrote under target `verse8`
+* (`createServerPushLedgerGrant`; the Agent8 commerce service writes it when
+* given a ledger).
+*/
+export declare function createVerse8Agent8EventLookupCommerceEvidenceEntry(input: {
+  readonly ledger: GameServicesStore;
+  readonly ledgerTarget?: string;
+  readonly targets?: readonly string[];
+}): CommerceEvidenceRegistryEntry;
+export interface CreateServerPushLedgerGrantInput {
+  readonly store: StoreId;
+  /** The ledger target the lookup verifier reads under (`reddit`, `verse8`). */
+  readonly target: string;
+  readonly deploymentTarget?: string;
+  readonly playerId: string;
+  readonly product: ProductCatalog['products'][number];
+  readonly platformProductId: string;
+  /** The store transaction id (a Reddit order id, an Agent8 purchase id). */
+  readonly transactionId: string;
+  /** Units bought in one transaction; a currency or resource grant is scaled by it. Default 1. */
+  readonly quantity?: number;
+  readonly purchasedAt: string;
+  readonly grantedAt: string;
+  /** The host's own evidence (`devvit.payment-order.v1`, `verse8.agent8-event.v1`). */
+  readonly evidence: PlatformEvidenceEnvelope;
+  /** Defaults to the reconciler's derived key `store:<store>:<transactionId>`. */
+  readonly idempotencyKey?: string;
+  /** Defaults to `<store>:<schema>:<transactionId>`. */
+  readonly evidenceVerificationId?: string;
+}
+/**
+* The ledger grant a host's fulfillment path writes for a server-push
+* purchase, in the shape the lookup verifiers read: `payload.target`,
+* `payload.store`, and `payload.platformTransactionId` identify it, and the
+* platform-evidence unique index keeps a second write of the same transaction
+* out. Write it with `GameServicesStore.recordEntitlementGrant`.
+*/
+export declare function createServerPushLedgerGrant(input: CreateServerPushLedgerGrantInput): EntitlementLedgerGrant;
+export type CommerceServiceAlignment = {
+  readonly status: 'aligned';
+  readonly store: StoreId;
+} | {
+  readonly status: 'configuration-required';
+  readonly store: StoreId;
+  readonly reason: 'STORE_NOT_ACCEPTED' | 'FINISH_OWNER_MISMATCH' | 'PROTOCOL_VERSION_MISMATCH';
+  readonly message: string;
+};
+/**
+* Compares a provider's capability block with the backend's published
+* capabilities (RFC "Provider capabilities endpoint"): a store the backend
+* does not accept, a finish owner that disagrees, or another protocol major
+* version sets the provider's availability to `configuration-required`
+* before any purchase UI opens. The reconciler applies it at start.
+*/
+export declare function compareCommerceServiceCapabilities(input: {
+  readonly store: StoreId;
+  readonly provider: Pick<CommerceCapabilities, 'lifecycle'>;
+  readonly service: CommerceServiceCapabilities;
+}): CommerceServiceAlignment;