@mpgd/platform 0.19.0 → 0.21.0

package/dist/commerce-conformance.d.ts

@@ -1,6 +1,8 @@
-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 CreditEntitlement, type CreditLot, type CreditLotSpendScope, type CreditOffer, type CreditSpendInput, type CreditSpendResult, type CreditWalletClient, type CreditWalletSubscribeInput, 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, CommerceConformanceVector, CommerceConformanceVerifyDecision } from './commerce-vectors.js';
+import { type CreditMembershipStartInput, type CreditMembershipStartResult, type CreditScheduledDebit, type CreditSubscriptionEvent } from './commerce-wallet.js';
 import type { PlatformEvidenceEnvelope } from './index.js';
+export { addIsoDuration, compareCreditLotSpendOrder, deriveCreditLotSpendScope, normalizeIsoTimestamp, } from './commerce-wallet.js';
 /**
 * Commerce v2 conformance runner (RFC "Conformance vectors") with the in-memory
 * reference pieces every vector needs: a fake clock, a fake store with its
@@ -12,7 +14,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";
@@ -27,10 +33,6 @@ export interface CommerceConformanceClock {
   set(at: string): void;
 }
 export declare function createCommerceConformanceClock(initial?: string): CommerceConformanceClock;
-/** Canonical `YYYY-MM-DDTHH:mm:ssZ`; milliseconds are kept only when non-zero. */
-export declare function normalizeIsoTimestamp(input: string): string;
-/** Adds an ISO-8601 duration (`P30D`, `P1M`, `PT12H`, ...) to a timestamp, in UTC calendar units. */
-export declare function addIsoDuration(at: string, duration: string): string;
 /** Capabilities of a vector profile: omitted blocks default to all supported and `available`. */
 export declare function createCommerceConformanceCapabilities(profile: CommerceConformanceProfile): CommerceCapabilities;
 export interface CommerceConformanceFixtureContext {
@@ -72,6 +74,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 +173,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 {
@@ -246,33 +268,11 @@ export interface CreateCommerceConformanceRuntimeInput {
 * `granted`, and only a ledger revocation moves it to `revoked`.
 */
 export declare function createCommerceConformanceRuntime(input: CreateCommerceConformanceRuntimeInput): CommerceConformanceRuntime;
-export interface CommerceScheduledDebit extends CreditDebit {
-  readonly idempotencyKey: string;
-}
-export interface CommerceConformanceSubscriptionEvent {
-  /** Stable id `<subscriptionId>:<periodIndex>:<type>`, so redelivery is idempotent. */
-  readonly eventId: string;
-  readonly type: CommerceConformanceSubscriptionEventType;
-  readonly subscriptionId: string;
-  readonly logicalId: CommerceLogicalProductId;
-  readonly periodIndex: number;
-  readonly expiresAt: string;
-  readonly reason?: CommerceErrorCode;
-}
-export interface CommerceConformanceMembershipStart {
-  readonly subscriptionId: string;
-  readonly titleId: string;
-  readonly logicalId: CommerceLogicalProductId;
-  readonly terms: CreditMembershipTerms;
-}
-export type CommerceConformanceMembershipResult = {
-  readonly status: 'started';
-  readonly subscription: ActiveSubscription;
-  readonly entitlementId: string;
-} | {
-  readonly status: 'rejected';
-  readonly error: CommerceErrorInfo;
-};
+export type CommerceScheduledDebit = CreditScheduledDebit;
+/** Stable id `<subscriptionId>:<periodIndex>:<type>`, so redelivery is idempotent. */
+export type CommerceConformanceSubscriptionEvent = CreditSubscriptionEvent;
+export type CommerceConformanceMembershipStart = CreditMembershipStartInput;
+export type CommerceConformanceMembershipResult = CreditMembershipStartResult;
 /** The wallet actor of a vector: wallet steps plus wallet observations. */
 export interface CommerceConformanceWalletActor {
   readonly lots: readonly CreditLot[];
@@ -297,8 +297,14 @@ export interface CommerceConformanceWalletActor {
 }
 export interface CommerceConformanceWallet extends CreditWalletClient, CommerceConformanceWalletActor {
   readonly entitlements: readonly CreditEntitlement[];
+  /** Offers the wallet prices spends against; the provider registers the vector catalog when empty. */
+  readonly offers: readonly CreditOffer[];
+  addOffers(offers: readonly CreditOffer[]): void;
   startMembership(input: CommerceConformanceMembershipStart): Promise<CommerceConformanceMembershipResult>;
-  subscribe(listener: (event: CommerceEvent) => void): () => void;
+  getActiveSubscriptions(input?: {
+    readonly titleId?: string;
+  }): Promise<readonly ActiveSubscription[]>;
+  subscribe(listener: (event: CommerceEvent) => void, input?: CreditWalletSubscribeInput): () => void;
 }
 export interface CreateCommerceConformanceWalletInput {
   readonly store: StoreId;
@@ -308,18 +314,12 @@ export interface CreateCommerceConformanceWalletInput {
   readonly offers?: readonly CreditOffer[];
 }
 /**
-* Reference in-memory wallet implementing the RFC "Credit lots" and "Billing
-* authority and memberships" rules: lot ids equal ledger entry ids, spend
-* scope derives from the lot origin, spends consume eligible lots in the
-* fixed order, are idempotent by key, and debit nothing on
-* `INSUFFICIENT_BALANCE`; memberships debit `membership:<id>:<period>` per
-* paid period and lapse at period end when the eligible balance runs out.
+* The reference wallet (`createInMemoryCreditWallet`) on the vector clock,
+* with the actor surface: fixture lots credit through `creditFromGrant`, the
+* backend finalizer redeems through `finalize`, and owner-side mistakes in a
+* vector surface as script errors.
 */
 export declare function createCommerceConformanceWallet(input: CreateCommerceConformanceWalletInput): CommerceConformanceWallet;
-/** Store lots are title-scoped, off-store lots cross-title, promotion lots as issued (title by default). */
-export declare function deriveCreditLotSpendScope(origin: CreditLot['origin'], explicit?: CreditLotSpendScope): CreditLotSpendScope;
-/** RFC spend order: earliest `expiresAt` (none last), `title` before `cross-title`, oldest `createdAt`, then `lotId`. */
-export declare function compareCreditLotSpendOrder(left: CreditLot, right: CreditLot): number;
 export interface CreateCommerceConformanceWalletProviderInput {
   readonly wallet: CommerceConformanceWallet;
   readonly profile: CommerceConformanceProfile;
@@ -330,13 +330,12 @@ export interface CreateCommerceConformanceWalletProviderInput {
   readonly clock: CommerceConformanceClock;
 }
 /**
-* `CommerceProvider` over the reference wallet: `fetchProducts` lists the
-* wallet's offers (catalog-derived offers only when the wallet lists none),
-* `requestPurchase` spends the offer price times the requested quantity
-* (outcome `purchased`, `settlement` set, evidence adapter-settled),
-* `getAvailablePurchases` lists unredeemed entitlements, and finishing is the
-* backend's `redeem`. Memberships exist only where the billing authority is
-* `host`.
+* `createCreditCommerceProvider` over the reference wallet with the vector
+* profile as its capability block. A wallet that lists no offers has the
+* vector catalog registered as its offers first (a fixture price of one unit
+* of the first wallet currency for entries without membership terms), so the
+* wallet prices every spend and starts memberships itself. Memberships exist
+* only where the billing authority is `host`.
 */
 export declare function createCommerceConformanceWalletProvider(input: CreateCommerceConformanceWalletProviderInput): CommerceProvider;
 export interface CommerceConformanceHarness {
@@ -364,10 +363,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 +397,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