@mpgd/game-services 0.8.2 → 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

@@ -2,7 +2,9 @@ import type { ProductGrant } from '@mpgd/catalog';
 import type { LeaderboardScoreInput, LogicalAdPlacementId, LogicalProductId, PlatformEvidenceEnvelope, PlatformTarget } from '@mpgd/platform';
 export type { PlatformEvidenceEnvelope } from '@mpgd/platform';
 export type GameServicesStoreTarget = Extract<PlatformTarget, 'android' | 'ios' | 'ait'>;
-export type GameServicesLedgerTarget = Extract<PlatformTarget, 'browser' | 'android' | 'ios' | 'ait' | 'reddit'>;
+export type GameServicesAdRewardTarget = Extract<PlatformTarget, 'android' | 'ios' | 'ait' | 'verse8'>;
+export type GameServicesLeaderboardTarget = Extract<PlatformTarget, 'browser' | 'android' | 'ios' | 'ait' | 'reddit'>;
+export type GameServicesLedgerTarget = Extract<PlatformTarget, 'browser' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8'>;
 export type PurchaseIdempotencyKey = string;
 export type AdRewardIdempotencyKey = string;
 export type EntitlementIdempotencyKey = PurchaseIdempotencyKey | AdRewardIdempotencyKey;
@@ -22,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: GameServicesStoreTarget;
+  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;
@@ -39,7 +50,7 @@ export interface ClaimAdRewardResponse {
   readonly reason?: string;
 }
 export interface RecordLeaderboardScoreRequest extends LeaderboardScoreInput {
-  readonly target: GameServicesLedgerTarget;
+  readonly target: GameServicesLeaderboardTarget;
   readonly playerId: string;
   readonly platformSubmissionId?: string;
 }
@@ -80,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,11 +15,35 @@ 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) {
     assertRecord(input, 'ClaimAdRewardRequest');
-    assertStoreTarget(input.target);
+    assertAdRewardTarget(input.target);
     assertNonEmptyString(input.playerId, 'playerId');
     assertNonEmptyString(input.placementId, 'placementId');
     assertOptionalNonEmptyString(input.platformImpressionId, 'platformImpressionId');
@@ -106,6 +130,11 @@ function assertStoreTarget(input) {
         throw new Error('target must be android, ios, or ait.');
     }
 }
+function assertAdRewardTarget(input) {
+    if (input !== 'android' && input !== 'ios' && input !== 'ait' && input !== 'verse8') {
+        throw new Error('target must be android, ios, ait, or verse8.');
+    }
+}
 function assertLeaderboardTarget(input) {
     if (input !== 'browser'
         && input !== 'android'
@@ -135,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.');
@@ -153,7 +190,15 @@ function assertProductGrant(input) {
         assertNonEmptyString(input.entitlement, 'grant.entitlement');
         return;
     }
-    throw new Error('grant.type must be currency or entitlement.');
+    if (input.type === 'resource') {
+        assertNonEmptyString(input.resource, 'grant.resource');
+        assertFiniteNumber(input.amount, 'grant.amount');
+        if (input.amount <= 0) {
+            throw new Error('grant.amount must be greater than zero for a resource grant.');
+        }
+        return;
+    }
+    throw new Error('grant.type must be currency, entitlement, or resource.');
 }
 function assertPayload(input) {
     assertRecord(input, 'payload');

package/dist/verified-leaderboard-durability-conformance.d.ts

@@ -0,0 +1,39 @@
+import { type VerifiedLeaderboardService } from './verified-leaderboard';
+export declare const verifiedLeaderboardDurabilityConformanceScenarios: readonly ['replacement-after-interrupted-retained-write', 'concurrent-retry-after-interrupted-retained-write', 'snapshot-after-interrupted-retained-write'];
+export type VerifiedLeaderboardDurabilityConformanceScenario = (typeof verifiedLeaderboardDurabilityConformanceScenarios)[number];
+export interface CreateVerifiedLeaderboardDurabilityConformanceFixtureInput {
+  readonly scenario: VerifiedLeaderboardDurabilityConformanceScenario;
+  readonly now: string;
+}
+export interface VerifiedLeaderboardDurabilityConformanceFixture {
+  readonly service: VerifiedLeaderboardService;
+  /**
+  * Arms one retained record so its caller observes a failure after the
+  * provider has crossed the recovery boundary. Transactional providers may
+  * simulate a committed write with a lost response. Multi-write providers
+  * should interrupt at their recoverable handoff boundary.
+  */
+  readonly interruptNextRetainedRecord: () => void;
+  readonly dispose?: () => Promise<void> | void;
+}
+export type CreateVerifiedLeaderboardDurabilityConformanceFixture = (input: CreateVerifiedLeaderboardDurabilityConformanceFixtureInput) => Promise<VerifiedLeaderboardDurabilityConformanceFixture> | VerifiedLeaderboardDurabilityConformanceFixture;
+export interface RunVerifiedLeaderboardDurabilityConformanceInput {
+  /** Return an isolated fixture, or a uniquely namespaced fixture, per scenario. */
+  readonly createFixture: CreateVerifiedLeaderboardDurabilityConformanceFixture;
+  readonly now?: string;
+}
+export interface VerifiedLeaderboardDurabilityConformanceReport {
+  readonly passedScenarios: readonly VerifiedLeaderboardDurabilityConformanceScenario[];
+}
+/**
+* Runs provider-neutral recovery checks that require a provider-specific fault
+* boundary. It complements the semantic conformance suite and deliberately
+* does not prescribe a shared persistence implementation.
+*/
+export declare function runVerifiedLeaderboardDurabilityConformance(input: RunVerifiedLeaderboardDurabilityConformanceInput): Promise<VerifiedLeaderboardDurabilityConformanceReport>;
+/**
+* Wraps an atomic provider so the next armed record commits successfully but
+* its caller observes an interruption. Use a provider-specific fixture when
+* the implementation has a recoverable boundary inside a multi-write flow.
+*/
+export declare function createAmbiguousCommitVerifiedLeaderboardDurabilityFixture(provider: VerifiedLeaderboardService, dispose?: () => Promise<void> | void): VerifiedLeaderboardDurabilityConformanceFixture;