@mpgd/platform 0.20.0 → 0.22.0

package/dist/commerce-wallet.d.ts

@@ -0,0 +1,324 @@
+import { type tags } from 'typia';
+import { type ActiveSubscription, type CommerceAuthorityCapabilities, type CommerceBillingAuthority, type CommerceCapabilities, type CommerceCatalogCapabilities, type CommerceErrorCode, type CommerceErrorInfo, type CommerceEvent, type CommerceLifecycleCapabilities, type CommerceLogicalProductId, type CommerceProvider, type CommercePurchaseCapabilities, type CreditDebit, type CreditEntitlement, type CreditLot, type CreditLotOrigin, type CreditLotSpendScope, type CreditMembershipScope, type CreditMembershipTerms, type CreditOffer, type CreditSpendResult, type CreditWalletClient, type CreditWalletSubscribeInput, type StoreId } from './commerce.js';
+import type { IsoTimestamp, NonEmptyString, NonNegativeInteger } from './commerce-contract.js';
+import type { PlatformEvidenceEnvelope, PlatformProviderAvailability } from './index.js';
+/**
+* Commerce v2 credit wallet contract (RFC "Credit wallet", "Credit lots",
+* "Billing authority and memberships", "Subscriptions"). The consuming
+* project implements `CreditWalletClient` against its own wallet service;
+* this module supplies the rules both sides share, the provider that turns a
+* client into a `CommerceProvider`, and a reference in-memory wallet that the
+* conformance runner and consumer tests can run the wallet vectors against.
+* Pure in-process code: no Phaser, DOM, network, or SDK imports. Nothing here
+* grants: a spend debits the wallet's own lots, the entitlement it creates is
+* a pointer the reconciler still verifies with the ledger, and a lot is
+* credited only from a ledger grant keyed by its entry id.
+*/
+export type { CommerceBillingAuthority, CreditBalance, CreditDebit, CreditEntitlement, CreditLot, CreditLotChannel, CreditLotOrigin, CreditLotSpendScope, CreditMembershipScope, CreditMembershipTerms, CreditOffer, CreditPrice, CreditSpendInput, CreditSpendResult, CreditWalletClient, CreditWalletSubscribeInput, } from './commerce.js';
+export { assertCreditBalance, assertCreditEntitlement, assertCreditLot, assertCreditOffer, assertCreditSpendInput, assertCreditSpendResult, } from './commerce.js';
+/** Canonical `YYYY-MM-DDTHH:mm:ssZ`; milliseconds are kept only when non-zero. */
+export declare function normalizeIsoTimestamp(input: string): string;
+/** The integer components of an ISO-8601 duration (`P1Y2M3W4DT5H6M7S`). */
+export interface IsoDurationParts {
+  readonly years: number;
+  readonly months: number;
+  readonly weeks: number;
+  readonly days: number;
+  readonly hours: number;
+  readonly minutes: number;
+  readonly seconds: number;
+}
+/**
+* Parses a positive ISO-8601 duration a membership period accepts (`P30D`,
+* `P1M`, `PT12H`, ...). Zero-length durations (`P0D`, `PT0S`), a bare `P` or
+* `PT`, and a `T` with no time components are rejected, so a period can
+* never renew without time passing.
+*/
+export declare function parseIsoDuration(duration: string): IsoDurationParts | undefined;
+export declare function isIsoDuration(duration: string): boolean;
+/**
+* Adds `times` ISO-8601 durations to a timestamp in UTC. Years and months are
+* calendar months with the day clamped to the target month's length
+* (`2026-01-31` + `P1M` is `2026-02-28`), so a membership's periods are
+* anchored on its start date: period `n` ends at `startedAt + (n + 1) × period`
+* rather than drifting from the previous period's end.
+*/
+export declare function addIsoDuration(at: string, duration: string, times?: number): string;
+/** Profiles whose distribution requires store billing for digital goods; their authority is always `store`. */
+export declare const storeBillingAuthorityProfiles: readonly ["google-play", "app-store"];
+/** Profiles whose authority defaults to `host`; every other profile defaults to `store`. */
+export declare const hostBillingAuthorityProfiles: readonly ["web", "web-preview"];
+export declare function isCommerceBillingAuthority(value: unknown): value is CommerceBillingAuthority;
+/** The RFC default for a release profile before any project override. */
+export declare function defaultCommerceBillingAuthority(profile: string): CommerceBillingAuthority;
+/**
+* Resolves a target's billing authority from its release profile. `google-play`
+* and `app-store` are always `store` and reject a `host` override (D-02: both
+* stores require their own billing for digital entitlements). `web` and
+* `web-preview` default to `host`, every other profile to `store`, and a
+* project may override those after its own policy review.
+*/
+export declare function resolveCommerceBillingAuthority(profile: string, override?: CommerceBillingAuthority): CommerceBillingAuthority;
+export type CreditScope = 'title' | 'cross-title';
+/**
+* `creditScope` per store id: which stores count as off-store, so their lots
+* are spendable across titles. Absent entries are `title`; the kit's reference
+* stores keep that default.
+*/
+export type CreditScopeRegistry = Readonly<Record<string, CreditScope>>;
+/** Stores whose lots are always title-scoped; neither a registry nor a promotion can make them `cross-title`. */
+export declare const titleScopedCreditStores: readonly ["google-play", "app-store"];
+export declare function isTitleScopedCreditStore(store: string): boolean;
+/** Rejects a registry that marks Google Play or the App Store `cross-title`, or holds an unknown scope. */
+export declare function assertCreditScopeRegistry(registry: CreditScopeRegistry): CreditScopeRegistry;
+export declare const assertCreditLotSpendScope: (input: unknown) => CreditLotSpendScope;
+export interface DeriveCreditLotSpendScopeOptions {
+  /** Scope a promotion lot was issued with; rejected for store and off-store lots, whose scope is derived. */
+  readonly explicit?: CreditLotSpendScope;
+  readonly creditScope?: CreditScopeRegistry;
+}
+/**
+* Derives a lot's `spendScope` from its origin (RFC "Credit lots"): a lot
+* bought through a store is `title`-scoped to its purchasing title, an
+* off-store lot is `cross-title`, and a promotion lot carries the scope it was
+* issued with (`title` by default). A registry entry overrides the channel for
+* store and off-store lots. A lot attributed to Google Play or the App Store is
+* always `title`, whatever the channel, registry, or issued scope says.
+*/
+export declare function deriveCreditLotSpendScope(origin: CreditLotOrigin, options?: DeriveCreditLotSpendScopeOptions): 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 CreditLotEligibility {
+  readonly titleId: string;
+  readonly currency: string;
+  /**
+  * `title` (the default) spends that title's lots and `cross-title` lots;
+  * `platform` spends `cross-title` lots only, as a platform-scoped membership
+  * does.
+  */
+  readonly scope?: CreditMembershipScope;
+  /** ISO-8601 timestamp or epoch milliseconds; a lot whose `expiresAt` is not after it is excluded. */
+  readonly now: string | number;
+  /**
+  * When set, a lot created after this instant is excluded. A catch-up
+  * renewal passes the boundary of the period it pays for, so credits granted
+  * after that period ended cannot fund it retroactively.
+  */
+  readonly createdBy?: string | number;
+}
+/** Whether a lot may fund a spend: same currency, credit left, not expired, and in scope. */
+export declare function isCreditLotEligible(lot: CreditLot, criteria: CreditLotEligibility): boolean;
+/** The eligible lots of a spend in the order they are consumed; the input is not mutated. */
+export declare function selectEligibleCreditLots(lots: readonly CreditLot[], criteria: CreditLotEligibility): readonly CreditLot[];
+export declare function sumCreditLotRemaining(lots: readonly CreditLot[]): number;
+export declare function sumCreditDebits(debits: readonly CreditDebit[]): number;
+export declare function sameCreditAmount(left: number, right: number): boolean;
+/** The whole number of `unit` prices in `amount`, or `undefined` when `amount` is not a positive multiple. */
+export declare function creditPriceMultiple(amount: number, unit: number): number | undefined;
+export type CreditDebitPlan = {
+  readonly status: 'debited';
+  readonly debits: readonly CreditDebit[];
+} | {
+  readonly status: 'rejected';
+  readonly error: CommerceErrorInfo;
+};
+/**
+* Plans the debits of `amount` across eligible lots in spend order without
+* mutating them. A spend the lots cannot cover is rejected with
+* `INSUFFICIENT_BALANCE` and plans nothing.
+*/
+export declare function planCreditDebits(eligible: readonly CreditLot[], amount: number): CreditDebitPlan;
+/** Prefix of every scheduled membership debit key; a client spend cannot use it. */
+export declare const membershipDebitKeyPrefix = "membership:";
+/** `membership:<subscriptionId>:<periodIndex>`, so a repeated scheduler tick cannot charge a period twice. */
+export declare function createMembershipRenewalKey(subscriptionId: string, periodIndex: number): string;
+export type CreditSubscriptionEventType = 'subscriptionStarted' | 'subscriptionRenewed' | 'subscriptionLapsed' | 'subscriptionRevoked';
+export declare const creditSubscriptionEventTypes: readonly ["subscriptionStarted", "subscriptionRenewed", "subscriptionLapsed", "subscriptionRevoked"];
+/** `<subscriptionId>:<periodIndex>:<type>`, so redelivery of a lifecycle event is idempotent. */
+export declare function createCreditSubscriptionEventId(subscriptionId: string, periodIndex: number, type: CreditSubscriptionEventType): string;
+/** A membership lifecycle event as the wallet service records and pushes it. */
+export interface CreditSubscriptionEvent {
+  readonly eventId: NonEmptyString;
+  readonly type: CreditSubscriptionEventType;
+  readonly subscriptionId: NonEmptyString;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly periodIndex: NonNegativeInteger;
+  readonly expiresAt: IsoTimestamp;
+  /** Why a membership lapsed, for example INSUFFICIENT_BALANCE. */
+  readonly reason?: CommerceErrorCode;
+}
+/** A ledger grant the wallet owner credits as a lot; `ledgerEntryId` becomes the `lotId`. */
+export interface CreditLotGrant {
+  readonly ledgerEntryId: NonEmptyString;
+  readonly currency: NonEmptyString;
+  readonly amount: number & tags.ExclusiveMinimum<0>;
+  readonly origin: CreditLotOrigin;
+  readonly createdAt: IsoTimestamp;
+  readonly expiresAt?: IsoTimestamp;
+}
+/** A debit with the idempotency key of the spend that made it. */
+export interface CreditScheduledDebit extends CreditDebit {
+  readonly idempotencyKey: NonEmptyString;
+}
+export interface CreditRedeemInput {
+  readonly entitlementId: NonEmptyString;
+  /** The ledger entry that granted the entitlement; a redeem without one is refused. */
+  readonly ledgerEntryId: NonEmptyString;
+}
+export interface CreditMembershipStartInput {
+  readonly subscriptionId: NonEmptyString;
+  readonly titleId: NonEmptyString;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly terms: CreditMembershipTerms;
+}
+export type CreditMembershipStartResult = {
+  readonly status: 'started';
+  readonly subscription: ActiveSubscription;
+  /** The period-0 entitlement, `membership:<subscriptionId>:0`. */
+  readonly entitlementId: NonEmptyString;
+  readonly debits: readonly CreditDebit[];
+  readonly createdAt: IsoTimestamp;
+  /** The id was already started with these terms; the original period-0 debits are returned. */
+  readonly alreadyProcessed?: boolean;
+} | {
+  readonly status: 'rejected';
+  readonly error: CommerceErrorInfo;
+};
+/** The `CreditSpendResult` a membership start answers a `spend` with. */
+export declare function creditSpendResultOfMembershipStart(result: CreditMembershipStartResult): CreditSpendResult;
+export declare const assertCreditLotGrant: (input: unknown) => CreditLotGrant;
+export declare const assertCreditMembershipTerms: (input: unknown) => CreditMembershipTerms;
+export declare const assertCreditRedeemInput: (input: unknown) => CreditRedeemInput;
+export declare const assertCreditSubscriptionEvent: (input: unknown) => CreditSubscriptionEvent;
+export declare const assertCreditMembershipStartInput: (input: unknown) => CreditMembershipStartInput;
+/**
+* `assertCreditOffer` plus the wallet rules an offer must satisfy: membership
+* terms only on a `subscription` offer, every `subscription` offer with terms,
+* a valid positive period, and a membership priced as its terms say.
+*/
+export declare function assertCreditWalletOffer(input: unknown): CreditOffer;
+export declare const creditWalletSpendEvidenceSchema: 'credit-wallet.spend.v1';
+export interface CreditWalletSpendEvidence {
+  readonly store: StoreId;
+  readonly titleId: string;
+  /** The wallet's own id for the settled spend (its entitlement id); not a backend ledger entry. */
+  readonly entitlementId: string;
+  readonly amount: number;
+  readonly debits: readonly CreditDebit[];
+}
+/** The `adapter-settled` evidence of a wallet spend; `debits` is JSON because envelope payloads are flat. */
+export declare function createCreditWalletSpendEvidence(evidence: CreditWalletSpendEvidence): PlatformEvidenceEnvelope;
+/** Reads a `credit-wallet.spend.v1` envelope; any other schema or a malformed payload is `undefined`. */
+export declare function readCreditWalletSpendEvidence(envelope: PlatformEvidenceEnvelope): CreditWalletSpendEvidence | undefined;
+export interface CreditCommerceCapabilityOverrides {
+  readonly purchase?: Partial<CommercePurchaseCapabilities>;
+  readonly catalog?: Partial<CommerceCatalogCapabilities>;
+  readonly lifecycle?: Partial<CommerceLifecycleCapabilities>;
+  readonly authority?: Partial<CommerceAuthorityCapabilities>;
+  readonly availability?: PlatformProviderAvailability;
+}
+export interface CreateCreditCommerceProviderOptions {
+  readonly titleId: string;
+  readonly billingAuthority: CommerceBillingAuthority;
+  /**
+  * The catalog's declared currencies. An offer priced in another currency is
+  * a configuration error (RFC "Catalog currencies"); omitted, no check runs.
+  */
+  readonly currencies?: readonly string[];
+  /**
+  * Overrides on the RFC wallet profile. `purchase.subscription` is forced
+  * `false` where the billing authority is `store` or the client cannot
+  * report active subscriptions, whatever the override.
+  */
+  readonly capabilities?: CreditCommerceCapabilityOverrides;
+  /** Clock for `purchasedAt` when the wallet reports no settlement time; defaults to the system clock. */
+  readonly now?: () => string;
+}
+/** A `CommerceProvider` over a wallet client that also releases its client subscription. */
+export interface CreditCommerceProvider extends CommerceProvider {
+  /** Unsubscribes from the client; events after this are no longer forwarded. */
+  dispose(): void;
+}
+/**
+* The RFC profile row of a project-owned wallet, before overrides.
+* `purchase.subscription` is true only where the billing authority is `host`
+* and the caller states that the client reports active subscriptions
+* (`client.subscriptions: true`); with no client description it is `false`.
+*/
+export declare function createCreditCommerceCapabilities(billingAuthority: CommerceBillingAuthority, overrides?: CreditCommerceCapabilityOverrides, client?: {
+  readonly subscriptions?: boolean;
+}): CommerceCapabilities;
+/**
+* `CommerceProvider` over a project-owned `CreditWalletClient` (RFC "Credit
+* wallet"): `fetchProducts` lists the wallet's offers (memberships omitted
+* where the billing authority is `store`), `requestPurchase` spends the offer
+* price times the quantity under the game's idempotency key and answers
+* `purchased` with `adapter-settled` evidence (`credit-wallet.spend.v1`)
+* once the wallet's debits add up to that price, without a `settlement`
+* pointer: the backend ledger entry exists only after the reconciler verifies
+* that evidence, so there is nothing to point at yet,
+* `getAvailablePurchases` lists the title's unredeemed entitlements,
+* `finishTransaction` redeems one with the ledger entry id of its grant and
+* refuses to run without it, `restorePurchases` re-reads the unredeemed
+* entitlements as `purchaseUpdated` events, and the client's own events pass
+* through the standard pre-listener buffer. Every client answer is
+* validated; a malformed one is `INVALID_RESPONSE`. The provider never
+* grants and never credits: lots are credited by the wallet owner from
+* ledger grants, and memberships renew, lapse, and expire on the wallet
+* service alone.
+*/
+export declare function createCreditCommerceProvider(client: CreditWalletClient, options: CreateCreditCommerceProviderOptions): CreditCommerceProvider;
+/** Periods one `renewDue` tick charges per membership before it yields to the next tick. */
+export declare const defaultMaxRenewalsPerTick = 12;
+export interface CreateInMemoryCreditWalletInput {
+  readonly store: StoreId;
+  /** Currencies the wallet keeps balances in; a lot or spend in another currency is refused. */
+  readonly currencies: readonly string[];
+  /** Clock for lot eligibility, entitlements, and periods; defaults to the system clock. */
+  readonly now?: () => string;
+  /** Offers the wallet prices spends against; a `spend` of a membership offer starts the membership. */
+  readonly offers?: readonly CreditOffer[];
+  readonly creditScope?: CreditScopeRegistry;
+  /** Cap on the periods a single `renewDue` tick charges per membership; defaults to 12. */
+  readonly maxRenewalsPerTick?: number;
+}
+/**
+* The reference wallet: the client surface plus the owner-side operations a
+* wallet service runs (credit a lot from a ledger grant, register offers,
+* start a membership, run the renewal scheduler) and the observations the
+* conformance vectors assert. The owner-side operations are not on
+* `CreditWalletClient`; a game client gets only that interface.
+*/
+export interface InMemoryCreditWallet extends CreditWalletClient {
+  readonly lots: readonly CreditLot[];
+  /** Every debit of every processed spend, in order; replays add nothing. */
+  readonly debits: readonly CreditScheduledDebit[];
+  readonly entitlements: readonly CreditEntitlement[];
+  readonly subscriptionEvents: readonly CreditSubscriptionEvent[];
+  readonly offers: readonly CreditOffer[];
+  /** Registers or replaces offers by logical id. */
+  addOffers(offers: readonly CreditOffer[]): void;
+  /** Credits a lot whose id is the ledger entry id; a replayed grant returns the existing lot. */
+  creditFromGrant(grant: CreditLotGrant, options?: DeriveCreditLotSpendScopeOptions): CreditLot;
+  /** Starts a membership by debiting period 0; an id already started with the same terms answers with its original debits. */
+  startMembership(input: CreditMembershipStartInput): Promise<CreditMembershipStartResult>;
+  /** Runs the renewal scheduler for memberships whose paid period has ended at `now` (default: the wallet clock). */
+  renewDue(now?: string): Promise<void>;
+  getActiveSubscriptions(input?: {
+    readonly titleId?: string;
+  }): Promise<readonly ActiveSubscription[]>;
+  /** With `input.titleId`, a title-scoped membership's events reach only that title's listeners. */
+  subscribe(listener: (event: CommerceEvent) => void, input?: CreditWalletSubscribeInput): () => void;
+}
+/**
+* Reference in-memory wallet implementing the RFC "Credit lots" and "Billing
+* authority and memberships" rules on the pure rule functions above: 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, are priced
+* by the wallet's own offers, and debit nothing on `INSUFFICIENT_BALANCE`;
+* memberships debit `membership:<subscriptionId>:<periodIndex>` per paid
+* period with lot eligibility judged at the period boundary, a
+* platform-scoped membership debits `cross-title` lots only, and a membership
+* lapses at period end when the eligible balance runs out.
+*/
+export declare function createInMemoryCreditWallet(input: CreateInMemoryCreditWalletInput): InMemoryCreditWallet;