@mpgd/adapter-capacitor 0.7.5 → 0.9.0

package/README.md

@@ -64,17 +64,128 @@ 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
 
-For an iOS game backend, install the optional
-`@apple/app-store-server-library@3.1.0` peer and import
-`createAppleSignedTransactionVerifier` from
-`@mpgd/adapter-capacitor/app-store-server`. Supply DER-encoded Apple root
-certificates from the [Apple PKI](https://www.apple.com/certificateauthority/),
-the game's bundle ID, environment, and production App Apple ID. Use the
-result as `signedTransactionVerifier` in
-`createAppStoreGameServicesEvidenceVerifier`. Keep App Store API credentials,
-trust roots, and this verifier on the backend, not in the Capacitor game.
+The server-side verifier moved to `@mpgd/game-services/app-store-server`
+(see the [game-services README](../../packages/game-services/README.md)):
+install the optional `@apple/app-store-server-library@3.1.0` peer next to
+`@mpgd/game-services` and import `createAppleSignedTransactionVerifier` from
+there. `@mpgd/adapter-capacitor/app-store-server` is deprecated: it re-exports
+the same function and options type for one release and is removed in the next
+major version. Supply DER-encoded Apple root certificates from the
+[Apple PKI](https://www.apple.com/certificateauthority/), the game's bundle
+ID, environment, and production App Apple ID. Use the result as
+`signedTransactionVerifier` in `createAppStoreGameServicesEvidenceVerifier`.
+Keep App Store API credentials, trust roots, and this verifier on the backend,
+not in the Capacitor game; the adapter itself no longer peers on Apple's
+library.
 
 The server fetches the transaction from Apple's API, verifies its JWS, checks
 the product, bundle, environment, account token and transaction ID, then

package/dist/app-store-server.d.ts

@@ -1,12 +1,12 @@
-import { type AppStoreEnvironment, type AppStoreSignedTransactionVerifier } from '@mpgd/game-services/app-store-verifier';
-export interface CreateAppleSignedTransactionVerifierOptions {
-  /** DER-encoded Apple root certificates, supplied by the server operator. */
-  readonly rootCertificates: readonly Uint8Array[];
-  readonly environment: AppStoreEnvironment;
-  readonly bundleId: string;
-  /** Required by Apple's verifier in production. */
-  readonly appAppleId?: number;
-  readonly enableOnlineChecks?: boolean;
-}
-/** Verify the App Store JWS before exposing any decoded purchase fields. */
-export declare function createAppleSignedTransactionVerifier(options: CreateAppleSignedTransactionVerifierOptions): AppStoreSignedTransactionVerifier;
+/**
+* @deprecated Moved to `@mpgd/game-services/app-store-server` in A4 of the
+* commerce v2 plan: server-side App Store verification does not belong in the
+* client adapter. This subpath re-exports the same symbols for one release and
+* will be removed in the next major version. Install
+* `@apple/app-store-server-library` next to `@mpgd/game-services`.
+*/
+import { createAppleSignedTransactionVerifier as createAppleSignedTransactionVerifierFromGameServices, type CreateAppleSignedTransactionVerifierOptions as GameServicesAppleVerifierOptions } from '@mpgd/game-services/app-store-server';
+/** @deprecated Import `createAppleSignedTransactionVerifier` from `@mpgd/game-services/app-store-server`. */
+export declare const createAppleSignedTransactionVerifier: typeof createAppleSignedTransactionVerifierFromGameServices;
+/** @deprecated Import `CreateAppleSignedTransactionVerifierOptions` from `@mpgd/game-services/app-store-server`. */
+export type CreateAppleSignedTransactionVerifierOptions = GameServicesAppleVerifierOptions;

package/dist/app-store-server.js

@@ -1,119 +1,10 @@
-import { Environment, SignedDataVerifier, VerificationException, VerificationStatus, } from '@apple/app-store-server-library';
-import { AppStoreDependencyUnavailableError, } from '@mpgd/game-services/app-store-verifier';
-/** Verify the App Store JWS before exposing any decoded purchase fields. */
-export function createAppleSignedTransactionVerifier(options) {
-    if (!Array.isArray(options.rootCertificates)
-        || options.rootCertificates.length === 0
-        || options.rootCertificates.some((certificate) => !(certificate instanceof Uint8Array)
-            || certificate.length === 0)) {
-        throw new TypeError('Apple root certificates are required.');
-    }
-    if (options.environment !== 'Production' && options.environment !== 'Sandbox') {
-        throw new TypeError('App Store environment must be Production or Sandbox.');
-    }
-    if (options.bundleId.trim() === '') {
-        throw new TypeError('App Store bundle ID is required.');
-    }
-    if (options.environment === 'Production'
-        && (!Number.isSafeInteger(options.appAppleId) || (options.appAppleId ?? 0) <= 0)) {
-        throw new TypeError('Production App Store verification requires appAppleId.');
-    }
-    if (options.environment === 'Production' && options.enableOnlineChecks === false) {
-        throw new TypeError('Production App Store verification requires online certificate checks.');
-    }
-    const verifier = new SignedDataVerifier(options.rootCertificates.map((certificate) => Buffer.from(certificate)), options.enableOnlineChecks ?? true, options.environment === 'Production' ? Environment.PRODUCTION : Environment.SANDBOX, options.bundleId, options.appAppleId);
-    return {
-        async verifyAndDecode(input) {
-            if (input.environment !== options.environment || input.bundleId !== options.bundleId) {
-                return { status: 'rejected', reason: 'APP_STORE_VERIFIER_SCOPE_MISMATCH' };
-            }
-            if (typeof input.signedTransaction !== 'string'
-                || input.signedTransaction.length === 0
-                || input.signedTransaction.length > 512 * 1024) {
-                return { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_INVALID' };
-            }
-            input.signal.throwIfAborted();
-            let decoded;
-            try {
-                decoded = await waitForVerification(verifier.verifyAndDecodeTransaction(input.signedTransaction), input.signal);
-                input.signal.throwIfAborted();
-            }
-            catch (error) {
-                if (input.signal.aborted) {
-                    throw input.signal.reason;
-                }
-                if (error instanceof VerificationException) {
-                    if (error.status === VerificationStatus.RETRYABLE_VERIFICATION_FAILURE) {
-                        throw new AppStoreDependencyUnavailableError('Apple signature checks are temporarily unavailable.', error);
-                    }
-                    return { status: 'rejected', reason: 'APP_STORE_SIGNATURE_INVALID' };
-                }
-                // Only Apple's explicit retryable status is a transient dependency
-                // failure. Unexpected adapter/library faults must reach the caller.
-                throw error;
-            }
-            const payload = decodeOneTimeTransaction(decoded);
-            return payload === undefined
-                ? { status: 'rejected', reason: 'APP_STORE_SIGNED_TRANSACTION_INVALID' }
-                : { status: 'verified', payload };
-        },
-    };
-}
-async function waitForVerification(operation, signal) {
-    signal.throwIfAborted();
-    let onAbort;
-    const aborted = new Promise((_resolve, reject) => {
-        onAbort = () => reject(signal.reason ?? new Error('Verification was aborted.'));
-        signal.addEventListener('abort', onAbort, { once: true });
-        if (signal.aborted) {
-            onAbort();
-        }
-    });
-    try {
-        return await Promise.race([operation, aborted]);
-    }
-    finally {
-        if (onAbort !== undefined) {
-            signal.removeEventListener('abort', onAbort);
-        }
-    }
-}
-function decodeOneTimeTransaction(decoded) {
-    if (!nonEmpty(decoded.transactionId)
-        || !nonEmpty(decoded.originalTransactionId)
-        || !nonEmpty(decoded.bundleId)
-        || !nonEmpty(decoded.productId)
-        || !validTimestamp(decoded.purchaseDate)
-        || !validTimestamp(decoded.signedDate)
-        || (decoded.environment !== 'Production' && decoded.environment !== 'Sandbox')
-        || (decoded.type !== 'Consumable' && decoded.type !== 'Non-Consumable')
-        || (decoded.quantity !== undefined
-            && (!Number.isSafeInteger(decoded.quantity) || decoded.quantity <= 0))
-        || (decoded.appAccountToken !== undefined && !nonEmpty(decoded.appAccountToken))
-        || (decoded.revocationDate !== undefined && !validTimestamp(decoded.revocationDate))
-        || (decoded.expiresDate !== undefined && !validTimestamp(decoded.expiresDate))
-        || (decoded.isUpgraded !== undefined && typeof decoded.isUpgraded !== 'boolean')) {
-        return undefined;
-    }
-    return {
-        transactionId: decoded.transactionId,
-        originalTransactionId: decoded.originalTransactionId,
-        bundleId: decoded.bundleId,
-        productId: decoded.productId,
-        purchaseDate: decoded.purchaseDate,
-        signedDate: decoded.signedDate,
-        environment: decoded.environment,
-        type: decoded.type,
-        ...(decoded.quantity === undefined ? {} : { quantity: decoded.quantity }),
-        ...(decoded.appAccountToken === undefined ? {} : { appAccountToken: decoded.appAccountToken }),
-        ...(decoded.revocationDate === undefined ? {} : { revocationDate: decoded.revocationDate }),
-        ...(decoded.expiresDate === undefined ? {} : { expiresDate: decoded.expiresDate }),
-        ...(decoded.isUpgraded === undefined ? {} : { isUpgraded: decoded.isUpgraded }),
-    };
-}
-function nonEmpty(value) {
-    return typeof value === 'string' && value.trim() !== '';
-}
-function validTimestamp(value) {
-    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
-}
+/**
+ * @deprecated Moved to `@mpgd/game-services/app-store-server` in A4 of the
+ * commerce v2 plan: server-side App Store verification does not belong in the
+ * client adapter. This subpath re-exports the same symbols for one release and
+ * will be removed in the next major version. Install
+ * `@apple/app-store-server-library` next to `@mpgd/game-services`.
+ */
+import { createAppleSignedTransactionVerifier as createAppleSignedTransactionVerifierFromGameServices, } from '@mpgd/game-services/app-store-server';
+/** @deprecated Import `createAppleSignedTransactionVerifier` from `@mpgd/game-services/app-store-server`. */
+export const createAppleSignedTransactionVerifier = createAppleSignedTransactionVerifierFromGameServices;

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;