@mpgd/platform 0.18.0 → 0.20.0

package/dist/commerce.d.ts

@@ -0,0 +1,303 @@
+import { type tags } from 'typia';
+import { PlatformOperationError, type CommerceAdapter, type CommerceCapabilities } from './index.js';
+import type { ActiveSubscription, CommerceErrorCode, CommerceErrorInfo, CommerceEvent, CommerceLogicalProductId, CommerceProvider, FetchProductsInput, FinishTransactionInput, FinishTransactionResult, GetAvailablePurchasesInput, IsoTimestamp, NonEmptyString, NonNegativeInteger, PurchaseKind, RequestPurchaseInput, RequestPurchaseResult, StoreId, StoreProduct, StorePurchase } from './commerce-contract.js';
+export { createUnsupportedCommerceCapabilities, deriveLegacyCommerceCapabilities, type LegacyCommerceCapabilities, } from './commerce-capabilities.js';
+export type { CommerceAccountBindingPolicy, CommerceAuthorityCapabilities, CommerceCapabilities, CommerceCatalogCapabilities, CommerceEvidenceAuthority, CommerceFinishOwner, CommerceLifecycleCapabilities, CommercePurchaseCapabilities, } from './index.js';
+/**
+* Commerce v2 client contract. Pure types, validators, and helpers only: no
+* provider lives here, and nothing in this module grants a purchase. The
+* contract is described by docs/specs/commerce/commerce-v2-rfc.md and is a
+* draft until the protocol version is released as 2.0.0.
+*/
+export declare const commerceProtocolVersion: '2.0.0-draft.1';
+export declare const commerceProtocol: 'mpgd.commerce.v2';
+export type { ActiveSubscription, ActiveSubscriptionState, CommerceErrorCode, CommerceErrorInfo, CommerceEvent, CommerceLogicalProductId, CommerceProvider, FetchProductsInput, FetchProductsType, FinishTransactionInput, FinishTransactionResult, GetAvailablePurchasesInput, PurchaseKind, PurchaseSource, RequestPurchaseInput, RequestPurchaseResult, StoreId, StoreOffer, StorePrice, StoreProduct, StorePurchase, StorePurchaseAccountBinding, StorePurchaseState, } from './commerce-contract.js';
+export declare const commerceErrorCodes: readonly ["USER_CANCELLED", "OUTCOME_UNKNOWN", "ALREADY_OWNED", "IN_PROGRESS", "ITEM_UNAVAILABLE", "NOT_PREPARED", "NETWORK", "STORE_UNAVAILABLE", "CONFIGURATION_REQUIRED", "ACTION_REQUIRED", "ACCOUNT_BINDING_REQUIRED", "INSUFFICIENT_BALANCE", "INVALID_RESPONSE", "UNKNOWN"];
+/** Bridge event envelope; `sequence` is per session and starts at 0. */
+export interface CommerceEventEnvelope {
+  readonly protocol: typeof commerceProtocol;
+  readonly sequence: NonNegativeInteger;
+  readonly event: CommerceEvent;
+}
+export type CommerceBillingAuthority = 'store' | 'host';
+export type CreditMembershipScope = 'title' | 'platform';
+export interface CreditPrice {
+  readonly currency: NonEmptyString;
+  readonly amount: number & tags.ExclusiveMinimum<0>;
+}
+export interface CreditMembershipTerms {
+  readonly scope: CreditMembershipScope;
+  readonly price: CreditPrice;
+  /** ISO 8601 duration, for example P30D. */
+  readonly period: NonEmptyString;
+}
+export interface CreditOffer {
+  readonly logicalId: CommerceLogicalProductId;
+  readonly storeSku: NonEmptyString;
+  readonly kind: PurchaseKind;
+  readonly title: string;
+  readonly description: string;
+  readonly price: CreditPrice;
+  /** Present only for credit-funded memberships. */
+  readonly membership?: CreditMembershipTerms;
+}
+export interface CreditSpendInput {
+  readonly titleId: NonEmptyString;
+  readonly currency: NonEmptyString;
+  readonly amount: number & tags.ExclusiveMinimum<0>;
+  readonly idempotencyKey: NonEmptyString;
+  readonly logicalId?: CommerceLogicalProductId;
+}
+export interface CreditDebit {
+  readonly lotId: NonEmptyString;
+  readonly amount: number & tags.ExclusiveMinimum<0>;
+}
+export type CreditSpendResult = {
+  readonly status: 'debited';
+  readonly entitlementId: NonEmptyString;
+  readonly debits: readonly CreditDebit[];
+  /** A repeated idempotency key returns the original debits. */
+  readonly alreadyProcessed?: boolean;
+} | {
+  readonly status: 'rejected';
+  readonly error: CommerceErrorInfo;
+};
+export interface CreditEntitlement {
+  readonly entitlementId: NonEmptyString;
+  readonly titleId: NonEmptyString;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly idempotencyKey: NonEmptyString;
+  readonly createdAt: IsoTimestamp;
+  readonly debits: readonly CreditDebit[];
+}
+export interface CreditBalance {
+  readonly titleId: NonEmptyString;
+  /** Spendable amount per currency, including eligible cross-title lots. */
+  readonly balances: Readonly<Record<string, number>>;
+}
+export type CreditLotChannel = 'store' | 'off-store' | 'promotion';
+export interface CreditLotOrigin {
+  readonly channel: CreditLotChannel;
+  readonly store: StoreId;
+  readonly titleId: NonEmptyString;
+}
+export type CreditLotSpendScope = {
+  readonly kind: 'title';
+  readonly titleId: NonEmptyString;
+} | {
+  readonly kind: 'cross-title';
+};
+export interface CreditLot {
+  /** Equals the ledgerEntryId of the granting purchase, so a replayed grant cannot create a second lot. */
+  readonly lotId: NonEmptyString;
+  readonly currency: NonEmptyString;
+  readonly amount: number & tags.ExclusiveMinimum<0>;
+  readonly remaining: number & tags.Minimum<0>;
+  readonly createdAt: IsoTimestamp;
+  readonly expiresAt?: IsoTimestamp;
+  readonly origin: CreditLotOrigin;
+  /** Derived from the origin, never supplied by the caller. */
+  readonly spendScope: CreditLotSpendScope;
+}
+export interface CreditWalletClient {
+  readonly store: StoreId;
+  listOffers(input: {
+    readonly titleId: string;
+  }): Promise<readonly CreditOffer[]>;
+  spend(input: CreditSpendInput): Promise<CreditSpendResult>;
+  listUnredeemed(input: {
+    readonly titleId: string;
+  }): Promise<readonly CreditEntitlement[]>;
+  redeem(input: {
+    readonly entitlementId: string;
+    readonly ledgerEntryId: string;
+  }): Promise<{
+    readonly redeemed: boolean;
+  }>;
+  getBalance(input: {
+    readonly titleId: string;
+  }): Promise<CreditBalance>;
+  subscribe?(listener: (event: CommerceEvent) => void): () => void;
+}
+export interface CommerceBridgeGetCapabilitiesPayload {
+  readonly protocol: typeof commerceProtocol;
+}
+export interface CommerceBridgeGetCapabilitiesResult {
+  readonly protocolVersion: NonEmptyString;
+  readonly store: StoreId;
+  readonly capabilities: CommerceCapabilities;
+}
+export type CommerceBridgeFetchProductsPayload = FetchProductsInput;
+export interface CommerceBridgeFetchProductsResult {
+  readonly products: readonly StoreProduct[];
+}
+export type CommerceBridgeRequestPurchasePayload = RequestPurchaseInput;
+export type CommerceBridgeRequestPurchaseResult = RequestPurchaseResult;
+export type CommerceBridgeGetAvailablePurchasesPayload = GetAvailablePurchasesInput;
+export interface CommerceBridgeGetAvailablePurchasesResult {
+  readonly purchases: readonly StorePurchase[];
+}
+export type CommerceBridgeFinishTransactionPayload = FinishTransactionInput;
+export type CommerceBridgeFinishTransactionResult = FinishTransactionResult;
+export interface CommerceBridgeRestorePurchasesPayload {
+  readonly protocol: typeof commerceProtocol;
+}
+export interface CommerceBridgeRestorePurchasesResult {
+  readonly restored: boolean;
+}
+export interface CommerceBridgeMethods {
+  readonly 'commerce.v2.getCapabilities': {
+    readonly payload: CommerceBridgeGetCapabilitiesPayload;
+    readonly result: CommerceBridgeGetCapabilitiesResult;
+  };
+  readonly 'commerce.v2.fetchProducts': {
+    readonly payload: CommerceBridgeFetchProductsPayload;
+    readonly result: CommerceBridgeFetchProductsResult;
+  };
+  readonly 'commerce.v2.requestPurchase': {
+    readonly payload: CommerceBridgeRequestPurchasePayload;
+    readonly result: CommerceBridgeRequestPurchaseResult;
+  };
+  readonly 'commerce.v2.getAvailablePurchases': {
+    readonly payload: CommerceBridgeGetAvailablePurchasesPayload;
+    readonly result: CommerceBridgeGetAvailablePurchasesResult;
+  };
+  readonly 'commerce.v2.finishTransaction': {
+    readonly payload: CommerceBridgeFinishTransactionPayload;
+    readonly result: CommerceBridgeFinishTransactionResult;
+  };
+  readonly 'commerce.v2.restorePurchases': {
+    readonly payload: CommerceBridgeRestorePurchasesPayload;
+    readonly result: CommerceBridgeRestorePurchasesResult;
+  };
+}
+export type CommerceBridgeMethod = keyof CommerceBridgeMethods;
+export declare const commerceBridgeMethods: readonly ["commerce.v2.getCapabilities", "commerce.v2.fetchProducts", "commerce.v2.requestPurchase", "commerce.v2.getAvailablePurchases", "commerce.v2.finishTransaction", "commerce.v2.restorePurchases"];
+/** Only NETWORK and STORE_UNAVAILABLE are retryable without reconciling first. */
+export declare function defaultCommerceErrorRetryable(code: CommerceErrorCode): boolean;
+export declare function isCommerceErrorCode(value: unknown): value is CommerceErrorCode;
+export interface CommerceErrorOptions {
+  readonly message?: string;
+  readonly storeCode?: string;
+  readonly retryable?: boolean;
+  readonly cause?: unknown;
+}
+/**
+* Normalized commerce failure. `code` is one of the v2 codes, `storeCode`
+* keeps the store's own code verbatim, and `retryable` defaults from the code.
+*/
+export declare class CommerceError extends PlatformOperationError {
+  readonly code: CommerceErrorCode;
+  readonly storeCode: string | undefined;
+  constructor(code: CommerceErrorCode, options?: CommerceErrorOptions);
+  toCommerceErrorInfo(): CommerceErrorInfo;
+}
+/**
+* Reads a normalized error info from any thrown value. A `CommerceError` keeps
+* its code; a plain object with a v2 `code` is accepted; any other platform
+* failure or error maps to UNKNOWN with the original code kept as `storeCode`.
+*/
+export declare function commerceErrorInfoOf(error: unknown): CommerceErrorInfo;
+export type CommercePurchaseState = 'requested' | 'launched' | 'pending' | 'purchased' | 'verifying' | 'granted' | 'finishing' | 'finished' | 'cancelled' | 'failed' | 'rejected' | 'revoked';
+export declare const commercePurchaseStates: readonly ["requested", "launched", "pending", "purchased", "verifying", "granted", "finishing", "finished", "cancelled", "failed", "rejected", "revoked"];
+/** Allowed transitions, from the RFC lifecycle table. `pending` covers both store-side and server-side waits. */
+export declare const commercePurchaseTransitions: Readonly<Record<CommercePurchaseState, readonly CommercePurchaseState[]>>;
+export declare const terminalCommercePurchaseStates: readonly ["finished", "cancelled", "failed", "rejected", "revoked"];
+export declare function canTransitionCommercePurchase(from: CommercePurchaseState, to: CommercePurchaseState): boolean;
+export declare function assertCommercePurchaseTransition(from: CommercePurchaseState, to: CommercePurchaseState): void;
+export declare function isTerminalCommercePurchaseState(state: CommercePurchaseState): boolean;
+/** Only `granted` may unlock content, and only because the ledger says so. */
+export type CommercePurchaseSummaryStatus = 'pending' | 'granted' | 'cancelled' | 'failed' | 'rejected' | 'revoked';
+export declare function summarizeCommercePurchaseState(state: CommercePurchaseState): CommercePurchaseSummaryStatus;
+/**
+* Rejects a purchase the provider cannot serve before any store UI opens.
+* `kind` is the catalog kind of `input.logicalId`; the caller resolves it.
+*/
+export declare function assertRequestPurchaseSupported(capabilities: CommerceCapabilities, input: RequestPurchaseInput, kind: PurchaseKind): void;
+export interface DerivedPurchaseIdempotencyKeyInput {
+  readonly store: StoreId;
+  readonly transactionId: string;
+  readonly token: string;
+}
+/**
+* Key for a purchase discovered without a journal record. Every runtime derives
+* the same key: `store:<storeId>:<transactionId>` by default, with each
+* component percent-encoded (`encodeURIComponent`) so ids containing `:`
+* cannot collide, and the forms v1 ledgers already use for Google Play
+* (`play-token-sha256:<hex>`) and Apps in Toss (`apps-in-toss:purchase:<orderId>`),
+* which stay byte-identical.
+*/
+export declare function createDerivedPurchaseIdempotencyKey(input: DerivedPurchaseIdempotencyKeyInput): Promise<string>;
+/** Byte-for-byte the v1 `createGooglePlayTokenTransactionId` form; A4 replaces the two copies with this helper. */
+export declare function createGooglePlayTokenPurchaseKey(purchaseToken: string): Promise<string>;
+export declare const commerceEventBufferLimit = 64;
+export interface CommerceEventBuffer {
+  readonly size: number;
+  /** Keeps the event for the first subscriber; drops the oldest recoverable `purchaseUpdated` when full. */
+  push(event: CommerceEvent): void;
+  /** Delivers and clears every buffered event in order. */
+  drain(listener: (event: CommerceEvent) => void): number;
+}
+/**
+* Buffer for events emitted before the first `subscribe` call. Over the limit
+* it drops the oldest recoverable `purchaseUpdated` first: a pending or
+* purchased purchase is still returned by `getAvailablePurchases`. A revoked
+* purchase is not, so revoked `purchaseUpdated`, `purchaseError`, and
+* `subscriptionUpdated` events are dropped oldest-first only when no
+* recoverable `purchaseUpdated` remains.
+*/
+export declare function createCommerceEventBuffer(options?: {
+  readonly limit?: number;
+}): CommerceEventBuffer;
+export declare const assertStoreProduct: (input: unknown) => StoreProduct;
+export declare const isStoreProduct: (input: unknown) => input is StoreProduct;
+export declare const assertStorePurchase: (input: unknown) => StorePurchase;
+export declare const isStorePurchase: (input: unknown) => input is StorePurchase;
+export declare const assertRequestPurchaseInput: (input: unknown) => RequestPurchaseInput;
+export declare const isRequestPurchaseInput: (input: unknown) => input is RequestPurchaseInput;
+export declare const assertRequestPurchaseResult: (input: unknown) => RequestPurchaseResult;
+export declare const isRequestPurchaseResult: (input: unknown) => input is RequestPurchaseResult;
+export declare const assertCommerceEvent: (input: unknown) => CommerceEvent;
+export declare const isCommerceEvent: (input: unknown) => input is CommerceEvent;
+export declare const assertCommerceEventEnvelope: (input: unknown) => CommerceEventEnvelope;
+export declare const isCommerceEventEnvelope: (input: unknown) => input is CommerceEventEnvelope;
+export declare const assertActiveSubscription: (input: unknown) => ActiveSubscription;
+export declare const isActiveSubscription: (input: unknown) => input is ActiveSubscription;
+export declare const assertFetchProductsInput: (input: unknown) => FetchProductsInput;
+export declare const assertCommerceCapabilities: (input: unknown) => CommerceCapabilities;
+export declare const isCommerceCapabilities: (input: unknown) => input is CommerceCapabilities;
+export declare const assertCommerceErrorInfo: (input: unknown) => CommerceErrorInfo;
+export declare const assertCreditOffer: (input: unknown) => CreditOffer;
+export declare const assertCreditSpendInput: (input: unknown) => CreditSpendInput;
+export declare const assertCreditSpendResult: (input: unknown) => CreditSpendResult;
+export declare const assertCreditEntitlement: (input: unknown) => CreditEntitlement;
+export declare const assertCreditBalance: (input: unknown) => CreditBalance;
+export declare const assertCreditLot: (input: unknown) => CreditLot;
+export declare const assertFinishTransactionInput: (input: unknown) => FinishTransactionInput;
+export declare const assertFinishTransactionResult: (input: unknown) => FinishTransactionResult;
+export declare const assertGetAvailablePurchasesInput: (input: unknown) => GetAvailablePurchasesInput;
+export declare const assertCommerceBridgeGetCapabilitiesPayload: (input: unknown) => CommerceBridgeGetCapabilitiesPayload;
+export declare const assertCommerceBridgeGetCapabilitiesResult: (input: unknown) => CommerceBridgeGetCapabilitiesResult;
+export declare const assertCommerceBridgeFetchProductsPayload: (input: unknown) => FetchProductsInput;
+export declare const assertCommerceBridgeFetchProductsResult: (input: unknown) => CommerceBridgeFetchProductsResult;
+export declare const assertCommerceBridgeRequestPurchasePayload: (input: unknown) => RequestPurchaseInput;
+export declare const assertCommerceBridgeRequestPurchaseResult: (input: unknown) => RequestPurchaseResult;
+export declare const assertCommerceBridgeGetAvailablePurchasesPayload: (input: unknown) => GetAvailablePurchasesInput;
+export declare const assertCommerceBridgeGetAvailablePurchasesResult: (input: unknown) => CommerceBridgeGetAvailablePurchasesResult;
+export declare const assertCommerceBridgeFinishTransactionPayload: (input: unknown) => FinishTransactionInput;
+export declare const assertCommerceBridgeFinishTransactionResult: (input: unknown) => FinishTransactionResult;
+export declare const assertCommerceBridgeRestorePurchasesPayload: (input: unknown) => CommerceBridgeRestorePurchasesPayload;
+export declare const assertCommerceBridgeRestorePurchasesResult: (input: unknown) => CommerceBridgeRestorePurchasesResult;
+export interface ToCommerceAdapterOptions {
+  /** Forwarded to `getAvailablePurchases` during `restore`. Defaults to false. */
+  readonly includePending?: boolean;
+}
+/**
+* Serves v1 `CommerceAdapter` callers from a v2 provider. The wrapper never
+* grants: a `purchased` outcome becomes a `completed` result with no
+* entitlements, and `authoritativeGrant` appears only when the provider reports
+* an adapter settlement that already points at a ledger entry. `restore`
+* returns settled purchases from `getAvailablePurchases` and no entitlements;
+* entitlements come from the ledger, not from the provider.
+*/
+export declare function toCommerceAdapter(provider: CommerceProvider, options?: ToCommerceAdapterOptions): CommerceAdapter;