@mpgd/adapter-capacitor 0.8.0 → 0.9.1

package/README.md

@@ -64,6 +64,113 @@ The source tests and installed-tarball consumer validate composition, types,
 error paths, and fallback behavior. They do not establish that any optional
 SDK works on a physical device or that a store/ad setup is release-ready.
 
+## Commerce v2 providers
+
+Commerce v2 ([RFC](../../docs/specs/commerce/commerce-v2-rfc.md), PR B1) adds
+a second commerce surface next to the v1 `commerce.*` bridge methods. A store
+plugin exposes an in-process `StoreSdk`, the adapter turns it into a
+`CommerceProvider` from `@mpgd/platform/commerce`, and the provider registry
+serves both the six `commerce.v2.*` bridge methods and the four v1 methods
+from it.
+
+`StoreSdk` is shaped like the OpenIAP Client Protocol so a future Capacitor
+IAP plugin over the OpenIAP cores is a drop-in: `fetchProducts({ skus, type })`,
+`requestPurchase({ sku, offerId?, quantity?, accountBinding? })` answering
+`launched`, `purchased`, `cancelled`, or `failed`, `getAvailablePurchases`
+listing unfinished store purchases, optional `finishTransaction` and
+`restorePurchases`, `addListener('purchaseUpdated' | 'purchaseError')`, an
+optional `getAvailability`, and a static `capabilities` declaration (purchase
+kinds, quantity, pending, restore, finish owner). The SDK speaks store SKUs
+and its own error codes only. B2 adapts `@mpgd/capacitor-play-billing` and B3
+adapts `@mpgd/capacitor-storekit` to this interface; B1 ships no plugin
+change.
+
+```ts
+import {
+  createCapacitorPlatformGateway,
+  createCommerceServiceProvider,
+  createStoreCommerceProvider,
+  type StoreSdk,
+} from '@mpgd/adapter-capacitor';
+
+export function createStoreGateway(sdk: StoreSdk) {
+  const commerce = createStoreCommerceProvider({
+    sdk,
+    products: [
+      { logicalId: 'gems_small', storeSku: 'gems.small', kind: 'consumable' },
+      { logicalId: 'remove_ads', storeSku: 'remove.ads', kind: 'durable' },
+    ],
+    evidenceSchema: 'google-play.product-purchase.v2',
+    evidencePayload: (purchase) => ({ purchaseToken: purchase.token }),
+    accountBinding: async () => ({ kind: 'obfuscated-account-id', value: 'player-1' }),
+    authority: { evidence: 'client-token', accountBinding: 'required' },
+    mapError: { PLAY_BILLING_OFFER_REQUIRED: 'CONFIGURATION_REQUIRED' },
+  });
+  return createCapacitorPlatformGateway({
+    target: 'android',
+    appVersion: '1.0.0',
+    buildId: 'game-build',
+    providers: [createCommerceServiceProvider({ id: 'play-billing', commerce })],
+  });
+}
+```
+
+`createStoreCommerceProvider` maps logical ids to store SKUs both ways (an
+unknown SKU is still reported, with `logicalId` undefined; an unknown logical
+id fails with `ITEM_UNAVAILABLE`), rejects unsupported kinds and quantities
+with `assertRequestPurchaseSupported` before any store UI opens, refuses to
+open the store while `getAvailability` is not `available`, builds every
+`StorePurchase` with the store `token` and the `{ schema: evidenceSchema,
+payload }` envelope, buffers SDK events until the first `subscribe` with
+`createCommerceEventBuffer`, composes `CommerceCapabilities` from the SDK
+declaration plus `capabilities` overrides and a fresh `availability` read
+(three-second timeout, degraded to `temporarily-unavailable`), validates every
+SDK answer with the platform typia asserts (`INVALID_RESPONSE` otherwise), and
+normalizes every SDK failure through `mapError` into a `CommerceError` whose
+`storeCode` keeps the store's own code. It never grants and never sets
+`settlement`; the backend ledger decides.
+
+Two failure classes are not terminal. When `requestPurchase` throws or
+returns a code that normalizes to `OUTCOME_UNKNOWN` (for example
+`PLAY_BILLING_TIMEOUT`, `PLAY_BILLING_INTERRUPTED`,
+`STOREKIT_PURCHASE_UNCERTAIN`) or `ALREADY_OWNED`, an unfinished purchase may
+exist, so the provider answers `{ outcome: 'launched' }` instead of `failed`
+and does not forward a `purchaseError` event carrying those codes
+(`recoverableErrorCodes`). The attempt stays open and the reconciler resolves
+it from `getAvailablePurchases`; the store UI is never reopened blindly. A
+`capabilities.lifecycle` override may hide `restore` or `finish`, but it
+cannot advertise one the SDK lacks: `restore: true` without
+`sdk.restorePurchases`, like `finish: 'client' | 'host'` without
+`sdk.finishTransaction`, is rejected when the provider is created.
+
+`createCommerceServiceProvider` wraps the provider as a `CapacitorServiceProvider`
+whose `commerce` field the registry recognizes: the ten commerce bridge
+methods are implied (declaring a v1 `commerce.*` method alongside is an
+error), `nativeIap` and `subscriptionIap` readiness derive from
+`commerce.getCapabilities()`, and the in-process bridge delivers events as
+`{ protocol: 'mpgd.commerce.v2', sequence, event }` with a per-session
+sequence starting at 0. v1 callers keep working: `gateway.commerce` is served
+by `toCommerceAdapter(provider)`, so a `launched` purchase is `pending`, a
+synchronous purchase is `completed` with evidence and no entitlements, and
+`restore` returns no entitlements. The gateway exposes the v2 surface as
+`gateway.commerceV2` (served through the same validated bridge path, which
+the conformance test exercises for every store vector) and adds a `commerce`
+block to `getCapabilities()` from which `nativeIap` and `subscriptionIap` are
+derived. The block comes from the registry's one bounded read per snapshot
+(`getCapabilitySnapshot`, three-second timeout, shape validated): a stalled,
+failing, or invalid provider yields a degraded block
+(`createDegradedCommerceCapabilities`: `availability:
+'temporarily-unavailable'`, nothing sold, `nativeIap: false`) and never
+rejects the capability read. A `launched` v2 purchase keeps
+`beginExternalActivity()` open after the request returns, since the store UI
+is still up: the gateway releases it when the provider reports that product
+(`purchaseUpdated` or `purchaseError`), after
+`launchedPurchaseActivityTimeoutMs` (two minutes), or on `lifecycle.dispose`;
+the v1 `commerce.purchase` path has no event to wait for and releases when
+its request returns. Without a v2 provider nothing changes: `commerceV2` is
+absent and a `commerce.v2.*` request still answers `COMMERCE_V2_UNAVAILABLE`
+as the transport left it.
+
 ## App Store server-side transaction signatures
 
 The server-side verifier moved to `@mpgd/game-services/app-store-server`

