@mpgd/platform 0.19.0 → 0.20.0

package/dist/commerce-conformance.d.ts

@@ -1,5 +1,5 @@
-import { type ActiveSubscription, type CommerceBillingAuthority, type CommerceCapabilities, type CommerceErrorCode, type CommerceErrorInfo, type CommerceEvent, type CommerceLogicalProductId, type CommerceProvider, type CommercePurchaseState, type CreditBalance, type CreditDebit, type CreditEntitlement, type CreditLot, type CreditLotSpendScope, type CreditMembershipTerms, type CreditOffer, type CreditSpendInput, type CreditSpendResult, type CreditWalletClient, type FetchProductsInput, type PurchaseKind, type RequestPurchaseInput, type RequestPurchaseResult, type StoreId, type StoreProduct, type StorePurchase } from './commerce.js';
-import type { CommerceConformanceCatalogEntry, CommerceConformanceErrorFixture, CommerceConformanceFinishResultFixture, CommerceConformanceLotFixture, CommerceConformanceProfile, CommerceConformancePurchaseFixture, CommerceConformanceRequestResultFixture, CommerceConformanceSubscriptionEventType, CommerceConformanceVector, CommerceConformanceVerifyDecision } from './commerce-vectors.js';
+import { type ActiveSubscription, type CommerceBillingAuthority, type CommerceCapabilities, type CommerceErrorCode, type CommerceErrorInfo, type CommerceEvent, type CommerceEvidenceAuthority, type CommerceFinishOwner, type CommerceLogicalProductId, type CommerceProvider, type CommercePurchaseState, type CreditBalance, type CreditDebit, type CreditEntitlement, type CreditLot, type CreditLotSpendScope, type CreditMembershipTerms, type CreditOffer, type CreditSpendInput, type CreditSpendResult, type CreditWalletClient, type FetchProductsInput, type PurchaseKind, type RequestPurchaseInput, type RequestPurchaseResult, type StoreId, type StoreProduct, type StorePurchase } from './commerce.js';
+import type { CommerceConformanceCatalogEntry, CommerceConformanceErrorFixture, CommerceConformanceExpectation, CommerceConformanceFinishResultFixture, CommerceConformanceLotFixture, CommerceConformanceProfile, CommerceConformancePurchaseFixture, CommerceConformanceRequestResultFixture, CommerceConformanceSubscriptionEventType, CommerceConformanceVector, CommerceConformanceVerifyDecision } from './commerce-vectors.js';
 import type { PlatformEvidenceEnvelope } from './index.js';
 /**
 * Commerce v2 conformance runner (RFC "Conformance vectors") with the in-memory
@@ -12,7 +12,11 @@ import type { PlatformEvidenceEnvelope } from './index.js';
 *
 * Store (B-phase) providers run the same vectors by supplying
 * `createProvider` and translating the store actor steps into their own fake
-* SDK; the reconciler, journal, backend, and matcher stay shared.
+* SDK; the reconciler, journal, backend, and matcher stay shared. A vector
+* flagged `profile.adaptive` then matches expectations derived from the
+* provider's declared capabilities rather than its fixture profile; see
+* `deriveAdaptiveCommerceConformanceExpectation` and
+* `commerceConformanceAdaptiveSkipReason`.
 */
 export declare const commerceConformanceDefaultPlayerId = "player-1";
 export declare const commerceConformanceDefaultTitleId = "title-a";
@@ -72,6 +76,14 @@ export interface CommerceConformanceStoreActor {
     readonly transactionId: string;
     readonly ledgerEntryId: string;
   }): void | Promise<void>;
+  /**
+  * The `token` this store reports for a fixture purchase when it is not the
+  * fixture's own: a host-order store reports the transaction id (RFC "Client
+  * contract"). An adaptive run replays the fixture purchases with this token
+  * into the reference store, so the derived verify requests carry the token
+  * the provider under test reports. Absent, the fixture token is used.
+  */
+  tokenOf?(purchase: CommerceConformancePurchaseFixture): string;
 }
 export interface CommerceConformanceStore extends CommerceConformanceStoreActor {
   /** The `CommerceProvider` over this fake store. */
@@ -163,12 +175,24 @@ export interface CreateCommerceConformanceBackendInput {
     readonly ledgerEntryId: string;
     readonly logicalId: CommerceLogicalProductId;
   }) => void | Promise<void>;
