@mpgd/game-services 0.30.2 → 0.30.4

package/dist/commerce-reconciler.d.ts

@@ -20,7 +20,8 @@ export declare const commercePurchaseOperationKind: 'commerce-purchase';
 export type CommercePurchaseOrigin = 'game' | 'discovered';
 /**
 * One commerce v2 purchase in the `MonetizationOperationStore`. `key` is the
-* store's global key (`createCommercePurchaseOperationKey`); `idempotencyKey`
+* store's global key (`createCommercePurchaseOperationKey`, player-scoped for
+* a durable restored while another player's record holds the shared key); `idempotencyKey`
 * is the purchase key the backend sees: the game's key for a purchase the
 * game started, or the derived key of a purchase discovered from the store.
 * Every state change is its own revision; `request` is saved before the
@@ -55,8 +56,14 @@ export interface CommercePurchaseOperationRecord {
   readonly error?: CommerceErrorInfo;
   readonly revokedBy?: string;
 }
-/** The store key of a commerce v2 purchase record: one namespace per ledger target. */
-export declare function createCommercePurchaseOperationKey(target: string, idempotencyKey: string): string;
+/**
+* The store key of a commerce v2 purchase record: one namespace per ledger
+* target, shared by every player of the install. `playerId` names the
+* player-scoped key the reconciler uses only when another player's record
+* already holds the shared key of a durable this player restores (a logout,
+* then the next guest's Restore Purchases on the same install).
+*/
+export declare function createCommercePurchaseOperationKey(target: string, idempotencyKey: string, playerId?: string): string;
 export declare function isCommercePurchaseOperationRecord(record: unknown): record is CommercePurchaseOperationRecord;
 /** Summary status of a record: the RFC mapping, with `revoked` kept distinct. */
 export declare function summarizeCommercePurchaseOperation(record: CommercePurchaseOperationRecord): CommercePurchaseSummaryStatus;

package/dist/commerce-reconciler.js

@@ -13,12 +13,24 @@ import { chunkLedgerEntryIds } from './commerce-ledger.js';
  */
 /** Journal record kind of a commerce v2 purchase. */
 export const commercePurchaseOperationKind = 'commerce-purchase';
