@mpgd/platform 0.12.1 → 0.13.0

package/dist/capability-conformance.d.ts

@@ -1,6 +1,6 @@
 import type { PlatformCapabilities, PlatformGateway, PlatformTarget } from './index.js';
 export declare const platformCapabilityKeys: readonly ["nativeIap", "nativeAds", "rewardedAds", "interstitialAds", "nativeLeaderboard", "remoteLeaderboard", "achievements", "cloudSave", "socialShare", "haptics", "localizedContent"];
-export declare const optionalPlatformCapabilityKeys: readonly ["bannerAds"];
+export declare const optionalPlatformCapabilityKeys: readonly ["bannerAds", "subscriptionIap"];
 export interface PlatformGatewayCapabilityConformanceTransition {
   readonly update: () => Promise<void> | void;
   readonly expectedCapabilities: PlatformCapabilities;
@@ -26,5 +26,11 @@ export interface PlatformGatewayCapabilityConformanceReport {
 * Runs provider-neutral capability checks against real adapter gateways or
 * target-configured wrappers. Every read must return a complete boolean
 * snapshot, a fresh object, and the provider's latest state.
+* @evidence docs/specs/platform-capability-snapshots.md#snapshot-shape Checks each gateway read against the required boolean keys and expected provider state.
+* @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #a1834db Reviewed required booleans, optional banner/subscription defaults, ordered readiness comparison, and fresh nested rereads.
+* @evidence docs/specs/platform-capability-snapshots.md#provider-transitions Checks a fresh provider read after the optional transition update.
+* @evidenceReview docs/specs/platform-capability-snapshots.md#provider-transitions #839c0c8 Reviewed the changed-state guard and post-update snapshot assertion.
+* @evidence docs/specs/platform-capability-snapshots.md#fixture-validation Rejects invalid fixture sets and returns the names of passing fixtures.
+* @evidenceReview docs/specs/platform-capability-snapshots.md#fixture-validation #d566052 Checked the nonempty and unique name guards and target assertion.
 */
 export declare function runPlatformGatewayCapabilityConformance(input: RunPlatformGatewayCapabilityConformanceInput): Promise<PlatformGatewayCapabilityConformanceReport>;

package/dist/capability-conformance.js

@@ -13,17 +13,44 @@ export const platformCapabilityKeys = Object.freeze([
 ]);
 export const optionalPlatformCapabilityKeys = Object.freeze([
     'bannerAds',
+    'subscriptionIap',
 ]);
 const allowedPlatformCapabilityKeys = Object.freeze([
     ...platformCapabilityKeys,
     ...optionalPlatformCapabilityKeys,
 ]);
-const allowedPlatformCapabilityKeySet = new Set(allowedPlatformCapabilityKeys);
+const allowedPlatformCapabilityKeySet = new Set([
+    ...allowedPlatformCapabilityKeys,
+    'providerAvailability',
+]);
 const optionalPlatformCapabilityKeySet = new Set(optionalPlatformCapabilityKeys);
+const providerFeatureSet = new Set([
+    'nativeIap',
+    'subscriptionIap',
+    'rewardedAds',
+    'interstitialAds',
+    'bannerAds',
+    'nativeLeaderboard',
+    'identityUpgrade',
+    'pushNotifications',
+]);
+const providerAvailabilitySet = new Set([
+    'unsupported',
+    'configuration-required',
+    'action-required',
+    'temporarily-unavailable',
+    'available',
+]);
 /**
  * Runs provider-neutral capability checks against real adapter gateways or
  * target-configured wrappers. Every read must return a complete boolean
  * snapshot, a fresh object, and the provider's latest state.
+ * @evidence docs/specs/platform-capability-snapshots.md#snapshot-shape Checks each gateway read against the required boolean keys and expected provider state.
+ * @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #a1834db Reviewed required booleans, optional banner/subscription defaults, ordered readiness comparison, and fresh nested rereads.
+ * @evidence docs/specs/platform-capability-snapshots.md#provider-transitions Checks a fresh provider read after the optional transition update.
+ * @evidenceReview docs/specs/platform-capability-snapshots.md#provider-transitions #839c0c8 Reviewed the changed-state guard and post-update snapshot assertion.
+ * @evidence docs/specs/platform-capability-snapshots.md#fixture-validation Rejects invalid fixture sets and returns the names of passing fixtures.
+ * @evidenceReview docs/specs/platform-capability-snapshots.md#fixture-validation #d566052 Checked the nonempty and unique name guards and target assertion.
  */
 export async function runPlatformGatewayCapabilityConformance(input) {
     if (input.fixtures.length === 0) {
@@ -52,21 +79,28 @@ export async function runPlatformGatewayCapabilityConformance(input) {
     return { passedFixtures };
 }
 async function runFixture(fixture) {
+    // A fixture may accidentally share its expected object with the provider.
+    // Keep the oracle independent before tryMutateSnapshot probes isolation.
+    const initialExpected = cloneExpectedCapabilities(fixture.expectedCapabilities);
+    const transitionExpected = fixture.transition === undefined
+        ? undefined
+        : cloneExpectedCapabilities(fixture.transition.expectedCapabilities);
     assertEqual(fixture.gateway.target, fixture.expectedTarget, 'gateway target must match the fixture target');
     const first = await fixture.gateway.getCapabilities();
-    assertCapabilitySnapshot(first, fixture.expectedCapabilities);
+    assertCapabilitySnapshot(first, initialExpected);
     tryMutateSnapshot(first);
     const second = await fixture.gateway.getCapabilities();
     assert(second !== first, 'getCapabilities must return a fresh snapshot object for every read');
-    assertCapabilitySnapshot(second, fixture.expectedCapabilities);
-    if (fixture.transition === undefined) {
+    assertCapabilitySnapshot(second, initialExpected);
+    if (fixture.transition === undefined || transitionExpected === undefined) {
         return;
     }
-    assert(hasCapabilityDifference(fixture.expectedCapabilities, fixture.transition.expectedCapabilities), 'a transition fixture must change at least one capability');
+    assert(hasCapabilityDifference(initialExpected, transitionExpected), 'a transition fixture must change at least one capability');
     await fixture.transition.update();
     const updated = await fixture.gateway.getCapabilities();
     assert(updated !== second, 'getCapabilities must return a fresh snapshot after a provider transition');
-    assertCapabilitySnapshot(updated, fixture.transition.expectedCapabilities);
+    assert(updated !== first, 'getCapabilities must not reuse an earlier snapshot after a provider transition');
+    assertCapabilitySnapshot(updated, transitionExpected);
 }
 function assertCapabilitySnapshot(actual, expected) {
     const actualKeys = Object.keys(actual).sort();
@@ -80,6 +114,29 @@ function assertCapabilitySnapshot(actual, expected) {
         }
         assertEqual(optional ? (actual[key] ?? false) : actual[key], optional ? (expected[key] ?? false) : expected[key], `capability ${key} must match the expected provider state`);
     }
+    assertProviderAvailabilityShape(actual.providerAvailability);
+    assertEqual(normalizedAvailability(actual.providerAvailability), normalizedAvailability(expected.providerAvailability), 'provider availability must match the expected provider state');
+}
+function assertProviderAvailabilityShape(value) {
+    if (value === undefined) {
+        return;
+    }
+    assert(typeof value === 'object' && value !== null && !Array.isArray(value), 'provider availability must be a non-array record');
+    for (const [feature, state] of Object.entries(value)) {
+        assert(providerFeatureSet.has(feature)
+            && providerAvailabilitySet.has(state), 'provider availability must contain only known features and readiness states');
+    }
+}
+function cloneExpectedCapabilities(value) {
+    return {
+        ...value,
+        ...(value.providerAvailability === undefined
+            ? {}
+            : { providerAvailability: { ...value.providerAvailability } }),
+    };
+}
+function normalizedAvailability(value) {
+    return JSON.stringify(Object.entries(value ?? {}).sort(([a], [b]) => a.localeCompare(b)));
 }
 function tryMutateSnapshot(snapshot) {
     try {
@@ -88,10 +145,23 @@ function tryMutateSnapshot(snapshot) {
     catch {
         // Frozen snapshots already satisfy the isolation requirement.
     }
+    if (snapshot.providerAvailability !== undefined) {
+        try {
+            const next = snapshot.providerAvailability.nativeIap === 'available'
+                ? 'unsupported'
+                : 'available';
+            Reflect.set(snapshot.providerAvailability, 'nativeIap', next);
+        }
+        catch {
+            // A frozen nested readiness record already satisfies isolation.
+        }
+    }
 }
 function hasCapabilityDifference(first, second) {
     return allowedPlatformCapabilityKeys
-        .some((key) => (first[key] ?? false) !== (second[key] ?? false));
+        .some((key) => (first[key] ?? false) !== (second[key] ?? false))
+        || normalizedAvailability(first.providerAvailability)
+            !== normalizedAvailability(second.providerAvailability);
 }
 function assert(condition, message) {
     if (!condition) {

package/dist/index.d.ts

@@ -59,7 +59,29 @@ export interface PurchaseResult {
 }
 export interface PurchaseRestoreResult {
   readonly restoredEntitlements: readonly Entitlement[];
+  /** Server-confirmed consumable outcomes; native order visibility alone is not a grant. */
+  readonly settledPurchases?: readonly PurchaseSettlement[];
 }
+export interface PurchaseSettlement {
+  readonly transactionId: string;
+  readonly productId: LogicalProductId;
+  readonly status: 'granted' | 'refunded';
+  readonly ledgerEntryId?: string;
+  readonly alreadyProcessed?: boolean;
+}
+/**
+* Resolve a specific purchase from authoritative checkout or restore evidence.
+* A completed native checkout without authoritativeGrant is still unconfirmed.
+* This is UI status evidence, never permission to credit a wallet locally.
+* The caller must pair `purchase` with its requested `productId` because
+* PurchaseResult itself does not carry a product identifier.
+*/
+export declare function findAuthoritativePurchaseSettlement(input: {
+  readonly productId: LogicalProductId;
+  readonly transactionId?: string;
+  readonly purchase?: PurchaseResult;
+  readonly restore?: PurchaseRestoreResult;
+}): PurchaseSettlement | null;
 export interface RewardedAdResult {
   readonly status: 'completed' | 'skipped' | 'unavailable' | 'failed';
   readonly rewardGranted: boolean;
@@ -92,6 +114,8 @@ export interface CommerceAdapter {
 export interface AdAdapter {
   preload(input: {
     readonly placementId: LogicalAdPlacementId;
+    /** Allows a shared provider preload method to enforce format readiness. */
+    readonly format?: 'rewarded' | 'interstitial' | 'banner';
   }): Promise<void>;
   showRewarded(input: {
     readonly placementId: LogicalAdPlacementId;
@@ -139,6 +163,8 @@ export interface LeaderboardScoreInput {
   readonly score: number;
   readonly runId: string;
   readonly submittedAt: string;
+  /** Optional target-selected route when native and remote backends coexist. */
+  readonly route?: 'native' | 'remote';
 }
 export interface LeaderboardSubmitResult {
   readonly submitted: boolean;
@@ -148,10 +174,17 @@ export interface LeaderboardAdapter {
   submitScore(input: LeaderboardScoreInput): Promise<LeaderboardSubmitResult>;
   open(input?: {
     readonly leaderboardId?: string;
+    readonly route?: 'native' | 'remote';
   }): Promise<void>;
 }
+/** Readiness of an installed platform provider, independent of target policy. */
+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 interface PlatformCapabilities {
   readonly nativeIap: boolean;
+  /** Optional for adapters published before subscription-specific support. */
+  readonly subscriptionIap?: boolean;
   readonly nativeAds: boolean;
   readonly rewardedAds: boolean;
   readonly interstitialAds: boolean;
@@ -165,6 +198,8 @@ export interface PlatformCapabilities {
   readonly socialShare: boolean;
   readonly haptics: boolean;
   readonly localizedContent: boolean;
+  /** Explains a false capability without claiming an unavailable SDK works. */
+  readonly providerAvailability?: Readonly<Partial<Record<PlatformProviderFeature, PlatformProviderAvailability>>>;
 }
 export interface PlayerIdentity {
   readonly playerId: string;
@@ -245,9 +280,77 @@ export interface NotificationSubscriptionAdapter {
   getStatus(topic: NotificationTopic): Promise<NotificationSubscriptionStatus>;
   requestSubscription(topic: NotificationTopic): Promise<NotificationSubscriptionResult>;
 }
+/** The source of an app URL, not a claim that the URL is trusted. */
+export interface NativeOpenUrlEvent {
+  readonly url: string;
+  readonly source: 'cold' | 'warm';
+}
+export interface NativeBackButtonEvent {
+  /** Whether the WebView history can navigate back, not the game's own scene stack. */
+  readonly canGoBack: boolean;
+}
+/** Full WebView viewport geometry in CSS pixels, before applying game-owned padding. */
+export interface PlatformViewportInsets {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+export interface PlatformViewportBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+/** An occupied game surface with stable identity, not an extra inset to sum. */
+export interface PlatformViewportOccupiedSurface {
+  readonly surfaceId: string;
+  readonly edge: 'top' | 'right' | 'bottom' | 'left';
+  readonly bounds: PlatformViewportBounds;
+}
+/**
+* Structurally matches `TargetViewportUsableAreaInput` in @mpgd/target-config
+* (field names, CSS-pixel units, and edge union), so consumers can pass the
+* same state to `resolveTargetViewportUsableArea` without conversion.
+*/
+export interface PlatformViewportState {
+  readonly width: number;
+  readonly height: number;
+  readonly safeAreaInsets: PlatformViewportInsets;
+  readonly systemBarInsets: PlatformViewportInsets;
+  readonly keyboardInsets: PlatformViewportInsets;
+  readonly occupiedSurfaces: readonly PlatformViewportOccupiedSurface[];
+}
+/** Optional native viewport source; consumers use one owner for canvas and DOM layout. */
+export interface ViewportAdapter {
+  getState(): PlatformViewportState;
+  onChange(callback: (state: PlatformViewportState) => void): () => void;
+  dispose?(): void;
+}
 export interface LifecycleAdapter {
   onPause(callback: () => void): () => void;
   onResume(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
+  * exits the app. The method's presence does not imply support on iOS: check
+  * the gateway target. Persist progress at checkpoints; back/exit callbacks
+  * are not guaranteed to run before process termination.
+  */
+  onBackButton?(handler: (event: NativeBackButtonEvent) => boolean | Promise<boolean>): () => void;
+  /** Game links and OAuth redirects use separate callbacks. */
+  onGameUrlOpen?(callback: (event: NativeOpenUrlEvent) => void): () => void;
+  onOAuthRedirect?(callback: (event: NativeOpenUrlEvent) => void): () => void;
+  getInitialGameUrl?(): Promise<NativeOpenUrlEvent | null>;
+  getInitialOAuthRedirect?(): Promise<NativeOpenUrlEvent | null>;
+  /**
+  * Keep execution paused while external UI is open. Call the returned
+  * idempotent release function when it closes, including failure paths;
+  * otherwise execution remains paused.
+  */
+  beginExternalActivity?(): () => void;
+  /** Remove only the native listeners owned by this adapter instance. */
+  dispose?(): Promise<void>;
 }
 export interface StorageLoadResult {
   readonly value: unknown;
@@ -262,6 +365,19 @@ export interface StorageAdapter {
     readonly value: unknown;
   }): Promise<void>;
 }
+/** Device-protected opaque credentials; never backed by ordinary game storage. */
+export interface SecureCredentialStore {
+  load(input: {
+    readonly key: string;
+  }): Promise<string | null>;
+  save(input: {
+    readonly key: string;
+    readonly value: string;
+  }): Promise<void>;
+  remove(input: {
+    readonly key: string;
+  }): Promise<void>;
+}
 export interface PlatformGateway {
   readonly target: PlatformTarget;
   getCapabilities(): Promise<PlatformCapabilities>;
@@ -270,7 +386,10 @@ export interface PlatformGateway {
   readonly ads: AdAdapter;
   readonly leaderboard: LeaderboardAdapter;
   readonly lifecycle: LifecycleAdapter;
+  readonly viewport?: ViewportAdapter;
   readonly storage: StorageAdapter;
+  /** Optional: missing native support must not fall back to plaintext storage. */
+  readonly secureCredentials?: SecureCredentialStore;
   readonly presentation?: PresentationAdapter;
   readonly sharing?: ShareAdapter;
   readonly notifications?: NotificationSubscriptionAdapter;

package/dist/index.js

@@ -41,6 +41,41 @@ function isPlatformOperationCode(code) {
         && code.length <= 128
         && /^[A-Z][A-Z0-9_:-]*$/u.test(code);
 }
+/**
+ * Resolve a specific purchase from authoritative checkout or restore evidence.
+ * A completed native checkout without authoritativeGrant is still unconfirmed.
+ * This is UI status evidence, never permission to credit a wallet locally.
+ * The caller must pair `purchase` with its requested `productId` because
+ * PurchaseResult itself does not carry a product identifier.
+ */
+export function findAuthoritativePurchaseSettlement(input) {
+    const effectiveTransactionId = input.transactionId ?? input.purchase?.transactionId;
+    const matchingRestored = input.restore?.settledPurchases?.filter((settlement) => settlement.productId === input.productId
+        && (effectiveTransactionId === undefined || settlement.transactionId === effectiveTransactionId));
+    // Without an order ID, multiple historical outcomes are ambiguous.
+    if (matchingRestored !== undefined && matchingRestored.length > 1) {
+        return null;
+    }
+    if (matchingRestored?.[0] !== undefined) {
+        return matchingRestored[0];
+    }
+    const purchase = input.purchase;
+    if (purchase?.status !== 'completed'
+        || purchase.transactionId === undefined
+        || purchase.authoritativeGrant === undefined
+        || (effectiveTransactionId !== undefined && effectiveTransactionId !== purchase.transactionId)) {
+        return null;
+    }
+    return {
+        transactionId: purchase.transactionId,
+        productId: input.productId,
+        status: 'granted',
+        ledgerEntryId: purchase.authoritativeGrant.ledgerEntryId,
+        ...(purchase.authoritativeGrant.alreadyProcessed === undefined
+            ? {}
+            : { alreadyProcessed: purchase.authoritativeGrant.alreadyProcessed }),
+    };
+}
 export function resolveShareCompletion(result) {
     if (result.status !== 'shared') {
         return undefined;

package/package.json

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