package/dist/commerce-bridge.d.ts

@@ -0,0 +1,59 @@
+import { type BridgeCommerceV2Method, type BridgeEvent, type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
+import { type PlatformProviderFeature } from '@mpgd/platform';
+import { type CommerceBridgeMethods, type CommerceProvider, type StoreId } from '@mpgd/platform/commerce';
+import type { CapacitorCommerceServiceProvider } from './providers.js';
+/** Bridge error for a commerce v2 payload the typia assert rejected. */
+export declare const commerceV2InvalidPayloadBridgeErrorCode: 'COMMERCE_V2_INVALID_PAYLOAD';
+/** Bridge error for a v2 method the provider does not implement (`finishTransaction`). */
+export declare const commerceV2MethodUnsupportedBridgeErrorCode: 'COMMERCE_V2_METHOD_UNSUPPORTED';
+export interface CommerceProviderBridge {
+  request(input: BridgeRequest): Promise<BridgeResponse>;
+  /** Delivers `{ protocol: 'mpgd.commerce.v2', sequence, event }`; `sequence` starts at 0 per bridge. */
+  subscribe(listener: (event: BridgeEvent) => void): () => void;
+}
+export interface CreateCommerceProviderBridgeInput {
+  readonly provider: CommerceProvider;
+  /** Serves the methods the provider does not own, for example a plugin's ad methods. */
+  readonly fallback?: {
+    request(input: BridgeRequest): Promise<BridgeResponse>;
+  };
+}
+/**
+* In-process `NativeBridge` over a commerce v2 provider: the six
+* `commerce.v2.*` methods validate their payload and result with the
+* `@mpgd/platform/commerce` asserts, the four v1 `commerce.*` methods are
+* served by `toCommerceAdapter(provider)`, and events carry the bridge envelope
+* with a per-session sequence. A thrown failure crosses the bridge as
+* `{ code, message, retryable }`; a `cancelled` or `failed` purchase result
+* keeps its `storeCode` because it is data, not an error.
+*/
+export declare function createCommerceProviderBridge(input: CreateCommerceProviderBridgeInput): CommerceProviderBridge;
+export type CapacitorCommerceFeature = Extract<PlatformProviderFeature, 'nativeIap' | 'subscriptionIap'>;
+export interface CreateCommerceServiceProviderInput {
+  readonly id: string;
+  readonly commerce: CommerceProvider;
+  /** Commerce features the provider serves. Defaults to `['nativeIap']`. */
+  readonly features?: readonly CapacitorCommerceFeature[];
+}
+/**
+* Registry entry for a commerce v2 provider: the implied commerce bridge
+* methods are served in process by `createCommerceProviderBridge`, and the
+* registry derives `nativeIap` and `subscriptionIap` readiness from
+* `commerce.getCapabilities()`.
+*/
+export declare function createCommerceServiceProvider(input: CreateCommerceServiceProviderInput): CapacitorCommerceServiceProvider;
+/** Validates a commerce v2 result; a provider answer the contract rejects never reaches the caller. */
+export declare function assertCommerceBridgeResult<TMethod extends BridgeCommerceV2Method>(method: TMethod, data: unknown): CommerceBridgeMethods[TMethod]['result'];
+export interface CreateBridgeCommerceProviderInput {
+  readonly store: StoreId;
+  /** Sends one validated bridge request; the gateway's `request` fits. */
+  readonly request: <TData>(method: BridgeCommerceV2Method, payload: unknown) => Promise<TData>;
+  readonly subscribe: (listener: (event: BridgeEvent) => void) => () => void;
+}
+/**
+* `CommerceProvider` over a bridge that serves the `commerce.v2.*` methods and
+* the event envelope. Results are validated again on this side, so a transport
+* that forgets to is still fail-closed; bridge errors become `CommerceError`s
+* with the bridge code kept as `storeCode` when it is not already a v2 code.
+*/
+export declare function createBridgeCommerceProvider(input: CreateBridgeCommerceProviderInput): CommerceProvider;

package/dist/commerce-bridge.js

@@ -0,0 +1,265 @@
+import { assertBridgeEvent, bridgeEventProtocol, createBridgeError, isBridgeCommerceV2Method, } from '@mpgd/bridge';
+import { PlatformOperationError, } from '@mpgd/platform';
+import { assertCommerceBridgeFetchProductsPayload, assertCommerceBridgeFetchProductsResult, assertCommerceBridgeFinishTransactionPayload, assertCommerceBridgeFinishTransactionResult, assertCommerceBridgeGetAvailablePurchasesPayload, assertCommerceBridgeGetAvailablePurchasesResult, assertCommerceBridgeGetCapabilitiesPayload, assertCommerceBridgeGetCapabilitiesResult, assertCommerceBridgeRequestPurchasePayload, assertCommerceBridgeRequestPurchaseResult, assertCommerceBridgeRestorePurchasesPayload, assertCommerceBridgeRestorePurchasesResult, CommerceError, commerceErrorInfoOf, commerceProtocol, commerceProtocolVersion, toCommerceAdapter, } from '@mpgd/platform/commerce';
+import { normalizeStoreSdkError } from './store-sdk.js';
+/** Bridge error for a commerce v2 payload the typia assert rejected. */
+export const commerceV2InvalidPayloadBridgeErrorCode = 'COMMERCE_V2_INVALID_PAYLOAD';
+/** Bridge error for a v2 method the provider does not implement (`finishTransaction`). */
+export const commerceV2MethodUnsupportedBridgeErrorCode = 'COMMERCE_V2_METHOD_UNSUPPORTED';
+const v1CommerceMethods = Object.freeze([
+    'commerce.getProducts',
+    'commerce.purchase',
+    'commerce.restore',
+    'commerce.getEntitlements',
+]);
+/**
+ * In-process `NativeBridge` over a commerce v2 provider: the six
+ * `commerce.v2.*` methods validate their payload and result with the
+ * `@mpgd/platform/commerce` asserts, the four v1 `commerce.*` methods are
+ * served by `toCommerceAdapter(provider)`, and events carry the bridge envelope
+ * with a per-session sequence. A thrown failure crosses the bridge as
+ * `{ code, message, retryable }`; a `cancelled` or `failed` purchase result
+ * keeps its `storeCode` because it is data, not an error.
+ */
+export function createCommerceProviderBridge(input) {
+    const { provider } = input;
+    const adapter = toCommerceAdapter(provider);
+    const listeners = new Set();
+    let sequence = 0;
+    let detach;
+    const deliver = (event) => {
+        const envelope = { protocol: commerceProtocol, sequence, event };
+        sequence += 1;
+        for (const listener of [...listeners]) {
+            listener(envelope);
+        }
+    };
+    const serve = async (request) => {
+        const { payload } = request;
+        switch (request.method) {
+            case 'commerce.v2.getCapabilities': {
+                assertCommerceBridgeGetCapabilitiesPayload(payload);
+                return assertResult('commerce.v2.getCapabilities', {
+                    protocolVersion: commerceProtocolVersion,
+                    store: provider.store,
+                    capabilities: await provider.getCapabilities(),
+                });
+            }
+            case 'commerce.v2.fetchProducts': {
+                const products = await provider.fetchProducts(assertCommerceBridgeFetchProductsPayload(payload));
+                return assertResult('commerce.v2.fetchProducts', { products });
+            }
+            case 'commerce.v2.requestPurchase':
+                return assertResult('commerce.v2.requestPurchase', await provider.requestPurchase(assertCommerceBridgeRequestPurchasePayload(payload)));
+            case 'commerce.v2.getAvailablePurchases': {
+                const purchases = await provider.getAvailablePurchases(
+                // The payload is asserted as sent; a caller meaning the default sends `{}`.
+                assertCommerceBridgeGetAvailablePurchasesPayload(payload));
+                return assertResult('commerce.v2.getAvailablePurchases', { purchases });
+            }
+            case 'commerce.v2.finishTransaction': {
+                const finish = assertCommerceBridgeFinishTransactionPayload(payload);
+                if (provider.finishTransaction === undefined) {
+                    throw new PlatformOperationError({
+                        code: commerceV2MethodUnsupportedBridgeErrorCode,
+                        message: `Store ${provider.store} does not finish transactions on the client.`,
+                    });
+                }
+                return assertResult('commerce.v2.finishTransaction', await provider.finishTransaction(finish));
+            }
+            case 'commerce.v2.restorePurchases': {
+                assertCommerceBridgeRestorePurchasesPayload(payload);
+                if (provider.restorePurchases === undefined) {
+                    return assertResult('commerce.v2.restorePurchases', { restored: false });
+                }
+                await provider.restorePurchases();
+                return assertResult('commerce.v2.restorePurchases', { restored: true });
+            }
+            case 'commerce.getProducts':
+                return adapter.getProducts();
+            case 'commerce.purchase':
+                return adapter.purchase(payload);
+            case 'commerce.restore':
+                if (adapter.restore === undefined) {
+                    return { restoredEntitlements: [] };
+                }
+                return adapter.restore();
+            case 'commerce.getEntitlements':
+                return adapter.getEntitlements();
+            default:
+                throw new PlatformOperationError({
+                    code: 'UNSUPPORTED_METHOD',
+                    message: `${request.method} is not a commerce method.`,
+                });
+        }
+    };
+    return {
+        async request(request) {
+            const isCommerce = isBridgeCommerceV2Method(request.method)
+                || v1CommerceMethods.includes(request.method);
+            if (!isCommerce && input.fallback !== undefined) {
+                return input.fallback.request(request);
+            }
+            try {
+                return { id: request.id, ok: true, data: await serve(request) };
+            }
+            catch (error) {
+                return toBridgeError(request, error);
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            if (listeners.size === 1) {
+                detach = provider.subscribe(deliver);
+            }
+            return () => {
+                if (!listeners.delete(listener) || listeners.size > 0) {
+                    return;
+                }
+                detach?.();
+                detach = undefined;
+            };
+        },
+    };
+}
+/**
+ * Registry entry for a commerce v2 provider: the implied commerce bridge
+ * methods are served in process by `createCommerceProviderBridge`, and the
+ * registry derives `nativeIap` and `subscriptionIap` readiness from
+ * `commerce.getCapabilities()`.
+ */
+export function createCommerceServiceProvider(input) {
+    return {
+        id: input.id,
+        features: input.features ?? ['nativeIap'],
+        methods: [],
+        commerce: input.commerce,
+        bridge: createCommerceProviderBridge({ provider: input.commerce }),
+        async getAvailability() {
+            return {};
+        },
+    };
+}
+// Each entry is the typia assert of that method's result type; the lookup is
+// typed by `assertCommerceBridgeResult`.
+const resultAsserts = {
+    'commerce.v2.getCapabilities': assertCommerceBridgeGetCapabilitiesResult,
+    'commerce.v2.fetchProducts': assertCommerceBridgeFetchProductsResult,
+    'commerce.v2.requestPurchase': assertCommerceBridgeRequestPurchaseResult,
+    'commerce.v2.getAvailablePurchases': assertCommerceBridgeGetAvailablePurchasesResult,
+    'commerce.v2.finishTransaction': assertCommerceBridgeFinishTransactionResult,
+    'commerce.v2.restorePurchases': assertCommerceBridgeRestorePurchasesResult,
+};
+/** Validates a commerce v2 result; a provider answer the contract rejects never reaches the caller. */
+export function assertCommerceBridgeResult(method, data) {
+    return resultAsserts[method](data);
+}
+function assertResult(method, data) {
+    try {
+        return assertCommerceBridgeResult(method, data);
+    }
+    catch (error) {
+        throw new PlatformOperationError({
+            code: 'NATIVE_PROVIDER_INVALID_RESPONSE',
+            message: `Commerce provider returned invalid data for ${method}: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+function toBridgeError(request, error) {
+    if (isTypiaGuardError(error)) {
+        return createBridgeError(request.id, commerceV2InvalidPayloadBridgeErrorCode, `${request.method} payload is invalid: ${error.message}`);
+    }
+    if (error instanceof PlatformOperationError) {
+        return createBridgeError(request.id, error.code, error.message, error.retryable);
+    }
+    const info = commerceErrorInfoOf(error);
+    return createBridgeError(request.id, info.code, info.message ?? `${request.method} failed.`, info.retryable);
+}
+function isTypiaGuardError(error) {
+    return error instanceof Error && error.name === 'TypeGuardError';
+}
+/**
+ * `CommerceProvider` over a bridge that serves the `commerce.v2.*` methods and
+ * the event envelope. Results are validated again on this side, so a transport
+ * that forgets to is still fail-closed; bridge errors become `CommerceError`s
+ * with the bridge code kept as `storeCode` when it is not already a v2 code.
+ */
+export function createBridgeCommerceProvider(input) {
+    const send = async (method, payload) => {
+        let data;
+        try {
+            data = await input.request(method, payload);
+        }
+        catch (error) {
+            throw toCommerceError(error);
+        }
+        try {
+            return assertCommerceBridgeResult(method, data);
+        }
+        catch (error) {
+            throw new CommerceError('INVALID_RESPONSE', {
+                message: `Bridge returned invalid data for ${method}.`,
+                cause: error,
+            });
+        }
+    };
+    return {
+        store: input.store,
+        async getCapabilities() {
+            return (await send('commerce.v2.getCapabilities', { protocol: commerceProtocol }))
+                .capabilities;
+        },
+        async fetchProducts(request) {
+            return (await send('commerce.v2.fetchProducts', request)).products;
+        },
+        requestPurchase(request) {
+            return send('commerce.v2.requestPurchase', request);
+        },
+        async getAvailablePurchases(request = {}) {
+            return (await send('commerce.v2.getAvailablePurchases', request)).purchases;
+        },
+        finishTransaction(request) {
+            return send('commerce.v2.finishTransaction', request);
+        },
+        async restorePurchases() {
+            await send('commerce.v2.restorePurchases', { protocol: commerceProtocol });
+        },
+        subscribe(listener) {
+            return input.subscribe((envelope) => {
+                // Another protocol on a shared event channel is not ours to judge.
+                if (typeof envelope === 'object' && envelope !== null
+                    && envelope.protocol !== bridgeEventProtocol) {
+                    return;
+                }
+                let event;
+                try {
+                    event = assertBridgeEvent(envelope);
+                }
+                catch (error) {
+                    listener({
+                        type: 'purchaseError',
+                        error: new CommerceError('INVALID_RESPONSE', {
+                            message: 'Bridge delivered an invalid commerce event.',
+                            cause: error,
+                        }).toCommerceErrorInfo(),
+                    });
+                    return;
+                }
+                listener(event.event);
+            });
+        },
+    };
+}
+function toCommerceError(error) {
+    if (error instanceof CommerceError) {
+        return error;
+    }
+    if (error instanceof PlatformOperationError) {
+        return normalizeStoreSdkError({
+            code: error.code,
+            message: error.message,
+            retryable: error.retryable,
+        });
+    }
+    return normalizeStoreSdkError(error);
+}

package/dist/index.d.ts

@@ -1,10 +1,19 @@
 import { type PlatformGateway, type PlatformTarget, type ViewportAdapter } from '@mpgd/platform';
 import { type CapacitorAppEventsApi, type CapacitorIncomingUrlKind, type CapacitorVisibilitySource } from './app-events.js';
 import { type CapacitorServiceProvider, type NativeBridge } from './providers.js';
-export { createCapacitorProviderRegistry, type CapacitorServiceProvider, type NativeBridge, } from './providers.js';
+export { createCapacitorProviderRegistry, createDegradedCommerceCapabilities, deriveCommerceFeatureStates, type CapacitorCommerceServiceProvider, type CapacitorProviderCapabilitySnapshot, type CapacitorProviderRegistry, type CapacitorServiceProvider, type NativeBridge, } from './providers.js';
+export { assertCommerceBridgeResult, commerceV2InvalidPayloadBridgeErrorCode, commerceV2MethodUnsupportedBridgeErrorCode, createBridgeCommerceProvider, createCommerceProviderBridge, createCommerceServiceProvider, type CapacitorCommerceFeature, type CommerceProviderBridge, type CreateBridgeCommerceProviderInput, type CreateCommerceProviderBridgeInput, type CreateCommerceServiceProviderInput, } from './commerce-bridge.js';
+export { createStoreCommerceProvider, recoverableErrorCodes, type CreateStoreCommerceProviderInput, type StoreCommerceCapabilityOverrides, type StoreCommerceProductMapping, type StoreCommerceProvider, } from './store-commerce-provider.js';
+export { defaultStoreSdkErrorCodeMap, normalizeStoreSdkError, type StoreSdk, type StoreSdkCapabilities, type StoreSdkError, type StoreSdkErrorCodeMap, type StoreSdkEvent, type StoreSdkEventName, type StoreSdkEventOf, type StoreSdkFetchProductsInput, type StoreSdkFinishTransactionInput, type StoreSdkFinishTransactionResult, type StoreSdkGetAvailablePurchasesInput, type StoreSdkProduct, type StoreSdkPurchase, type StoreSdkRequestPurchaseInput, type StoreSdkRequestPurchaseResult, } from './store-sdk.js';
 export { createCapacitorAppEvents, type CapacitorAppEventsApi, type CapacitorIncomingUrlKind, type CapacitorVisibilitySource, } from './app-events.js';
 export { CapacitorNativeHttpError, createCapacitorNativeJsonTransport, type CapacitorJsonRequest, type CapacitorJsonResponse, type CapacitorNativeHttpErrorCode, type CapacitorNativeJsonTransport, type CreateCapacitorNativeJsonTransportInput, } from './native-http.js';
 export { createCapacitorViewport, type CapacitorViewportBaseState, type CapacitorOccupiedSurfaceInput, type CapacitorViewportController, type CapacitorViewportHost, } from './viewport.js';
+/**
+* Upper bound on how long a `launched` commerce v2 purchase keeps the game
+* paused when no purchase event for the product arrives (for example a store
+* sheet dismissed without a callback).
+*/
+export declare const launchedPurchaseActivityTimeoutMs = 120000;
 export declare function createCapacitorPlatformGateway(input: {
   readonly target: Extract<PlatformTarget, 'android' | 'ios'>;
   readonly appVersion: string;

package/dist/index.js

@@ -1,15 +1,21 @@
 import { decodeBridgeCredentialLoadData, decodeBridgeStorageLoadData, } from '@mpgd/bridge';
 import { CapacitorGameServices } from '@mpgd/capacitor-game-services';
 import { PlatformOperationError, } from '@mpgd/platform';
+import { deriveLegacyCommerceCapabilities } from '@mpgd/platform/commerce';
 import { createCapacitorAppEvents, } from './app-events.js';
+import { createBridgeCommerceProvider } from './commerce-bridge.js';
 import { assertProviderResponseData, createCapacitorProviderRegistry, } from './providers.js';
 import { createCapacitorViewport } from './viewport.js';
-export { createCapacitorProviderRegistry, } from './providers.js';
+export { createCapacitorProviderRegistry, createDegradedCommerceCapabilities, deriveCommerceFeatureStates, } from './providers.js';
+export { assertCommerceBridgeResult, commerceV2InvalidPayloadBridgeErrorCode, commerceV2MethodUnsupportedBridgeErrorCode, createBridgeCommerceProvider, createCommerceProviderBridge, createCommerceServiceProvider, } from './commerce-bridge.js';
+export { createStoreCommerceProvider, recoverableErrorCodes, } from './store-commerce-provider.js';
+export { defaultStoreSdkErrorCodeMap, normalizeStoreSdkError, } from './store-sdk.js';
 export { createCapacitorAppEvents, } from './app-events.js';
 export { CapacitorNativeHttpError, createCapacitorNativeJsonTransport, } from './native-http.js';
 export { createCapacitorViewport, } from './viewport.js';
 const externalActivityMethods = new Set([
     'commerce.purchase',
+    'commerce.v2.requestPurchase',
     'ads.showRewarded',
     'ads.showInterstitial',
     'identity.requestUpgrade',
@@ -18,6 +24,12 @@ const externalActivityMethods = new Set([
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Upper bound on how long a `launched` commerce v2 purchase keeps the game
+ * paused when no purchase event for the product arrives (for example a store
+ * sheet dismissed without a callback).
+ */
+export const launchedPurchaseActivityTimeoutMs = 120_000;
 const safeFallbackMethods = new Set([
     'identity.getPlayer',
     'identity.getSession',
@@ -46,6 +58,17 @@ export function createCapacitorPlatformGateway(input) {
     const providers = createCapacitorProviderRegistry(input.providers ?? []);
     const adProvider = providers.byMethod.get('ads.showRewarded')?.adProvider
         ?? providers.byMethod.get('ads.showInterstitial')?.adProvider;
+    const commerceProvider = providers.commerce;
+    // The v2 surface is served through the same request path as every other
+    // provider method, so the bridge envelope, response validation, and external
+    // activity bookkeeping are exercised in process exactly as over a transport.
+    const commerceV2 = commerceProvider === undefined
+        ? undefined
+        : createBridgeCommerceProvider({
+            store: commerceProvider.commerce.store,
+            request: (method, payload) => request(method, payload),
+            subscribe: (listener) => commerceProvider.bridge.subscribe(listener),
+        });
     const lifecycle = createCapacitorAppEvents({
         target: input.target,
         ...(input.app === undefined ? {} : { app: input.app }),
@@ -59,10 +82,14 @@ export function createCapacitorPlatformGateway(input) {
     const viewport = input.viewport ?? createCapacitorViewport({
         ...(input.onAppEventError === undefined ? {} : { onError: input.onAppEventError }),
     });
+    const launchedPurchaseHolds = new Set();
     const gatewayLifecycle = {
         ...lifecycle,
         async dispose() {
             try {
+                for (const finish of [...launchedPurchaseHolds]) {
+                    finish();
+                }
                 await lifecycle.dispose?.();
             }
             finally {
@@ -76,6 +103,7 @@ export function createCapacitorPlatformGateway(input) {
         const releaseExternalActivity = externalActivityMethods.has(method)
             ? lifecycle.beginExternalActivity?.()
             : undefined;
+        let holdActivity = false;
         try {
             const provider = leaderboardRoute === 'remote'
                 && (method === 'leaderboard.submitScore' || method === 'leaderboard.open')
@@ -98,7 +126,17 @@ export function createCapacitorPlatformGateway(input) {
                 }
                 try {
                     await providers.assertMethodReady(method, payload, productType);
-                    return await sendRequest(method, payload, provider);
+                    const data = await sendRequest(method, payload, provider);
+                    if (releaseExternalActivity !== undefined
+                        && method === 'commerce.v2.requestPurchase'
+                        && isRecord(data) && data.outcome === 'launched') {
+                        // The store UI is still open: stay paused until this product's
+                        // purchase event arrives or the safety timeout ends. The v1 path
+                        // has no event to wait for and releases when its request returns.
+                        holdActivity = true;
+                        holdLaunchedPurchaseActivity(releaseExternalActivity, isRecord(payload) ? payload.logicalId : undefined);
+                    }
+                    return data;
                 }
                 catch (error) {
                     // Only non-mutating guest/status queries may degrade. A stale readiness
@@ -112,7 +150,53 @@ export function createCapacitorPlatformGateway(input) {
             return await sendRequest(method, payload, undefined);
         }
         finally {
-            releaseExternalActivity?.();
+            if (!holdActivity) {
+                releaseExternalActivity?.();
+            }
+        }
+    }
+    /**
+     * Keeps the external activity of a `launched` purchase open until the
+     * provider reports that product (`purchaseUpdated` or `purchaseError`, or an
+     * event without a logical id), the safety timeout ends, or the gateway is
+     * disposed. Every path releases exactly once.
+     */
+    function holdLaunchedPurchaseActivity(release, logicalId) {
+        let done = false;
+        let unsubscribe;
+        const finish = () => {
+            if (done) {
+                return;
+            }
+            done = true;
+            launchedPurchaseHolds.delete(finish);
+            clearTimeout(timer);
+            unsubscribe?.();
+            release();
+        };
+        launchedPurchaseHolds.add(finish);
+        const timer = setTimeout(finish, launchedPurchaseActivityTimeoutMs);
+        if (commerceProvider === undefined) {
+            return;
+        }
+        const subscription = commerceProvider.bridge.subscribe(({ event }) => {
+            if (event.type === 'subscriptionUpdated') {
+                return;
+            }
+            const eventLogicalId = event.type === 'purchaseUpdated'
+                ? event.purchase.logicalId
+                : event.logicalId;
+            if (eventLogicalId === undefined || typeof logicalId !== 'string'
+                || eventLogicalId === logicalId) {
+                finish();
+            }
+        });
+        // A buffered event may have finished the hold while subscribing.
+        if (done) {
+            subscription();
+        }
+        else {
+            unsubscribe = subscription;
         }
     }
     async function sendRequest(method, payload, provider) {
@@ -161,22 +245,28 @@ export function createCapacitorPlatformGateway(input) {
         target: input.target,
         async getCapabilities() {
             const base = await request('runtime.getCapabilities', {});
-            const states = await providers.getAvailability();
+            // One bounded registry read serves the feature states and the commerce
+            // block, so a stalled or invalid provider degrades the snapshot instead
+            // of rejecting it, and the boolean flags always follow the block.
+            const { availability: states, commerce } = await providers.getCapabilitySnapshot();
             const rewardedAds = states.rewardedAds === 'available';
             const interstitialAds = states.interstitialAds === 'available';
             const bannerAds = states.bannerAds === 'available';
+            const legacy = commerce === undefined ? undefined : deriveLegacyCommerceCapabilities(commerce);
             return {
                 ...base,
-                nativeIap: states.nativeIap === 'available',
-                subscriptionIap: states.subscriptionIap === 'available',
+                nativeIap: legacy?.nativeIap ?? states.nativeIap === 'available',
+                subscriptionIap: legacy?.subscriptionIap ?? states.subscriptionIap === 'available',
                 nativeAds: rewardedAds || interstitialAds || bannerAds,
                 rewardedAds,
                 interstitialAds,
                 bannerAds,
                 nativeLeaderboard: states.nativeLeaderboard === 'available',
                 providerAvailability: states,
+                ...(commerce === undefined ? {} : { commerce }),
             };
         },
+        ...(commerceV2 === undefined ? {} : { commerceV2 }),
         identity: {
             getPlayer: () => request('identity.getPlayer', {}),
             getSession: () => request('identity.getSession', {}),