@mpgd/game-services 0.23.0 → 0.24.0

package/dist/monetization-operation-store.d.ts

@@ -1,14 +1,23 @@
-import type { MonetizationOperationRecord, MonetizationOperationStore } from './monetization-recovery.js';
+import type { MonetizationOperationRecord, MonetizationOperationStore, RetiredPurchaseOperationRecord } from './monetization-recovery.js';
 /**
 * Whether a journal record still needs a reconcile pass. A game's durable
 * `MonetizationOperationStore.listRecoverable` applies this rule (or an
-* equivalent index): a v1 purchase or rewarded-ad record is open until it
-* holds a non-pending result with no pending finalization; a commerce v2
-* purchase record is open until its state is terminal (`finished`,
-* `cancelled`, `failed`, `rejected`, `revoked`). Terminal records stay
-* addressable by `read` for duplicate protection.
+* equivalent index): a rewarded-ad record is open until it holds a
+* non-pending result; a commerce purchase record is open until its state is
+* terminal (`finished`, `cancelled`, `failed`, `rejected`, `revoked`). A
+* retired v1 `purchase` record (written before commerce v2 C4) is open only
+* while it holds a completed platform result and either no terminal result or
+* a grant whose finalization is still pending: the recoverable client sends
+* its verification to the backend once more and closes it. Terminal records stay addressable by `read` for duplicate
+* protection.
 */
 export declare function isMonetizationOperationRecoverable(record: MonetizationOperationRecord): boolean;
