@mpgd/game-services 0.16.0 → 0.17.1

package/dist/client.js

@@ -1,6 +1,8 @@
 import { createORPCClient } from '@orpc/client';
 import { RPCLink } from '@orpc/client/fetch';
 import { createAnalyticsReporter } from '@mpgd/analytics';
+import { isAuthoritativeMicrosoftStoreCompletion } from './authoritative-purchase.js';
+import { isClientRewardEvidence, resolveRewardPlatformImpressionId, } from './admob-client-reward.js';
 import { observeGameServicesOperation } from './operation-progress.js';
 export const gameServicesBackendEndpoints = {
     verifyPurchase: '/game-services/purchases/verify',
@@ -54,6 +56,7 @@ export async function resolveGameServicesRequestHeaders(input) {
 }
 export function createGameServicesClient(input) {
     const now = input.now ?? (() => new Date().toISOString());
+    const requestNow = input.requestNow ?? now;
     const analytics = createAnalyticsReporter({
         target: input.target,
         sessionId: input.analyticsSessionId ?? input.playerId,
@@ -88,7 +91,7 @@ export function createGameServicesClient(input) {
                 if (target === 'verse8') {
                     const status = purchase.status === 'completed' ? 'rejected' : purchase.status;
                     await analytics.track({
-                        name: 'purchase_rejected',
+                        name: purchase.status === 'pending' ? 'purchase_pending' : 'purchase_rejected',
                         properties: {
                             productId: purchaseInput.productId,
                             status,
@@ -123,7 +126,7 @@ export function createGameServicesClient(input) {
                 }
                 if (purchase.status !== 'completed' || purchase.transactionId === undefined) {
                     await analytics.track({
-                        name: 'purchase_rejected',
+                        name: purchase.status === 'pending' ? 'purchase_pending' : 'purchase_rejected',
                         properties: {
                             productId: purchaseInput.productId,
                             status: purchase.status,
@@ -144,14 +147,14 @@ export function createGameServicesClient(input) {
                     productId: purchaseInput.productId,
                     platformTransactionId: purchase.transactionId,
                     idempotencyKey: purchaseInput.idempotencyKey,
-                    purchasedAt: now(),
+                    purchasedAt: requestNow(),
                     ...(purchase.evidence === undefined ? {} : { evidence: purchase.evidence }),
                 };
                 progress.serverRequested();
                 const verification = await input.backend.purchases.verifyPurchase(verificationRequest);
                 progress.serverResult(verification.verified);
                 const result = {
-                    status: verification.verified ? 'granted' : 'rejected',
+                    status: verification.verified ? 'granted' : (verification.disposition ?? 'rejected'),
                     purchase,
                     verification,
                     ...(verification.ledgerEntryId === undefined
@@ -159,7 +162,7 @@ export function createGameServicesClient(input) {
                         : { ledgerEntryId: verification.ledgerEntryId }),
                 };
                 await analytics.track({
-                    name: verification.verified ? 'purchase_granted' : 'purchase_rejected',
+                    name: verification.verified ? 'purchase_granted' : verification.disposition === 'pending' ? 'purchase_pending' : 'purchase_rejected',
                     properties: {
                         productId: purchaseInput.productId,
                         status: result.status,
@@ -196,9 +199,10 @@ export function createGameServicesClient(input) {
                 progress.platformRequested();
                 const reward = await input.gateway.ads.showRewarded(rewardInput);
                 progress.platformResult(reward.status);
-                if (reward.status !== 'completed' || !reward.rewardGranted) {
+                if ((reward.status !== 'completed' || !reward.rewardGranted)
+                    && !isClientRewardEvidence(reward)) {
                     await analytics.track({
-                        name: 'rewarded_ad_rejected',
+                        name: reward.status === 'pending' ? 'rewarded_ad_pending' : 'rewarded_ad_rejected',
                         properties: {
                             placementId: rewardInput.placementId,
                             status: reward.status,
@@ -210,6 +214,7 @@ export function createGameServicesClient(input) {
                         reward,
                     };
                 }
+                const platformImpressionId = resolveRewardPlatformImpressionId(reward);
                 const claimRequest = {
                     target,
                     ...(input.deploymentTarget === undefined || input.deploymentTarget === target
@@ -217,24 +222,24 @@ export function createGameServicesClient(input) {
                         : { deploymentTarget: input.deploymentTarget }),
                     playerId: input.playerId,
                     placementId: rewardInput.placementId,
-                    ...(reward.ledgerEntryId === undefined
+                    ...(platformImpressionId === undefined
                         ? {}
-                        : { platformImpressionId: reward.ledgerEntryId }),
+                        : { platformImpressionId }),
                     idempotencyKey: rewardInput.idempotencyKey,
-                    completedAt: now(),
+                    completedAt: requestNow(),
                     ...(reward.evidence === undefined ? {} : { evidence: reward.evidence }),
                 };
                 progress.serverRequested();
                 const claim = await input.backend.adRewards.claimAdReward(claimRequest);
                 progress.serverResult(claim.granted);
                 const result = {
-                    status: claim.granted ? 'granted' : 'rejected',
+                    status: claim.granted ? 'granted' : (claim.disposition ?? 'rejected'),
                     reward,
                     claim,
                     ...(claim.ledgerEntryId === undefined ? {} : { ledgerEntryId: claim.ledgerEntryId }),
                 };
                 await analytics.track({
-                    name: claim.granted ? 'rewarded_ad_granted' : 'rewarded_ad_rejected',
+                    name: claim.granted ? 'rewarded_ad_granted' : claim.disposition === 'pending' ? 'rewarded_ad_pending' : 'rewarded_ad_rejected',
                     properties: {
                         placementId: rewardInput.placementId,
                         status: result.status,
@@ -402,12 +407,6 @@ function purchaseRejectionReason(purchase) {
     }
     return undefined;
 }
-function isAuthoritativeMicrosoftStoreCompletion(target, purchase) {
-    return target === 'microsoft-store'
-        && purchase.status === 'completed'
-        && purchase.transactionId !== undefined
-        && purchase.authoritativeGrant?.ledgerEntryId === purchase.transactionId;
-}
 function isGameServicesCommerceTarget(target) {
     return target === 'microsoft-store'
         || target === 'android'

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

@@ -0,0 +1,11 @@
+import type { GooglePlayProductPurchaseClient } from './google-play-purchase.js';
+export interface GooglePlayPublisherClientOptions {
+  /** Supplies an androidpublisher-scoped OAuth access token for each request. */
+  readonly getAccessToken: (signal: AbortSignal) => Promise<string> | string;
+  readonly fetch?: typeof fetch;
+}
+/**
+* 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;

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,14 +1,18 @@
 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';
+export * from './admob-client-reward.js';
 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,14 +1,18 @@
 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';
+export * from './admob-client-reward.js';
 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 {};