@mpgd/adapter-capacitor 0.8.0 → 0.9.0

package/dist/providers.d.ts

@@ -1,6 +1,7 @@
 import { type BridgeEvent, type BridgeMethod, type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
 import type { AdProvider } from '@mpgd/platform/ads';
-import { type PlatformProviderAvailability, type PlatformProviderFeature, type ProductType } from '@mpgd/platform';
+import { type CommerceCapabilities, type PlatformProviderAvailability, type PlatformProviderFeature, type ProductType } from '@mpgd/platform';
+import { type CommerceProvider } from '@mpgd/platform/commerce';
 export interface NativeBridge {
   request(input: BridgeRequest): Promise<BridgeResponse>;
   /**
@@ -17,17 +18,61 @@ export interface NativeBridge {
 */
 export interface CapacitorServiceProvider {
   readonly id: string;
+  /**
+  * Serves the declared `methods`. For a provider with `commerce`, it also
+  * serves the ten commerce bridge methods and must implement `subscribe`;
+  * `createCommerceServiceProvider` builds one from a `CommerceProvider`.
+  */
   readonly bridge: NativeBridge;
   readonly features: readonly PlatformProviderFeature[];
+  /**
+  * Declared v1 bridge methods. A provider with `commerce` declares no
+  * `commerce.*` method: the four v1 commerce methods and the six
+  * `commerce.v2.*` methods are implied and owned by the v2 provider.
+  */
   readonly methods: readonly BridgeMethod[];
   /** Optional native event surface. The base adapter never imports its SDK. */
   readonly adProvider?: AdProvider;
+  /**
+  * Optional commerce v2 provider (`createStoreCommerceProvider`). Its
+  * `getCapabilities()` is the readiness of the declared `nativeIap` and
+  * `subscriptionIap` features; `getAvailability` covers the other features.
+  */
+  readonly commerce?: CommerceProvider;
   getAvailability(): Promise<Readonly<Partial<Record<PlatformProviderFeature, PlatformProviderAvailability>>>>;
 }
+/** The provider the registry serves commerce v2 from. */
+export interface CapacitorCommerceServiceProvider extends CapacitorServiceProvider {
+  readonly commerce: CommerceProvider;
+  readonly bridge: NativeBridge & Required<Pick<NativeBridge, 'subscribe'>>;
+}
+export interface CapacitorProviderCapabilitySnapshot {
+  readonly availability: Readonly<Record<PlatformProviderFeature, PlatformProviderAvailability>>;
+  /**
+  * Present when a commerce v2 provider is registered: its validated
+  * `getCapabilities()` answer from the same bounded read that produced the
+  * `nativeIap` and `subscriptionIap` states, or a degraded block
+  * (`availability: 'temporarily-unavailable'`, nothing sold) when that read
+  * stalled, failed, or returned a shape the contract rejects.
+  */
+  readonly commerce?: CommerceCapabilities;
+}
 export interface CapacitorProviderRegistry {
   readonly byMethod: ReadonlyMap<BridgeMethod, CapacitorServiceProvider>;
+  /** The provider that serves commerce v2, when one is registered. */
+  readonly commerce?: CapacitorCommerceServiceProvider;
+  /** Feature readiness plus the commerce block, from one bounded read per provider. */
+  getCapabilitySnapshot(): Promise<CapacitorProviderCapabilitySnapshot>;
   assertMethodReady(method: BridgeMethod, payload?: unknown, productType?: ProductType): Promise<void>;
   getAvailability(): Promise<Readonly<Record<PlatformProviderFeature, PlatformProviderAvailability>>>;
 }
 export declare function createCapacitorProviderRegistry(input: readonly CapacitorServiceProvider[]): CapacitorProviderRegistry;
 export declare function assertProviderResponseData(method: BridgeMethod, data: unknown): void;
+/** The commerce block a gateway reports while its provider cannot be read. */
+export declare function createDegradedCommerceCapabilities(): CommerceCapabilities;
+/**
+* Readiness of the commerce features a v2 provider declares, from its own
+* capability declaration: a feature it does not sell is `unsupported`, and a
+* read that failed or stalled is `temporarily-unavailable`.
+*/
+export declare function deriveCommerceFeatureStates(capabilities: CommerceCapabilities | undefined, features: readonly PlatformProviderFeature[]): Partial<Record<PlatformProviderFeature, PlatformProviderAvailability>>;

package/dist/providers.js

@@ -1,6 +1,8 @@
-import { isBridgeCommerceV2Method, } from '@mpgd/bridge';
+import { bridgeCommerceV2Methods, isBridgeCommerceV2Method, } from '@mpgd/bridge';
 import { isAdMobClientRewardEvidence } from '@mpgd/game-services/admob-client-reward';
 import { PlatformOperationError, } from '@mpgd/platform';
+import { createUnsupportedCommerceCapabilities, isCommerceCapabilities, } from '@mpgd/platform/commerce';
+import { assertCommerceBridgeResult } from './commerce-bridge.js';
 const featureMethods = {
     nativeIap: [
         'commerce.getProducts',
@@ -23,6 +25,12 @@ const featureMethods = {
 };
 const providerFeatures = Object.keys(featureMethods);
 const providerMethodSet = new Set(Object.values(featureMethods).flat());
+const commerceFeatures = ['nativeIap', 'subscriptionIap'];
+const v1CommerceMethods = featureMethods.nativeIap;
+const impliedCommerceMethods = [
+    ...v1CommerceMethods,
+    ...bridgeCommerceV2Methods,
+];
 const availabilitySet = new Set([
     'unsupported',
     'configuration-required',
@@ -41,12 +49,14 @@ export function createCapacitorProviderRegistry(input) {
     const byMethod = new Map();
     const byFeature = new Map();
     const ids = new Set();
+    let commerce;
     for (const provider of providers) {
         if (provider.id.trim() === '' || ids.has(provider.id)) {
             throw new Error(`Capacitor provider ID is empty or registered twice: ${provider.id}`);
         }
         ids.add(provider.id);
-        if (provider.features.length === 0 || provider.methods.length === 0) {
+        if (provider.features.length === 0
+            || (provider.methods.length === 0 && provider.commerce === undefined)) {
             throw new Error(`Capacitor provider ${provider.id} must declare features and methods.`);
         }
         const methods = new Set(provider.methods);
@@ -55,24 +65,43 @@ export function createCapacitorProviderRegistry(input) {
         }
         for (const method of methods) {
             if (isBridgeCommerceV2Method(method)) {
-                // v1 providers own the v1 commerce methods only; a v2 provider arrives
-                // with B1 and is registered through its own surface.
+                // A v2 provider is registered through `commerce`; its bridge methods are implied.
                 throw new Error(`Capacitor provider ${provider.id} cannot declare commerce v2 method ${method}; `
-                    + 'commerce v2 is unavailable through the provider registry.');
+                    + 'register a v2 provider through `commerce` instead, commerce v2 is unavailable as '
+                    + 'a declared method.');
             }
             if (!providerMethodSet.has(method)) {
                 throw new Error(`Capacitor provider ${provider.id} cannot replace base method ${method}.`);
             }
+            if (provider.commerce !== undefined && v1CommerceMethods.includes(method)) {
+                throw new Error(`Capacitor provider ${provider.id} cannot declare both a commerce v2 provider and `
+                    + `v1 method ${method}; the registry serves v1 callers from the v2 provider.`);
+            }
+        }
+        const implied = provider.commerce === undefined ? [] : impliedCommerceMethods;
+        for (const method of [...methods, ...implied]) {
             if (byMethod.has(method)) {
                 throw new Error(`Capacitor bridge method ${method} has multiple providers.`);
             }
         }
+        const owned = new Set([...methods, ...implied]);
+        if (provider.commerce !== undefined) {
+            if (!provider.features.some((feature) => commerceFeatures.includes(feature))) {
+                throw new Error(`Capacitor provider ${provider.id} declares a commerce v2 provider but no commerce feature.`);
+            }
+            if (provider.bridge.subscribe === undefined) {
+                // Without the event surface a purchase that completes after the store
+                // UI closed would never reach the reconciler.
+                throw new Error(`Capacitor provider ${provider.id} declares a commerce v2 provider but its bridge has no `
+                    + 'subscribe; build it with createCommerceServiceProvider.');
+            }
+        }
         for (const feature of provider.features) {
             const required = featureMethods[feature];
             if (required === undefined || byFeature.has(feature)) {
                 throw new Error(`Capacitor feature ${feature} has multiple or invalid providers.`);
             }
-            if (required.some((method) => !methods.has(method))) {
+            if (required.some((method) => !owned.has(method))) {
                 throw new Error(`Capacitor provider ${provider.id} lacks methods for ${feature}.`);
             }
             byFeature.set(feature, provider);
@@ -80,67 +109,80 @@ export function createCapacitorProviderRegistry(input) {
         if ([...methods].some((method) => !provider.features.some((feature) => featureMethods[feature].includes(method)))) {
             throw new Error(`Capacitor provider ${provider.id} declares an unowned method.`);
         }
-        for (const method of methods) {
+        for (const method of owned) {
             byMethod.set(method, provider);
         }
+        if (provider.commerce !== undefined) {
+            // Validated above: the bridge implements `subscribe`.
+            commerce = provider;
+        }
     }
     const readProviderStates = async (provider) => {
-        let reported;
-        let timer;
-        try {
-            reported = await Promise.race([
-                Promise.resolve().then(() => provider.getAvailability()),
-                new Promise((_resolve, reject) => {
-                    timer = setTimeout(() => reject(new Error('Provider availability timed out.')), availabilityTimeoutMs);
-                }),
-            ]);
-            if (!isRecord(reported)) {
-                throw new Error('Invalid provider availability.');
-            }
-        }
-        catch {
-            reported = {};
+        const states = {};
+        const commerceOwned = provider.commerce === undefined
+            ? []
+            : provider.features.filter((feature) => commerceFeatures.includes(feature));
+        const bridged = provider.features.filter((feature) => !commerceOwned.includes(feature));
+        let commerceBlock;
+        if (provider.commerce !== undefined && commerceOwned.length > 0) {
+            commerceBlock = await readCommerceCapabilities(provider.commerce);
+            Object.assign(states, deriveCommerceFeatureStates(commerceBlock, commerceOwned));
         }
-        finally {
-            if (timer !== undefined) {
-                clearTimeout(timer);
+        if (bridged.length > 0) {
+            const reported = await readWithTimeout(Promise.resolve().then(() => provider.getAvailability()));
+            for (const feature of bridged) {
+                const state = isRecord(reported) ? reported[feature] : undefined;
+                states[feature] = availabilitySet.has(state)
+                    ? state
+                    : 'temporarily-unavailable';
             }
         }
-        const states = {};
-        for (const feature of provider.features) {
-            const state = reported[feature];
-            states[feature] = availabilitySet.has(state)
-                ? state
-                : 'temporarily-unavailable';
-        }
-        return states;
+        return { states, ...(commerceBlock === undefined ? {} : { commerce: commerceBlock }) };
     };
-    const getAvailability = async () => {
+    const getCapabilitySnapshot = async () => {
         const states = {};
         for (const feature of providerFeatures) {
             states[feature] = 'unsupported';
         }
+        let commerceBlock;
         const snapshots = await Promise.all(providers.map(readProviderStates));
         for (const snapshot of snapshots) {
-            Object.assign(states, snapshot);
+            Object.assign(states, snapshot.states);
+            commerceBlock = snapshot.commerce ?? commerceBlock;
         }
-        return states;
+        if (commerce !== undefined && commerceBlock === undefined) {
+            // One bounded read serves the feature states and the block, so a stalled,
+            // failed, or invalid provider degrades both the same way.
+            commerceBlock = createDegradedCommerceCapabilities();
+        }
+        return {
+            availability: states,
+            ...(commerceBlock === undefined ? {} : { commerce: commerceBlock }),
+        };
     };
+    const getAvailability = async () => (await getCapabilitySnapshot()).availability;
     return {
         byMethod,
+        ...(commerce === undefined ? {} : { commerce }),
         getAvailability,
+        getCapabilitySnapshot,
         async assertMethodReady(method, payload, productType) {
             const provider = byMethod.get(method);
             if (provider === undefined) {
                 return;
             }
+            if (isBridgeCommerceV2Method(method)) {
+                // The v2 provider reads its own `availability` and fails closed before
+                // any store UI opens; the registry adds no second, stale snapshot.
+                return;
+            }
             if (method === 'ads.unmountBanner') {
                 // Teardown must reach the provider that mounted the banner even after
                 // its serving state becomes unavailable.
                 return;
             }
             // An unrelated provider must not delay a purchase, ad, or identity call.
-            const states = await readProviderStates(provider);
+            const { states } = await readProviderStates(provider);
             let relevant = provider.features.filter((feature) => featureMethods[feature].includes(method));
             if (method === 'commerce.purchase' && relevant.length > 1) {
                 relevant = relevant.filter((feature) => feature === (productType === 'subscription' ? 'subscriptionIap'
@@ -205,6 +247,73 @@ export function assertProviderResponseData(method, data) {
         });
     }
 }
+/**
+ * One bounded, validated capability read. A stalled, throwing, or invalid
+ * provider yields `undefined`; the block is copied so the gateway never hands
+ * out a provider-owned object.
+ */
+async function readCommerceCapabilities(provider) {
+    const reported = await readWithTimeout(Promise.resolve().then(() => provider.getCapabilities()));
+    if (!isCommerceCapabilities(reported)) {
+        return undefined;
+    }
+    return {
+        purchase: { ...reported.purchase },
+        catalog: { ...reported.catalog },
+        lifecycle: { ...reported.lifecycle },
+        authority: { ...reported.authority },
+        availability: reported.availability,
+    };
+}
+/** The commerce block a gateway reports while its provider cannot be read. */
+export function createDegradedCommerceCapabilities() {
+    return { ...createUnsupportedCommerceCapabilities(), availability: 'temporarily-unavailable' };
+}
+async function readWithTimeout(read) {
+    let timer;
+    try {
+        return await Promise.race([
+            read,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error('Provider availability timed out.')), availabilityTimeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Readiness of the commerce features a v2 provider declares, from its own
+ * capability declaration: a feature it does not sell is `unsupported`, and a
+ * read that failed or stalled is `temporarily-unavailable`.
+ */
+export function deriveCommerceFeatureStates(capabilities, features) {
+    const states = {};
+    const availability = capabilities === undefined
+        || !availabilitySet.has(capabilities.availability)
+        ? 'temporarily-unavailable'
+        : capabilities.availability;
+    for (const feature of features) {
+        if (feature === 'nativeIap') {
+            states.nativeIap = capabilities !== undefined
+                && !(capabilities.purchase.consumable || capabilities.purchase.durable)
+                ? 'unsupported'
+                : availability;
+        }
+        else if (feature === 'subscriptionIap') {
+            states.subscriptionIap = capabilities !== undefined && !capabilities.purchase.subscription
+                ? 'unsupported'
+                : availability;
+        }
+    }
+    return states;
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -218,6 +327,15 @@ function isVoidData(value) {
     return value === undefined || value === null || (isRecord(value) && Object.keys(value).length === 0);
 }
 function isValidProviderData(method, value) {
+    if (isBridgeCommerceV2Method(method)) {
+        try {
+            assertCommerceBridgeResult(method, value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     switch (method) {
         case 'commerce.getProducts':
             return Array.isArray(value) && value.every((product) => isRecord(product)

package/dist/store-commerce-provider.d.ts

@@ -0,0 +1,55 @@
+import type { PlatformEvidenceEnvelope } from '@mpgd/platform';
+import { type CommerceAuthorityCapabilities, type CommerceCatalogCapabilities, type CommerceErrorCode, type CommerceLifecycleCapabilities, type CommerceLogicalProductId, type CommerceProvider, type CommercePurchaseCapabilities, type PurchaseKind, type StoreId, type StorePurchaseAccountBinding } from '@mpgd/platform/commerce';
+import { type StoreSdk, type StoreSdkErrorCodeMap, type StoreSdkPurchase } from './store-sdk.js';
+/** One catalog product sold through the store under `storeSku`. */
+export interface StoreCommerceProductMapping {
+  readonly logicalId: CommerceLogicalProductId;
+  readonly storeSku: string;
+  readonly kind: PurchaseKind;
+  /** Default store offer when the request names none. */
+  readonly offerId?: string;
+}
+/** Deep-partial overrides applied over the capabilities composed from the SDK declaration. */
+export interface StoreCommerceCapabilityOverrides {
+  readonly purchase?: Partial<CommercePurchaseCapabilities>;
+  readonly catalog?: Partial<CommerceCatalogCapabilities>;
+  readonly lifecycle?: Partial<CommerceLifecycleCapabilities>;
+}
+export interface CreateStoreCommerceProviderInput {
+  readonly sdk: StoreSdk;
+  /** Defaults to `sdk.store`. */
+  readonly store?: StoreId;
+  readonly products: readonly StoreCommerceProductMapping[];
+  /** Evidence schema the backend registry routes on, for example `google-play.product-purchase.v2`. */
+  readonly evidenceSchema: string;
+  /**
+  * Evidence payload for a purchase. Defaults to the token, transaction id,
+  * and SKU; a store provider replaces it to match its backend verifier.
+  */
+  readonly evidencePayload?: (purchase: StoreSdkPurchase) => PlatformEvidenceEnvelope['payload'];
+  /** Resolves the player's store account binding before a purchase opens. */
+  readonly accountBinding?: () => Promise<StorePurchaseAccountBinding | undefined>;
+  readonly capabilities?: StoreCommerceCapabilityOverrides;
+  readonly authority: CommerceAuthorityCapabilities;
+  /** Per-store error codes merged over `defaultStoreSdkErrorCodeMap`. */
+  readonly mapError?: StoreSdkErrorCodeMap;
+}
+export interface StoreCommerceProvider extends CommerceProvider {
+  /** Detaches the SDK listeners; buffered events are dropped. */
+  dispose(): void;
+}
+/**
+* `CommerceProvider` over an in-process `StoreSdk`. The provider maps logical
+* ids to store SKUs both ways, composes `CommerceCapabilities` from the SDK
+* declaration, builds `StorePurchase` evidence, buffers SDK events until the
+* first subscriber, and normalizes every SDK failure into a `CommerceError`.
+* It never grants and never sets `settlement`; the backend ledger decides.
+*/
+export declare function createStoreCommerceProvider(input: CreateStoreCommerceProviderInput): StoreCommerceProvider;
+/**
+* Codes that mean an unfinished purchase may exist (RFC "Errors": reconcile,
+* never reopen the store UI blindly). The attempt stays `launched` so the
+* reconciler resolves it from `getAvailablePurchases`; a terminal `failed`
+* would exclude it from recovery.
+*/
+export declare const recoverableErrorCodes: ReadonlySet<CommerceErrorCode>;