@mpgd/platform 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -47,6 +47,15 @@ export declare class PlatformOperationError extends Error implements PlatformOpe
   }>);
 }
 export declare function readPlatformOperationFailure(error: unknown): PlatformOperationFailure | null;
+/**
+* Stable, non-sensitive reason attached to a commerce outcome that did not
+* fully complete. It is diagnostic only: it never grants or revokes anything.
+* Games may use it for UI copy, retry decisions and support logs.
+*/
+export interface CommerceDiagnostic extends PlatformOperationFailure {
+  /** Provider SDK error code, passed through only when it is a safe identifier. */
+  readonly providerCode?: string;
+}
 export interface PurchaseResult {
   readonly status: 'completed' | 'cancelled' | 'pending' | 'failed';
   readonly transactionId?: string;
@@ -57,11 +66,15 @@ export interface PurchaseResult {
     readonly ledgerEntryId: string;
     readonly alreadyProcessed?: boolean;
   }>;
+  /** Optional reason for a cancelled, pending or failed result. */
+  readonly diagnostic?: CommerceDiagnostic;
 }
 export interface PurchaseRestoreResult {
   readonly restoredEntitlements: readonly Entitlement[];
   /** Server-confirmed consumable outcomes; native order visibility alone is not a grant. */
   readonly settledPurchases?: readonly PurchaseSettlement[];
+  /** Present when restore finished only partially, for example with orders still unresolved. */
+  readonly diagnostic?: CommerceDiagnostic;
 }
 export interface PurchaseSettlement {
   readonly transactionId: string;
@@ -69,6 +82,8 @@ export interface PurchaseSettlement {
   readonly status: 'granted' | 'refunded';
   readonly ledgerEntryId?: string;
   readonly alreadyProcessed?: boolean;
+  /** Client purchase idempotency key the order was started with, when the adapter can link it. */
+  readonly idempotencyKey?: string;
 }
 /**
 * Resolve a specific purchase from authoritative checkout or restore evidence.
@@ -193,6 +208,45 @@ export interface LeaderboardAdapter {
 export type PlatformProviderAvailability = 'unsupported' | 'configuration-required' | 'action-required' | 'temporarily-unavailable' | 'available';
 /** Existing capabilities and integrations annotated by optional providers. */
 export type PlatformProviderFeature = 'nativeIap' | 'subscriptionIap' | 'rewardedAds' | 'interstitialAds' | 'bannerAds' | 'nativeLeaderboard' | 'identityUpgrade' | 'pushNotifications';
+export type CommerceFinishOwner = 'client' | 'server' | 'host' | 'none';
+export type CommerceEvidenceAuthority = 'client-token' | 'host-callback' | 'adapter-settled' | 'server-push';
+export type CommerceAccountBindingPolicy = 'required' | 'optional' | 'host';
+export interface CommercePurchaseCapabilities {
+  readonly consumable: boolean;
+  readonly durable: boolean;
+  readonly subscription: boolean;
+  readonly quantity: boolean;
+}
+export interface CommerceCatalogCapabilities {
+  readonly products: boolean;
+  readonly offers: boolean;
+  readonly localizedPrice: boolean;
+}
+export interface CommerceLifecycleCapabilities {
+  readonly availablePurchases: boolean;
+  readonly pending: boolean;
+  readonly restore: boolean;
+  readonly events: boolean;
+  /** Who finishes a granted purchase. */
+  readonly finish: CommerceFinishOwner;
+}
+export interface CommerceAuthorityCapabilities {
+  /** What the backend verifies to grant. */
+  readonly evidence: CommerceEvidenceAuthority;
+  readonly accountBinding: CommerceAccountBindingPolicy;
+}
+/**
+* Commerce v2 capability declaration (`@mpgd/platform/commerce`). Declared
+* here so the main entry stays free of validator imports; code branches on
+* these declarations, never on a store id or target name.
+*/
+export interface CommerceCapabilities {
+  readonly purchase: CommercePurchaseCapabilities;
+  readonly catalog: CommerceCatalogCapabilities;
+  readonly lifecycle: CommerceLifecycleCapabilities;
+  readonly authority: CommerceAuthorityCapabilities;
+  readonly availability: PlatformProviderAvailability;
+}
 export interface PlatformCapabilities {
   readonly nativeIap: boolean;
   /** Optional for adapters published before subscription-specific support. */
@@ -212,6 +266,12 @@ export interface PlatformCapabilities {
   readonly localizedContent: boolean;
   /** Explains a false capability without claiming an unavailable SDK works. */
   readonly providerAvailability?: Readonly<Partial<Record<PlatformProviderFeature, PlatformProviderAvailability>>>;
+  /**
+  * Optional commerce v2 capability block. When present it must be a fresh
+  * object on every read with no unknown keys, and `nativeIap` and
+  * `subscriptionIap` must equal `deriveLegacyCommerceCapabilities(commerce)`.
+  */
+  readonly commerce?: CommerceCapabilities;
 }
 export interface PlayerIdentity {
   readonly playerId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/platform",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Shared platform gateway, monetization, ads, leaderboard, identity, lifecycle, and storage contracts for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -44,12 +44,28 @@
     "./storage-conformance": {
       "types": "./dist/storage-conformance.d.ts",
       "default": "./dist/storage-conformance.js"
+    },
+    "./commerce": {
+      "types": "./dist/commerce.d.ts",
+      "default": "./dist/commerce.js"
+    },
+    "./commerce-vectors": {
+      "types": "./dist/commerce-vectors.d.ts",
+      "default": "./dist/commerce-vectors.js"
+    },
+    "./commerce-conformance": {
+      "types": "./dist/commerce-conformance.d.ts",
+      "default": "./dist/commerce-conformance.js"
     }
   },
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "typia": "13.0.2"
+  },
   "devDependencies": {
+    "@ttsc/unplugin": "0.30.4",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
     "vitest": "^4.0.0"
@@ -64,6 +80,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "vitest run && node test/capability-conformance-dist-import.mjs && node test/storage-conformance-dist-import.mjs && node test/ads-dist-import.mjs"
+    "test": "vitest run && node test/capability-conformance-dist-import.mjs && node test/storage-conformance-dist-import.mjs && node test/ads-dist-import.mjs && node test/commerce-dist-import.mjs && node test/commerce-conformance-dist-import.mjs && cd ../.. && node tools/run-ttsx.mjs packages/platform/test/commerce-derived-key-parity.ts"
   }
 }