@mpgd/platform 0.16.0 → 0.18.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { AdProvider } from './ads.js';
-export type PlatformTarget = 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8' | 'crazygames' | 'telegram' | 'tauri' | 'wechat' | 'tiktok';
+export type PlatformTarget = 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8' | 'crazygames' | 'oneplay' | 'telegram' | 'tauri' | 'wechat' | 'tiktok';
 export type StarterLogicalProductId = 'COINS_100' | 'COINS_500' | 'REMOVE_ADS';
 export type LogicalProductId = StarterLogicalProductId | (string & Record<never, never>);
 export type StarterLogicalAdPlacementId = 'CONTINUE_AFTER_FAIL' | 'STAGE_END_INTERSTITIAL';
@@ -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.
@@ -102,7 +117,16 @@ export interface InterstitialAdResult {
 export interface BannerAdMountResult {
   readonly status: 'mounted' | 'unavailable' | 'failed';
 }
+export interface PlatformPurchasePresentationEvent {
+  readonly idempotencyKey: string;
+  readonly sequence: number;
+  readonly state: 'open' | 'closed' | 'not-started' | 'unknown';
+}
 export interface CommerceAdapter {
+  /** Trusted native presentation facts, independent of the purchase grant result. */
+  readonly presentation?: {
+    subscribe(listener: (event: PlatformPurchasePresentationEvent) => void): () => void;
+  };
   getProducts(): Promise<readonly ProductInfo[]>;
   purchase(input: {
     readonly productId: LogicalProductId;
@@ -333,6 +357,8 @@ export interface ViewportAdapter {
 export interface LifecycleAdapter {
   onPause(callback: () => void): () => void;
   onResume(callback: () => void): () => void;
+  /** Synchronous checkpoint only. The host may destroy the document immediately afterward. */
+  onExit?(callback: () => void): () => void;
   /**
   * Android handlers run last-registered-first until one returns true. If none
   * consumes the event, Capacitor navigates WebView history when possible or
@@ -367,6 +393,16 @@ export interface StorageAdapter {
     readonly key: string;
     readonly value: unknown;
   }): Promise<void>;
+  /** Optional synchronous checkpoint for hosts whose exit event cannot await promises. */
+  saveSync?(input: {
+    readonly key: string;
+    readonly value: unknown;
+  }): void;
+}
+/** Host loading UI. Completion is an acknowledgement, not progress reaching 100%. */
+export interface GameLoadingAdapter {
+  setProgress(progress: number): void;
+  complete(): Promise<void>;
 }
 /** Device-protected opaque credentials; never backed by ordinary game storage. */
 export interface SecureCredentialStore {
@@ -392,9 +428,11 @@ export interface GameActivityAdapter {
 export interface GameSettingsAdapter {
   getAudioMuted(): boolean;
   onAudioMuteChange(callback: (muted: boolean) => void): () => void;
+  getLocale?(): string;
 }
 export interface PlatformGateway {
   readonly target: PlatformTarget;
+  readonly gameLoading?: GameLoadingAdapter;
   getCapabilities(): Promise<PlatformCapabilities>;
   readonly identity: IdentityAdapter;
   readonly commerce: CommerceAdapter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/platform",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Shared platform gateway, monetization, ads, leaderboard, identity, lifecycle, and storage contracts for mpgd games.",
   "license": "MIT",
   "repository": {