@mpgd/game-services 0.16.0 → 0.17.0

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

@@ -0,0 +1,113 @@
+const publisherOrigin = 'https://androidpublisher.googleapis.com';
+/**
+ * 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 function createGooglePlayPublisherClient(options) {
+    const requestFetch = options.fetch ?? fetch;
+    async function request(method, path, signal) {
+        const accessToken = await options.getAccessToken(signal);
+        if (accessToken.length === 0 || /[\s\x00-\x1f\x7f]/u.test(accessToken)) {
+            throw new TypeError('Google Play Publisher access token is invalid.');
+        }
+        let response;
+        try {
+            response = await requestFetch(`${publisherOrigin}${path}`, {
+                method,
+                headers: { Authorization: `Bearer ${accessToken}` },
+                redirect: 'error',
+                signal,
+            });
+        }
+        catch {
+            if (signal.aborted) {
+                throw new DOMException('Google Play Publisher request was cancelled.', 'AbortError');
+            }
+            // Fetch errors can contain the request URL (including the purchase token).
+            throw new Error('Google Play Publisher request failed.');
+        }
+        if (!response.ok) {
+            await discardBody(response);
+            // Do not forward an error body or URL: both can contain purchase credentials.
+            throw new Error(`Google Play Publisher request failed (HTTP ${response.status}).`);
+        }
+        return response;
+    }
+    return {
+        async getProductPurchaseV2({ packageName, purchaseToken, signal }) {
+            const path = `${purchasePath(packageName)}/productsv2/tokens/${pathPart(purchaseToken)}`;
+            const response = await request('GET', path, signal);
+            try {
+                return 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 purchase JSON.');
+            }
+        },
+        async acknowledgeProductPurchase({ packageName, productId, purchaseToken, signal }) {
+            const path = `${purchasePath(packageName)}/products/${pathPart(productId)}`
+                + `/tokens/${pathPart(purchaseToken)}:acknowledge`;
+            await discardBody(await request('POST', path, signal));
+        },
+        async consumeProductPurchase({ packageName, productId, purchaseToken, signal }) {
+            const path = `${purchasePath(packageName)}/products/${pathPart(productId)}`
+                + `/tokens/${pathPart(purchaseToken)}:consume`;
+            await discardBody(await request('POST', path, signal));
+        },
+    };
+}
+function purchasePath(packageName) {
+    return `/androidpublisher/v3/applications/${pathPart(packageName)}/purchases`;
+}
+function pathPart(value) {
+    if (value.length === 0
+        || value === '.'
+        || value === '..'
+        || value.trim() !== value
+        || /[\x00-\x1f\x7f]/u.test(value)) {
+        throw new TypeError('Google Play Publisher path parameter is invalid.');
+    }
+    return encodeURIComponent(value);
+}
+async function discardBody(response) {
+    await response.body?.cancel().catch(() => undefined);
+}
+async function readBoundedJson(response) {
+    const body = response.body;
+    if (body === null) {
+        throw new Error('Missing Google Play Publisher response body.');
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done) {
+                break;
+            }
+            size += next.value.byteLength;
+            if (size > 1024 * 1024) {
+                throw new Error('Google Play Publisher response exceeds maximum size.');
+            }
+            chunks.push(next.value);
+        }
+    }
+    catch (error) {
+        await reader.cancel().catch(() => undefined);
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+}

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

@@ -38,3 +38,5 @@ export interface GooglePlayProductPurchaseBoundary extends GameServicesPurchaseG
   verifyPurchase(input: VerifyPurchaseEvidenceInput): ReturnType<GameServicesEvidenceVerifier['verifyPurchase']>;
 }
 export declare function createGooglePlayProductPurchaseBoundary(input: CreateGooglePlayProductPurchaseBoundaryInput): GooglePlayProductPurchaseBoundary;
+/** A non-secret transaction ID for purchases whose Google order ID is absent or delayed. */
+export declare function createGooglePlayTokenTransactionId(purchaseToken: string): Promise<string>;

