@mpgd/platform 0.20.0 → 0.22.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 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 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
@@ -31,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 {
@@ -270,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[];
@@ -321,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;
@@ -332,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;
@@ -354,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 {
@@ -380,6 +355,14 @@ export interface CommerceConformanceContext extends CommerceConformanceFixtureCo
 export interface CommerceConformanceRunOptions {
   /** Supplies a provider over the caller's fake SDK; defaults to the fake store or the reference wallet. */
   readonly createProvider?: (context: CommerceConformanceContext) => CommerceConformanceHarness | Promise<CommerceConformanceHarness>;
+  /**
+  * Supplies the runtime under test over the harness provider, backend, and
+  * journal; defaults to the reference reconciler
+  * (`createCommerceConformanceRuntime`). The reference run an adaptive
+  * vector is derived from always uses the reference reconciler, so the
+  * derived expectations stay the RFC's regardless of the runtime under test.
+  */
+  readonly createRuntime?: (input: CreateCommerceConformanceRuntimeInput, context: CommerceConformanceContext) => CommerceConformanceRuntime | Promise<CommerceConformanceRuntime>;
   readonly playerId?: string;
   readonly titleId?: string;
 }