@mpgd/capacitor-play-billing 0.4.5 → 0.5.0

package/README.md

@@ -105,13 +105,21 @@ recoverable, so the provider answers `launched` and the reconciler resolves
 the attempt from `getAvailablePurchases` without reopening the store UI.
 
 `createCapacitorPlayBillingCommerceProvider({ products, accountBinding,
-plugin?, isAndroid?, store?, mapError? })` composes the provider: evidence
+purchaseGate?, plugin?, isAndroid?, store?, mapError? })` composes the provider: evidence
 schema `google-play.product-purchase.v2` with payload `{ purchaseToken }`,
 which `createGooglePlayProductPurchaseBoundary` verifies; authority
 `{ evidence: 'client-token', accountBinding: 'required' }`; no
 `finishTransaction` and no `restorePurchases`. A thrown `accountBinding`
 lookup is `ACCOUNT_BINDING_REQUIRED` with `PLAY_BILLING_ACCOUNT_LOOKUP_FAILED`
-kept as the store code. `store` defaults to `google-play`; only a conformance
+kept as the store code (a thrown `CommerceError` keeps its own code), answered
+as a `failed` result before the sheet opens. The optional `purchaseGate` is
+the sales switch: it is asked before a new purchase opens the Play sheet,
+never during recovery, and a refusal is `failed` with `ITEM_UNAVAILABLE` and
+`PURCHASES_PAUSED` (see the adapter-capacitor README). With an adapter-capacitor from before
+the gate, which would ignore it, the plugin detects the missing gate support
+and answers every new purchase itself with a `failed` result, `ITEM_UNAVAILABLE` and
+`PURCHASE_GATE_UNSUPPORTED` instead of selling; recovery is unaffected.
+`store` defaults to `google-play`; only a conformance
 harness overrides it, because the derived idempotency key follows the store
 id. `createPlayBillingCommerceCapabilities(availability)` (from
 `src/commerce-profile.ts`, which imports types only and no Capacitor code)

package/dist/commerce-provider.d.ts

@@ -3,6 +3,7 @@ import type { PlatformEvidenceEnvelope } from '@mpgd/platform';
 import { type StoreId, type StorePurchaseAccountBinding } from '@mpgd/platform/commerce';
 import { googlePlayProductPurchaseEvidenceSchema, playBillingCommerceAuthority } from './commerce-profile.js';
 import type { CapacitorPlayBillingPlugin, PlayPurchase } from './definitions.js';
+import { type StorePurchaseGate } from './purchase-gate-support.js';
 export { googlePlayProductPurchaseEvidenceSchema, playBillingCommerceAuthority };
 /** The default registry id of the Play Billing commerce v2 service provider. */
 export declare const playBillingCommerceServiceProviderId: 'google-play-billing';
@@ -20,10 +21,18 @@ export interface CreateCapacitorPlayBillingCommerceProviderInput {
   /**
   * Resolves the player's obfuscated account id (`{ kind:
   * 'obfuscated-account-id', value }`) before a purchase opens. It must agree
-  * with the backend's `resolveObfuscatedAccountId`. A thrown lookup becomes
-  * `ACCOUNT_BINDING_REQUIRED` with `PLAY_BILLING_ACCOUNT_LOOKUP_FAILED` kept.
+  * with the backend's `resolveObfuscatedAccountId`. A thrown `CommerceError`
+  * keeps its code; any other thrown lookup becomes `ACCOUNT_BINDING_REQUIRED`
+  * with `PLAY_BILLING_ACCOUNT_LOOKUP_FAILED` kept. Either is answered as a
+  * `failed` purchase result before the store opens.
   */
   readonly accountBinding: () => Promise<StorePurchaseAccountBinding | undefined> | StorePurchaseAccountBinding | undefined;
+  /**
+  * Optional sales switch, asked before a new purchase opens the Play sheet
+  * and never during recovery; a refusal is `ITEM_UNAVAILABLE` with
+  * `PURCHASES_PAUSED` (see `StorePurchaseGate` in `@mpgd/adapter-capacitor`).
+  */
+  readonly purchaseGate?: StorePurchaseGate;
   /** Defaults to the registered `CapacitorPlayBilling` plugin. */
   readonly plugin?: CapacitorPlayBillingPlugin;
   /** Defaults to `Capacitor.getPlatform() === 'android'`. */

package/dist/commerce-provider.js

@@ -1,6 +1,7 @@
 import { createCommerceServiceProvider, createStoreCommerceProvider, } from '@mpgd/adapter-capacitor';
 import { CommerceError, } from '@mpgd/platform/commerce';
 import { googlePlayProductPurchaseEvidenceSchema, playBillingCommerceAuthority, } from './commerce-profile.js';
+import { refuseNewPurchasesUnlessGated, resolvePurchaseGateSupport, } from './purchase-gate-support.js';
 import { createCapacitorPlayBillingStoreSdk, googlePlayStoreId, playBillingStoreSdkErrorCodeMap, } from './store-sdk.js';
 // The profile constants live in the SDK-free `commerce-profile.ts` so a tools
 // project can read them without loading Capacitor; they stay exported here.
@@ -44,7 +45,8 @@ export function createCapacitorPlayBillingCommerceProvider(input) {
             : { onUnmappedPurchase: input.onUnmappedPurchase }),
     });
     const resolveAccountBinding = input.accountBinding;
-    return createStoreCommerceProvider({
+    const gate = resolvePurchaseGateSupport(input.purchaseGate);
+    return refuseNewPurchasesUnlessGated(createStoreCommerceProvider({
         sdk,
         store: input.store ?? googlePlayStoreId,
         products: input.products,
@@ -55,6 +57,9 @@ export function createCapacitorPlayBillingCommerceProvider(input) {
                 return await resolveAccountBinding();
             }
             catch (error) {
+                if (error instanceof CommerceError) {
+                    throw error;
+                }
                 throw new CommerceError('ACCOUNT_BINDING_REQUIRED', {
                     message: 'Play Billing could not resolve the obfuscated account id.',
                     storeCode: 'PLAY_BILLING_ACCOUNT_LOOKUP_FAILED',
@@ -62,9 +67,10 @@ export function createCapacitorPlayBillingCommerceProvider(input) {
                 });
             }
         },
+        ...(gate.purchaseGate === undefined ? {} : { purchaseGate: gate.purchaseGate }),
         authority: playBillingCommerceAuthority,
         mapError: { ...playBillingStoreSdkErrorCodeMap, ...input.mapError },
-    });
+    }), gate);
 }
 /**
  * Registry entry for `createCapacitorPlatformGateway({ providers })`: the

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export * from './commerce-provider.js';
 export * from './definitions.js';
 export * from './plugin.js';
 export * from './store-sdk.js';
+export { purchaseGateUnsupportedStoreCode, type StorePurchaseGate, type StorePurchaseGateDecision, type StorePurchaseGateRequest, } from './purchase-gate-support.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export * from './commerce-provider.js';
 export * from './definitions.js';
 export * from './plugin.js';
 export * from './store-sdk.js';
+export { purchaseGateUnsupportedStoreCode, } from './purchase-gate-support.js';

package/dist/purchase-gate-support.d.ts

@@ -0,0 +1,50 @@
+import { CommerceError, type CommerceLogicalProductId, type CommerceProvider, type PurchaseKind, type PurchaseSource, type StoreId } from '@mpgd/platform/commerce';
+/** 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; see `StorePurchaseGateDecision` in `@mpgd/adapter-capacitor`. */
+export type StorePurchaseGateDecision = {
+  readonly allowed: true;
+} | {
+  readonly allowed: false;
+  readonly storeCode?: string;
+  readonly message?: string;
+  readonly retryable?: boolean;
+};
+/** The game's sales switch for new purchases; see `StorePurchaseGate` in `@mpgd/adapter-capacitor`. */
+export type StorePurchaseGate = (request: StorePurchaseGateRequest) => StorePurchaseGateDecision | Promise<StorePurchaseGateDecision>;
+/** `storeCode` of every new purchase refused because the adapter cannot run the gate. */
+export declare const purchaseGateUnsupportedStoreCode: 'PURCHASE_GATE_UNSUPPORTED';
+/**
+* Whether the installed `@mpgd/adapter-capacitor` runs `purchaseGate`. An
+* adapter from before the gate ignores the option and would keep selling, so
+* the probe reads an export the gate release added (`purchasesPausedStoreCode`)
+* through the module namespace, where a missing export is `undefined` rather
+* than a link error.
+*/
+export declare function adapterSupportsPurchaseGate(adapterExports?: object): boolean;
+export interface PurchaseGateSupport {
+  /** The gate to hand the adapter, when it runs one. */
+  readonly purchaseGate?: StorePurchaseGate;
+  /**
+  * Set when a gate was given but the adapter cannot run it: the plugin then
+  * answers every new purchase itself (`refuseNewPurchasesUnlessGated`).
+  */
+  readonly refuseNewPurchases: boolean;
+}
+/** Fails closed: a gate the adapter would ignore refuses every new purchase instead. */
+export declare function resolvePurchaseGateSupport(purchaseGate: StorePurchaseGate | undefined, supported?: boolean): PurchaseGateSupport;
+export declare function createPurchaseGateUnsupportedError(): CommerceError;
+/**
+* Refuses every new purchase at the plugin boundary when the adapter cannot
+* run the configured gate, before the adapter's `requestPurchase` (which
+* would open the store) is reached. The refusal is a `failed` result, not a
+* throw, so `PURCHASE_GATE_UNSUPPORTED` survives the bridge whatever the
+* adapter version. Recovery, finishing, restore, and events are untouched.
+*/
+export declare function refuseNewPurchasesUnlessGated<TProvider extends CommerceProvider>(provider: TProvider, support: PurchaseGateSupport): TProvider;

package/dist/purchase-gate-support.js

@@ -0,0 +1,50 @@
+import * as adapterCapacitor from '@mpgd/adapter-capacitor';
+import { CommerceError, } from '@mpgd/platform/commerce';
+/** `storeCode` of every new purchase refused because the adapter cannot run the gate. */
+export const purchaseGateUnsupportedStoreCode = 'PURCHASE_GATE_UNSUPPORTED';
+/**
+ * Whether the installed `@mpgd/adapter-capacitor` runs `purchaseGate`. An
+ * adapter from before the gate ignores the option and would keep selling, so
+ * the probe reads an export the gate release added (`purchasesPausedStoreCode`)
+ * through the module namespace, where a missing export is `undefined` rather
+ * than a link error.
+ */
+export function adapterSupportsPurchaseGate(adapterExports = adapterCapacitor) {
+    return typeof adapterExports.purchasesPausedStoreCode
+        === 'string';
+}
+/** Fails closed: a gate the adapter would ignore refuses every new purchase instead. */
+export function resolvePurchaseGateSupport(purchaseGate, supported = adapterSupportsPurchaseGate()) {
+    if (purchaseGate === undefined) {
+        return { refuseNewPurchases: false };
+    }
+    return supported ? { purchaseGate, refuseNewPurchases: false } : { refuseNewPurchases: true };
+}
+export function createPurchaseGateUnsupportedError() {
+    return new CommerceError('ITEM_UNAVAILABLE', {
+        message: 'A purchase gate is configured but @mpgd/adapter-capacitor is too old to run it; '
+            + 'new purchases are refused until the adapter is upgraded.',
+        storeCode: purchaseGateUnsupportedStoreCode,
+        retryable: false,
+    });
+}
+/**
+ * Refuses every new purchase at the plugin boundary when the adapter cannot
+ * run the configured gate, before the adapter's `requestPurchase` (which
+ * would open the store) is reached. The refusal is a `failed` result, not a
+ * throw, so `PURCHASE_GATE_UNSUPPORTED` survives the bridge whatever the
+ * adapter version. Recovery, finishing, restore, and events are untouched.
+ */
+export function refuseNewPurchasesUnlessGated(provider, support) {
+    if (!support.refuseNewPurchases) {
+        return provider;
+    }
+    return Object.assign(provider, {
+        async requestPurchase() {
+            return {
+                outcome: 'failed',
+                error: createPurchaseGateUnsupportedError().toCommerceErrorInfo(),
+            };
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/capacitor-play-billing",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Opt-in Android Google Play Billing purchase collector for mpgd Capacitor games.",
   "license": "MIT",
   "repository": {
@@ -38,20 +38,20 @@
   ],
   "peerDependencies": {
     "@capacitor/core": "^8.5.1",
-    "@mpgd/adapter-capacitor": "^0.16.0",
-    "@mpgd/bridge": "^0.16.0",
-    "@mpgd/platform": "^0.32.0"
+    "@mpgd/adapter-capacitor": "^0.17.0",
+    "@mpgd/bridge": "^0.17.0",
+    "@mpgd/platform": "^0.33.0"
   },
   "devDependencies": {
     "@capacitor/core": "8.5.2",
     "@types/node": "^24.0.0",
-    "ttsc": "0.32.1",
+    "ttsc": "0.34.2",
     "typescript": "7.0.2",
     "vitest": "^4.0.0",
-    "@mpgd/adapter-capacitor": "0.16.3",
-    "@mpgd/bridge": "0.16.4",
-    "@mpgd/game-services": "0.30.5",
-    "@mpgd/platform": "0.32.0"
+    "@mpgd/adapter-capacitor": "0.17.0",
+    "@mpgd/bridge": "0.17.0",
+    "@mpgd/platform": "0.33.0",
+    "@mpgd/game-services": "0.31.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",