package/dist/google-play-purchase.js

@@ -45,10 +45,7 @@ export function createGooglePlayProductPurchaseBoundary(input) {
                 purchaseToken,
                 expectedProductId: verificationInput.platformProductId,
                 expectedProductType: verificationInput.product.type,
-                orderMatch: {
-                    mode: 'if-present',
-                    orderId: verificationInput.request.platformTransactionId,
-                },
+                orderMatch: createGooglePlayObservedOrderMatch(verificationInput.request.platformTransactionId, await createGooglePlayTokenTransactionId(purchaseToken)),
                 accountBinding,
                 allowConsumed: false,
                 signal: verificationInput.signal,
@@ -146,7 +143,7 @@ async function finalizeGooglePlayPurchase(input, packageName, purchaseToken, pro
             purchaseToken,
             expectedProductId: finalizationInput.platformProductId,
             expectedProductType: productType,
-            orderMatch: createGooglePlayFinalizationOrderMatch(verifiedContext, finalizationInput.request.platformTransactionId),
+            orderMatch: createGooglePlayFinalizationOrderMatch(verifiedContext, finalizationInput.request.platformTransactionId, await createGooglePlayTokenTransactionId(purchaseToken)),
             accountBinding,
             allowConsumed: true,
             signal: finalizationInput.signal,
@@ -369,15 +366,32 @@ async function inspectGooglePlayPurchase(input) {
         },
     };
 }
