@mpgd/game-services 0.9.0 → 0.10.0

package/dist/server.js

@@ -4,7 +4,7 @@ import { createAnalyticsReporter } from '@mpgd/analytics';
 import { gameServicesBackendEndpoints, } from './client';
 import { gameServicesContract } from './contract';
 import { createRejectingGameServicesEvidenceVerifier, } from './evidence-verification';
-import { assertClaimAdRewardRequest, assertClaimAdRewardResponse, assertEntitlementLedgerGrant, assertEntitlementLedgerResult, assertLeaderboardScoreTransaction, assertProductGrantTransaction, assertRecordLeaderboardScoreRequest, assertRecordLeaderboardScoreResponse, assertVerifyPurchaseRequest, assertVerifyPurchaseResponse, } from './types';
+import { assertClaimAdRewardRequest, assertClaimAdRewardResponse, assertEntitlementLedgerGrant, assertEntitlementLedgerResult, assertLeaderboardScoreTransaction, assertProductGrantTransaction, assertPurchaseGrantFinalization, assertRecordLeaderboardScoreRequest, assertRecordLeaderboardScoreResponse, assertVerifyPurchaseRequest, assertVerifyPurchaseResponse, } from './types';
 export class InMemoryGameServicesStore {
     entitlementTransactionsByKey = new Map();
     entitlementTransactionsByEvidence = new Map();
@@ -129,6 +129,7 @@ export function createGameServicesBackend(input) {
     const version = input.version ?? '0.0.0';
     const evidenceVerifier = input.evidenceVerifier ?? createRejectingGameServicesEvidenceVerifier();
     const evidenceVerificationTimeoutMs = resolveEvidenceVerificationTimeout(input.evidenceVerificationTimeoutMs);
+    const purchaseGrantFinalizationTimeoutMs = resolvePurchaseGrantFinalizationTimeout(input.purchaseGrantFinalizationTimeoutMs);
     const analytics = createAnalyticsReporter({
         target: 'server',
         sessionId: input.analyticsSessionId ?? 'game-services',
@@ -145,6 +146,10 @@ export function createGameServicesBackend(input) {
                     now,
                     evidenceVerifier,
                     evidenceVerificationTimeoutMs,
+                    purchaseGrantFinalizationTimeoutMs,
+                    ...(input.purchaseGrantFinalizer === undefined
+                        ? {}
+                        : { purchaseGrantFinalizer: input.purchaseGrantFinalizer }),
                 });
                 await analytics.track({
                     name: verification.verified ? 'purchase_granted' : 'purchase_rejected',
@@ -155,6 +160,10 @@ export function createGameServicesBackend(input) {
                         ledgerEntryId: verification.ledgerEntryId,
                         alreadyProcessed: verification.alreadyProcessed,
                         reason: verification.reason,
+                        finalizationStatus: verification.finalization?.status,
+                        finalizationAction: verification.finalization?.action,
+                        finalizationAlreadyCompleted: verification.finalization?.alreadyCompleted,
+                        finalizationReason: verification.finalization?.reason,
                     },
                 });
                 return verification;
@@ -313,20 +322,25 @@ async function verifyPurchaseWithStore(input, context) {
         grantId: request.productId,
         target: request.target,
     };
-    const existing = await findEntitlementTransactionByIdempotency(context.store, retryIdentity);
-    if (existing !== undefined) {
-        if (!matchesEntitlementRetry(existing, retryIdentity)) {
+    const completeExistingRetry = async (transaction) => {
+        if (!matchesEntitlementRetry(transaction, retryIdentity)) {
             return assertVerifyPurchaseResponse({
                 verified: false,
                 alreadyProcessed: false,
                 reason: 'IDEMPOTENCY_KEY_CONFLICT',
             });
         }
+        const finalization = await finalizeExistingPurchaseGrant(request, transaction, context);
         return assertVerifyPurchaseResponse({
             verified: true,
-            ledgerEntryId: existing.ledgerEntryId,
+            ledgerEntryId: transaction.ledgerEntryId,
             alreadyProcessed: true,
+            ...(finalization === undefined ? {} : { finalization }),
         });
+    };
+    const existing = await findEntitlementTransactionByIdempotency(context.store, retryIdentity);
+    if (existing !== undefined) {
+        return completeExistingRetry(existing);
     }
     const product = context.catalog.products.find((entry) => entry.id === request.productId);
     if (product === undefined) {
@@ -354,6 +368,12 @@ async function verifyPurchaseWithStore(input, context) {
         });
     }, context.evidenceVerificationTimeoutMs);
     if (verification.status !== 'verified') {
+        // A matching grant can land while provider verification is in flight. Recheck
+        // before returning a stale provider state such as an already-consumed token.
+        const racedExisting = await findEntitlementTransactionByIdempotency(context.store, retryIdentity);
+        if (racedExisting !== undefined) {
+            return completeExistingRetry(racedExisting);
+        }
         return assertVerifyPurchaseResponse({
             verified: false,
             alreadyProcessed: false,
@@ -362,6 +382,7 @@ async function verifyPurchaseWithStore(input, context) {
                 : verification.reason,
         });
     }
+    const verificationPayload = createPurchaseVerificationPayload(verification);
     const grant = await recordEntitlementGrantWithEvidence(context.store, {
         playerId: request.playerId,
         grantId: product.id,
@@ -371,11 +392,16 @@ async function verifyPurchaseWithStore(input, context) {
         grant: product.grant,
         evidenceVerificationId: verification.verificationId,
         payload: {
-            ...verification.payload,
+            ...verificationPayload,
             target: request.target,
             productId: request.productId,
+            productType: product.type,
             platformProductId,
-            platformTransactionId: request.platformTransactionId,
+            ...(verification.platformEvidenceId === null
+                ? {}
+                : {
+                    platformTransactionId: verification.platformEvidenceId ?? request.platformTransactionId,
+                }),
             purchasedAt: request.purchasedAt,
             evidenceVerificationId: verification.verificationId,
             evidenceVerifiedAt: verification.verifiedAt,
@@ -388,20 +414,160 @@ async function verifyPurchaseWithStore(input, context) {
             reason: 'EVIDENCE_ALREADY_PROCESSED',
         });
     }
-    if (grant.result.alreadyProcessed
-        && !await recordedEntitlementMatchesRetry(context.store, grant.result, retryIdentity)) {
-        return assertVerifyPurchaseResponse({
-            verified: false,
-            alreadyProcessed: false,
-            reason: 'IDEMPOTENCY_KEY_CONFLICT',
-        });
+    if (grant.result.alreadyProcessed) {
+        const recordedTransaction = await context.store.getEntitlementTransaction(grant.result.ledgerEntryId);
+        const storedEvidenceVerificationId = recordedTransaction?.evidenceVerificationId
+            ?? recordedTransaction?.payload.evidenceVerificationId;
+        if (recordedTransaction === undefined
+            || !matchesEntitlementRetry(recordedTransaction, retryIdentity)
+            || storedEvidenceVerificationId !== verification.verificationId) {
+            return assertVerifyPurchaseResponse({
+                verified: false,
+                alreadyProcessed: false,
+                reason: 'IDEMPOTENCY_KEY_CONFLICT',
+            });
+        }
     }
+    const finalization = await finalizePurchaseGrant(context.purchaseGrantFinalizer, {
+        request,
+        product,
+        platformProductId,
+        evidenceVerificationId: verification.verificationId,
+        ...(verification.payload === undefined
+            ? {}
+            : { evidencePayload: verification.payload }),
+        ledgerEntryId: grant.result.ledgerEntryId,
+        alreadyProcessed: grant.result.alreadyProcessed,
+        timeoutMs: context.purchaseGrantFinalizationTimeoutMs,
+    });
     return assertVerifyPurchaseResponse({
         verified: true,
         ledgerEntryId: grant.result.ledgerEntryId,
         alreadyProcessed: grant.result.alreadyProcessed,
+        ...(finalization === undefined ? {} : { finalization }),
+    });
+}
+async function finalizeExistingPurchaseGrant(request, transaction, context) {
+    if (context.purchaseGrantFinalizer === undefined) {
+        return undefined;
+    }
+    const currentProduct = context.catalog.products.find((entry) => entry.id === request.productId);
+    const storedPlatformProductId = readStoredPlatformProductId(transaction);
+    const product = createStoredPurchaseProduct(request, transaction) ?? currentProduct;
+    const platformProductId = storedPlatformProductId
+        ?? currentProduct?.platformProductIds[request.target];
+    const evidenceVerificationId = transaction.evidenceVerificationId
+        ?? transaction.payload.evidenceVerificationId;
+    const finalizationRequest = createStoredPurchaseRequest(request, transaction);
+    if (product === undefined
+        || platformProductId === undefined
+        || typeof evidenceVerificationId !== 'string'
+        || evidenceVerificationId.length === 0) {
+        return assertPurchaseGrantFinalization({
+            status: 'pending',
+            alreadyCompleted: false,
+            reason: 'PURCHASE_FINALIZER_CONTEXT_UNAVAILABLE',
+        });
+    }
+    return finalizePurchaseGrant(context.purchaseGrantFinalizer, {
+        request: finalizationRequest,
+        product,
+        platformProductId,
+        evidenceVerificationId,
+        evidencePayload: transaction.payload,
+        ledgerEntryId: transaction.ledgerEntryId,
+        alreadyProcessed: true,
+        timeoutMs: context.purchaseGrantFinalizationTimeoutMs,
     });
 }
+async function finalizePurchaseGrant(finalizer, input) {
+    if (finalizer === undefined) {
+        return undefined;
+    }
+    const controller = new AbortController();
+    const timeoutDecision = assertPurchaseGrantFinalization({
+        status: 'pending',
+        alreadyCompleted: false,
+        reason: 'PURCHASE_FINALIZER_TIMEOUT',
+    });
+    let timedOut = false;
+    let timeout;
+    try {
+        if (finalizer.supportsPurchaseGrant?.(input) === false) {
+            return undefined;
+        }
+        return await Promise.race([
+            finalizer.finalizePurchaseGrant({ ...input, signal: controller.signal })
+                .then(assertPurchaseGrantFinalization)
+                .catch((error) => {
+                if (timedOut) {
+                    return timeoutDecision;
+                }
+                throw error;
+            }),
+            new Promise((resolve) => {
+                timeout = setTimeout(() => {
+                    timedOut = true;
+                    resolve(timeoutDecision);
+                    controller.abort();
+                }, input.timeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        return assertPurchaseGrantFinalization({
+            status: 'pending',
+            alreadyCompleted: false,
+            reason: 'PURCHASE_FINALIZER_ERROR',
+        });
+    }
+    finally {
+        if (timeout !== undefined) {
+            clearTimeout(timeout);
+        }
+    }
+}
+function readStoredPlatformProductId(transaction) {
+    const platformProductId = transaction.payload.platformProductId;
+    return typeof platformProductId === 'string' && platformProductId.length > 0
+        ? platformProductId
+        : undefined;
+}
+function createStoredPurchaseProduct(request, transaction) {
+    const productType = transaction.payload.productType;
+    const platformProductId = readStoredPlatformProductId(transaction);
+    if (transaction.grant === undefined
+        || platformProductId === undefined
+        || (productType !== 'consumable'
+            && productType !== 'non_consumable'
+            && productType !== 'subscription')) {
+        return undefined;
+    }
+    return {
+        id: request.productId,
+        type: productType,
+        grant: transaction.grant,
+        platformProductIds: { [request.target]: platformProductId },
+    };
+}
+/**
+ * Reuses the current request only for retry dimensions already matched against
+ * the stored grant, while restoring provider identity and time metadata from
+ * the durable transaction for a coherent finalization retry.
+ */
+function createStoredPurchaseRequest(request, transaction) {
+    const platformTransactionId = transaction.payload.platformTransactionId;
+    const purchasedAt = transaction.payload.purchasedAt;
+    return {
+        ...request,
+        ...(typeof platformTransactionId === 'string' && platformTransactionId.length > 0
+            ? { platformTransactionId }
+            : {}),
+        ...(typeof purchasedAt === 'string' && purchasedAt.length > 0
+            ? { purchasedAt }
+            : {}),
+    };
+}
 async function claimAdRewardWithStore(input, context) {
     const request = assertClaimAdRewardRequest(input);
     const retryIdentity = {
@@ -538,6 +704,14 @@ async function verifyEvidence(verify, timeoutMs) {
         }
     }
 }
+function createPurchaseVerificationPayload(verification) {
+    if (verification.platformEvidenceId !== null || verification.payload === undefined) {
+        return verification.payload;
+    }
+    const { platformTransactionId: suppressedPlatformTransactionId, ...payload } = verification.payload;
+    void suppressedPlatformTransactionId;
+    return payload;
+}
 function assertEvidenceVerificationDecision(decision) {
     if (decision.status === 'verified') {
         assertNonEmptyDecisionString(decision.verificationId, 'verificationId');
@@ -559,6 +733,10 @@ function assertEvidenceVerificationDecision(decision) {
                 }
             }
         }
+        if (decision.platformEvidenceId !== undefined
+            && decision.platformEvidenceId !== null) {
+            assertNonEmptyDecisionString(decision.platformEvidenceId, 'platformEvidenceId');
+        }
         return decision;
     }
     if (decision.status === 'pending') {
@@ -739,6 +917,13 @@ function resolveEvidenceVerificationTimeout(timeoutMs) {
     }
     return resolved;
 }
+function resolvePurchaseGrantFinalizationTimeout(timeoutMs) {
+    const resolved = timeoutMs ?? 15000;
+    if (!Number.isFinite(resolved) || resolved <= 0) {
+        throw new Error('purchaseGrantFinalizationTimeoutMs must be a positive finite number.');
+    }
+    return resolved;
+}
 function assertNonEmptyDecisionString(value, label) {
     if (typeof value !== 'string' || value.length === 0) {
         throw new Error(`Evidence verification ${label} must be a non-empty string.`);

package/dist/types.d.ts

@@ -24,11 +24,20 @@ export interface VerifyPurchaseResponse {
   readonly ledgerEntryId?: string;
   readonly alreadyProcessed: boolean;
   readonly reason?: string;
+  readonly finalization?: PurchaseGrantFinalization;
+}
+export type PurchaseGrantFinalizationAction = 'acknowledge' | 'consume' | 'finish' | 'complete';
+export interface PurchaseGrantFinalization {
+  readonly status: 'completed' | 'pending';
+  readonly action?: PurchaseGrantFinalizationAction;
+  readonly alreadyCompleted: boolean;
+  readonly reason?: string;
 }
 export interface ClaimAdRewardRequest {
   readonly target: GameServicesAdRewardTarget;
   readonly playerId: string;
   readonly placementId: LogicalAdPlacementId;
+  /** Platform evidence identity; AIT uses the game-issued reward correlation identifier. */
   readonly platformImpressionId?: string;
   readonly idempotencyKey: AdRewardIdempotencyKey;
   readonly completedAt: string;
@@ -82,6 +91,7 @@ export interface LeaderboardScoreTransaction extends RecordLeaderboardScoreReque
 }
 export declare function assertVerifyPurchaseRequest(input: VerifyPurchaseRequest): VerifyPurchaseRequest;
 export declare function assertVerifyPurchaseResponse(input: VerifyPurchaseResponse): VerifyPurchaseResponse;
+export declare function assertPurchaseGrantFinalization(input: PurchaseGrantFinalization): PurchaseGrantFinalization;
 export declare function assertClaimAdRewardRequest(input: ClaimAdRewardRequest): ClaimAdRewardRequest;
 export declare function assertClaimAdRewardResponse(input: ClaimAdRewardResponse): ClaimAdRewardResponse;
 export declare function assertRecordLeaderboardScoreRequest(input: RecordLeaderboardScoreRequest): RecordLeaderboardScoreRequest;

package/dist/types.js

@@ -15,6 +15,30 @@ export function assertVerifyPurchaseResponse(input) {
     assertOptionalNonEmptyString(input.ledgerEntryId, 'ledgerEntryId');
     assertBoolean(input.alreadyProcessed, 'alreadyProcessed');
     assertOptionalNonEmptyString(input.reason, 'reason');
+    if (input.finalization !== undefined) {
+        assertPurchaseGrantFinalization(input.finalization);
+    }
+    return input;
+}
+export function assertPurchaseGrantFinalization(input) {
+    assertRecord(input, 'PurchaseGrantFinalization');
+    if (input.status !== 'completed' && input.status !== 'pending') {
+        throw new Error('finalization.status must be completed or pending.');
+    }
+    if (input.action !== undefined) {
+        assertPurchaseGrantFinalizationAction(input.action);
+    }
+    if (input.status === 'completed' && input.action === undefined) {
+        throw new Error('completed finalization requires an action.');
+    }
+    assertBoolean(input.alreadyCompleted, 'finalization.alreadyCompleted');
+    assertOptionalNonEmptyString(input.reason, 'finalization.reason');
+    if (input.status === 'pending' && input.alreadyCompleted) {
+        throw new Error('pending finalization cannot already be completed.');
+    }
+    if (input.status === 'pending' && input.reason === undefined) {
+        throw new Error('pending finalization requires a reason.');
+    }
     return input;
 }
 export function assertClaimAdRewardRequest(input) {
@@ -140,6 +164,14 @@ function assertBoolean(input, label) {
         throw new Error(`${label} must be a boolean.`);
     }
 }
+function assertPurchaseGrantFinalizationAction(input) {
+    if (input !== 'acknowledge'
+        && input !== 'consume'
+        && input !== 'finish'
+        && input !== 'complete') {
+        throw new Error('finalization.action must be acknowledge, consume, finish, or complete.');
+    }
+}
 function assertLedgerSource(input) {
     if (input !== 'purchase' && input !== 'ad_reward' && input !== 'admin') {
         throw new Error('source must be purchase, ad_reward, or admin.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,30 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./admob-ssv": {
+      "types": "./dist/admob-ssv.d.ts",
+      "default": "./dist/admob-ssv.js"
+    },
+    "./admob-ssv-conformance": {
+      "types": "./dist/admob-ssv-conformance.d.ts",
+      "default": "./dist/admob-ssv-conformance.js"
+    },
+    "./app-store-verifier": {
+      "types": "./dist/app-store-verifier.d.ts",
+      "default": "./dist/app-store-verifier.js"
+    },
+    "./app-store-verifier-conformance": {
+      "types": "./dist/app-store-verifier-conformance.d.ts",
+      "default": "./dist/app-store-verifier-conformance.js"
+    },
+    "./apps-in-toss-evidence-verification": {
+      "types": "./dist/apps-in-toss-evidence-verification.d.ts",
+      "default": "./dist/apps-in-toss-evidence-verification.js"
+    },
+    "./apps-in-toss-evidence-verification-conformance": {
+      "types": "./dist/apps-in-toss-evidence-verification-conformance.d.ts",
+      "default": "./dist/apps-in-toss-evidence-verification-conformance.js"
+    },
     "./client": {
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
@@ -41,6 +65,14 @@
       "types": "./dist/evidence-verification.d.ts",
       "default": "./dist/evidence-verification.js"
     },
+    "./google-play-purchase": {
+      "types": "./dist/google-play-purchase.d.ts",
+      "default": "./dist/google-play-purchase.js"
+    },
+    "./google-play-purchase-conformance": {
+      "types": "./dist/google-play-purchase-conformance.d.ts",
+      "default": "./dist/google-play-purchase-conformance.js"
+    },
     "./notification-delivery": {
       "types": "./dist/notification-delivery.d.ts",
       "default": "./dist/notification-delivery.js"
@@ -86,12 +118,13 @@
     "dist"
   ],
   "dependencies": {
+    "@noble/secp256k1": "3.1.0",
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
-    "@mpgd/analytics": "0.3.7",
     "@mpgd/catalog": "0.5.0",
-    "@mpgd/platform": "0.7.0"
+    "@mpgd/platform": "0.7.0",
+    "@mpgd/analytics": "0.3.7"
   },
   "devDependencies": {
     "ttsc": "0.18.4",
@@ -107,6 +140,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/types.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/platform-order.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-durability-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-transport.test.ts"
+    "test": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/types.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/platform-order.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/admob-ssv.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-verifier.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-evidence-verification-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-durability-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-transport.test.ts"
   }
 }