@mpgd/game-services 0.28.1 → 0.30.0

package/dist/commerce-reconciler.js

@@ -461,22 +461,49 @@ export function createCommerceReconciler(input) {
         trigger();
         scheduleRun();
     };
-    const readAvailable = async (capabilitiesNow) => {
+    /**
+     * Reads the store's available purchases into the inbox. `restore` is the
+     * player's Restore Purchases read only: the store also lists owned
+     * non-consumables its recovery list hides (acknowledged on Play, bound to
+     * another guest's token on StoreKit), so a reinstall or a new device can
+     * restore them. Startup and resume recovery never set it, so an
+     * acknowledged durable is not sent again on every launch.
+     */
+    const readAvailable = async (capabilitiesNow, restore = false) => {
         if (!capabilitiesNow.lifecycle.availablePurchases) {
             return true;
         }
-        try {
+        const read = async (withRestore) => {
             const available = await provider.getAvailablePurchases({
                 includePending: capabilitiesNow.lifecycle.pending,
+                ...(withRestore ? { restore: true } : {}),
             });
             for (const purchase of available) {
                 inbox.push({ type: 'purchaseUpdated', purchase });
             }
+        };
+        try {
+            await read(restore);
             return true;
         }
         catch (error) {
+            if (!restore) {
+                fail('available', error);
+                return false;
+            }
+            // A failed restore read still makes the recovery read, so Restore
+            // Purchases never finds less than a recovery pass: a bridge host built
+            // before `restore` rejects the field, and a store may fail only the
+            // wider read. The restore failure is still reported.
             fail('available', error);
-            return false;
+            try {
+                await read(false);
+                return true;
+            }
+            catch (fallbackError) {
+                fail('available', fallbackError);
+                return false;
+            }
         }
     };
     const buildRequest = (record) => {
@@ -497,6 +524,11 @@ export function createCommerceReconciler(input) {
             idempotencyKey: record.idempotencyKey,
             purchasedAt: purchase.purchasedAt ?? now(),
             evidence: purchase.evidence,
+            // A purchase the store reported without this journal starting it (a
+            // reinstall, a new device, Restore Purchases) is a restore: the backend
+            // may grant this player a non-consumable bound to another guest (RFC
+            // "Restore sharing"). A purchase the game started never asks for it.
+            ...(record.origin === 'discovered' ? { intent: 'restore' } : {}),
         };
     };
     // Reconciler step 2: match a reported purchase to a journal record.
@@ -847,7 +879,8 @@ export function createCommerceReconciler(input) {
         // read again until it succeeds, so a purchase that predates the
         // subscription is not missed for the session.
         if (capabilitiesNow !== undefined && (!capabilitiesNow.lifecycle.events || initialScanPending)) {
-            initialScanPending = !(await readAvailable(capabilitiesNow)) && capabilitiesNow.lifecycle.events;
+            initialScanPending = !(await readAvailable(capabilitiesNow, options.restore === true))
+                && capabilitiesNow.lifecycle.events;
         }
         // An event for a product whose store call is still running waits for that
         // call to journal the store answer: matched then, it is never journaled
@@ -1292,11 +1325,18 @@ export function createCommerceReconciler(input) {
                     await loadRecords();
                 }
                 const capabilitiesNow = await readCapabilities(true);
-                // A polled provider is read by the pass itself.
+                // A polled provider is read by the pass itself. Either read is a
+                // restore read: owned non-consumables the store's recovery list
+                // hides (a reinstall, a new device) reach the backend as restores.
+                let restoreRead = false;
                 if (capabilitiesNow !== undefined && capabilitiesNow.lifecycle.events) {
-                    await readAvailable(capabilitiesNow);
+                    restoreRead = await readAvailable(capabilitiesNow, true);
+                    if (restoreRead) {
+                        // This read covers a start-time read that failed.
+                        initialScanPending = false;
+                    }
                 }
-                await pass({ explicit: true, refreshCapabilities: false });
+                await pass({ explicit: true, refreshCapabilities: false, restore: !restoreRead });
             });
             await runUntilIdle();
         },