-function createGooglePlayFinalizationOrderMatch(verifiedContext, clientOrderId) {
+function createGooglePlayFinalizationOrderMatch(verifiedContext, clientOrderId, tokenTransactionId) {
     if (verifiedContext === undefined) {
-        return { mode: 'if-present', orderId: clientOrderId };
+        return createGooglePlayObservedOrderMatch(clientOrderId, tokenTransactionId);
     }
     if (verifiedContext.orderId === undefined) {
         return { mode: 'token-only' };
     }
     return { mode: 'exact', orderId: verifiedContext.orderId };
 }
+function createGooglePlayObservedOrderMatch(observedTransactionId, tokenTransactionId) {
+    return observedTransactionId === tokenTransactionId
+        ? { mode: 'token-only' }
+        : { mode: 'if-present', orderId: observedTransactionId };
+}
+/** A non-secret transaction ID for purchases whose Google order ID is absent or delayed. */
+export async function createGooglePlayTokenTransactionId(purchaseToken) {
+    if (readOptionalIdentifier(purchaseToken, 4096) === undefined) {
+        throw new TypeError('Google Play purchase token is invalid.');
+    }
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined) {
+        throw new Error('Web Crypto is required to hash Google Play purchase tokens.');
+    }
+    const digest = new Uint8Array(await subtle.digest('SHA-256', new TextEncoder().encode(purchaseToken)));
+    return `play-token-sha256:${[...digest].map((value) => value.toString(16).padStart(2, '0')).join('')}`;
+}
 function readGooglePlayVerifiedContext(payload, packageName, productId, purchaseTokenDigest) {
     if (payload?.googlePlayPackageName !== packageName
         || payload.googlePlayProductId !== productId

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './admob-ssv.js';
 export * from './app-store-verifier.js';
+export * from './app-store-recovery.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
@@ -7,8 +8,10 @@ export * from './contract.js';
 export * from './evidence-verification.js';
 export * from './guest-session.js';
 export * from './google-play-purchase.js';
+export * from './google-play-publisher-client.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';
+export * from './monetization-recovery.js';
 export * from './notification-delivery.js';
 export * from './platform-order.js';
 export * from './progress-link.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './admob-ssv.js';
 export * from './app-store-verifier.js';
+export * from './app-store-recovery.js';
 export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
@@ -7,8 +8,10 @@ export * from './contract.js';
 export * from './evidence-verification.js';
 export * from './guest-session.js';
 export * from './google-play-purchase.js';
+export * from './google-play-publisher-client.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';
+export * from './monetization-recovery.js';
 export * from './notification-delivery.js';
 export * from './platform-order.js';
 export * from './progress-link.js';

package/dist/monetization-recovery.d.ts

@@ -0,0 +1,63 @@
+import type { PurchaseResult, RewardedAdResult } from '@mpgd/platform';
+import { type CreateGameServicesClientInput } from './client.js';
+import type { GameServicesOperationClient, GameServicesPurchaseInput, GameServicesPurchaseResult, GameServicesRewardedAdInput, GameServicesRewardedAdResult } from './operations.js';
+import type { ClaimAdRewardRequest, ClaimAdRewardResponse, VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.js';
+interface OperationIdentity {
+  /** The store must enforce uniqueness across users, not just within one account. */
+  readonly key: string;
+  readonly playerId: string;
+  readonly target: string;
+  readonly deploymentTarget: string;
+  readonly revision: number;
+  /** Fixed when a platform result is first journaled, before backend dispatch. */
+  readonly platformCompletedAt?: string;
+}
+export type MonetizationOperationRecord = (OperationIdentity & {
+  readonly kind: 'purchase';
+  readonly input: GameServicesPurchaseInput;
+  readonly platform?: PurchaseResult;
+  readonly request?: VerifyPurchaseRequest;
+  readonly response?: VerifyPurchaseResponse;
+  readonly result?: GameServicesPurchaseResult;
+}) | (OperationIdentity & {
+  readonly kind: 'rewarded-ad';
+  readonly input: GameServicesRewardedAdInput;
+  readonly platform?: RewardedAdResult;
+  readonly request?: ClaimAdRewardRequest;
+  readonly response?: ClaimAdRewardResponse;
+  readonly result?: GameServicesRewardedAdResult;
+});
+/** Games must supply a durable, atomic implementation; an in-memory map is not recovery. */
+export interface MonetizationOperationStore {
+  /** Atomically insert or return the existing operation for this global key. */
+  reserve(record: MonetizationOperationRecord): Promise<{
+    readonly created: boolean;
+    readonly record: MonetizationOperationRecord;
+  }>;
+  read(key: string): Promise<MonetizationOperationRecord | undefined>;
+  /** Compare-and-swap; reject stale revisions and changes to immutable identity. */
+  replace(expectedRevision: number, record: MonetizationOperationRecord): Promise<void>;
+  /** Return only unresolved operations; keep terminal records addressable by read for deduplication. */
+  listRecoverable(playerId: string): Promise<readonly MonetizationOperationRecord[]>;
+}
+export interface CreateRecoverableMonetizationClientInput extends CreateGameServicesClientInput {
+  readonly operationStore: MonetizationOperationStore;
+}
+export interface MonetizationOperationSummary {
+  readonly kind: MonetizationOperationRecord['kind'];
+  readonly idempotencyKey: string;
+  readonly status: 'pending' | 'granted' | 'rejected' | 'cancelled' | 'failed' | 'skipped' | 'unavailable' | 'action-required';
+  readonly finalizationPending: boolean;
+}
+export interface RecoverableMonetizationClient extends GameServicesOperationClient {
+  recoverPurchaseResult(idempotencyKey: string, platform: PurchaseResult): Promise<GameServicesPurchaseResult>;
+  recoverRewardResult(idempotencyKey: string, platform: RewardedAdResult): Promise<GameServicesRewardedAdResult>;
+  reconcile(): Promise<readonly MonetizationOperationSummary[]>;
+}
+/**
+* Client-side recovery coordinates UI callbacks and authoritative backend calls.
+* It never grants a wallet locally. Journal evidence can contain receipts/tokens,
+* so the game's durable store must encrypt and access-control its records.
+*/
+export declare function createRecoverableMonetizationClient(input: CreateRecoverableMonetizationClientInput): RecoverableMonetizationClient;
+export {};