-/** The store key of a commerce v2 purchase record: one namespace per ledger target. */
-export function createCommercePurchaseOperationKey(target, idempotencyKey) {
+/**
+ * The store key of a commerce v2 purchase record: one namespace per ledger
+ * target, shared by every player of the install. `playerId` names the
+ * player-scoped key the reconciler uses only when another player's record
+ * already holds the shared key of a durable this player restores (a logout,
+ * then the next guest's Restore Purchases on the same install).
+ */
+export function createCommercePurchaseOperationKey(target, idempotencyKey, playerId) {
     if (typeof idempotencyKey !== 'string' || idempotencyKey.trim() === '') {
         throw new Error('Commerce purchase operations require a nonempty idempotency key.');
     }
-    return JSON.stringify([target, commercePurchaseOperationKind, idempotencyKey]);
+    if (playerId === undefined) {
+        return JSON.stringify([target, commercePurchaseOperationKind, idempotencyKey]);
+    }
+    if (typeof playerId !== 'string' || playerId.trim() === '') {
+        throw new Error('A player-scoped commerce purchase key requires a nonempty player id.');
+    }
+    return JSON.stringify([target, commercePurchaseOperationKind, idempotencyKey, playerId]);
 }
 export function isCommercePurchaseOperationRecord(record) {
     return typeof record === 'object'
@@ -105,6 +117,21 @@ export const defaultInFlightTimeoutMs = 10 * 60 * 1000;
 function isOpen(state) {
     return state === 'launched' || state === 'pending';
 }
+/** The backend's answer for a restore past the restore sharing holder limit (RFC "Restore sharing"). */
+const purchaseHolderLimitReason = 'PURCHASE_HOLDER_LIMIT_REACHED';
+/**
+ * A backend-pending record that only the player's Restore Purchases resends:
+ * a restore the backend answered `pending` at the holder limit. Nothing a
+ * pass can observe frees a holder, so an automatic resend would repeat the
+ * same answer on every launch, resume, and event; an explicit restore may
+ * find a holder freed (a deleted player, a reversed grant).
+ */
+function waitsForRestoreTrigger(record) {
+    return record.state === 'pending'
+        && record.response !== undefined
+        && !record.response.verified
+        && record.response.reason === purchaseHolderLimitReason;
+}
 /** A backend answer that the capabilities read does not exist: HTTP 404 or oRPC NOT_FOUND. */
 function isNotFoundError(error) {
     if (typeof error !== 'object' || error === null) {
@@ -235,6 +262,15 @@ export function createCommerceReconciler(input) {
         && record.target === target
         && record.deploymentTarget === deploymentTarget
         && record.store === storeId;
+    /**
+     * Another player's record of this store under a shared key: on one install
+     * the derived key of a store purchase is the same for every player, so the
+     * player who journaled it first holds that key.
+     */
+    const heldByAnotherPlayer = (record) => isCommercePurchaseOperationRecord(record)
+        && record.playerId !== playerId
+        && record.target === target
+        && record.store === storeId;
     const remember = (record) => {
         records.set(record.idempotencyKey, record);
         return record;
@@ -378,11 +414,15 @@ export function createCommerceReconciler(input) {
         emit({ type: 'transition', record: next, previous: record.state });
         return next;
     };
-    const reserve = async (record) => {
+    /**
+     * Reserves the record under `key`: the shared key of its idempotency key
+     * unless `resolveSlot` chose this player's player-scoped one.
+     */
+    const reserve = async (record, key = createCommercePurchaseOperationKey(target, record.idempotencyKey)) => {
         const candidate = {
             ...record,
             kind: commercePurchaseOperationKind,
-            key: createCommercePurchaseOperationKey(target, record.idempotencyKey),
+            key,
             playerId,
             target,
             deploymentTarget,
@@ -417,8 +457,39 @@ export function createCommerceReconciler(input) {
         retryAt.delete(record.idempotencyKey);
         return next;
     };
-    const readRecord = async (idempotencyKey) => {
-        const found = await journal.read(createCommercePurchaseOperationKey(target, idempotencyKey));
+    /**
+     * Where this player's record of an idempotency key lives, and what that key
+     * holds now. A record is under the shared key, or under this player's
+     * player-scoped key, which only the player's Restore Purchases takes, for a
+     * durable another player journaled first (`ingestPurchase`). The scoped key
+     * is read only where such a record can be, so a journal is never asked for
+     * one on a game key or a consumable:
+     *
+     * - `takeHeld`: when another player's record holds the shared key, the
+     *   scoped key is the slot. Without it, another player's record is what
+     *   the slot holds, and `recordIn` refuses it.
+     * - `probeFree`: when the shared key is free, a record under the scoped key
+     *   still answers (retention may have dropped the other player's record).
+     */
+    const resolveSlot = async (idempotencyKey, options = {}) => {
+        const sharedKey = createCommercePurchaseOperationKey(target, idempotencyKey);
+        const shared = await journal.read(sharedKey);
+        const heldByAnother = shared !== undefined && heldByAnotherPlayer(shared);
+        const probeScoped = heldByAnother
+            ? options.takeHeld === true
+            : shared === undefined && options.probeFree === true;
+        if (!probeScoped) {
+            return { key: sharedKey, found: shared, heldByAnother };
+        }
+        const scopedKey = createCommercePurchaseOperationKey(target, idempotencyKey, playerId);
+        const scoped = await journal.read(scopedKey);
+        return scoped !== undefined || heldByAnother
+            ? { key: scopedKey, found: scoped, heldByAnother }
+            : { key: sharedKey, found: undefined, heldByAnother };
+    };
+    /** This player's record in a slot; another player's or another store's is refused. */
+    const recordIn = (slot, idempotencyKey) => {
+        const found = slot.found;
         if (found === undefined) {
             return records.get(idempotencyKey);
         }
@@ -427,6 +498,13 @@ export function createCommerceReconciler(input) {
         }
         return remember(found);
     };
+    /**
+     * This player's record of a purchase idempotency key, under the shared key
+     * or its player-scoped key. A key another player's record holds is refused,
+     * so another player's consumable, subscription, or game-started attempt is
+     * never matched, sent, or replayed for this player.
+     */
+    const readRecord = async (idempotencyKey) => recordIn(await resolveSlot(idempotencyKey), idempotencyKey);
     const ownedRecordsOf = (listed) => listed.filter((record) => isCommercePurchaseOperationRecord(record) && ownsRecord(record));
     const listRecoverable = async () => ownedRecordsOf(await journal.listRecoverable(playerId))
         .filter((record) => !isTerminalCommercePurchaseState(record.state))
@@ -532,7 +610,7 @@ export function createCommerceReconciler(input) {
         };
     };
     // Reconciler step 2: match a reported purchase to a journal record.
-    const ingestPurchase = async (purchase) => {
+    const ingestPurchase = async (purchase, restoring) => {
         if (purchase.store !== storeId) {
             fail('match', new Error(`Purchase ${purchase.transactionId} belongs to store ${purchase.store}, not ${storeId}.`));
             return;
@@ -583,7 +661,21 @@ export function createCommerceReconciler(input) {
                 transactionId: purchase.transactionId,
                 token: purchase.token,
             });
-            record = await readRecord(idempotencyKey);
+            // The derived key is the same for every player of the install. On the
+            // player's Restore Purchases pass, a durable another player journaled
+            // first (a logout, then this player's restore) is this player's own
+            // restore, journaled under its player-scoped key; the backend keys the
+            // grant by player and key. Automatic passes, and any other kind held by
+            // another player, stay refused: a purchase a normal read lists for the
+            // earlier player (Play lists an unacknowledged one whoever is signed in)
+            // is never shared without the player asking, and one player's
+            // consumable is never sent for another.
+            const durable = product.kind === 'durable';
+            const slot = await resolveSlot(idempotencyKey, {
+                takeHeld: restoring && durable,
+                probeFree: durable,
+            });
+            record = recordIn(slot, idempotencyKey);
             if (record !== undefined
                 && (record.logicalId !== product.logicalId
                     || (record.purchase !== undefined && !samePurchase(record.purchase, purchase)))) {
@@ -601,7 +693,7 @@ export function createCommerceReconciler(input) {
                     origin: 'discovered',
                     state: purchase.state,
                     purchase,
-                });
+                }, slot.key);
                 return;
             }
         }
@@ -897,7 +989,7 @@ export function createCommerceReconciler(input) {
                         defer(event);
                         continue;
                     }
-                    await ingestPurchase(event.purchase);
+                    await ingestPurchase(event.purchase, options.restoreTrigger === true);
                 }
                 else if (event.type === 'purchaseError') {
                     if (event.logicalId !== undefined && busy.has(event.logicalId)) {
@@ -911,8 +1003,14 @@ export function createCommerceReconciler(input) {
                 fail('journal', error);
             }
         }
-        for (const record of await listRecoverable()) {
-            await drive(records.get(record.idempotencyKey) ?? record, capabilitiesNow, options.explicit);
+        for (const listed of await listRecoverable()) {
+            const record = records.get(listed.idempotencyKey) ?? listed;
+            if (options.restoreTrigger !== true && waitsForRestoreTrigger(record)) {
+                // At the holder limit only the player's Restore Purchases asks again;
+                // other passes skip the record before driving it.
+                continue;
+            }
+            await drive(record, capabilitiesNow, options.explicit);
         }
         await revokeReversed();
     };
@@ -1336,7 +1434,12 @@ export function createCommerceReconciler(input) {
                         initialScanPending = false;
                     }
                 }
-                await pass({ explicit: true, refreshCapabilities: false, restore: !restoreRead });
+                await pass({
+                    explicit: true,
+                    refreshCapabilities: false,
+                    restore: !restoreRead,
+                    restoreTrigger: true,
+                });
             });
             await runUntilIdle();
         },
@@ -1344,7 +1447,14 @@ export function createCommerceReconciler(input) {
         async fetchProducts(request = {}) {
             return provider.fetchProducts(request);
         },
-        read: readRecord,
+        // A restored durable under this player's player-scoped key answers; any
+        // other key another player's record holds is refused as before.
+        read: async (idempotencyKey) => {
+            const slot = await resolveSlot(idempotencyKey, { takeHeld: true });
+            return slot.heldByAnother && slot.found === undefined
+                ? readRecord(idempotencyKey)
+                : recordIn(slot, idempotencyKey);
+        },
         listRecoverable,
         subscribe(listenerToAdd) {
             listeners.add(listenerToAdd);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.30.2",
+  "version": "0.30.4",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -233,7 +233,7 @@
     "@orpc/server": "2.0.0-beta.14",
     "@mpgd/analytics": "0.5.5",
     "@mpgd/platform": "0.32.0",
-    "@mpgd/catalog": "0.11.3"
+    "@mpgd/catalog": "0.12.0"
   },
   "peerDependencies": {
     "@apple/app-store-server-library": "^3.1.0"