@mpgd/capacitor-play-billing 0.1.8 → 0.2.0

package/README.md

@@ -13,6 +13,131 @@ This package is published for opt-in integration, but Kit's mock and compile
 checks do not establish live Play purchase behavior. Validate it in a
 game-owned Play Console project before relying on it in a published game.
 
+## Commerce v2 provider
+
+Commerce v2 ([RFC](../../docs/specs/commerce/commerce-v2-rfc.md), PR B2) adds
+a `StoreSdk` over this plugin and a `CommerceProvider` built from it with
+`createStoreCommerceProvider` from `@mpgd/adapter-capacitor` (a peer
+dependency since 0.2.0). Register the service provider with the Capacitor
+gateway and it serves the six `commerce.v2.*` bridge methods as
+`gateway.commerceV2`, plus the four v1 `commerce.*` methods through
+`toCommerceAdapter`, so v1 callers keep working.
+
+```ts
+import { createCapacitorPlatformGateway } from '@mpgd/adapter-capacitor';
+import { createCapacitorPlayBillingServiceProvider } from '@mpgd/capacitor-play-billing';
+
+export function createPlayGateway(getObfuscatedAccountId: () => Promise<string>) {
+  return createCapacitorPlatformGateway({
+    target: 'android',
+    appVersion: '1.0.0',
+    buildId: 'game-build',
+    providers: [
+      createCapacitorPlayBillingServiceProvider({
+        products: [
+          { logicalId: 'gems_small', storeSku: 'gems.small', kind: 'consumable' },
+          { logicalId: 'remove_ads', storeSku: 'remove.ads', kind: 'durable', offerId: 'intro' },
+        ],
+        // Must agree with the backend's resolveObfuscatedAccountId.
+        accountBinding: async () => ({
+          kind: 'obfuscated-account-id',
+          value: await getObfuscatedAccountId(),
+        }),
+      }),
+    ],
+  });
+}
+```
+
+`createCapacitorPlayBillingStoreSdk({ products, plugin?, isAndroid? })` is
+the `StoreSdk`: store `google-play`; capabilities consumable and durable
+(no subscriptions, no multi-quantity), `pending: true`, `restore: false`,
+`offers: true`, and `finish: 'server'`. `fetchProducts` is `getProducts`
+with the selected one-time offer as the price (`PLAY_BILLING_OFFER_REQUIRED`
+when several offers are eligible and none is configured) and every eligible
+offer listed as `offers[].offerId` (the Play `offerToken`). `requestPurchase`
+is `purchase` with the obfuscated account id from the request's
+`accountBinding` (`kind: 'obfuscated-account-id'`; anything else is
+`PLAY_BILLING_ACCOUNT_REQUIRED`) and `offerToken` from `offerId`: a
+`purchased` outcome is `purchased`, a `pending` outcome is `launched` because
+Play resolves it later through `purchaseUpdated` or `getPurchases`, a
+`cancelled` outcome is `cancelled`, and a plugin rejection is `failed` with
+the plugin code. `getAvailablePurchases` is `getPurchases` filtered to
+unfinished entries: `purchased` with `isAcknowledged: false`, plus `pending`
+when `includePending` is set; each carries `token = purchaseToken` and
+`transactionId = orderId`, or the `play-token-sha256:<hex>` token key until
+Play assigns an order id, so ledgers written by v1 deduplicate. A purchased
+entry from a 0.1 native build carries no `isAcknowledged`; an absent flag
+counts as unfinished so a paid purchase is never dropped during a staged
+upgrade. A purchase for a SKU that is not in `products` (a retired product)
+or a multi-line purchase has no logical id for the reconciler, so it is left
+out of the list and of events and handed to the optional `onUnmappedPurchase`
+diagnostics hook instead; the backend finalizer still sees it through the
+Play Developer API. The plugin's `purchaseUpdated` listener backs
+`addListener`: deliveries leave in the order the plugin reported them (a
+purchase without an order id waits for the token digest, and later updates
+queue behind it), and a `cancelled` or `failed` update without a purchase is
+the plugin's late terminal result for a purchase call that already timed out
+(`PLAY_BILLING_TIMEOUT`), emitted as a `purchaseError` for that product so
+the attempt the timeout left open closes. `getAvailability` is the v1 logic
+(Android check, offer configuration, service state).
+`playBillingStoreSdkErrorCodeMap` extends `defaultStoreSdkErrorCodeMap` with
+every other `PLAY_BILLING_*` code (`BUSY` is `IN_PROGRESS`, `OFFER_REQUIRED`
+and the invalid-product codes are `CONFIGURATION_REQUIRED`,
+`ACTIVITY_REQUIRED` is `NOT_PREPARED`, `ANDROID_REQUIRED` is
+`STORE_UNAVAILABLE`); `PLAY_BILLING_TIMEOUT`, `PLAY_BILLING_INTERRUPTED`,
+`PLAY_BILLING_EMPTY_PURCHASE`, and `PLAY_BILLING_ALREADY_OWNED` stay
+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
+schema `google-play.product-purchase.v2` with payload `{ purchaseToken }`,
+byte-identical to the v1 provider's evidence, so
+`createGooglePlayProductPurchaseBoundary` verifies both; 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
+harness overrides it, because the derived idempotency key follows the store
+id. The conformance test runs every store vector whose profile the Play
+capabilities can serve (`purchase-server-finish`) against a fake plugin,
+directly and through the gateway bridge path, and lists the skipped vectors
+with their reason: the client-finish, host-finish, adapter-settled, and
+server-push profiles need a finish owner or evidence authority Play does not
+have.
+
+The plugin surface gained the Billing Library 9.1.0 `Purchase` getters on
+every purchase (`getPurchases()`, `purchase()`, and `purchaseUpdated`):
+`products`, `purchaseState`, `purchaseTime`, `quantity`, `isAcknowledged`,
+and `obfuscatedAccountId`, with `priceAmountMicros` on offers. The 0.1 names
+`productIds`, `state`, and `purchaseTimeMillis` carry the same values and are
+deprecated until the next major version. `purchaseUpdated` is now retained
+until a listener consumes it, so a purchase that completes after the
+`purchase` call timed out, or before the web view attached its listener,
+still reaches the provider, and a cancel or non-OK result that arrives after
+the 180-second `purchase` timeout is delivered as `{ status: 'cancelled' |
+'failed', productId, code? }` for the timed-out product instead of being
+discarded. The plugin still never acknowledges or consumes;
+`isAcknowledged: false` on a purchased entry marks it unfinished for the
+backend finalizer.
+
+### Migrating from the v1 provider
+
+`createCapacitorPlayBillingProvider` and `recoverOwnedPlayPurchases` are
+unchanged and keep working; both providers can share the plugin. Games that
+move to v2 replace the v1 provider in `providers` with
+`createCapacitorPlayBillingServiceProvider`, turn `getObfuscatedAccountId`
+into an `accountBinding` resolver returning `{ kind: 'obfuscated-account-id',
+value }`, rename `id`/`storeId`/`type` to `logicalId`/`storeSku`/`kind`
+(`non_consumable` becomes `durable`) and `offerToken` to `offerId`, and stop
+calling `recoverOwnedPlayPurchases`: it is deprecated in favour of the single
+reconciler landing in `@mpgd/game-services` (PR C1), which reads
+`getAvailablePurchases` and `purchaseUpdated` from `gateway.commerceV2`. The
+backend contract is unchanged, since the evidence payload is the same.
+
+## v1 provider
+
 The provider maps game logical product IDs to Play product IDs and requires a
 stable obfuscated account ID that agrees with the backend account resolver.
 When Play returns multiple eligible one-time offers, map an explicit