+  /**
+  * When it returns true, a verify request that replays a key this backend
+  * already granted is a finalization re-read (the reference reconciler under a
+  * server-owned finish): it is answered `{ granted, ledgerEntryId,
+  * finalization: 'completed', alreadyProcessed: true }` from the backend's own
+  * grant state and runs the finalizer, consuming no queued decision. Read on
+  * every call, so the runner can decide it once the provider's capabilities
+  * are known.
+  */
+  readonly finalizeOnReread?: () => boolean;
 }
 /**
 * Fake backend: every verify call consumes the next `queueVerify` decision in
 * order and is logged; an unqueued verify is an unscripted operation. A
 * `granted` decision makes sure the ledger holds the entry, so a replayed
-* grant and a host-pushed grant never create a second entry.
+* grant and a host-pushed grant never create a second entry. With
+* `finalizeOnReread`, a replayed granted key is answered as finalized from
+* the backend's own state.
 */
 export declare function createCommerceConformanceBackend(input?: CreateCommerceConformanceBackendInput): CommerceConformanceBackend;
 export interface CommerceJournalRecord {
@@ -364,10 +388,33 @@ export interface CommerceConformanceFailure {
   readonly expected: unknown;
   readonly actual: unknown;
 }
+export type CommerceConformanceVectorStatus = 'passed' | 'failed' | 'skipped';
+/**
+* `CommerceConformanceExpectation` as the matcher consumes it: a derived
+* `finishCalls` list carries the store actor's own records, whose `result` may
+* also be `unfinished`.
+*/
+export interface CommerceConformanceResolvedExpectation extends Omit<CommerceConformanceExpectation, 'finishCalls'> {
+  readonly finishCalls?: readonly CommerceConformanceFinishCall[];
+}
+/** How an adaptive vector's expectations were derived for the provider under test. */
+export interface CommerceConformanceAdaptation {
+  /** The provider's store id; it replaces the fixture store id in derived keys and verify requests. */
+  readonly store: StoreId;
+  readonly finish: CommerceFinishOwner;
+  readonly evidence: CommerceEvidenceAuthority;
+  /** The expectation the vector was matched against. */
+  readonly expect: CommerceConformanceResolvedExpectation;
+}
 export interface CommerceConformanceVectorResult {
   readonly vector: string;
+  /** `skipped` vectors did not run; `passed` is false and `reason` says why. */
+  readonly status: CommerceConformanceVectorStatus;
   readonly passed: boolean;
   readonly failures: readonly CommerceConformanceFailure[];
+  readonly reason?: string;
+  /** Present when the vector ran with adaptive expectations. */
+  readonly adaptive?: CommerceConformanceAdaptation;
 }
 export declare function createCommerceConformanceHarness(context: CommerceConformanceContext): CommerceConformanceHarness;
 /**
@@ -375,9 +422,94 @@ export declare function createCommerceConformanceHarness(context: CommerceConfor
 * each, then matches `expect`. Matching compares only the listed fields; arrays
 * compare in order and by length; a listed `journal` is the whole journal.
 * Any unscripted operation fails the vector at the step that needed it.
+*
+* With `options.createProvider`, a vector flagged `profile.adaptive` is first
+* checked against the provider's declared capabilities
+* (`commerceConformanceAdaptiveSkipReason`) and then matched against
+* expectations derived from a reference run under those capabilities
+* (`deriveAdaptiveCommerceConformanceExpectation`). Duplicate detection needs
+* the whole run set, so it applies through `runCommerceConformanceVectors`.
 */
 export declare function runCommerceConformanceVector(vector: CommerceConformanceVector, options?: CommerceConformanceRunOptions): Promise<CommerceConformanceVectorResult>;
 export declare function runCommerceConformanceVectors(vectors: readonly CommerceConformanceVector[], options?: CommerceConformanceRunOptions): Promise<readonly CommerceConformanceVectorResult[]>;
+export declare function isAdaptiveCommerceConformanceVector(vector: CommerceConformanceVector): boolean;
+/**
+* Why an adaptive vector does not apply to a provider with `capabilities`, or
+* `undefined` when it runs. `set` is the whole run (for duplicate detection).
+* The rules:
+*
+* - a `game.requestPurchase` of a product kind the provider does not sell
+*   (`purchase.<kind>` false, by the vector catalog), or with a quantity above
+*   one without `purchase.quantity`, cannot open the store UI;
+* - a store-side `pending` purchase needs `lifecycle.pending`;
+* - a store `error` event needs `lifecycle.events`;
+* - without `lifecycle.events`, a store `complete` or `update` reaches the
+*   reconciler only by polling, so the next `runtime` step after it must be
+*   `reconcile` or `start`;
+* - a `queueFinish` script needs a `client` or `host` finish owner, since the
+*   provider never calls `finishTransaction` under `server` or `none`;
+* - within the `purchase-<owner>-finish` family only one member runs: the
+*   one named after the provider's owner, else the first by name.
+*/
+export declare function commerceConformanceAdaptiveSkipReason(vector: CommerceConformanceVector, capabilities: CommerceCapabilities, set?: readonly CommerceConformanceVector[]): string | undefined;
+/**
+* The vector with every scripted store purchase (`complete`, `update`, and a
+* `queueRequest` answering `purchased`) carrying the token the store actor
+* reports for it (`CommerceConformanceStoreActor.tokenOf`).
+*/
+export declare function withStoreTokens(vector: CommerceConformanceVector, tokenOf: (purchase: CommerceConformancePurchaseFixture) => string): CommerceConformanceVector;
+/**
+* Derives the adaptive expectation for `vector` from the observable state of a
+* finished reference run under the provider's capabilities, applying the
+* rules the RFC table states:
+*
+* - `journal`: the reference journal, so the tail after `granted` is
+*   `finishing, finished` for `client`, `host`, and `server` owners and
+*   `finished` for `none`; derived keys carry the provider's store id;
+* - `finishCalls`: the reference store's calls, `by` the owner for `client`
+*   and `host`, none for `server` and `none`;
+* - `verifyRequests`: the reference backend's log, with the finalization
+*   re-read a `server` owner adds unless the grant already reported
+*   `finalization: 'completed'`;
+* - `available`: what the reference store still lists once idle, so empty
+*   after a completed finish for `client`, `host`, and `server` owners.
+*
+* Fields the fixture does not assert stay unasserted. The derivation is
+* refused (a skip reason) when the reference run does not end every journal
+* key in the fixture's terminal state, since the scenario then depends on a
+* capability the provider lacks.
+*/
+export declare function deriveAdaptiveCommerceConformanceExpectation(vector: CommerceConformanceVector, reference: {
+  readonly store: StoreId;
+  readonly journal: Readonly<Record<string, readonly CommercePurchaseState[]>>;
+  readonly verifyRequests: readonly CommerceVerifyRequest[];
+  readonly finishCalls: readonly CommerceConformanceFinishCall[];
+  /** What the reference store still lists (pending included) once the run is idle. */
+  readonly available: readonly StorePurchase[];
+}): Promise<{
+  readonly expect: CommerceConformanceResolvedExpectation;
+  readonly reason?: undefined;
+} | {
+  readonly expect?: undefined;
+  readonly reason: string;
+}>;
+/**
+* A fixture journal key as the provider's store id derives it: only the
+* encoded store segment of a `store:<store>:<transactionId>` key
+* (`createDerivedPurchaseIdempotencyKey`) is replaced, so a transaction id
+* that happens to contain the fixture store id is left alone. Game-chosen
+* keys and store-specific key forms carry no such prefix and pass through.
+*/
+export declare function adaptDerivedPurchaseKeyStore(key: string, fixtureStore: string, providerStore: string): string;
+/**
+* A fixture journal key as the provider's store id derives it. When the key is
+* the derived key of a purchase the vector scripts under the fixture store, it
+* is re-derived with `createDerivedPurchaseIdempotencyKey` for the provider
+* store, which also covers the store-specific key forms (`google-play` token
+* keys, `apps-in-toss:purchase:<id>`); otherwise only the generic
+* `store:<store>:` prefix is swapped (`adaptDerivedPurchaseKeyStore`).
+*/
+export declare function adaptDerivedPurchaseKey(vector: CommerceConformanceVector, key: string, providerStore: string): Promise<string>;
 /**
 * Partial match: an expected object asserts only its listed keys, an expected
 * array asserts its length and each element in order, and primitives compare