@mpgd/capacitor-storekit 0.4.5 → 0.5.0

package/README.md

@@ -61,10 +61,12 @@ once (a current non-consumable entitlement the native side marks
 still be verified; the server ledger dedupes. A finished consumable is not
 listed. A `revokedAt` maps to `state: 'revoked'`, and one malformed
 transaction is reported as a `purchaseError` without blocking its siblings);
-`finishTransaction({ transactionId, ledgerEntryId })` resolves the session
-app account token and finishes only a listed, non-revoked transaction bound
-to that token, or a durable of another token a restore shared to this
-player (see Recovery);
+`finishTransaction({ transactionId, ledgerEntryId, isConsumable, retry? })`
+resolves the session app account token and finishes only a listed,
+non-revoked transaction bound to that token, or a durable of another token a
+restore shared to this player (see Recovery), and on a retry (`retry: true`)
+answers `finished: true` without a native call for a consumable the list no
+longer carries (a lost acknowledgement, see Recovery);
 `restorePurchases` over `sync`; `transactionUpdated` as `purchaseUpdated`;
 and an availability probe as `getAvailability`, probing the configured
 SKUs batch by batch until one is sold. Every purchase carries the
@@ -105,7 +107,7 @@ consumables of another token stay excluded. The native
 or a `purchaseError` subscriber exists.
 
 `createCapacitorStoreKitCommerceProvider({ products, getAppAccountToken,
-bundleId?, sdk?, isIos?, mapError?, onDiagnostic? })` builds the provider
+purchaseGate?, bundleId?, sdk?, isIos?, mapError?, onDiagnostic? })` builds the provider
 with `authority: { evidence: 'client-token', accountBinding: 'required' }`
 and evidence `{ schema: 'app-store.signed-transaction.v1', payload: {
 signedTransaction, transactionId, originalTransactionId?, bundleId? } }`,
@@ -115,7 +117,18 @@ its `signedTransactionVerifier` (authenticity and transaction id binding)
 and then, by default, decides the grant on the transaction's current status
 from the App Store Server API, so a JWS retained from before a refund never
 grants; see the backend guide for the opt-in offline-only mode. Subscription
-mappings are rejected at construction. `createCapacitorStoreKitServiceProvider`
+mappings are rejected at construction. `getAppAccountToken` also filters
+recovery and finishing to the current player, so it must keep answering
+while sales are paused: pause new sales with the optional `purchaseGate`
+instead, which is asked only before a new purchase opens the StoreKit sheet
+(never by recovery, restore, or finishing) and refuses with `failed`,
+`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.
+A token that cannot be resolved is a `failed` result with
+`STOREKIT_ACCOUNT_LOOKUP_FAILED` (a thrown `CommerceError` keeps its own code). `createCapacitorStoreKitServiceProvider`
 wraps the provider as a `CapacitorServiceProvider` (id `apple-storekit` by
 default, no `features`, no `methods`) so the gateway serves the six
 `commerce.v2.*` bridge methods from it, exposes it as `gateway.commerce`, and
@@ -131,13 +144,17 @@ Finishing never grants. The SDK finishes any transaction it is given a
 (`createCommerceReconciler` in `@mpgd/game-services`) is the gate, and it
 calls `finishTransaction` only for a journal record in `granted` or
 `finishing` that holds the ledger entry id the backend grant wrote
-(`assertCommerceFinishAllowed`). The journal revision the grant wrote is the
-pairing, and the real control stays server-side, in the verifier that checks
-the JWS before the ledger grant, and in the native plugin never granting
-anything on finish. `src/commerce-reconciler-storekit-smoke.test.ts` shows the
-reconciler over the fake plugin: a grant finishes with the ledger entry, a
-rejection and an outage never finish, a failed finish is retried, and another
-account's transaction is never submitted.
+(`assertCommerceFinishAllowed`), or for a `finished` consumable StoreKit
+lists again, with that same ledger entry (see Recovery). The journal revision
+the grant wrote is the pairing, and the real control stays server-side, in
+the verifier that checks the JWS before the ledger grant, and in the native
+plugin never granting anything on finish.
+`src/commerce-reconciler-storekit-smoke.test.ts` shows the reconciler over
+the fake plugin: a grant finishes with the ledger entry, a rejection and an
+outage never finish, a failed finish is retried, another account's
+transaction is never submitted, a finish whose answer was lost ends
+`finished` on the next run, a transaction listed again is finished again
+without a second verify, and an Ask to Buy purchase finishes once approved.
 
 The conformance test runs every store vector whose profile the App Store
 supports against a fake plugin, directly and through the gateway bridge path,
