@mpgd/adapter-capacitor 0.16.3 → 0.17.0

package/README.md

@@ -133,6 +133,47 @@ 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.
 
+`purchaseGate` is an optional sales switch for new purchases, separate from
+the account binding (and from StoreKit's `appAccountToken`). It is asked once
+per `requestPurchase`, after the product, availability, and kind checks and
+before `accountBinding`, with `{ store, logicalId, storeSku, kind, source }`,
+and answers `{ allowed: true }` or `{ allowed: false, storeCode?, message?,
+retryable? }`. A refusal never opens the store UI and is answered as data:
+`{ outcome: 'failed', error: { code: 'ITEM_UNAVAILABLE', storeCode:
+'PURCHASES_PAUSED' } }` (or the gate's own `storeCode`), `retryable` false
+unless the gate says otherwise. A gate that could not answer refuses too,
+with `PURCHASE_GATE_FAILED` and always retryable, whether it threw, returned
+something malformed, or did not answer within `purchaseGateTimeoutMs` (three
+seconds): the sales flag is unknown rather than closed. An answer that
+arrives after the timeout is ignored and never opens the store. A thrown
+`CommerceError` keeps its own code, except a code that claims a launched or
+cancelled sheet (`OUTCOME_UNKNOWN`, `ALREADY_OWNED`, `USER_CANCELLED`), which
+becomes `PURCHASE_GATE_FAILED` because nothing was launched. The reconciler
+journals a refused attempt as terminal `failed` even when it is retryable:
+only trusted presentation facts (`not-started`) keep a key reusable, and the
+Capacitor bridge does not carry them yet, so a later try uses a new
+idempotency key. The store provider deliberately exposes no `presentation`
+that could only ever say `not-started`, because the game runtime's purchase
+coordinator would take it as a closure source and quarantine the game after
+every launched purchase. The gate runs while the gateway already holds the
+purchase's external activity (the game is paused, with no sheet shown), so it
+should answer from a flag the game already holds rather than a slow network
+call; the timeout bounds that pause. Recovery, restore, finishing, events, `fetchProducts`, and
+`getAvailablePurchases` never
+ask the gate, so purchases already paid for keep reconciling while new sales
+are refused. A failed or missing account binding is a `failed` result too,
+not a throw: a thrown `CommerceError` keeps its code (with the same exception
+for launched or cancelled codes), and anything else is
+`ACCOUNT_BINDING_REQUIRED` with `ACCOUNT_BINDING_LOOKUP_FAILED`, retryable.
+Over the bridge a thrown error keeps only `code`, `message`, and
+`retryable`, while a result keeps `storeCode`, so the game can tell
+`PURCHASES_PAUSED` from `PLAY_BILLING_ACCOUNT_LOOKUP_FAILED`. The gate is not
+reflected in `getCapabilities()`: `availability` describes the store and
+gates the reconciler (a paused gate there would read as `STORE_UNAVAILABLE`
+and lose the reason), and a capability read stays free of server round trips.
+A shop hides its buy buttons from the same server flag it hands the gate,
+for example the sales flag of its account binding response.
+
 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`,

package/dist/commerce-bridge.d.ts

@@ -45,6 +45,12 @@ export interface CreateBridgeCommerceProviderInput {
   /** Sends one validated bridge request; the gateway's `request` fits. */
   readonly request: <TData>(method: BridgeCommerceV2Method, payload: unknown) => Promise<TData>;
   readonly subscribe: (listener: (event: BridgeCommerceEvent) => void) => () => void;
+  /**
+  * The bridge host accepts `FinishTransactionInput.retry` (it is built on the
+  * same contract and its provider declares `acceptsFinishRetry`). Absent, the
+  * provider does not declare it and callers never send `retry`.
+  */
+  readonly acceptsFinishRetry?: boolean;
 }
 /**
 * `CommerceProvider` over a bridge that serves the `commerce.v2.*` methods and

package/dist/commerce-bridge.js

@@ -186,6 +186,7 @@ export function createBridgeCommerceProvider(input) {
     };
     return {
         store: input.store,
+        ...(input.acceptsFinishRetry === true ? { acceptsFinishRetry: true } : {}),
         async getCapabilities() {
             return (await send('commerce.v2.getCapabilities', { protocol: commerceProtocol }))
                 .capabilities;

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { type CapacitorServiceProvider, type NativeBridge } from './providers.js
 export { capacitorCrashlyticsPluginName, capacitorCrashReportingProvider, createCapacitorCrashReporter, createLocalCrashCollectionPreferenceStore, type CrashCollectionPreferenceStore, type CapacitorCrashlyticsPlugin, type CapacitorCrashReporterOptions, type CapacitorCrashReportingOptions, } from './crash-reporting.js';
 export { createCapacitorProviderRegistry, createDegradedCommerceCapabilities, createDegradedNotificationCapabilities, type CapacitorCommerceServiceProvider, type CapacitorNotificationServiceProvider, type CapacitorNotificationsV2Service, type CapacitorProviderCapabilitySnapshot, type CapacitorProviderRegistry, type CapacitorServiceProvider, type NativeBridge, } from './providers.js';
 export { assertCommerceBridgeResult, commerceV2InvalidPayloadBridgeErrorCode, commerceV2MethodUnsupportedBridgeErrorCode, createBridgeCommerceProvider, createCommerceProviderBridge, createCommerceServiceProvider, 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 { accountBindingLookupFailedStoreCode, createStoreCommerceProvider, purchaseGateFailedStoreCode, purchaseGateTimeoutMs, purchasesPausedStoreCode, recoverableErrorCodes, type CreateStoreCommerceProviderInput, type StoreCommerceCapabilityOverrides, type StoreCommerceProductMapping, type StoreCommerceProvider, type StorePurchaseGate, type StorePurchaseGateDecision, type StorePurchaseGateRequest, } 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';

package/dist/index.js

@@ -12,7 +12,7 @@ import { createCapacitorViewport } from './viewport.js';
 export { capacitorCrashlyticsPluginName, capacitorCrashReportingProvider, createCapacitorCrashReporter, createLocalCrashCollectionPreferenceStore, } from './crash-reporting.js';
 export { createCapacitorProviderRegistry, createDegradedCommerceCapabilities, createDegradedNotificationCapabilities, } from './providers.js';
 export { assertCommerceBridgeResult, commerceV2InvalidPayloadBridgeErrorCode, commerceV2MethodUnsupportedBridgeErrorCode, createBridgeCommerceProvider, createCommerceProviderBridge, createCommerceServiceProvider, } from './commerce-bridge.js';
-export { createStoreCommerceProvider, recoverableErrorCodes, } from './store-commerce-provider.js';
+export { accountBindingLookupFailedStoreCode, createStoreCommerceProvider, purchaseGateFailedStoreCode, purchaseGateTimeoutMs, purchasesPausedStoreCode, 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';
@@ -63,6 +63,8 @@ export function createCapacitorPlatformGateway(input) {
         ? undefined
         : createBridgeCommerceProvider({
             store: commerceProvider.commerce.store,
+            // The host below is this package's, on the same contract.
+            acceptsFinishRetry: commerceProvider.commerce.acceptsFinishRetry === true,
             request: (method, payload) => request(method, payload),
             // The provider's channel (`NativeBridge`) may carry other protocols.
             // Only an envelope that names another protocol is dropped; anything

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

@@ -1,5 +1,5 @@
 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 CommerceAuthorityCapabilities, type CommerceCatalogCapabilities, type CommerceErrorCode, type CommerceLifecycleCapabilities, type CommerceLogicalProductId, type CommerceProvider, type CommercePurchaseCapabilities, type PurchaseKind, type PurchaseSource, 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 {
@@ -15,6 +15,41 @@ export interface StoreCommerceCapabilityOverrides {
   readonly catalog?: Partial<CommerceCatalogCapabilities>;
   readonly lifecycle?: Partial<CommerceLifecycleCapabilities>;
 }
+/** What a purchase gate is asked about: one new purchase, before any store UI opens. */
+export interface StorePurchaseGateRequest {
+  readonly store: StoreId;
+  readonly logicalId: CommerceLogicalProductId;
+  readonly storeSku: string;
+  readonly kind: PurchaseKind;
+  readonly source: PurchaseSource;
+}
+/**
+* A purchase gate's answer. A refusal becomes a `failed` purchase result with
+* `ITEM_UNAVAILABLE` and `storeCode` (default `PURCHASES_PAUSED`), returned as
+* data so the reason survives the bridge; `retryable` defaults to false.
+*/
+export type StorePurchaseGateDecision = {
+  readonly allowed: true;
+} | {
+  readonly allowed: false;
+  readonly storeCode?: string;
+  readonly message?: string;
+  readonly retryable?: boolean;
+};
+/**
+* The game's sales switch: asked before a NEW purchase opens the store UI,
+* after the product, availability, and kind checks and before the account
+* binding. Recovery, restore, finishing, events, and `getAvailablePurchases`
+* never consult it, so purchases already paid for keep reconciling while new
+* sales are refused. A gate that throws refuses the purchase (fail closed).
+*/
+export type StorePurchaseGate = (request: StorePurchaseGateRequest) => StorePurchaseGateDecision | Promise<StorePurchaseGateDecision>;
+/** `storeCode` of a purchase the gate refused without naming its own. */
+export declare const purchasesPausedStoreCode: 'PURCHASES_PAUSED';
+/** `storeCode` of a purchase refused because the gate threw or answered nonsense. */
+export declare const purchaseGateFailedStoreCode: 'PURCHASE_GATE_FAILED';
+/** `storeCode` of a purchase refused because the account binding lookup threw. */
+export declare const accountBindingLookupFailedStoreCode: 'ACCOUNT_BINDING_LOOKUP_FAILED';
 export interface CreateStoreCommerceProviderInput {
   readonly sdk: StoreSdk;
   /** Defaults to `sdk.store`. */
@@ -27,8 +62,15 @@ export interface CreateStoreCommerceProviderInput {
   * 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. */
+  /**
+  * Resolves the player's store account binding before a purchase opens. A
+  * failure (thrown, or no binding while `authority.accountBinding` is
+  * `required`) is answered as a `failed` purchase result, not thrown, so its
+  * `storeCode` survives the bridge.
+  */
   readonly accountBinding?: () => Promise<StorePurchaseAccountBinding | undefined>;
+  /** Optional sales switch for new purchases; see `StorePurchaseGate`. */
+  readonly purchaseGate?: StorePurchaseGate;
   readonly capabilities?: StoreCommerceCapabilityOverrides;
   readonly authority: CommerceAuthorityCapabilities;
   /** Per-store error codes merged over `defaultStoreSdkErrorCodeMap`. */
@@ -39,6 +81,13 @@ export interface StoreCommerceProvider extends CommerceProvider {
   dispose(): void;
 }
 /**
+* Upper bound on one purchase gate answer. The gate runs while the gateway
+* holds the purchase's external activity, so a gate that never settles would
+* keep the game paused; past this bound the purchase is refused
+* (`PURCHASE_GATE_FAILED`, retryable) and a late answer is ignored.
+*/
+export declare const purchaseGateTimeoutMs = 3000;
+/**
 * `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

package/dist/store-commerce-provider.js

@@ -1,6 +1,19 @@
 import { assertFinishTransactionInput, assertFinishTransactionResult, assertRequestPurchaseSupported, assertStoreProduct, assertStorePurchase, CommerceError, createCommerceEventBuffer, } from '@mpgd/platform/commerce';
 import { defaultStoreSdkErrorCodeMap, normalizeStoreSdkError, } from './store-sdk.js';
+/** `storeCode` of a purchase the gate refused without naming its own. */
+export const purchasesPausedStoreCode = 'PURCHASES_PAUSED';
+/** `storeCode` of a purchase refused because the gate threw or answered nonsense. */
+export const purchaseGateFailedStoreCode = 'PURCHASE_GATE_FAILED';
+/** `storeCode` of a purchase refused because the account binding lookup threw. */
+export const accountBindingLookupFailedStoreCode = 'ACCOUNT_BINDING_LOOKUP_FAILED';
 const availabilityTimeoutMs = 3_000;
+/**
+ * Upper bound on one purchase gate answer. The gate runs while the gateway
+ * holds the purchase's external activity, so a gate that never settles would
+ * keep the game paused; past this bound the purchase is refused
+ * (`PURCHASE_GATE_FAILED`, retryable) and a late answer is ignored.
+ */
+export const purchaseGateTimeoutMs = 3_000;
 const availabilitySet = new Set([
     'unsupported',
     'configuration-required',
@@ -176,6 +189,8 @@ export function createStoreCommerceProvider(input) {
     const restorePurchases = sdk.restorePurchases;
     const provider = {
         store,
+        // `retry` is forwarded to the SDK below.
+        ...(finishTransaction === undefined ? {} : { acceptsFinishRetry: true }),
         getCapabilities,
         async fetchProducts(request = {}) {
             const type = request.type ?? 'all';
@@ -245,11 +260,34 @@ export function createStoreCommerceProvider(input) {
             const capabilities = await getCapabilities();
             assertAvailable(capabilities.availability, store);
             assertRequestPurchaseSupported(capabilities, request, mapping.kind);
-            const accountBinding = await input.accountBinding?.();
-            if (input.authority.accountBinding === 'required' && accountBinding === undefined) {
-                throw new CommerceError('ACCOUNT_BINDING_REQUIRED', {
-                    message: `Store ${store} requires an account binding before a purchase.`,
+            // Pre-launch refusals below are data, not throws: a `failed` result
+            // keeps its `storeCode` across the bridge, a thrown error does not.
+            if (input.purchaseGate !== undefined) {
+                const refusal = await askPurchaseGate(input.purchaseGate, {
+                    store,
+                    logicalId: mapping.logicalId,
+                    storeSku: mapping.storeSku,
+                    kind: mapping.kind,
+                    source: request.source,
                 });
+                if (refusal !== undefined) {
+                    return { outcome: 'failed', error: refusal };
+                }
+            }
+            let accountBinding;
+            try {
+                accountBinding = await input.accountBinding?.();
+            }
+            catch (error) {
+                return { outcome: 'failed', error: accountBindingFailure(error, store) };
+            }
+            if (input.authority.accountBinding === 'required' && accountBinding === undefined) {
+                return {
+                    outcome: 'failed',
+                    error: new CommerceError('ACCOUNT_BINDING_REQUIRED', {
+                        message: `Store ${store} requires an account binding before a purchase.`,
+                    }).toCommerceErrorInfo(),
+                };
             }
             const offerId = request.offerId ?? mapping.offerId;
             let result;
@@ -322,6 +360,7 @@ export function createStoreCommerceProvider(input) {
                         transactionId: finish.transactionId,
                         isConsumable: finish.isConsumable,
                         ledgerEntryId: finish.ledgerEntryId,
+                        ...(finish.retry === true ? { retry: true } : {}),
                     });
                 }
                 catch (error) {
@@ -387,6 +426,88 @@ function defaultEvidencePayload(purchase) {
             : { originalTransactionId: purchase.originalTransactionId }),
     };
 }
+/**
+ * Codes a pre-launch hook (the purchase gate or the account binding) must not
+ * report: they claim a store sheet was shown or may hold a purchase, and
+ * nothing was launched. A hook that throws one is reported under the hook's
+ * own refusal code instead.
+ */
+function misleadsBeforeLaunch(code) {
+    return recoverableErrorCodes.has(code) || code === 'USER_CANCELLED';
+}
+/**
+ * Asks the gate about one new purchase, bounded by `purchaseGateTimeoutMs`;
+ * undefined means allowed. A refusal
+ * (`allowed: false`) is the gate's definitive answer: `PURCHASES_PAUSED` or
+ * its own code, retryable only when it says so. A gate that could not answer
+ * (it threw, timed out, or returned anything malformed) is `PURCHASE_GATE_FAILED`, and
+ * always retryable: the sales flag is unknown, not closed, so asking again
+ * may succeed. A thrown `CommerceError` keeps its code unless the code
+ * claims a launched or cancelled sheet.
+ */
+async function askPurchaseGate(gate, request) {
+    const gateFailed = (message, cause) => new CommerceError('ITEM_UNAVAILABLE', {
+        message,
+        storeCode: purchaseGateFailedStoreCode,
+        retryable: true,
+        ...(cause === undefined ? {} : { cause }),
+    }).toCommerceErrorInfo();
+    let decision;
+    let timer;
+    try {
+        decision = await Promise.race([
+            Promise.resolve().then(() => gate(request)),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`The purchase gate did not answer within ${purchaseGateTimeoutMs} ms.`)), purchaseGateTimeoutMs);
+            }),
+        ]);
+    }
+    catch (error) {
+        if (error instanceof CommerceError && !misleadsBeforeLaunch(error.code)) {
+            return error.toCommerceErrorInfo();
+        }
+        return gateFailed(`The purchase gate of ${request.store} failed; ${request.logicalId} is not sold now.`, error);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+    if (isRecord(decision) && decision.allowed === true) {
+        return undefined;
+    }
+    if (!isRecord(decision) || decision.allowed !== false) {
+        return gateFailed(`The purchase gate of ${request.store} returned an invalid decision.`);
+    }
+    const storeCode = typeof decision.storeCode === 'string' && decision.storeCode.length > 0
+        ? decision.storeCode
+        : purchasesPausedStoreCode;
+    return new CommerceError('ITEM_UNAVAILABLE', {
+        message: typeof decision.message === 'string' && decision.message.length > 0
+            ? decision.message
+            : `New purchases of ${request.logicalId} are paused.`,
+        storeCode,
+        retryable: decision.retryable === true,
+    }).toCommerceErrorInfo();
+}
+/**
+ * A failed account binding lookup. A `CommerceError` keeps its code (a store
+ * provider names its own lookup failure) unless the code claims a launched or
+ * cancelled sheet; anything else is `ACCOUNT_BINDING_REQUIRED` with
+ * `ACCOUNT_BINDING_LOOKUP_FAILED`, retryable, so every store reports the
+ * same reason.
+ */
+function accountBindingFailure(error, store) {
+    if (error instanceof CommerceError && !misleadsBeforeLaunch(error.code)) {
+        return error.toCommerceErrorInfo();
+    }
+    return new CommerceError('ACCOUNT_BINDING_REQUIRED', {
+        message: `Store ${store} could not resolve the account binding.`,
+        storeCode: accountBindingLookupFailedStoreCode,
+        retryable: true,
+        cause: error,
+    }).toCommerceErrorInfo();
+}
 function assertAvailable(availability, store) {
     switch (availability) {
         case 'available':

package/dist/store-sdk.d.ts

@@ -91,6 +91,8 @@ export interface StoreSdkPurchase {
 export interface StoreSdkFinishTransactionInput {
   readonly transactionId: string;
   readonly isConsumable: boolean;
+  /** `FinishTransactionInput.retry`: an earlier finish of this purchase was asked for. */
+  readonly retry?: boolean;
   /** The ledger entry that authorized the finish; a plugin may record it. */
   readonly ledgerEntryId: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-capacitor",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "description": "Capacitor platform adapter for mpgd Android and iOS shells.",
   "license": "MIT",
   "repository": {
@@ -51,11 +51,11 @@
   ],
   "dependencies": {
     "@capacitor/app": "8.1.1",
-    "@mpgd/capacitor-game-services": "0.9.3",
-    "@mpgd/platform": "0.32.0",
-    "@mpgd/game-services": "0.30.5",
-    "@mpgd/bridge": "0.16.4",
-    "@mpgd/target-config": "0.24.3"
+    "@mpgd/capacitor-game-services": "0.9.4",
+    "@mpgd/game-services": "0.31.0",
+    "@mpgd/platform": "0.33.0",
+    "@mpgd/bridge": "0.17.0",
+    "@mpgd/target-config": "0.24.4"
   },
   "peerDependencies": {
     "@capacitor-community/admob": "^8.1.0",
@@ -89,10 +89,10 @@
     "@capacitor/core": "8.5.2",
     "@capacitor/local-notifications": "8.3.1",
     "@capawesome/capacitor-app-review": "8.1.0",
-    "ttsc": "0.32.1",
+    "ttsc": "0.34.2",
     "typescript": "7.0.2",
     "vitest": "^4.0.0",
-    "@mpgd/game-runtime": "0.8.9"
+    "@mpgd/game-runtime": "0.8.10"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",