@mpgd/platform 0.18.0 → 0.20.0

package/dist/commerce-contract.d.ts

@@ -0,0 +1,222 @@
+import type { CommerceCapabilities, LogicalProductId, PlatformEvidenceEnvelope, StarterLogicalProductId } from './index.js';
+/**
+* Commerce v2 client contract types (RFC "Client contract"). This module is
+* typia-free on purpose: `./index` references `CommerceProvider` for
+* `PlatformGateway.commerceV2`, and headless consumers type-check
+* `@mpgd/platform` with `skipLibCheck: false` and no DOM lib, where typia's
+* root declarations do not compile. `./commerce` re-exports everything here
+* and builds the validators and JSON Schemas from these same types.
+*
+* The validation tags below are the structural phantom form typia reads
+* (`'typia.tag'`), mirrored field for field from `@typia/interface` so the
+* generated validators and schemas are identical to the typia aliases;
+* `commerce-contract.test.ts` proves that parity and the schema alignment
+* validator compares the committed files byte for byte.
+*/
+type CommerceTag<Props extends object> = {
+  'typia.tag'?: Props;
+};
+/** `tags.MinLength<Value>` */
+export type CommerceMinLength<Value extends number> = CommerceTag<{
+  target: 'string';
+  kind: 'minLength';
+  value: Value;
+  validate: `${Value} <= $input.length`;
+  exclusive: true;
+  schema: {
+    minLength: Value;
+  };
+}>;
+/** `tags.Format<'date-time'>` */
+export type CommerceDateTimeFormat = CommerceTag<{
+  target: 'string';
+  kind: 'format';
+  value: 'date-time';
+  validate: '$importInternal("isFormatDateTime")($input)';
+  exclusive: ['format', 'pattern'];
+  schema: {
+    format: 'date-time';
+  };
+}>;
+/** `tags.Type<'uint32'>` */
+export type CommerceUint32 = CommerceTag<{
+  target: 'number';
+  kind: 'type';
+  value: 'uint32';
+  validate: '$importInternal("isTypeUint32")($input)';
+  exclusive: true;
+  schema: {
+    type: 'integer';
+    minimum: 0;
+  };
+}>;
+/** `tags.Type<'int64'>` */
+export type CommerceInt64 = CommerceTag<{
+  target: 'bigint' | 'number';
+  kind: 'type';
+  value: 'int64';
+  validate: {
+    number: '$importInternal("isTypeInt64")($input)';
+    bigint: 'true';
+  };
+  exclusive: true;
+  schema: {
+    type: 'integer';
+  };
+}>;
+/** `tags.Minimum<Value>` for a number literal */
+export type CommerceMinimum<Value extends number> = CommerceTag<{
+  target: 'number';
+  kind: 'minimum';
+  value: Value;
+  validate: `${Value} <= $input`;
+  exclusive: ['minimum', 'exclusiveMinimum'];
+  schema: {
+    minimum: Value;
+  };
+}>;
+export type NonEmptyString = string & CommerceMinLength<1>;
+export type IsoTimestamp = string & CommerceDateTimeFormat;
+export type PositiveQuantity = number & CommerceUint32 & CommerceMinimum<1>;
+export type NonNegativeInteger = number & CommerceUint32;
+/**
+* Open store identifier. Reference providers use 'google-play', 'app-store',
+* 'microsoft-store', 'apps-in-toss', 'devvit', and 'verse8'; a consuming
+* project adds its own, for example a credit wallet id.
+*/
+export type StoreId = NonEmptyString;
+export type PurchaseKind = 'consumable' | 'durable' | 'subscription';
+/**
+* `LogicalProductId` narrowed to its open string branch and tagged non-empty,
+* so validators and the generated schemas carry `minLength: 1`. Starter ids and
+* plain `LogicalProductId` values remain assignable.
+*/
+export type CommerceLogicalProductId = Exclude<LogicalProductId, StarterLogicalProductId> & CommerceMinLength<1>;
+export interface StorePrice {
+  readonly formatted: string;
+  /** ISO 4217 code or a project-declared code such as a wallet currency. */
+  readonly currencyCode: NonEmptyString;
+  readonly amountMicros?: number & CommerceInt64;
+}
+export interface StoreOffer {
+  readonly offerId: NonEmptyString;
+  readonly price: StorePrice;
+  readonly title?: string;
+  readonly description?: string;
+}
+export interface StoreProduct {
+  readonly logicalId: CommerceLogicalProductId;
+  readonly store: StoreId;
+  readonly storeSku: NonEmptyString;
+  readonly kind: PurchaseKind;
+  readonly title: string;
+  readonly description: string;
+  readonly price: StorePrice;
+  readonly offers?: readonly StoreOffer[];
+}
+export type StorePurchaseState = 'pending' | 'purchased' | 'revoked';
+export interface StorePurchaseAccountBinding {
+  readonly kind: 'obfuscated-account-id' | 'app-account-token' | 'host-identity';
+  readonly value?: string;
+}
+export interface StorePurchase {
+  readonly store: StoreId;
+  /** Store transaction id; a provider derives one when the store has none. */
+  readonly transactionId: NonEmptyString;
+  readonly originalTransactionId?: NonEmptyString;
+  readonly storeSku: NonEmptyString;
+  readonly logicalId?: CommerceLogicalProductId;
+  readonly quantity: PositiveQuantity;
+  readonly state: StorePurchaseState;
+  readonly purchasedAt?: IsoTimestamp;
+  /** Play purchase token, App Store signed transaction (JWS), or host order id. */
+  readonly token: NonEmptyString;
+  readonly evidence: PlatformEvidenceEnvelope;
+  readonly accountBinding?: StorePurchaseAccountBinding;
+  /** Present only for `authority.evidence: 'adapter-settled'`; a reconciler pointer, not a grant. */
+  readonly settlement?: {
+    readonly ledgerEntryId: NonEmptyString;
+  };
+}
+export type PurchaseSource = 'shop' | 'stage_fail' | 'result' | 'event';
+export interface RequestPurchaseInput {
+  readonly logicalId: CommerceLogicalProductId;
+  readonly idempotencyKey: NonEmptyString;
+  readonly source: PurchaseSource;
+  readonly offerId?: NonEmptyString;
+  /** Integer >= 1. Rejected with ITEM_UNAVAILABLE when the provider does not declare `purchase.quantity`. */
+  readonly quantity?: PositiveQuantity;
+}
+export type RequestPurchaseResult = {
+  readonly outcome: 'launched';
+} | {
+  readonly outcome: 'purchased';
+  readonly purchase: StorePurchase;
+} | {
+  readonly outcome: 'cancelled' | 'failed';
+  readonly error: CommerceErrorInfo;
+};
+export type CommerceErrorCode = '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';
+export interface CommerceErrorInfo {
+  readonly code: CommerceErrorCode;
+  readonly retryable: boolean;
+  /** The store's original code, for example PLAY_BILLING_SERVICE_UNAVAILABLE. */
+  readonly storeCode?: string;
+  readonly message?: string;
+}
+export type CommerceEvent = {
+  readonly type: 'purchaseUpdated';
+  readonly purchase: StorePurchase;
+} | {
+  readonly type: 'purchaseError';
+  readonly logicalId?: CommerceLogicalProductId;
+  readonly error: CommerceErrorInfo;
+} | {
+  readonly type: 'subscriptionUpdated';
+  readonly subscription: ActiveSubscription;
+};
+export type FetchProductsType = 'in-app' | 'subscription' | 'all';
+export interface FetchProductsInput {
+  readonly logicalIds?: readonly CommerceLogicalProductId[];
+  readonly type?: FetchProductsType;
+}
+export interface GetAvailablePurchasesInput {
+  readonly includePending?: boolean;
+}
+export interface FinishTransactionInput {
+  readonly transactionId: NonEmptyString;
+  readonly ledgerEntryId: NonEmptyString;
+  readonly isConsumable: boolean;
+}
+export interface FinishTransactionResult {
+  readonly finished: boolean;
+}
+export interface CommerceProvider {
+  readonly store: StoreId;
+  getCapabilities(): Promise<CommerceCapabilities>;
+  fetchProducts(input: FetchProductsInput): Promise<readonly StoreProduct[]>;
+  /** Returns `launched` when the result arrives later as a `purchaseUpdated` event. */
+  requestPurchase(input: RequestPurchaseInput): Promise<RequestPurchaseResult>;
+  /** Purchases the store still reports as unfinished. */
+  getAvailablePurchases(input?: GetAvailablePurchasesInput): Promise<readonly StorePurchase[]>;
+  /** Required when `lifecycle.finish` is 'client' or 'host'. */
+  finishTransaction?(input: FinishTransactionInput): Promise<FinishTransactionResult>;
+  /** Asks the store to resynchronize, for example `AppStore.sync`. */
+  restorePurchases?(): Promise<void>;
+  /** Designed, not implemented by any reference store provider. */
+  getActiveSubscriptions?(): Promise<readonly ActiveSubscription[]>;
+  /** Events emitted before the first listener are delivered to that listener. */
+  subscribe(listener: (event: CommerceEvent) => void): () => void;
+}
+export type ActiveSubscriptionState = 'active' | 'lapsed' | 'revoked';
+export interface ActiveSubscription {
+  readonly store: StoreId;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly subscriptionId: NonEmptyString;
+  readonly periodIndex: NonNegativeInteger;
+  readonly state: ActiveSubscriptionState;
+  readonly startedAt: IsoTimestamp;
+  readonly expiresAt: IsoTimestamp;
+  readonly autoRenew: boolean;
+}
+export {};