@@ -211,6 +228,44 @@ separately on the server. `restorePurchases` invokes the user-initiated
 entitlements. Subscriptions are not supported by this package; they require a
 separate subscription status and renewal flow.
 
+A finish whose answer is lost after StoreKit applied it (the app is closed
+between the native finish and the journal write) leaves the record
+`finishing`. The reconciler's next finish of a record that was already
+`finishing` carries `retry: true`, and on a retry the SDK reads the
+consumable missing from `getTransactions` as finished: StoreKit keeps a
+transaction in
+[`Transaction.unfinished`](https://developer.apple.com/documentation/storekit/transaction/unfinished)
+until `finish()`, and a finished consumable is in neither that list nor
+`currentEntitlements`, so the SDK answers `finished: true` without a native
+call and the record ends `finished`. The first finish after the grant never
+does: right after a purchase the list may not carry the new transaction yet,
+so a missing one stays `{ finished: false }` and the reconciler retries (by
+then StoreKit lists it and it is finished natively). A caller that never
+sets `retry` (an older reconciler) keeps the earlier behaviour. The
+reconciler finishes only records holding a ledger grant, and nothing is
+verified again. A durable missing from the list is never answered finished
+(a finished durable stays listed with `unfinished: false`, so a missing one
+is revoked or unverifiable), nor is an entry of that id in a malformed
+shape. The kind of a missing transaction is the caller's `isConsumable`
+(the list no longer says, and reading `Transaction.all` would need a native
+change); a durable the catalog maps as a consumable never reaches a grant
+through this SDK, which excludes kind mismatches (`kind-mismatch`).
+
+Should StoreKit list the consumable again (an entry the native read skipped
+as unverifiable), the reconciler finishes it again with the journaled ledger
+entry, once per session, without a second verify. If the finished record has
+already left the journal (the generated game's journal keeps terminal
+records for 30 days), the transaction is verified under its derived key; the
+reference backend answers that with this player's recorded grant
+(`alreadyProcessed: true`, the same ledger entry, no second grant) because
+the App Store entry is a `client`-finish consumable, and the reconciler then
+finishes it. Another player's ask under another key stays refused
+(`EVIDENCE_ALREADY_PROCESSED`), so nothing is granted twice. Ask to Buy is
+unaffected: a deferred purchase has no transaction
+until it is approved, so its `launched` record holds no ledger grant and is
+never finished; the approved transaction arrives through `transactionUpdated`
+and is verified and finished once.
+
 ### Migrating from v1
 
 Commerce v2 PR C4 removed the v1 provider and its recovery driver.

package/dist/commerce-provider.d.ts

@@ -1,5 +1,6 @@
 import { type CapacitorCommerceServiceProvider, type StoreCommerceProductMapping, type StoreCommerceProvider, type StoreSdkErrorCodeMap } from '@mpgd/adapter-capacitor';
 import { appStoreSignedTransactionEvidenceSchema } from './commerce-profile.js';
+import { type StorePurchaseGate } from './purchase-gate-support.js';
 import { type CapacitorStoreKitDiagnostic, type CapacitorStoreKitStoreSdkPlugin } from './store-sdk.js';
 export { appStoreSignedTransactionEvidenceSchema };
 /** Payload of an `app-store.signed-transaction.v1` envelope. */
@@ -14,9 +15,18 @@ export interface CreateCapacitorStoreKitCommerceProviderInput {
   readonly products: readonly StoreCommerceProductMapping[];
   /**
   * Authenticated, stable UUID app account token of the current player. The
-  * backend's `resolveAppAccountToken` must resolve the same value.
+  * backend's `resolveAppAccountToken` must resolve the same value. It also
+  * filters recovery and finishing to this player, so it must keep answering
+  * while sales are paused; pause sales with `purchaseGate` instead.
   */
   readonly getAppAccountToken: () => string | Promise<string>;
+  /**
+  * Optional sales switch, asked before a new purchase opens the StoreKit
+  * sheet and never by recovery, restore, or finishing, which keep using
+  * `getAppAccountToken` alone; a refusal is `ITEM_UNAVAILABLE` with
+  * `PURCHASES_PAUSED` (see `StorePurchaseGate` in `@mpgd/adapter-capacitor`).
+  */
+  readonly purchaseGate?: StorePurchaseGate;
   /** Recorded in the evidence payload when known; the backend checks the signed value anyway. */
   readonly bundleId?: string;
   readonly sdk?: CapacitorStoreKitStoreSdkPlugin;

package/dist/commerce-provider.js

@@ -1,6 +1,7 @@
 import { createCommerceServiceProvider, createStoreCommerceProvider, } from '@mpgd/adapter-capacitor';
 import { CommerceError } from '@mpgd/platform/commerce';
 import { appStoreSignedTransactionEvidenceSchema, appStoreStoreId, storeKitCommerceAuthority, } from './commerce-profile.js';
+import { refuseNewPurchasesUnlessGated, resolvePurchaseGateSupport, } from './purchase-gate-support.js';
 import { capacitorStoreKitErrorCodeMap, createCapacitorStoreKitStoreSdk, readAppAccountToken, } 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.
@@ -31,6 +32,7 @@ export function createCapacitorStoreKitCommerceProvider(input) {
         throw new TypeError('StoreKit bundleId must be a non-empty string when provided.');
     }
     const bundleId = input.bundleId;
+    const gate = resolvePurchaseGateSupport(input.purchaseGate);
     const sdk = createCapacitorStoreKitStoreSdk({
         products: input.products.map((product) => ({
             sku: product.storeSku,
@@ -41,7 +43,7 @@ export function createCapacitorStoreKitCommerceProvider(input) {
         ...(input.isIos === undefined ? {} : { isIos: input.isIos }),
         ...(input.onDiagnostic === undefined ? {} : { onDiagnostic: input.onDiagnostic }),
     });
-    return createStoreCommerceProvider({
+    return refuseNewPurchasesUnlessGated(createStoreCommerceProvider({
         sdk,
         store: appStoreStoreId,
         products: input.products,
@@ -63,6 +65,9 @@ export function createCapacitorStoreKitCommerceProvider(input) {
                 value = await input.getAppAccountToken();
             }
             catch (error) {
+                if (error instanceof CommerceError) {
+                    throw error;
+                }
                 throw new CommerceError('ACCOUNT_BINDING_REQUIRED', {
                     message: 'The StoreKit app account token could not be resolved.',
                     storeCode: 'STOREKIT_ACCOUNT_LOOKUP_FAILED',
@@ -86,9 +91,10 @@ export function createCapacitorStoreKitCommerceProvider(input) {
                 });
             }
         },
+        ...(gate.purchaseGate === undefined ? {} : { purchaseGate: gate.purchaseGate }),
         authority: storeKitCommerceAuthority,
         mapError: { ...capacitorStoreKitErrorCodeMap, ...input.mapError },
-    });
+    }), gate);
 }
 /**
  * The commerce provider wrapped as a `CapacitorServiceProvider` for

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/dist/store-sdk.js

@@ -259,9 +259,33 @@ export function createCapacitorStoreKitStoreSdk(input) {
     /**
      * Mirrors the native finish gate: the transaction must be listed, not
      * revoked, and bound to the session app account token. A missing list is
-     * an invalid response, not a quiet "not finished". Two exceptions for a
-     * listed, non-revoked durable, the only kind the restore read admits from
-     * another token:
+     * an invalid response, not a quiet "not finished".
+     *
+     * On a retried finish (`retry`: the caller asked to finish this purchase
+     * before, in an earlier attempt or session), a consumable the list no
+     * longer carries is already finished: StoreKit keeps a transaction in
+     * `Transaction.unfinished` until `finish()`, and a finished consumable is in
+     * neither that list nor `currentEntitlements`. That is the lost
+     * acknowledgement: an earlier finish reached StoreKit but its answer never
+     * reached the journal (the app was closed between the two), and the record
+     * would otherwise stay `finishing` forever. A first finish never reads a
+     * missing transaction that way: right after the grant the list may not
+     * carry the new transaction yet, so it stays refused and the caller retries.
+     * Nothing native is called, and an entry of that id the native side reports
+     * in any shape keeps it refused. If the transaction is listed again later
+     * (an unverifiable entry the native read skipped, or a list read before
+     * StoreKit carried it), the reconciler finishes it again without a second
+     * verify. A durable missing from the list is refused: a durable stays in
+     * `currentEntitlements` after its finish, so a missing one is revoked or
+     * unverifiable, never a lost acknowledgement. The kind of a missing
+     * transaction is the caller's `isConsumable` (the list no longer says), so a
+     * catalog that maps a durable as a consumable would be answered finished
+     * here; the SDK never admits such a transaction (`kind-mismatch`), so the
+     * reconciler cannot hold a grant for it from this SDK, and the answer
+     * neither grants nor takes anything.
+     *
+     * Two exceptions for a listed, non-revoked durable, the only kind the
+     * restore read admits from another token:
      *
      * - StoreKit already finished it (`unfinished: false`): nothing is left to
      *   finish whatever its token, so a restore shared to this player ends
@@ -279,13 +303,17 @@ export function createCapacitorStoreKitStoreSdk(input) {
      * A consumable of another token, or a transaction bound to no token, is
      * never finished here.
      */
-    const finishPermitted = async (transactionId, appAccountToken) => {
+    const finishPermitted = async (transactionId, appAccountToken, lostAcknowledgement) => {
         const response = await sdk.getTransactions();
         if (!isRecord(response) || !Array.isArray(response.transactions)) {
             throw evidenceInvalid('StoreKit returned an invalid transaction list.');
         }
-        const transaction = response.transactions.find((candidate) => isValidStoreKitTransaction(candidate) && candidate.transactionId === transactionId);
-        if (transaction === undefined || transaction.revokedAt !== undefined) {
+        const entries = response.transactions.filter((candidate) => isRecord(candidate) && candidate.transactionId === transactionId);
+        const transaction = entries.find(isValidStoreKitTransaction);
+        if (transaction === undefined) {
+            return { verdict: entries.length === 0 && lostAcknowledgement ? 'finished' : 'refused' };
+        }
+        if (transaction.revokedAt !== undefined) {
             return { verdict: 'refused' };
         }
         if (transaction.type === 'non_consumable' && transaction.unfinished === false) {
@@ -409,8 +437,10 @@ export function createCapacitorStoreKitStoreSdk(input) {
             const promise = (async () => {
                 // Same match the native plugin applies: missing, revoked, unbound, or
                 // another account never reaches `transaction.finish()`, except a
-                // durable of another token (see `finishPermitted`).
-                const permitted = await finishPermitted(transactionId, appAccountToken);
+                // durable of another token (see `finishPermitted`). On a retry, a
+                // consumable that left the unfinished list is already finished (a
+                // lost acknowledgement).
+                const permitted = await finishPermitted(transactionId, appAccountToken, request.isConsumable === true && request.retry === true);
                 if (permitted.verdict !== 'finish') {
                     return { finished: permitted.verdict === 'finished' };
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/capacitor-storekit",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Opt-in StoreKit 2 one-time purchase collector and commerce v2 provider for mpgd Capacitor games.",
   "license": "MIT",
   "repository": {
@@ -38,18 +38,18 @@
   ],
   "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",
-    "ttsc": "0.32.1",
+    "ttsc": "0.34.2",
     "typescript": "7.0.2",
-    "@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/game-services": "0.31.0",
+    "@mpgd/platform": "0.33.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",