package/dist/evidence-verification.d.ts

@@ -24,6 +24,25 @@ export type EvidenceVerificationDecision = {
   readonly ledgerEntryId: string;
   /** The ledger target the entry was written under when it is not the request's target. */
   readonly ledgerTarget?: string;
+} | {
+  /**
+  * The store verified a restored non-consumable, but its account
+  * binding (Google Play `obfuscatedAccountId` / `obfuscatedProfileId`,
+  * StoreKit `appAccountToken`) names another account than the
+  * requesting player's, or none: the player reinstalled or moved to a
+  * new device and is a new guest (RFC "Restore sharing"). Every other
+  * check passed. The reference verifiers answer it only for a request
+  * with `intent: 'restore'` of a non-consumable; the backend then grants
+  * the player its own share under its `restoreSharing` policy, or
+  * answers `rejected` with `reason` (the binding mismatch) when the
+  * policy refuses. Fields are those of `verified`.
+  */
+  readonly status: 'restorable';
+  readonly reason: string;
+  readonly verificationId: string;
+  readonly verifiedAt: string;
+  readonly payload?: EntitlementLedgerPayload;
+  readonly platformEvidenceId?: string | null;
 } | {
   readonly status: 'pending';
   readonly reason?: string;

package/dist/google-play-publisher-client.d.ts

@@ -1,4 +1,5 @@
 import type { GooglePlayProductPurchaseClient } from './google-play-purchase.js';
+import type { GooglePlayVoidedPurchasesClient } from './google-play-store-server.js';
 export interface GooglePlayPublisherClientOptions {
   /** Supplies an androidpublisher-scoped OAuth access token for each request. */
   readonly getAccessToken: (signal: AbortSignal) => Promise<string> | string;
@@ -8,4 +9,4 @@ export interface GooglePlayPublisherClientOptions {
 * Google Play purchase verification and post-ledger finalization transport.
 * The caller owns OAuth credential rotation and must never expose this client to the game.
 */
-export declare function createGooglePlayPublisherClient(options: GooglePlayPublisherClientOptions): GooglePlayProductPurchaseClient;
+export declare function createGooglePlayPublisherClient(options: GooglePlayPublisherClientOptions): GooglePlayProductPurchaseClient & GooglePlayVoidedPurchasesClient;

package/dist/google-play-publisher-client.js

@@ -59,8 +59,88 @@ export function createGooglePlayPublisherClient(options) {
                 + `/tokens/${pathPart(purchaseToken)}:consume`;
             await discardBody(await request('POST', path, signal));
         },
+        async listVoidedPurchases({ packageName, startTimeMillis, endTimeMillis, pageToken, maxResults, signal, }) {
+            // purchases.voidedpurchases.list, in-app products only (type 0, the
+            // default): https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.voidedpurchases/list
+            const query = new URLSearchParams();
+            if (pageToken === undefined) {
+                query.set('startTime', String(readMillis(startTimeMillis, 'startTimeMillis')));
+                query.set('endTime', String(readMillis(endTimeMillis, 'endTimeMillis')));
+            }
+            else {
+                query.set('token', pageToken);
+            }
+            if (maxResults !== undefined) {
+                if (!Number.isSafeInteger(maxResults) || maxResults < 1 || maxResults > 1000) {
+                    throw new RangeError('maxResults must be an integer from 1 to 1000.');
+                }
+                query.set('maxResults', String(maxResults));
+            }
+            const response = await request('GET', `${purchasePath(packageName)}/voidedpurchases?${query.toString()}`, signal);
+            let body;
+            try {
+                body = await readBoundedJson(response);
+            }
+            catch {
+                if (signal.aborted) {
+                    throw new DOMException('Google Play Publisher request was cancelled.', 'AbortError');
+                }
+                throw new Error('Google Play Publisher returned invalid voided purchases JSON.');
+            }
+            return readVoidedPurchasesPage(body);
+        },
     };
 }
+function readMillis(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${label} must be a non-negative integer of milliseconds.`);
+    }
+    return value;
+}
+function readVoidedPurchasesPage(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        throw new Error('Google Play Publisher returned an invalid voided purchases page.');
+    }
+    const record = body;
+    const entries = record.voidedPurchases ?? [];
+    if (!Array.isArray(entries)) {
+        throw new Error('Google Play Publisher returned an invalid voided purchases page.');
+    }
+    const voidedPurchases = [];
+    let droppedEntries = 0;
+    for (const entry of entries) {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            droppedEntries += 1;
+            continue;
+        }
+        const item = entry;
+        if (typeof item.purchaseToken !== 'string' || item.purchaseToken.length === 0) {
+            droppedEntries += 1;
+            continue;
+        }
+        voidedPurchases.push({
+            purchaseToken: item.purchaseToken,
+            ...(typeof item.orderId === 'string' ? { orderId: item.orderId } : {}),
+            ...pickMillisOrCode(item, 'voidedTimeMillis'),
+            ...pickMillisOrCode(item, 'purchaseTimeMillis'),
+            ...pickMillisOrCode(item, 'voidedSource'),
+            ...pickMillisOrCode(item, 'voidedReason'),
+        });
+    }
+    const pagination = record.tokenPagination;
+    const nextPageToken = typeof pagination === 'object' && pagination !== null
+        ? pagination.nextPageToken
+        : undefined;
+    return {
+        voidedPurchases,
+        ...(typeof nextPageToken === 'string' && nextPageToken.length > 0 ? { nextPageToken } : {}),
+        ...(droppedEntries === 0 ? {} : { droppedEntries }),
+    };
+}
+function pickMillisOrCode(item, key) {
+    const value = item[key];
+    return typeof value === 'string' || typeof value === 'number' ? { [key]: value } : {};
+}
 function purchasePath(packageName) {
     return `/androidpublisher/v3/applications/${pathPart(packageName)}/purchases`;
 }

package/dist/google-play-purchase.d.ts

@@ -38,3 +38,10 @@ export interface GooglePlayProductPurchaseBoundary extends GameServicesPurchaseG
   verifyPurchase(input: VerifyPurchaseEvidenceInput): ReturnType<GameServicesEvidenceVerifier['verifyPurchase']>;
 }
 export declare function createGooglePlayProductPurchaseBoundary(input: CreateGooglePlayProductPurchaseBoundaryInput): GooglePlayProductPurchaseBoundary;
+/**
+* The ledger's authority identity of a Play one-time purchase: what
+* `verifyPurchase` records as `evidenceVerificationId`. Store-side handlers
+* (voided purchases, RTDN) find the grant of a purchase token with it, so the
+* raw token never needs to be stored in the ledger.
+*/
+export declare function createGooglePlayProductVerificationId(packageName: string, purchaseToken: string): Promise<string>;

package/dist/google-play-purchase.js

@@ -49,18 +49,25 @@ export function createGooglePlayProductPurchaseBoundary(input) {
                 orderMatch: createGooglePlayObservedOrderMatch(verificationInput.request.platformTransactionId, await createGooglePlayTokenPurchaseKey(purchaseToken)),
                 accountBinding,
                 allowConsumed: false,
+                // A restored non-consumable bound to an earlier player (a reinstall,
+                // a new device) is reported, not refused: the backend's restore
+                // sharing policy decides (RFC "Restore sharing").
+                reportForeignBinding: verificationInput.request.intent === 'restore'
+                    && verificationInput.product.type === 'non_consumable',
                 signal: verificationInput.signal,
             });
             if (inspection.status !== 'verified') {
                 return inspection;
             }
-            return {
-                status: 'verified',
+            const verified = {
                 verificationId: createGooglePlayVerificationId(inspection.purchase.purchaseTokenDigest),
                 verifiedAt: now(),
                 platformEvidenceId: inspection.purchase.orderId ?? null,
                 payload: createVerificationPayload(packageName, inspection.purchase),
             };
+            return inspection.foreignBinding === undefined
+                ? { status: 'verified', ...verified }
+                : { status: 'restorable', reason: inspection.foreignBinding, ...verified };
         },
         async finalizePurchaseGrant(finalizationInput) {
             if (finalizationInput.product.type === 'subscription') {
@@ -318,6 +325,7 @@ async function inspectGooglePlayPurchase(input) {
         && obfuscatedExternalProfileId === undefined) {
         return rejected('GOOGLE_PLAY_PROFILE_INVALID');
     }
+    let foreignBinding;
     if (input.accountBinding.status === 'bound') {
         // Defensive invariant: every bound context must carry at least one
         // identifier, even though the constructors below already enforce it.
@@ -325,19 +333,26 @@ async function inspectGooglePlayPurchase(input) {
             && input.accountBinding.profileId === undefined) {
             return rejected('GOOGLE_PLAY_ACCOUNT_BINDING_REQUIRED');
         }
+        // A purchase made outside the app (a promo code) carries no ids at all
+        // ("purchases made outside your app won't have these identifiers set").
         if (input.accountBinding.accountId !== undefined
             && obfuscatedExternalAccountId !== input.accountBinding.accountId) {
-            return rejected('GOOGLE_PLAY_ACCOUNT_MISMATCH');
+            foreignBinding = 'GOOGLE_PLAY_ACCOUNT_MISMATCH';
         }
-        if (input.accountBinding.profileId !== undefined
+        else if (input.accountBinding.profileId !== undefined
             && obfuscatedExternalProfileId !== input.accountBinding.profileId) {
-            return rejected('GOOGLE_PLAY_PROFILE_MISMATCH');
+            foreignBinding = 'GOOGLE_PLAY_PROFILE_MISMATCH';
+        }
+        if (foreignBinding !== undefined && input.reportForeignBinding !== true) {
+            return rejected(foreignBinding);
         }
-        if (input.accountBinding.profileId === undefined
+        if (foreignBinding === undefined
+            && input.accountBinding.profileId === undefined
             && obfuscatedExternalProfileId !== undefined) {
             return rejected('GOOGLE_PLAY_PROFILE_BINDING_REQUIRED');
         }
-        if (input.accountBinding.accountId === undefined
+        if (foreignBinding === undefined
+            && input.accountBinding.accountId === undefined
             && obfuscatedExternalAccountId !== undefined) {
             return rejected('GOOGLE_PLAY_ACCOUNT_BINDING_REQUIRED');
         }
@@ -350,6 +365,7 @@ async function inspectGooglePlayPurchase(input) {
     }
     return {
         status: 'verified',
+        ...(foreignBinding === undefined ? {} : { foreignBinding }),
         purchase: {
             purchaseToken: input.purchaseToken,
             purchaseTokenDigest: await digestPurchaseToken(input.packageName, input.purchaseToken),
@@ -545,6 +561,15 @@ async function digestPurchaseToken(packageName, purchaseToken) {
     const digest = new Uint8Array(await subtle.digest('SHA-256', bytes));
     return [...digest].map((value) => value.toString(16).padStart(2, '0')).join('');
 }
+/**
+ * The ledger's authority identity of a Play one-time purchase: what
+ * `verifyPurchase` records as `evidenceVerificationId`. Store-side handlers
+ * (voided purchases, RTDN) find the grant of a purchase token with it, so the
+ * raw token never needs to be stored in the ledger.
+ */
+export async function createGooglePlayProductVerificationId(packageName, purchaseToken) {
+    return createGooglePlayVerificationId(await digestPurchaseToken(packageName, purchaseToken));
+}
 function createGooglePlayVerificationId(purchaseTokenDigest) {
     return `google-play:product:${purchaseTokenDigest}`;
 }

package/dist/google-play-store-server.d.ts

@@ -0,0 +1,160 @@
+import type { GameServicesPurchaseGrantFinalizer } from './evidence-verification.js';
+import type { GameServicesStore } from './server.js';
+import type { PurchaseGrantFinalization } from './types.js';
+/**
+* Server-side Google Play upkeep that does not wait for the game client:
+* revoking grants of voided purchases (refunds, chargebacks, Play's own
+* refund of a purchase left unacknowledged) and retrying the acknowledge or
+* consume of a grant whose client went away. Both read the ledger the
+* purchase verifier wrote; neither grants anything.
+*
+* - Voided Purchases API: https://developers.google.com/android-publisher/voided-purchases
+* - Three-day acknowledgement window: https://developer.android.com/google/play/billing/integrate#process
+*/
+/** One entry of `purchases.voidedpurchases.list` (in-app products, `type=0`). */
+export interface GooglePlayVoidedPurchase {
+  readonly purchaseToken: string;
+  readonly orderId?: string;
+  /** Milliseconds since the epoch, as Google's int64 string or a number. */
+  readonly voidedTimeMillis?: string | number;
+  readonly purchaseTimeMillis?: string | number;
+  /** 0 user, 1 developer, 2 Google. */
+  readonly voidedSource?: string | number;
+  /**
+  * 0 other, 1 remorse, 2 not received, 3 defective, 4 accidental purchase,
+  * 5 fraud, 6 friendly fraud, 7 chargeback, 8 unacknowledged purchase.
+  */
+  readonly voidedReason?: string | number;
+}
+export interface GooglePlayVoidedPurchasesPage {
+  readonly voidedPurchases: readonly GooglePlayVoidedPurchase[];
+  readonly nextPageToken?: string;
+  /** Entries of the page the client could not read (no purchase token); reported, never revoked. */
+  readonly droppedEntries?: number;
+}
+export interface GooglePlayVoidedPurchasesClient {
+  /**
+  * One page of voided in-app purchases. `startTimeMillis` and
+  * `endTimeMillis` filter on when Google recorded the void, at most 30 days
+  * back; Google ignores them when `pageToken` is set.
+  */
+  listVoidedPurchases(input: {
+    readonly packageName: string;
+    readonly startTimeMillis: number;
+    readonly endTimeMillis: number;
+    readonly pageToken?: string;
+    readonly maxResults?: number;
+    readonly signal: AbortSignal;
+  }): Promise<GooglePlayVoidedPurchasesPage>;
+}
+export type GooglePlayVoidedPurchaseOutcome = {
+  readonly status: 'revoked';
+  readonly ledgerEntryId: string;
+  readonly alreadyProcessed: boolean;
+}
+/** No purchase grant of this token on this ledger (granted elsewhere, or never). */
+| {
+  readonly status: 'grant_not_found';
+}
+/** The ledger refused the revocation; logged, not retried. */
+| {
+  readonly status: 'conflict';
+  readonly reason: string;
+} | {
+  readonly status: 'invalid';
+  readonly reason: string;
+};
+/** Google keeps voided purchases for 30 days. */
+export declare const googlePlayVoidedPurchasesWindowMs: number;
+/**
+* Kept off the oldest edge of that window: Google refuses a `startTime` older
+* than 30 days at the time it receives the request, which is a little after
+* the caller's clock read.
+*/
+export declare const googlePlayVoidedPurchasesWindowSlackMs = 60000;
+/**
+* Appends the `revoke` entry for one voided purchase. The grant is found by
+* the purchase token's verification id, so the revocation is keyed by the
+* token: a purchase seen again by a later sweep (or an RTDN message) answers
+* the first entry with `alreadyProcessed`.
+*/
+export declare function revokeGooglePlayVoidedPurchase(input: {
+  readonly store: GameServicesStore;
+  readonly packageName: string;
+  readonly voided: GooglePlayVoidedPurchase;
+  readonly now?: () => string;
+}): Promise<GooglePlayVoidedPurchaseOutcome>;
+export interface SweepGooglePlayVoidedPurchasesInput {
+  readonly client: GooglePlayVoidedPurchasesClient;
+  readonly store: GameServicesStore;
+  readonly packageName: string;
+  /** Raised to Google's 30-day window, measured from `now` (`clamped` reports it). */
+  readonly startTimeMillis: number;
+  readonly endTimeMillis: number;
+  readonly signal: AbortSignal;
+  /**
+  * Pages read before the sweep stops as incomplete; 10 by default. A window
+  * that does not fit is not finished by repeating it (the listing does not
+  * shrink as grants are revoked): raise the cap or split the window into
+  * shorter ones.
+  */
+  readonly maxPages?: number;
+  /** Asked before every page and voided purchase; `false` stops the sweep as incomplete. */
+  readonly shouldContinue?: (next: 'page' | 'purchase') => boolean;
+  /** The clock, for the revocation time of a void without one and the 30-day window. */
+  readonly now?: () => string;
+  /** Every voided purchase's outcome; the purchase token is left out so it can be logged. */
+  readonly onOutcome?: (voided: Omit<GooglePlayVoidedPurchase, 'purchaseToken'>, outcome: GooglePlayVoidedPurchaseOutcome | {
+    readonly status: 'error';
+    readonly reason: 'GOOGLE_PLAY_VOIDED_STORE_ERROR';
+    /** The error's name and message; store errors carry no purchase token. */
+    readonly detail: string;
+  }) => void;
+}
+export interface GooglePlayVoidedPurchasesSweep {
+  /**
+  * Every page in the window was read and every entry applied or refused;
+  * the caller may advance its cursor to `endTimeMillis`. A store error on
+  * an entry (`errored`) leaves the sweep incomplete, since reading the window
+  * again retries it. Entries counted in `failed` are not retried that way:
+  * they need an operator (see `onOutcome`).
+  */
+  readonly complete: boolean;
+  /** The requested start was older than Google keeps and was raised: voids before it are gone. */
+  readonly clamped: boolean;
+  readonly pages: number;
+  readonly revoked: number;
+  readonly alreadyProcessed: number;
+  readonly notFound: number;
+  /** Ledger refusals and unreadable entries. */
+  readonly failed: number;
+  /** Entries a store error kept from being applied; the window must be read again. */
+  readonly errored: number;
+}
+/**
+* Reads the voided purchases of one time window and revokes their grants.
+* The sweep is the reliable path even next to RTDN, because a Pub/Sub push
+* can be missed: run it on a schedule with a window that overlaps the last
+* complete one (revocations are idempotent per token). An incomplete sweep
+* (page budget, `shouldContinue`) must be repeated from the same start.
+*/
+export declare function sweepGooglePlayVoidedPurchases(input: SweepGooglePlayVoidedPurchasesInput): Promise<GooglePlayVoidedPurchasesSweep>;
+/**
+* Retries the acknowledge or consume of a durable Play grant from the ledger
+* entry and the purchase token the Worker kept for it (the ledger itself
+* stores only the token digest). The finalizer is the same Play boundary the
+* purchase path uses, so the provider state is re-read before acting and an
+* already completed purchase answers `completed`. A grant that was reversed
+* is never finalized: Google is refunding it.
+*/
+export declare function retryGooglePlayPurchaseFinalization(input: {
+  readonly finalizer: GameServicesPurchaseGrantFinalizer;
+  readonly store: GameServicesStore;
+  readonly ledgerEntryId: string;
+  readonly purchaseToken: string;
+  readonly signal: AbortSignal;
+  readonly timeoutMs: number;
+}): Promise<PurchaseGrantFinalization | {
+  readonly status: 'abandoned';
+  readonly reason: string;
+}>;