package/dist/commerce-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/commerce-vectors.d.ts

@@ -0,0 +1,277 @@
+import { type tags } from 'typia';
+import type { ActiveSubscriptionState, CommerceAuthorityCapabilities, CommerceBillingAuthority, CommerceErrorCode, CommerceLifecycleCapabilities, CommerceLogicalProductId, CommercePurchaseCapabilities, CommercePurchaseState, CreditLotOrigin, CreditLotSpendScope, CreditMembershipTerms, PurchaseKind, PurchaseSource, StorePurchaseState } from './commerce.js';
+/**
+* Conformance vector format for docs/specs/commerce/vectors/*.json. A3 adds
+* the runner; A2 fixes the file shape so every provider and the reference
+* runtime read the same fixtures. Step inputs are fixture shorthand: the
+* runner fills the profile's store, quantity 1, request source `shop`, and
+* fake evidence before calling the typed provider.
+*/
+type NonEmptyString = string & tags.MinLength<1>;
+type IsoTimestamp = string & tags.Format<'date-time'>;
+type NonNegativeInteger = number & tags.Type<'uint32'>;
+export interface CommerceConformanceProfile {
+  readonly store: NonEmptyString;
+  /** Omitted blocks default to all supported. */
+  readonly purchase?: CommercePurchaseCapabilities;
+  readonly lifecycle?: CommerceLifecycleCapabilities;
+  readonly authority?: CommerceAuthorityCapabilities;
+  /**
+  * The scenario is finish-owner independent: when a caller-supplied provider
+  * runs the vector, the runner derives `journal`, `finishCalls`,
+  * `verifyRequests`, and `available` from the provider's declared
+  * capabilities instead of this fixture profile (RFC "Conformance vectors",
+  * adaptive vectors). The reference harness ignores the flag.
+  */
+  readonly adaptive?: boolean;
+}
+export interface CommerceConformanceCatalogEntry {
+  readonly logicalId: CommerceLogicalProductId;
+  readonly kind: PurchaseKind;
+  readonly storeSku: NonEmptyString;
+  /** Membership terms for credit-funded subscription products. */
+  readonly membership?: CreditMembershipTerms;
+}
+export interface CommerceConformanceWallet {
+  readonly currencies: readonly NonEmptyString[] & tags.MinItems<1>;
+  readonly billingAuthority: CommerceBillingAuthority;
+}
+/** Fixture purchase; `store`, `quantity`, and `evidence` come from the profile. */
+export interface CommerceConformancePurchaseFixture {
+  readonly transactionId: NonEmptyString;
+  readonly storeSku: NonEmptyString;
+  readonly token: NonEmptyString;
+  readonly state: StorePurchaseState;
+  readonly originalTransactionId?: NonEmptyString;
+  readonly purchasedAt?: IsoTimestamp;
+  readonly settlement?: {
+    readonly ledgerEntryId: NonEmptyString;
+  };
+}
+/** Explicit normalized class; the runner never guesses it from `storeCode`. */
+export interface CommerceConformanceErrorFixture {
+  readonly code: CommerceErrorCode;
+  readonly retryable: boolean;
+  readonly storeCode?: string;
+}
+/** Partial expectation; omitted fields are not assertions. */
+export interface CommerceConformanceErrorExpectation {
+  readonly code: CommerceErrorCode;
+  readonly retryable?: boolean;
+  readonly storeCode?: string;
+}
+export type CommerceConformanceRequestResultFixture = {
+  readonly outcome: 'launched';
+} | {
+  readonly outcome: 'purchased';
+  readonly purchase: CommerceConformancePurchaseFixture;
+} | {
+  readonly outcome: 'cancelled' | 'failed';
+  readonly error: CommerceConformanceErrorFixture;
+};
+export type CommerceConformanceFinishResultFixture = {
+  readonly finished: boolean;
+} | {
+  readonly error: CommerceErrorCode;
+};
+export interface CommerceConformanceVerifyDecision {
+  readonly status: 'granted' | 'pending' | 'rejected';
+  readonly ledgerEntryId?: NonEmptyString;
+  readonly finalization?: 'pending' | 'completed';
+  readonly alreadyProcessed?: boolean;
+}
+export interface CommerceConformanceLotFixture {
+  readonly ledgerEntryId: NonEmptyString;
+  readonly currency: NonEmptyString;
+  readonly amount: number & tags.ExclusiveMinimum<0>;
+  readonly origin: CreditLotOrigin;
+  readonly createdAt: IsoTimestamp;
+  readonly expiresAt?: IsoTimestamp;
+}
+export interface CommerceConformanceSpendInput {
+  readonly titleId: NonEmptyString;
+  readonly currency: NonEmptyString;
+  readonly amount: number & tags.ExclusiveMinimum<0>;
+  readonly idempotencyKey: NonEmptyString;
+}
+export interface CommerceConformanceDebitExpectation {
+  readonly lotId: NonEmptyString;
+  readonly amount: number & tags.ExclusiveMinimum<0>;
+}
+export interface CommerceConformanceSpendExpectation {
+  readonly status: 'debited' | 'rejected';
+  readonly debits?: readonly CommerceConformanceDebitExpectation[];
+  readonly alreadyProcessed?: boolean;
+  readonly error?: CommerceConformanceErrorExpectation;
+}
+export interface CommerceConformanceRequestPurchaseExpectation {
+  readonly outcome: 'launched' | 'purchased' | 'cancelled' | 'failed';
+  readonly error?: CommerceConformanceErrorExpectation;
+}
+export interface CommerceConformanceFetchProductsExpectation {
+  readonly logicalIds: readonly CommerceLogicalProductId[];
+}
+export type CommerceConformanceStep = {
+  readonly actor: 'runtime';
+  readonly action: 'start' | 'stop' | 'reconcile';
+} | {
+  readonly actor: 'game';
+  readonly action: 'requestPurchase';
+  readonly input: {
+    readonly logicalId: CommerceLogicalProductId;
+    readonly idempotencyKey: NonEmptyString;
+    readonly source?: PurchaseSource;
+    readonly offerId?: NonEmptyString;
+    readonly quantity?: number & tags.Type<'uint32'> & tags.Minimum<1>;
+  };
+  readonly returns?: CommerceConformanceRequestPurchaseExpectation;
+} | {
+  readonly actor: 'game';
+  readonly action: 'fetchProducts';
+  readonly input?: {
+    readonly logicalIds?: readonly CommerceLogicalProductId[];
+    readonly type?: 'in-app' | 'subscription' | 'all';
+  };
+  readonly returns?: CommerceConformanceFetchProductsExpectation;
+} | {
+  readonly actor: 'store';
+  readonly action: 'complete' | 'update';
+  readonly purchase: CommerceConformancePurchaseFixture;
+} | {
+  readonly actor: 'store';
+  readonly action: 'error';
+  readonly logicalId?: CommerceLogicalProductId;
+  readonly error: CommerceConformanceErrorFixture;
+} | {
+  readonly actor: 'store';
+  readonly action: 'queueRequest';
+  readonly result: CommerceConformanceRequestResultFixture;
+} | {
+  readonly actor: 'store';
+  readonly action: 'queueFinish';
+  readonly result: CommerceConformanceFinishResultFixture;
+} | {
+  readonly actor: 'backend';
+  readonly action: 'queueVerify';
+  readonly decision: CommerceConformanceVerifyDecision;
+} | {
+  readonly actor: 'backend';
+  readonly action: 'push';
+  readonly transactionId: NonEmptyString;
+  readonly entryId: NonEmptyString;
+  readonly logicalId: CommerceLogicalProductId;
+} | {
+  readonly actor: 'backend';
+  readonly action: 'revoke';
+  readonly ledgerEntryId: NonEmptyString;
+  readonly entryId: NonEmptyString;
+  readonly reason: NonEmptyString;
+} | {
+  readonly actor: 'wallet';
+  readonly action: 'creditFromGrant';
+  readonly lot: CommerceConformanceLotFixture;
+} | {
+  readonly actor: 'wallet';
+  readonly action: 'spend';
+  readonly input: CommerceConformanceSpendInput;
+  readonly returns?: CommerceConformanceSpendExpectation;
+} | {
+  readonly actor: 'wallet';
+  readonly action: 'renewDue';
+} | {
+  readonly actor: 'clock';
+  readonly action: 'set';
+  readonly at: IsoTimestamp;
+};
+export type CommerceConformanceActor = CommerceConformanceStep['actor'];
+export type CommerceConformanceAction = CommerceConformanceStep['action'];
+export interface CommerceConformanceVerifyRequestExpectation {
+  readonly idempotencyKey: NonEmptyString;
+  readonly store: NonEmptyString;
+  readonly transactionId: NonEmptyString;
+  readonly token: NonEmptyString;
+}
+export interface CommerceConformanceLedgerEntryExpectation {
+  readonly entryId: NonEmptyString;
+  readonly type: 'grant' | 'revoke' | 'period';
+  readonly logicalId: CommerceLogicalProductId;
+  /** The grant a `revoke` entry reverses. */
+  readonly reverses?: NonEmptyString;
+  readonly reason?: NonEmptyString;
+}
+export interface CommerceConformanceFinishCallExpectation {
+  readonly by: 'client' | 'host';
+  readonly transactionId: NonEmptyString;
+  readonly ledgerEntryId: NonEmptyString;
+  readonly isConsumable: boolean;
+  readonly result: 'finished' | CommerceErrorCode;
+}
+export interface CommerceConformanceAvailableExpectation {
+  readonly transactionId: NonEmptyString;
+  readonly storeSku?: NonEmptyString;
+  readonly state?: StorePurchaseState;
+}
+export interface CommerceConformanceEntitlementExpectation {
+  readonly id: NonEmptyString;
+  readonly logicalId?: CommerceLogicalProductId;
+}
+export interface CommerceConformanceLotExpectation {
+  readonly lotId: NonEmptyString;
+  readonly currency?: NonEmptyString;
+  readonly amount?: number & tags.ExclusiveMinimum<0>;
+  readonly remaining: number & tags.Minimum<0>;
+  readonly origin?: CreditLotOrigin;
+  readonly spendScope?: CreditLotSpendScope;
+}
+export interface CommerceConformanceScheduledDebitExpectation {
+  readonly idempotencyKey: NonEmptyString;
+  readonly lotId: NonEmptyString;
+  readonly amount: number & tags.ExclusiveMinimum<0>;
+}
+export type CommerceConformanceSubscriptionEventType = 'subscriptionStarted' | 'subscriptionRenewed' | 'subscriptionLapsed' | 'subscriptionRevoked';
+export interface CommerceConformanceSubscriptionEventExpectation {
+  readonly type: CommerceConformanceSubscriptionEventType;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly periodIndex: NonNegativeInteger;
+  readonly expiresAt: IsoTimestamp;
+  readonly reason?: CommerceErrorCode;
+}
+export interface CommerceConformanceActiveSubscriptionExpectation {
+  readonly logicalId: CommerceLogicalProductId;
+  readonly periodIndex?: NonNegativeInteger;
+  readonly state?: ActiveSubscriptionState;
+  readonly expiresAt?: IsoTimestamp;
+}
+export interface CommerceConformanceExpectation {
+  /** Full state sequence per journal key. */
+  readonly journal?: Readonly<Record<string, readonly CommercePurchaseState[]>>;
+  readonly verifyRequests?: readonly CommerceConformanceVerifyRequestExpectation[];
+  readonly ledger?: readonly CommerceConformanceLedgerEntryExpectation[];
+  readonly finishCalls?: readonly CommerceConformanceFinishCallExpectation[];
+  readonly available?: readonly CommerceConformanceAvailableExpectation[];
+  readonly entitlements?: readonly CommerceConformanceEntitlementExpectation[];
+  readonly lots?: readonly CommerceConformanceLotExpectation[];
+  /** Spendable balance per title and currency. */
+  readonly balances?: Readonly<Record<string, Readonly<Record<string, number>>>>;
+  readonly debits?: readonly CommerceConformanceScheduledDebitExpectation[];
+  readonly events?: readonly CommerceConformanceSubscriptionEventExpectation[];
+  readonly activeSubscriptions?: readonly CommerceConformanceActiveSubscriptionExpectation[];
+  readonly purchaseUiOpened?: NonNegativeInteger;
+}
+export interface CommerceConformanceVector {
+  /** Equals the file name without `.json`. */
+  readonly vector: string & tags.Pattern<'^[a-z0-9]+(?:-[a-z0-9]+)*$'>;
+  readonly protocol: NonEmptyString;
+  readonly summary: NonEmptyString;
+  readonly profile: CommerceConformanceProfile;
+  readonly catalog?: readonly CommerceConformanceCatalogEntry[];
+  readonly wallet?: CommerceConformanceWallet;
+  readonly steps: readonly CommerceConformanceStep[] & tags.MinItems<1>;
+  readonly expect: CommerceConformanceExpectation;
+}
+/** Validates one vector file. Catalog logical ids must be unique. */
+export declare function assertCommerceConformanceVector(input: unknown): CommerceConformanceVector;
+export declare function isCommerceConformanceVector(input: unknown): input is CommerceConformanceVector;
+/** The vector name a file at `path` must declare. */
+export declare function commerceConformanceVectorNameOf(path: string): string;
+export {};