+/**
+* A retired v1 purchase record whose backend verification was never settled,
+* or whose grant still waits for the backend to consume or acknowledge the
+* store purchase (`response.finalization.status === 'pending'`).
+*/
+export declare function isRetiredPurchaseOpen(record: RetiredPurchaseOperationRecord): boolean;
 /** Whether a commerce v2 record holds a ledger grant the revocation pass should keep checking. */
 export declare function isMonetizationOperationGranted(record: MonetizationOperationRecord): boolean;
 /**

package/dist/monetization-operation-store.js

@@ -2,20 +2,35 @@ import { isTerminalCommercePurchaseState } from '@mpgd/platform/commerce';
 /**
  * Whether a journal record still needs a reconcile pass. A game's durable
  * `MonetizationOperationStore.listRecoverable` applies this rule (or an
- * equivalent index): a v1 purchase or rewarded-ad record is open until it
- * holds a non-pending result with no pending finalization; a commerce v2
- * purchase record is open until its state is terminal (`finished`,
- * `cancelled`, `failed`, `rejected`, `revoked`). Terminal records stay
- * addressable by `read` for duplicate protection.
+ * equivalent index): a rewarded-ad record is open until it holds a
+ * non-pending result; a commerce purchase record is open until its state is
+ * terminal (`finished`, `cancelled`, `failed`, `rejected`, `revoked`). A
+ * retired v1 `purchase` record (written before commerce v2 C4) is open only
+ * while it holds a completed platform result and either no terminal result or
+ * a grant whose finalization is still pending: the recoverable client sends
+ * its verification to the backend once more and closes it. Terminal records stay addressable by `read` for duplicate
+ * protection.
  */
 export function isMonetizationOperationRecoverable(record) {
     if (record.kind === 'commerce-purchase') {
         return !isTerminalCommercePurchaseState(record.state);
     }
-    if (record.result === undefined || record.result.status === 'pending') {
-        return true;
+    if (record.kind === 'purchase') {
+        return isRetiredPurchaseOpen(record);
     }
-    return record.kind === 'purchase' && record.response?.finalization?.status === 'pending';
+    return record.result === undefined || record.result.status === 'pending';
+}
+/**
+ * A retired v1 purchase record whose backend verification was never settled,
+ * or whose grant still waits for the backend to consume or acknowledge the
+ * store purchase (`response.finalization.status === 'pending'`).
+ */
+export function isRetiredPurchaseOpen(record) {
+    return record.platform?.status === 'completed'
+        && record.platform.transactionId !== undefined
+        && (record.result === undefined
+            || record.result.status === 'pending'
+            || record.response?.finalization?.status === 'pending');
 }
 /** Whether a commerce v2 record holds a ledger grant the revocation pass should keep checking. */
 export function isMonetizationOperationGranted(record) {

package/dist/monetization-recovery.d.ts

@@ -13,27 +13,42 @@ interface OperationIdentity {
   /** Fixed when a platform result is first journaled, before backend dispatch. */
   readonly platformCompletedAt?: string;
 }
-/** The v1 purchase and rewarded-ad journal records. */
-export type LegacyMonetizationOperationRecord = (OperationIdentity & {
+/**
+* The v1 purchase journal record. Releases before commerce v2 C4 wrote them;
+* the reconciler is now the only purchase path, so nothing starts, reopens, or
+* grants from one. A durable journal still parses it, and the one thing
+* `reconcile()` still does with it is finish an in-flight verification: a
+* record that holds a completed platform result and no terminal result sends
+* its saved verify request (or the one its own fields describe) to the
+* backend once more, through the ledger and under the same idempotency key,
+* then closes the record with what the backend answered. A record without a
+* completed platform result is closed without a request: whatever the store
+* still holds is found again from the store's own unfinished list.
+*/
+export type RetiredPurchaseOperationRecord = OperationIdentity & {
   readonly kind: 'purchase';
   readonly input: GameServicesPurchaseInput;
   readonly platform?: PurchaseResult;
   readonly request?: VerifyPurchaseRequest;
   readonly response?: VerifyPurchaseResponse;
   readonly result?: GameServicesPurchaseResult;
-}) | (OperationIdentity & {
+};
+/** The rewarded-ad journal record. */
+export type RewardedAdOperationRecord = OperationIdentity & {
   readonly kind: 'rewarded-ad';
   readonly input: GameServicesRewardedAdInput;
   readonly platform?: RewardedAdResult;
   readonly request?: ClaimAdRewardRequest;
   readonly response?: ClaimAdRewardResponse;
   readonly result?: GameServicesRewardedAdResult;
-});
+};
+/** The pre-reconciler journal records: a retired purchase record and the live rewarded-ad record. */
+export type LegacyMonetizationOperationRecord = RetiredPurchaseOperationRecord | RewardedAdOperationRecord;
 /**
 * Every record kind the journal holds. `commerce-purchase` records are the
-* commerce v2 reconciler's (`./commerce-reconciler`); their open state is
-* `state`, not `result`, and `isMonetizationOperationRecoverable` applies the
-* rule for every kind.
+* reconciler's (`./commerce-reconciler`); their open state is `state`, not
+* `result`, and `isMonetizationOperationRecoverable` applies the rule for
+* every kind.
 */
 export type MonetizationOperationRecord = LegacyMonetizationOperationRecord | CommercePurchaseOperationRecord;
 /** Games must supply a durable, atomic implementation; an in-memory map is not recovery. */
@@ -49,13 +64,13 @@ export interface MonetizationOperationStore {
   /** Return only unresolved operations; keep terminal records addressable by read for deduplication. */
   listRecoverable(playerId: string): Promise<readonly MonetizationOperationRecord[]>;
   /**
-  * Commerce v2 records in `granted`, `finishing`, or `finished` kept within
+  * Reconciler records in `granted`, `finishing`, or `finished` kept within
   * the journal retention window, for the reconciler's revocation pass. A
   * store without it only reports reversals of grants seen in this session.
   */
   listGranted?(playerId: string): Promise<readonly MonetizationOperationRecord[]>;
   /**
-  * The commerce v2 record, terminal or not, whose `purchase.transactionId`
+  * The reconciler record, terminal or not, whose `purchase.transactionId`
   * is this store transaction. With it a transaction the store lists again
   * after a restart (an owned durable, a rejected or finished purchase) meets
   * its own record instead of being verified again under a derived key.
@@ -75,7 +90,7 @@ export interface MonetizationOperationSummary {
   readonly kind: MonetizationOperationRecord['kind'];
   readonly idempotencyKey: string;
   /**
-  * RFC "Purchase lifecycle" mapping for a commerce v2 record: `granted`
+  * RFC "Purchase lifecycle" mapping for a reconciler record: `granted`
   * covers `granted`, `finishing`, and `finished`; `pending` covers
   * `launched`, `pending`, `purchased`, and `verifying`; `revoked` is a
   * reversed grant.
@@ -84,29 +99,19 @@ export interface MonetizationOperationSummary {
   readonly finalizationPending: boolean;
 }
 export interface RecoverableMonetizationClient extends GameServicesOperationClient {
-  /**
-  * Replays a platform purchase callback into a v1 journal record.
-  *
-  * @deprecated For a gateway with a commerce v2 provider the reconciler
-  * learns the result from the provider itself: this call then runs one
-  * reconcile pass and returns the journaled result for the key, ignoring
-  * `platform`. Removed with the v1 adapter in C4.
-  */
-  recoverPurchaseResult(idempotencyKey: string, platform: PurchaseResult): Promise<GameServicesPurchaseResult>;
   recoverRewardResult(idempotencyKey: string, platform: RewardedAdResult): Promise<GameServicesRewardedAdResult>;
   /**
-  * Startup and app-resume recovery: resumes v1 records and, with a commerce
-  * v2 provider, starts or runs the reconciler (subscribe, read available
+  * Startup and app-resume recovery: resumes rewarded-ad records and, with a
+  * commerce provider, starts or runs the reconciler (subscribe, read available
   * purchases, send saved verify requests, finish granted purchases).
   */
   reconcile(): Promise<readonly MonetizationOperationSummary[]>;
   /**
-  * The manual restore trigger of the commerce v2 reconciler
-  * (`provider.restorePurchases` when offered, then a pass). Without a v2
-  * provider it is `reconcile()`.
+  * The manual restore trigger of the reconciler (`provider.restorePurchases`
+  * when offered, then a pass). Without a commerce provider it is `reconcile()`.
   */
   restorePurchases(): Promise<readonly MonetizationOperationSummary[]>;
-  /** Present when the gateway exposes `commerceV2`. */
+  /** Present when the gateway exposes `commerce`. */
   readonly commerceReconciler?: CommerceReconciler;
 }
 /**