package/android/src/main/java/dev/mpgd/capacitor/playbilling/CapacitorPlayBillingPlugin.java

@@ -2,6 +2,7 @@ package dev.mpgd.capacitor.playbilling;
 
 import android.os.Handler;
 import android.os.Looper;
+import com.android.billingclient.api.AccountIdentifiers;
 import com.android.billingclient.api.BillingClient;
 import com.android.billingclient.api.BillingClientStateListener;
 import com.android.billingclient.api.BillingFlowParams;
@@ -22,7 +23,11 @@ import java.util.Collections;
 import java.util.List;
 import org.json.JSONException;
 
-/** Purchase collection only. Finalization is server-owned after the mpgd ledger grant. */
+/**
+ * Purchase collection only. Finalization is server-owned after the mpgd ledger grant: this
+ * plugin never calls acknowledgePurchase or consumeAsync, and the encoded isAcknowledged flag
+ * lets the TypeScript provider list unfinished purchases for the backend finalizer.
+ */
 @CapacitorPlugin(name = "CapacitorPlayBilling")
 public class CapacitorPlayBillingPlugin extends Plugin {
     private BillingClient billingClient;
@@ -32,6 +37,12 @@ public class CapacitorPlayBillingPlugin extends Plugin {
     private PluginCall activePurchase;
     private String activeProductId;
     private Runnable purchaseTimeout;
+    /**
+     * Product of a purchase call that timed out while the Play UI was still up. A later
+     * terminal callback (cancel or non-OK result) is delivered for it as a purchaseUpdated
+     * event, so the JavaScript attempt the timeout left open can close.
+     */
+    private String timedOutProductId;
 
     @Override
     public void load() {
@@ -107,7 +118,8 @@ public class CapacitorPlayBillingPlugin extends Plugin {
                             eligibleOffers.put(new JSObject()
                                 .put("offerToken", offer.getOfferToken())
                                 .put("formattedPrice", offer.getFormattedPrice())
-                                .put("currencyCode", offer.getPriceCurrencyCode()));
+                                .put("currencyCode", offer.getPriceCurrencyCode())
+                                .put("priceAmountMicros", offer.getPriceAmountMicros()));
                         }
                     }
                     if (eligibleOffers.length() == 0) {
@@ -144,8 +156,10 @@ public class CapacitorPlayBillingPlugin extends Plugin {
         }
         activePurchase = call;
         activeProductId = productId;
+        timedOutProductId = null;
         purchaseTimeout = () -> {
             if (activePurchase == call) {
+                timedOutProductId = activeProductId;
                 clearActivePurchase(call);
                 call.reject("Purchase confirmation timed out; requery owned purchases.",
                     "PLAY_BILLING_TIMEOUT");
@@ -248,6 +262,8 @@ public class CapacitorPlayBillingPlugin extends Plugin {
             if (pending != null) {
                 clearActivePurchase(pending);
                 pending.resolve(new JSObject().put("status", "cancelled"));
+            } else {
+                notifyLateTerminalResult("cancelled", null);
             }
             return;
         }
@@ -255,6 +271,8 @@ public class CapacitorPlayBillingPlugin extends Plugin {
             if (pending != null) {
                 clearActivePurchase(pending);
                 rejectBilling(pending, result);
+            } else {
+                notifyLateTerminalResult("failed", billingErrorCode(result));
             }
             return;
         }
@@ -272,9 +290,15 @@ public class CapacitorPlayBillingPlugin extends Plugin {
                 continue;
             }
             JSObject outcome = new JSObject()
-                .put("status", encoded.optString("state"))
+                .put("status", encoded.optString("purchaseState"))
                 .put("purchase", encoded);
-            notifyListeners("purchaseUpdated", outcome);
+            // Retained until a listener consumes it: a purchase that completes after the
+            // purchase call timed out, or before the web view attached its listener, must
+            // still reach the provider's purchaseUpdated subscription.
+            notifyListeners("purchaseUpdated", outcome, true);
+            if (timedOutProductId != null && purchase.getProducts().contains(timedOutProductId)) {
+                timedOutProductId = null;
+            }
             if (pending != null && purchase.getProducts().contains(expectedProductId)) {
                 clearActivePurchase(pending);
                 pending.resolve(outcome);
@@ -283,6 +307,24 @@ public class CapacitorPlayBillingPlugin extends Plugin {
         }
     }
 
+    /**
+     * A cancel or non-OK result that arrives after the purchase call already timed out has no
+     * call to answer; without this event the JavaScript attempt would stay open forever and
+     * block another purchase of the product. Only the timed-out product is correlated.
+     */
+    private void notifyLateTerminalResult(String status, String code) {
+        String productId = timedOutProductId;
+        if (productId == null) {
+            return;
+        }
+        timedOutProductId = null;
+        JSObject outcome = new JSObject().put("status", status).put("productId", productId);
+        if (code != null) {
+            outcome.put("code", code);
+        }
+        notifyListeners("purchaseUpdated", outcome, true);
+    }
+
     private JSObject encodePurchase(Purchase purchase) {
         int state = purchase.getPurchaseState();
         if (state != Purchase.PurchaseState.PURCHASED
@@ -293,20 +335,32 @@ public class CapacitorPlayBillingPlugin extends Plugin {
         if (token == null || token.trim().isEmpty() || purchase.getProducts().isEmpty()) {
             return null;
         }
-        JSArray productIds = new JSArray();
+        JSArray products = new JSArray();
         for (String productId : purchase.getProducts()) {
-            productIds.put(productId);
+            products.put(productId);
         }
+        String purchaseState = state == Purchase.PurchaseState.PURCHASED ? "purchased" : "pending";
+        // Billing 9.1.0 Purchase getters under their own names, plus the 0.1 names
+        // (productIds, state, purchaseTimeMillis) until the next major version.
         JSObject encoded = new JSObject()
-            .put("productIds", productIds)
+            .put("products", products)
+            .put("productIds", products)
             .put("purchaseToken", token)
-            .put("state", state == Purchase.PurchaseState.PURCHASED ? "purchased" : "pending");
+            .put("purchaseState", purchaseState)
+            .put("state", purchaseState)
+            .put("purchaseTime", purchase.getPurchaseTime())
+            .put("quantity", purchase.getQuantity())
+            .put("isAcknowledged", purchase.isAcknowledged());
         if (purchase.getPurchaseTime() > 0) {
             encoded.put("purchaseTimeMillis", purchase.getPurchaseTime());
         }
         if (purchase.getOrderId() != null) {
             encoded.put("orderId", purchase.getOrderId());
         }
+        AccountIdentifiers accountIdentifiers = purchase.getAccountIdentifiers();
+        if (accountIdentifiers != null && accountIdentifiers.getObfuscatedAccountId() != null) {
+            encoded.put("obfuscatedAccountId", accountIdentifiers.getObfuscatedAccountId());
+        }
         return encoded;
     }
 
@@ -378,6 +432,11 @@ public class CapacitorPlayBillingPlugin extends Plugin {
     }
 
     private void rejectBilling(PluginCall call, BillingResult result) {
+        call.reject("Google Play Billing is unavailable (" + result.getResponseCode() + ").",
+            billingErrorCode(result));
+    }
+
+    private String billingErrorCode(BillingResult result) {
         int responseCode = result.getResponseCode();
         String code;
         switch (responseCode) {
@@ -406,8 +465,7 @@ public class CapacitorPlayBillingPlugin extends Plugin {
             default:
                 code = "PLAY_BILLING_ERROR";
         }
-        call.reject("Google Play Billing is unavailable (" + result.getResponseCode() + ").",
-            code);
+        return code;
     }
 
     private void clearActivePurchase(PluginCall call) {

package/dist/commerce-provider.d.ts

@@ -0,0 +1,68 @@
+import { type CapacitorCommerceServiceProvider, type StoreCommerceProductMapping, type StoreCommerceProvider, type StoreSdkErrorCodeMap, type StoreSdkPurchase } from '@mpgd/adapter-capacitor';
+import type { PlatformEvidenceEnvelope } from '@mpgd/platform';
+import { type CommerceAuthorityCapabilities, type StoreId, type StorePurchaseAccountBinding } from '@mpgd/platform/commerce';
+import type { CapacitorPlayBillingPlugin, PlayPurchase } from './definitions.js';
+/** The evidence schema the Google Play verifier in `@mpgd/game-services` routes on. */
+export declare const googlePlayProductPurchaseEvidenceSchema: 'google-play.product-purchase.v2';
+/** RFC "Capabilities" profile row for `google-play`: the purchase token is the proof, bound to an obfuscated account id. */
+export declare const playBillingCommerceAuthority: CommerceAuthorityCapabilities;
+/** The default registry id of the Play Billing commerce v2 service provider. */
+export declare const playBillingCommerceServiceProviderId: 'google-play-billing';
+/**
+* Evidence payload of a Play purchase: exactly `{ purchaseToken }`, which is
+* what `createGooglePlayProductPurchaseBoundary` reads and what the v1
+* provider emits, so v1 and v2 evidence verify through the same code path.
+*/
+export declare function createPlayBillingEvidencePayload(purchase: Pick<StoreSdkPurchase, 'token'>): PlatformEvidenceEnvelope['payload'];
+/** One catalog product sold through Play; `offerId` is the default one-time offer token. */
+export interface PlayBillingCommerceProductMapping extends StoreCommerceProductMapping {
+  readonly kind: 'consumable' | 'durable';
+}
+export interface CreateCapacitorPlayBillingCommerceProviderInput {
+  readonly products: readonly PlayBillingCommerceProductMapping[];
+  /**
+  * 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.
+  */
+  readonly accountBinding: () => Promise<StorePurchaseAccountBinding | undefined> | StorePurchaseAccountBinding | undefined;
+  /** Defaults to the registered `CapacitorPlayBilling` plugin. */
+  readonly plugin?: CapacitorPlayBillingPlugin;
+  /** Defaults to `Capacitor.getPlatform() === 'android'`. */
+  readonly isAndroid?: () => boolean;
+  /**
+  * Store id on purchases and in derived idempotency keys. Defaults to
+  * `google-play`, which keeps the `play-token-sha256:<hex>` key v1 ledgers
+  * use; a conformance harness sets the vector's fixture store id.
+  */
+  readonly store?: StoreId;
+  /** Extra plugin codes merged over `playBillingStoreSdkErrorCodeMap`. */
+  readonly mapError?: StoreSdkErrorCodeMap;
+  /** Diagnostics for plugin purchases left out of recovery (retired SKU, multi-line); see the SDK input. */
+  readonly onUnmappedPurchase?: (purchase: PlayPurchase) => void;
+}
+/**
+* Commerce v2 `CommerceProvider` for Google Play: `createStoreCommerceProvider`
+* over `createCapacitorPlayBillingStoreSdk`, with store `google-play`, evidence
+* schema `google-play.product-purchase.v2` carrying `{ purchaseToken }`, and
+* the `client-token` / `required` authority block. Finishing stays on the
+* server (the backend acknowledges or consumes after the ledger grant), so
+* the provider has no `finishTransaction` and no `restorePurchases`. It never
+* grants.
+*/
+export declare function createCapacitorPlayBillingCommerceProvider(input: CreateCapacitorPlayBillingCommerceProviderInput): StoreCommerceProvider;
+export interface CreateCapacitorPlayBillingServiceProviderInput extends CreateCapacitorPlayBillingCommerceProviderInput {
+  /** Registry id; defaults to `google-play-billing`. */
+  readonly id?: string;
+}
+/**
+* Registry entry for `createCapacitorPlatformGateway({ providers })`: the
+* gateway serves the six `commerce.v2.*` bridge methods and exposes
+* `gateway.commerceV2`, and v1 callers keep working through
+* `toCommerceAdapter`. Only `nativeIap` is declared; Play sells no
+* subscriptions in this release.
+*/
+export declare function createCapacitorPlayBillingServiceProvider(input: CreateCapacitorPlayBillingServiceProviderInput): CapacitorCommerceServiceProvider & {
+  readonly commerce: StoreCommerceProvider;
+};

package/dist/commerce-provider.js

@@ -0,0 +1,91 @@
+import { createCommerceServiceProvider, createStoreCommerceProvider, } from '@mpgd/adapter-capacitor';
+import { CommerceError, } from '@mpgd/platform/commerce';
+import { createCapacitorPlayBillingStoreSdk, googlePlayStoreId, playBillingStoreSdkErrorCodeMap, } from './store-sdk.js';
+/** The evidence schema the Google Play verifier in `@mpgd/game-services` routes on. */
+export const googlePlayProductPurchaseEvidenceSchema = 'google-play.product-purchase.v2';
+/** RFC "Capabilities" profile row for `google-play`: the purchase token is the proof, bound to an obfuscated account id. */
+export const playBillingCommerceAuthority = Object.freeze({
+    evidence: 'client-token',
+    accountBinding: 'required',
+});
+/** The default registry id of the Play Billing commerce v2 service provider. */
+export const playBillingCommerceServiceProviderId = 'google-play-billing';
+/**
+ * Evidence payload of a Play purchase: exactly `{ purchaseToken }`, which is
+ * what `createGooglePlayProductPurchaseBoundary` reads and what the v1
+ * provider emits, so v1 and v2 evidence verify through the same code path.
+ */
+export function createPlayBillingEvidencePayload(purchase) {
+    return { purchaseToken: purchase.token };
+}
+/**
+ * Commerce v2 `CommerceProvider` for Google Play: `createStoreCommerceProvider`
+ * over `createCapacitorPlayBillingStoreSdk`, with store `google-play`, evidence
+ * schema `google-play.product-purchase.v2` carrying `{ purchaseToken }`, and
+ * the `client-token` / `required` authority block. Finishing stays on the
+ * server (the backend acknowledges or consumes after the ledger grant), so
+ * the provider has no `finishTransaction` and no `restorePurchases`. It never
+ * grants.
+ */
+export function createCapacitorPlayBillingCommerceProvider(input) {
+    const sdkProducts = [];
+    for (const mapping of input.products) {
+        if (mapping.kind !== 'consumable' && mapping.kind !== 'durable') {
+            throw new TypeError(`Play Billing sells one-time products only; ${String(mapping.logicalId)} is ${String(mapping.kind)}.`);
+        }
+        sdkProducts.push({
+            sku: mapping.storeSku,
+            kind: mapping.kind,
+            ...(mapping.offerId === undefined ? {} : { offerToken: mapping.offerId }),
+        });
+    }
+    const sdk = createCapacitorPlayBillingStoreSdk({
+        products: sdkProducts,
+        ...(input.plugin === undefined ? {} : { plugin: input.plugin }),
+        ...(input.isAndroid === undefined ? {} : { isAndroid: input.isAndroid }),
+        ...(input.onUnmappedPurchase === undefined
+            ? {}
+            : { onUnmappedPurchase: input.onUnmappedPurchase }),
+    });
+    const resolveAccountBinding = input.accountBinding;
+    return createStoreCommerceProvider({
+        sdk,
+        store: input.store ?? googlePlayStoreId,
+        products: input.products,
+        evidenceSchema: googlePlayProductPurchaseEvidenceSchema,
+        evidencePayload: createPlayBillingEvidencePayload,
+        accountBinding: async () => {
+            try {
+                return await resolveAccountBinding();
+            }
+            catch (error) {
+                throw new CommerceError('ACCOUNT_BINDING_REQUIRED', {
+                    message: 'Play Billing could not resolve the obfuscated account id.',
+                    storeCode: 'PLAY_BILLING_ACCOUNT_LOOKUP_FAILED',
+                    cause: error,
+                });
+            }
+        },
+        authority: playBillingCommerceAuthority,
+        mapError: { ...playBillingStoreSdkErrorCodeMap, ...input.mapError },
+    });
+}
+/**
+ * Registry entry for `createCapacitorPlatformGateway({ providers })`: the
+ * gateway serves the six `commerce.v2.*` bridge methods and exposes
+ * `gateway.commerceV2`, and v1 callers keep working through
+ * `toCommerceAdapter`. Only `nativeIap` is declared; Play sells no
+ * subscriptions in this release.
+ */
+export function createCapacitorPlayBillingServiceProvider(input) {
+    const { id, ...providerInput } = input;
+    const commerce = createCapacitorPlayBillingCommerceProvider(providerInput);
+    return {
+        ...createCommerceServiceProvider({
+            id: id ?? playBillingCommerceServiceProviderId,
+            commerce,
+            features: ['nativeIap'],
+        }),
+        commerce,
+    };
+}

package/dist/definitions.d.ts

@@ -1,26 +1,68 @@
 import type { PluginListenerHandle } from '@capacitor/core';
 export type PlayPurchaseState = 'purchased' | 'pending';
+export interface PlayOneTimeOffer {
+  readonly offerToken: string;
+  readonly formattedPrice: string;
+  readonly currencyCode: string;
+  /** `OneTimePurchaseOfferDetails.getPriceAmountMicros()`; absent on older plugin builds. */
+  readonly priceAmountMicros?: number;
+}
 export interface PlayProduct {
   readonly productId: string;
   readonly title: string;
   readonly description: string;
   /** Explicit offer selection is required when Google returns multiple offers. */
-  readonly offers: readonly {
-    readonly offerToken: string;
-    readonly formattedPrice: string;
-    readonly currencyCode: string;
-  }[];
+  readonly offers: readonly PlayOneTimeOffer[];
 }
+/**
+* One Play purchase as the plugin encodes `com.android.billingclient.api.Purchase`.
+* `products`, `purchaseState`, `purchaseTime`, `quantity`, `isAcknowledged`, and
+* `obfuscatedAccountId` follow the Billing Library 9.1.0 getters; `productIds`,
+* `state`, and `purchaseTimeMillis` are the 0.1 names and carry the same values
+* until the next major version.
+*/
 export interface PlayPurchase {
+  /** `Purchase.getProducts()`: the product ids this purchase covers (one for a single-line purchase). */
+  readonly products: readonly string[];
+  /** @deprecated Same value as `products`; removed in the next major version. */
   readonly productIds: readonly string[];
   readonly purchaseToken: string;
+  /** `Purchase.getOrderId()`; absent while Play has not assigned one (for example a pending purchase). */
   readonly orderId?: string;
+  /** `Purchase.getPurchaseTime()` in milliseconds since the epoch. */
+  readonly purchaseTime: number;
+  /** @deprecated Same value as `purchaseTime` when it is positive; removed in the next major version. */
   readonly purchaseTimeMillis?: number;
+  /** `Purchase.getPurchaseState()`; the plugin never reports `UNSPECIFIED_STATE`. */
+  readonly purchaseState: PlayPurchaseState;
+  /** @deprecated Same value as `purchaseState`; removed in the next major version. */
   readonly state: PlayPurchaseState;
+  /**
+  * `Purchase.isAcknowledged()`. The plugin never acknowledges or consumes; the
+  * backend finalizer does after the ledger grant, so `false` on a purchased
+  * entry means the purchase is still unfinished.
+  */
+  readonly isAcknowledged: boolean;
+  /** `Purchase.getQuantity()`; 1 unless multi-quantity purchases are enabled in Play Console. */
+  readonly quantity: number;
+  /** `Purchase.getAccountIdentifiers().getObfuscatedAccountId()` when the purchase flow set one. */
+  readonly obfuscatedAccountId?: string;
 }
+/**
+* Result of a `purchase` call (`purchased`, `pending`, or `cancelled`) and
+* payload of every `purchaseUpdated` event. A `purchase` call never resolves
+* `failed`: it rejects with the plugin code instead. On `purchaseUpdated`, a
+* `cancelled` or `failed` outcome without a `purchase` is a terminal result
+* that arrived after the `purchase` call for `productId` already timed out
+* (`PLAY_BILLING_TIMEOUT`), so the attempt the timeout left open can close.
+*/
 export interface PlayPurchaseOutcome {
-  readonly status: 'purchased' | 'pending' | 'cancelled';
+  readonly status: 'purchased' | 'pending' | 'cancelled' | 'failed';
   readonly purchase?: PlayPurchase;
+  /** The timed-out product a late `cancelled` or `failed` result belongs to. */
+  readonly productId?: string;
+  /** The `PLAY_BILLING_*` code of a late `failed` result. */
+  readonly code?: string;
 }
 export interface CapacitorPlayBillingPlugin {
   getProducts(input: {
@@ -33,9 +75,20 @@ export interface CapacitorPlayBillingPlugin {
     readonly offerToken?: string;
     readonly obfuscatedAccountId: string;
   }): Promise<PlayPurchaseOutcome>;
-  /** Requeries owned, unconsumed purchases after restart or missed callbacks. */
+  /**
+  * Requeries every purchased or pending in-app purchase Play still reports
+  * for this user and device (`queryPurchasesAsync`): unconsumed consumables,
+  * acknowledged and unacknowledged durables, and pending purchases. The
+  * `isAcknowledged` flag separates finished durables from unfinished ones.
+  */
   getPurchases(): Promise<{
     readonly purchases: readonly PlayPurchase[];
   }>;
+  /**
+  * Every purchase update Play delivers (`PurchasesUpdatedListener`), including
+  * one that completes after the `purchase` call timed out or the app
+  * restarted. Updates delivered before a listener attaches are retained
+  * until the first listener consumes them.
+  */
   addListener(eventName: 'purchaseUpdated', listener: (event: PlayPurchaseOutcome) => void): Promise<PluginListenerHandle>;
 }

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export * from './commerce-provider.js';
 export * from './definitions.js';
 export * from './plugin.js';
 export * from './provider.js';
+export * from './store-sdk.js';

package/dist/index.js

@@ -1,3 +1,5 @@
+export * from './commerce-provider.js';
 export * from './definitions.js';
 export * from './plugin.js';
 export * from './provider.js';
+export * from './store-sdk.js';

package/dist/provider.d.ts

@@ -66,6 +66,12 @@ export interface PlayPurchaseRecoveryBackend {
 /**
 * Resubmit owned purchases after a callback was missed or the app restarted.
 * A native purchase is never credited locally; only the backend response grants it.
+*
+* @deprecated v1 recovery driver. Commerce v2 games register
+* `createCapacitorPlayBillingServiceProvider` and let the single reconciler
+* in `@mpgd/game-services` (PR C1) resolve unfinished purchases from
+* `getAvailablePurchases` and `purchaseUpdated`; this driver is removed with
+* the v1 adapter in the next major version.
 */
 export declare function recoverOwnedPlayPurchases(input: {
   readonly provider: CapacitorPlayBillingProvider;

package/dist/provider.js

@@ -14,6 +14,12 @@ function isValidPurchaseToken(value) {
 /**
  * Resubmit owned purchases after a callback was missed or the app restarted.
  * A native purchase is never credited locally; only the backend response grants it.
+ *
+ * @deprecated v1 recovery driver. Commerce v2 games register
+ * `createCapacitorPlayBillingServiceProvider` and let the single reconciler
+ * in `@mpgd/game-services` (PR C1) resolve unfinished purchases from
+ * `getAvailablePurchases` and `purchaseUpdated`; this driver is removed with
+ * the v1 adapter in the next major version.
  */
 export async function recoverOwnedPlayPurchases(input) {
     if (input.playerId.trim() === '') {