@mpgd/game-services 0.7.0 → 0.8.1

package/dist/client.js

@@ -69,6 +69,7 @@ export function createGameServicesClient(input) {
                 platformTransactionId: purchase.transactionId,
                 idempotencyKey: purchaseInput.idempotencyKey,
                 purchasedAt: now(),
+                ...(purchase.evidence === undefined ? {} : { evidence: purchase.evidence }),
             });
             const result = {
                 status: verification.verified ? 'granted' : 'rejected',
@@ -135,6 +136,7 @@ export function createGameServicesClient(input) {
                     : { platformImpressionId: reward.ledgerEntryId }),
                 idempotencyKey: rewardInput.idempotencyKey,
                 completedAt: now(),
+                ...(reward.evidence === undefined ? {} : { evidence: reward.evidence }),
             });
             const result = {
                 status: claim.granted ? 'granted' : 'rejected',

package/dist/evidence-verification.d.ts

@@ -0,0 +1,34 @@
+import type { AdPlacements, ProductCatalog } from '@mpgd/catalog';
+import type { ClaimAdRewardRequest, EntitlementLedgerPayload, VerifyPurchaseRequest } from './types';
+export type EvidenceVerificationDecision = {
+  readonly status: 'verified';
+  readonly verificationId: string;
+  readonly verifiedAt: string;
+  readonly payload?: EntitlementLedgerPayload;
+} | {
+  readonly status: 'pending';
+  readonly reason?: string;
+} | {
+  readonly status: 'rejected';
+  readonly reason: string;
+};
+export interface VerifyPurchaseEvidenceInput {
+  readonly request: VerifyPurchaseRequest;
+  readonly product: ProductCatalog['products'][number];
+  readonly platformProductId: string;
+  readonly signal: AbortSignal;
+  readonly timeoutMs: number;
+}
+export interface VerifyAdRewardEvidenceInput {
+  readonly request: ClaimAdRewardRequest;
+  readonly placement: AdPlacements['placements'][number];
+  readonly platformPlacementId?: string;
+  readonly signal: AbortSignal;
+  readonly timeoutMs: number;
+}
+export interface GameServicesEvidenceVerifier {
+  verifyPurchase(input: VerifyPurchaseEvidenceInput): Promise<EvidenceVerificationDecision>;
+  verifyAdReward(input: VerifyAdRewardEvidenceInput): Promise<EvidenceVerificationDecision>;
+}
+export declare function createDevelopmentGameServicesEvidenceVerifier(now?: () => string): GameServicesEvidenceVerifier;
+export declare function createRejectingGameServicesEvidenceVerifier(): GameServicesEvidenceVerifier;

package/dist/evidence-verification.js

@@ -0,0 +1,34 @@
+export function createDevelopmentGameServicesEvidenceVerifier(now = () => new Date().toISOString()) {
+    return {
+        async verifyPurchase({ request }) {
+            return {
+                status: 'verified',
+                verificationId: `development:purchase:${request.target}:${request.platformTransactionId}`,
+                verifiedAt: now(),
+            };
+        },
+        async verifyAdReward({ request }) {
+            return {
+                status: 'verified',
+                verificationId: `development:ad-reward:${request.target}:${request.platformImpressionId ?? request.idempotencyKey}`,
+                verifiedAt: now(),
+            };
+        },
+    };
+}
+export function createRejectingGameServicesEvidenceVerifier() {
+    return {
+        async verifyPurchase() {
+            return {
+                status: 'rejected',
+                reason: 'EVIDENCE_VERIFIER_UNAVAILABLE',
+            };
+        },
+        async verifyAdReward() {
+            return {
+                status: 'rejected',
+                reason: 'EVIDENCE_VERIFIER_UNAVAILABLE',
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export * from './client';
 export * from './contract';
+export * from './evidence-verification';
 export * from './notification-delivery';
+export * from './platform-order';
 export * from './progress-link';
 export * from './runtime.js';
 export * from './server';

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from './client';
 export * from './contract';
+export * from './evidence-verification';
 export * from './notification-delivery';
+export * from './platform-order';
 export * from './progress-link';
 export * from './runtime.js';
 export * from './server';

package/dist/platform-order.d.ts

@@ -0,0 +1,22 @@
+import type { PlatformEvidenceEnvelope } from '@mpgd/platform';
+export type PlatformOrderTarget = 'reddit';
+export interface FulfillPlatformOrderInput {
+  readonly target: PlatformOrderTarget;
+  readonly orderId: string;
+  readonly playerId: string;
+  readonly platformSku: string;
+  readonly paidAt: string;
+  readonly evidence: PlatformEvidenceEnvelope;
+}
+export interface RefundPlatformOrderInput {
+  readonly target: PlatformOrderTarget;
+  readonly orderId: string;
+  readonly playerId: string;
+  readonly platformSku: string;
+  readonly refundedAt: string;
+  readonly evidence: PlatformEvidenceEnvelope;
+}
+export type PlatformOrderIdempotencyKey = `${PlatformOrderTarget}:${string}`;
+export declare function createPlatformOrderIdempotencyKey(input: Pick<FulfillPlatformOrderInput, 'target' | 'orderId'>): PlatformOrderIdempotencyKey;
+export declare function assertFulfillPlatformOrderInput(input: FulfillPlatformOrderInput): FulfillPlatformOrderInput;
+export declare function assertRefundPlatformOrderInput(input: RefundPlatformOrderInput): RefundPlatformOrderInput;

package/dist/platform-order.js

@@ -0,0 +1,69 @@
+export function createPlatformOrderIdempotencyKey(input) {
+    assertPlatformOrderTarget(input.target);
+    assertIdentifier(input.orderId, 'orderId');
+    return `${input.target}:${input.orderId}`;
+}
+export function assertFulfillPlatformOrderInput(input) {
+    assertPlatformOrderBase(input, 'FulfillPlatformOrderInput');
+    assertIsoTimestamp(input.paidAt, 'paidAt');
+    return input;
+}
+export function assertRefundPlatformOrderInput(input) {
+    assertPlatformOrderBase(input, 'RefundPlatformOrderInput');
+    assertIsoTimestamp(input.refundedAt, 'refundedAt');
+    return input;
+}
+function assertPlatformOrderBase(input, label) {
+    assertRecord(input, label);
+    assertPlatformOrderTarget(input.target);
+    assertIdentifier(input.orderId, 'orderId');
+    assertIdentifier(input.playerId, 'playerId');
+    assertIdentifier(input.platformSku, 'platformSku');
+    assertEvidenceEnvelope(input.evidence);
+}
+function assertPlatformOrderTarget(input) {
+    if (input !== 'reddit') {
+        throw new TypeError('target must be reddit.');
+    }
+}
+function assertIdentifier(input, label) {
+    if (typeof input !== 'string'
+        || input.length === 0
+        || input.length > 256
+        || input.trim() !== input
+        || /[\u0000-\u001f\u007f]/u.test(input)) {
+        throw new TypeError(`${label} must be a non-empty identifier.`);
+    }
+}
+function assertIsoTimestamp(input, label) {
+    if (typeof input !== 'string'
+        || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/u.test(input)) {
+        throw new TypeError(`${label} must be an ISO 8601 UTC timestamp.`);
+    }
+    const parsed = new Date(input);
+    const canonicalInput = input.includes('.') ? input : `${input.slice(0, -1)}.000Z`;
+    if (Number.isNaN(parsed.getTime()) || parsed.toISOString() !== canonicalInput) {
+        throw new TypeError(`${label} must be an ISO 8601 UTC timestamp.`);
+    }
+}
+function assertEvidenceEnvelope(input) {
+    assertRecord(input, 'evidence');
+    assertIdentifier(input.schema, 'evidence.schema');
+    assertRecord(input.payload, 'evidence.payload');
+    for (const [key, value] of Object.entries(input.payload)) {
+        assertIdentifier(key, 'evidence.payload key');
+        if (typeof value !== 'string'
+            && typeof value !== 'number'
+            && typeof value !== 'boolean') {
+            throw new TypeError('evidence.payload values must be strings, numbers, or booleans.');
+        }
+        if (typeof value === 'number' && !Number.isFinite(value)) {
+            throw new TypeError('evidence.payload numbers must be finite.');
+        }
+    }
+}
+function assertRecord(input, label) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new TypeError(`${label} must be an object.`);
+    }
+}

package/dist/server.d.ts

@@ -2,6 +2,7 @@ import { type AnalyticsSink } from '@mpgd/analytics';
 import type { AdPlacements, ProductCatalog } from '@mpgd/catalog';
 import { type GameServicesBackendApi, type GameServicesBackendTransport, type GameServicesBackendTransportRequest, type GameServicesBackendTransportResponse } from './client';
 import { type GameServicesHealthResponse } from './contract';
+import { type GameServicesEvidenceVerifier } from './evidence-verification';
 import { type ClaimAdRewardRequest, type ClaimAdRewardResponse, type EntitlementLedgerGrant, type EntitlementLedgerResult, type LeaderboardScoreTransaction, type ProductGrantTransaction, type RecordLeaderboardScoreRequest, type RecordLeaderboardScoreResponse, type VerifyPurchaseRequest, type VerifyPurchaseResponse } from './types';
 type CorsHeaders = Record<string, string>;
 export interface CreateGameServicesBackendInput {
@@ -12,6 +13,8 @@ export interface CreateGameServicesBackendInput {
   readonly analyticsSessionId?: string;
   readonly now?: () => string;
   readonly version?: string;
+  readonly evidenceVerifier?: GameServicesEvidenceVerifier;
+  readonly evidenceVerificationTimeoutMs?: number;
 }
 export interface GameServicesBackendApiHandler {
   readonly version?: string;
@@ -22,6 +25,16 @@ export interface GameServicesBackendErrorResponse {
 }
 export interface GameServicesStore {
   recordEntitlementGrant(input: EntitlementLedgerGrant): Promise<EntitlementLedgerResult>;
+  findEntitlementTransactionByIdempotency?(input: {
+    readonly source: EntitlementLedgerGrant['source'];
+    readonly playerId: string;
+    readonly idempotencyKey: string;
+  }): Promise<ProductGrantTransaction | undefined>;
+  findEntitlementTransactionByEvidenceVerificationId?(input: {
+    readonly source: EntitlementLedgerGrant['source'];
+    readonly evidenceVerificationId: string;
+  }): Promise<ProductGrantTransaction | undefined>;
+  findEntitlementTransactionByPlatformEvidence?(input: EntitlementPlatformEvidenceIdentity): Promise<ProductGrantTransaction | undefined>;
   getEntitlementTransaction(ledgerEntryId: string): Promise<ProductGrantTransaction | undefined>;
   listEntitlementTransactions(): Promise<readonly ProductGrantTransaction[]>;
   recordLeaderboardScore(input: RecordLeaderboardScoreRequest, options?: {
@@ -30,6 +43,11 @@ export interface GameServicesStore {
   getLeaderboardTransaction(ledgerEntryId: string): Promise<LeaderboardScoreTransaction | undefined>;
   listLeaderboardTransactions(): Promise<readonly LeaderboardScoreTransaction[]>;
 }
+export interface EntitlementPlatformEvidenceIdentity {
+  readonly source: Extract<EntitlementLedgerGrant['source'], 'purchase' | 'ad_reward'>;
+  readonly target: string;
+  readonly platformEvidenceId: string;
+}
 export interface CreateGameServicesFetchHandlerOptions {
   readonly corsHeaders?: CorsHeaders;
   readonly healthPath?: string;
@@ -43,10 +61,22 @@ export interface GameServicesOrpcContext {
 }
 export declare class InMemoryGameServicesStore implements GameServicesStore {
   private readonly entitlementTransactionsByKey;
+  private readonly entitlementTransactionsByEvidence;
+  private readonly entitlementTransactionsByPlatformEvidence;
   private readonly entitlementTransactionsById;
   private readonly leaderboardTransactionsByRun;
   private readonly leaderboardTransactionsById;
   recordEntitlementGrant(input: EntitlementLedgerGrant): Promise<EntitlementLedgerResult>;
+  findEntitlementTransactionByIdempotency(input: {
+    readonly source: EntitlementLedgerGrant['source'];
+    readonly playerId: string;
+    readonly idempotencyKey: string;
+  }): Promise<ProductGrantTransaction | undefined>;
+  findEntitlementTransactionByEvidenceVerificationId(input: {
+    readonly source: EntitlementLedgerGrant['source'];
+    readonly evidenceVerificationId: string;
+  }): Promise<ProductGrantTransaction | undefined>;
+  findEntitlementTransactionByPlatformEvidence(input: EntitlementPlatformEvidenceIdentity): Promise<ProductGrantTransaction | undefined>;
   getEntitlementTransaction(ledgerEntryId: string): Promise<ProductGrantTransaction | undefined>;
   listEntitlementTransactions(): Promise<readonly ProductGrantTransaction[]>;
   recordLeaderboardScore(input: RecordLeaderboardScoreRequest, options?: {
@@ -57,6 +87,9 @@ export declare class InMemoryGameServicesStore implements GameServicesStore {
   private rankFor;
   private sortedLeaderboardTransactions;
 }
+export declare class EvidenceAlreadyProcessedError extends Error {
+  constructor();
+}
 export declare function createInMemoryGameServicesStore(): InMemoryGameServicesStore;
 export declare function createGameServicesBackend(input: CreateGameServicesBackendInput): GameServicesBackendApi;
 export declare function createGameServicesBackendApiHandler(input: CreateGameServicesBackendInput): GameServicesBackendApiHandler;

package/dist/server.js

@@ -3,9 +3,12 @@ import { RPCHandler } from '@orpc/server/fetch';
 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';
 export class InMemoryGameServicesStore {
     entitlementTransactionsByKey = new Map();
+    entitlementTransactionsByEvidence = new Map();
+    entitlementTransactionsByPlatformEvidence = new Map();
     entitlementTransactionsById = new Map();
     leaderboardTransactionsByRun = new Map();
     leaderboardTransactionsById = new Map();
@@ -19,14 +22,46 @@ export class InMemoryGameServicesStore {
                 alreadyProcessed: true,
             });
         }
+        if (grant.evidenceVerificationId !== undefined) {
+            const evidenceKey = createEntitlementEvidenceKey({
+                source: grant.source,
+                evidenceVerificationId: grant.evidenceVerificationId,
+            });
+            if (this.entitlementTransactionsByEvidence.has(evidenceKey)) {
+                throw new EvidenceAlreadyProcessedError();
+            }
+        }
+        const platformEvidenceIdentity = getEntitlementPlatformEvidenceIdentity(grant);
+        if (platformEvidenceIdentity !== undefined
+            && this.entitlementTransactionsByPlatformEvidence.has(createEntitlementPlatformEvidenceKey(platformEvidenceIdentity))) {
+            throw new EvidenceAlreadyProcessedError();
+        }
         const transaction = createEntitlementTransaction(grant);
         this.entitlementTransactionsByKey.set(key, transaction);
         this.entitlementTransactionsById.set(transaction.ledgerEntryId, transaction);
+        if (grant.evidenceVerificationId !== undefined) {
+            this.entitlementTransactionsByEvidence.set(createEntitlementEvidenceKey({
+                source: grant.source,
+                evidenceVerificationId: grant.evidenceVerificationId,
+            }), transaction);
+        }
+        if (platformEvidenceIdentity !== undefined) {
+            this.entitlementTransactionsByPlatformEvidence.set(createEntitlementPlatformEvidenceKey(platformEvidenceIdentity), transaction);
+        }
         return assertEntitlementLedgerResult({
             ledgerEntryId: transaction.ledgerEntryId,
             alreadyProcessed: false,
         });
     }
+    async findEntitlementTransactionByIdempotency(input) {
+        return this.entitlementTransactionsByKey.get(createEntitlementIdempotencyKey(input));
+    }
+    async findEntitlementTransactionByEvidenceVerificationId(input) {
+        return this.entitlementTransactionsByEvidence.get(createEntitlementEvidenceKey(input));
+    }
+    async findEntitlementTransactionByPlatformEvidence(input) {
+        return this.entitlementTransactionsByPlatformEvidence.get(createEntitlementPlatformEvidenceKey(input));
+    }
     async getEntitlementTransaction(ledgerEntryId) {
         return this.entitlementTransactionsById.get(ledgerEntryId);
     }
@@ -79,6 +114,12 @@ export class InMemoryGameServicesStore {
         });
     }
 }
+export class EvidenceAlreadyProcessedError extends Error {
+    constructor() {
+        super('Evidence verification identity has already been processed.');
+        this.name = 'EvidenceAlreadyProcessedError';
+    }
+}
 export function createInMemoryGameServicesStore() {
     return new InMemoryGameServicesStore();
 }
@@ -86,6 +127,8 @@ export function createGameServicesBackend(input) {
     const store = input.store ?? createInMemoryGameServicesStore();
     const now = input.now ?? (() => new Date().toISOString());
     const version = input.version ?? '0.0.0';
+    const evidenceVerifier = input.evidenceVerifier ?? createRejectingGameServicesEvidenceVerifier();
+    const evidenceVerificationTimeoutMs = resolveEvidenceVerificationTimeout(input.evidenceVerificationTimeoutMs);
     const analytics = createAnalyticsReporter({
         target: 'server',
         sessionId: input.analyticsSessionId ?? 'game-services',
@@ -100,6 +143,8 @@ export function createGameServicesBackend(input) {
                     catalog: input.catalog,
                     store,
                     now,
+                    evidenceVerifier,
+                    evidenceVerificationTimeoutMs,
                 });
                 await analytics.track({
                     name: verification.verified ? 'purchase_granted' : 'purchase_rejected',
@@ -121,6 +166,8 @@ export function createGameServicesBackend(input) {
                     placements: input.placements,
                     store,
                     now,
+                    evidenceVerifier,
+                    evidenceVerificationTimeoutMs,
                 });
                 await analytics.track({
                     name: claim.granted ? 'rewarded_ad_granted' : 'rewarded_ad_rejected',
@@ -259,6 +306,28 @@ export function createGameServicesHttpFetchHandler(handler, options = {}) {
 }
 async function verifyPurchaseWithStore(input, context) {
     const request = assertVerifyPurchaseRequest(input);
+    const retryIdentity = {
+        source: 'purchase',
+        playerId: request.playerId,
+        idempotencyKey: request.idempotencyKey,
+        grantId: request.productId,
+        target: request.target,
+    };
+    const existing = await findEntitlementTransactionByIdempotency(context.store, retryIdentity);
+    if (existing !== undefined) {
+        if (!matchesEntitlementRetry(existing, retryIdentity)) {
+            return assertVerifyPurchaseResponse({
+                verified: false,
+                alreadyProcessed: false,
+                reason: 'IDEMPOTENCY_KEY_CONFLICT',
+            });
+        }
+        return assertVerifyPurchaseResponse({
+            verified: true,
+            ledgerEntryId: existing.ledgerEntryId,
+            alreadyProcessed: true,
+        });
+    }
     const product = context.catalog.products.find((entry) => entry.id === request.productId);
     if (product === undefined) {
         return assertVerifyPurchaseResponse({
@@ -275,29 +344,88 @@ async function verifyPurchaseWithStore(input, context) {
             reason: 'PRODUCT_NOT_AVAILABLE_ON_TARGET',
         });
     }
-    const grant = await context.store.recordEntitlementGrant({
+    const verification = await verifyEvidence((signal) => {
+        return context.evidenceVerifier.verifyPurchase({
+            request,
+            product,
+            platformProductId,
+            signal,
+            timeoutMs: context.evidenceVerificationTimeoutMs,
+        });
+    }, context.evidenceVerificationTimeoutMs);
+    if (verification.status !== 'verified') {
+        return assertVerifyPurchaseResponse({
+            verified: false,
+            alreadyProcessed: false,
+            reason: verification.status === 'pending'
+                ? (verification.reason ?? 'EVIDENCE_PENDING')
+                : verification.reason,
+        });
+    }
+    const grant = await recordEntitlementGrantWithEvidence(context.store, {
         playerId: request.playerId,
         grantId: product.id,
         source: 'purchase',
         idempotencyKey: request.idempotencyKey,
         grantedAt: context.now(),
         grant: product.grant,
+        evidenceVerificationId: verification.verificationId,
         payload: {
+            ...verification.payload,
             target: request.target,
             productId: request.productId,
             platformProductId,
             platformTransactionId: request.platformTransactionId,
             purchasedAt: request.purchasedAt,
+            evidenceVerificationId: verification.verificationId,
+            evidenceVerifiedAt: verification.verifiedAt,
         },
     });
+    if (grant.status === 'evidence_already_processed') {
+        return assertVerifyPurchaseResponse({
+            verified: false,
+            alreadyProcessed: false,
+            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',
+        });
+    }
     return assertVerifyPurchaseResponse({
         verified: true,
-        ledgerEntryId: grant.ledgerEntryId,
-        alreadyProcessed: grant.alreadyProcessed,
+        ledgerEntryId: grant.result.ledgerEntryId,
+        alreadyProcessed: grant.result.alreadyProcessed,
     });
 }
 async function claimAdRewardWithStore(input, context) {
     const request = assertClaimAdRewardRequest(input);
+    const retryIdentity = {
+        source: 'ad_reward',
+        playerId: request.playerId,
+        idempotencyKey: request.idempotencyKey,
+        grantId: request.placementId,
+        target: request.target,
+    };
+    const existing = await findEntitlementTransactionByIdempotency(context.store, retryIdentity);
+    if (existing !== undefined) {
+        if (!matchesEntitlementRetry(existing, retryIdentity)) {
+            return assertClaimAdRewardResponse({
+                granted: false,
+                alreadyProcessed: false,
+                reason: 'IDEMPOTENCY_KEY_CONFLICT',
+            });
+        }
+        return assertClaimAdRewardResponse({
+            granted: true,
+            ledgerEntryId: existing.ledgerEntryId,
+            alreadyProcessed: true,
+        });
+    }
     const placement = context.placements.placements.find((entry) => entry.id === request.placementId);
     if (placement === undefined || placement.type !== 'rewarded' || placement.reward === undefined) {
         return assertClaimAdRewardResponse({
@@ -306,12 +434,34 @@ async function claimAdRewardWithStore(input, context) {
             reason: placement === undefined ? 'UNKNOWN_PLACEMENT' : 'NOT_REWARDED_PLACEMENT',
         });
     }
+    const platformPlacementId = placement.platformPlacementIds[request.target];
+    const verification = await verifyEvidence((signal) => {
+        return context.evidenceVerifier.verifyAdReward({
+            request,
+            placement,
+            ...(platformPlacementId === undefined ? {} : { platformPlacementId }),
+            signal,
+            timeoutMs: context.evidenceVerificationTimeoutMs,
+        });
+    }, context.evidenceVerificationTimeoutMs);
+    if (verification.status !== 'verified') {
+        return assertClaimAdRewardResponse({
+            granted: false,
+            alreadyProcessed: false,
+            reason: verification.status === 'pending'
+                ? (verification.reason ?? 'EVIDENCE_PENDING')
+                : verification.reason,
+        });
+    }
     const payload = {
+        ...verification.payload,
         target: request.target,
         placementId: request.placementId,
         rewardType: placement.reward.type,
         amount: placement.reward.amount,
         completedAt: request.completedAt,
+        evidenceVerificationId: verification.verificationId,
+        evidenceVerifiedAt: verification.verifiedAt,
     };
     if (placement.reward.type === 'currency') {
         payload.currency = placement.reward.currency;
@@ -319,20 +469,281 @@ async function claimAdRewardWithStore(input, context) {
     if (request.platformImpressionId !== undefined) {
         payload.platformImpressionId = request.platformImpressionId;
     }
-    const result = await context.store.recordEntitlementGrant({
+    const result = await recordEntitlementGrantWithEvidence(context.store, {
         playerId: request.playerId,
         grantId: request.placementId,
         source: 'ad_reward',
         idempotencyKey: request.idempotencyKey,
         grantedAt: context.now(),
+        evidenceVerificationId: verification.verificationId,
         payload,
     });
+    if (result.status === 'evidence_already_processed') {
+        return assertClaimAdRewardResponse({
+            granted: false,
+            alreadyProcessed: false,
+            reason: 'EVIDENCE_ALREADY_PROCESSED',
+        });
+    }
+    if (result.result.alreadyProcessed
+        && !await recordedEntitlementMatchesRetry(context.store, result.result, retryIdentity)) {
+        return assertClaimAdRewardResponse({
+            granted: false,
+            alreadyProcessed: false,
+            reason: 'IDEMPOTENCY_KEY_CONFLICT',
+        });
+    }
     return assertClaimAdRewardResponse({
         granted: true,
-        ledgerEntryId: result.ledgerEntryId,
-        alreadyProcessed: result.alreadyProcessed,
+        ledgerEntryId: result.result.ledgerEntryId,
+        alreadyProcessed: result.result.alreadyProcessed,
     });
 }
+async function verifyEvidence(verify, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutDecision = {
+        status: 'rejected',
+        reason: 'EVIDENCE_VERIFIER_TIMEOUT',
+    };
+    let timedOut = false;
+    let timeout;
+    try {
+        return await Promise.race([
+            verify(controller.signal)
+                .then(assertEvidenceVerificationDecision)
+                .catch((error) => {
+                if (timedOut) {
+                    return timeoutDecision;
+                }
+                throw error;
+            }),
+            new Promise((resolve) => {
+                timeout = setTimeout(() => {
+                    timedOut = true;
+                    resolve(timeoutDecision);
+                    controller.abort();
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        return {
+            status: 'rejected',
+            reason: 'EVIDENCE_VERIFIER_ERROR',
+        };
+    }
+    finally {
+        if (timeout !== undefined) {
+            clearTimeout(timeout);
+        }
+    }
+}
+function assertEvidenceVerificationDecision(decision) {
+    if (decision.status === 'verified') {
+        assertNonEmptyDecisionString(decision.verificationId, 'verificationId');
+        assertNonEmptyDecisionString(decision.verifiedAt, 'verifiedAt');
+        if (!Number.isFinite(Date.parse(decision.verifiedAt))) {
+            throw new Error('Evidence verification verifiedAt must be a valid timestamp.');
+        }
+        if (decision.payload !== undefined) {
+            if (typeof decision.payload !== 'object'
+                || decision.payload === null
+                || Array.isArray(decision.payload)) {
+                throw new Error('Evidence verification payload must be a record.');
+            }
+            for (const [key, value] of Object.entries(decision.payload)) {
+                if (typeof value !== 'string'
+                    && (typeof value !== 'number' || !Number.isFinite(value))
+                    && typeof value !== 'boolean') {
+                    throw new Error(`Evidence verification payload.${key} must be primitive.`);
+                }
+            }
+        }
+        return decision;
+    }
+    if (decision.status === 'pending') {
+        if (decision.reason !== undefined) {
+            assertNonEmptyDecisionString(decision.reason, 'reason');
+        }
+        return decision;
+    }
+    if (decision.status === 'rejected') {
+        assertNonEmptyDecisionString(decision.reason, 'reason');
+        return decision;
+    }
+    throw new Error('Unknown evidence verification status.');
+}
+async function recordEntitlementGrantWithEvidence(store, grant) {
+    const evidenceVerificationId = grant.evidenceVerificationId;
+    if (evidenceVerificationId !== undefined) {
+        const evidenceIdentity = {
+            source: grant.source,
+            evidenceVerificationId,
+        };
+        const platformEvidenceIdentity = getEntitlementPlatformEvidenceIdentity(grant);
+        const lockKeys = [createEntitlementEvidenceKey(evidenceIdentity)];
+        if (platformEvidenceIdentity !== undefined) {
+            lockKeys.push(createEntitlementPlatformEvidenceKey(platformEvidenceIdentity));
+        }
+        return withEntitlementEvidenceLocks(store, lockKeys, async () => {
+            const authorityMatch = await findEntitlementTransactionByEvidenceVerificationId(store, {
+                source: grant.source,
+                evidenceVerificationId,
+            });
+            const existing = authorityMatch ?? (platformEvidenceIdentity === undefined
+                ? undefined
+                : await findEntitlementTransactionByPlatformEvidence(store, platformEvidenceIdentity));
+            if (existing !== undefined) {
+                if (existing.source === grant.source
+                    && existing.playerId === grant.playerId
+                    && existing.idempotencyKey === grant.idempotencyKey) {
+                    return {
+                        status: 'recorded',
+                        result: assertEntitlementLedgerResult({
+                            ledgerEntryId: existing.ledgerEntryId,
+                            alreadyProcessed: true,
+                        }),
+                    };
+                }
+                return { status: 'evidence_already_processed' };
+            }
+            return recordEntitlementGrantUnchecked(store, grant);
+        });
+    }
+    return recordEntitlementGrantUnchecked(store, grant);
+}
+async function recordEntitlementGrantUnchecked(store, grant) {
+    try {
+        return {
+            status: 'recorded',
+            result: await store.recordEntitlementGrant(grant),
+        };
+    }
+    catch (error) {
+        if (error instanceof EvidenceAlreadyProcessedError) {
+            return { status: 'evidence_already_processed' };
+        }
+        throw error;
+    }
+}
+const entitlementEvidenceLocks = new WeakMap();
+async function withEntitlementEvidenceLocks(store, lockKeys, task) {
+    const orderedLockKeys = [...new Set(lockKeys)].sort((left, right) => left.localeCompare(right));
+    async function runWithLock(index) {
+        const lockKey = orderedLockKeys[index];
+        return lockKey === undefined
+            ? task()
+            : withEntitlementEvidenceLockKey(store, lockKey, () => runWithLock(index + 1));
+    }
+    return runWithLock(0);
+}
+async function withEntitlementEvidenceLockKey(store, lockKey, task) {
+    const storeLocks = entitlementEvidenceLocks.get(store) ?? new Map();
+    entitlementEvidenceLocks.set(store, storeLocks);
+    const previous = storeLocks.get(lockKey) ?? Promise.resolve();
+    const gate = createPromiseGate();
+    const current = previous.then(() => gate.promise);
+    storeLocks.set(lockKey, current);
+    await previous;
+    try {
+        return await task();
+    }
+    finally {
+        gate.release();
+        if (storeLocks.get(lockKey) === current) {
+            storeLocks.delete(lockKey);
+            if (storeLocks.size === 0) {
+                entitlementEvidenceLocks.delete(store);
+            }
+        }
+    }
+}
+function createPromiseGate() {
+    let release = () => { };
+    const promise = new Promise((resolve) => {
+        release = resolve;
+    });
+    return { promise, release };
+}
+async function findEntitlementTransactionByIdempotency(store, identity) {
+    if (store.findEntitlementTransactionByIdempotency !== undefined) {
+        return store.findEntitlementTransactionByIdempotency(identity);
+    }
+    const transactions = await store.listEntitlementTransactions();
+    return transactions.find((transaction) => {
+        return transaction.source === identity.source
+            && transaction.playerId === identity.playerId
+            && transaction.idempotencyKey === identity.idempotencyKey;
+    });
+}
+async function findEntitlementTransactionByEvidenceVerificationId(store, input) {
+    if (store.findEntitlementTransactionByEvidenceVerificationId !== undefined) {
+        return store.findEntitlementTransactionByEvidenceVerificationId(input);
+    }
+    const transactions = await store.listEntitlementTransactions();
+    return transactions.find((transaction) => {
+        const storedEvidenceVerificationId = transaction.evidenceVerificationId
+            ?? transaction.payload.evidenceVerificationId;
+        return transaction.source === input.source
+            && storedEvidenceVerificationId === input.evidenceVerificationId;
+    });
+}
+async function findEntitlementTransactionByPlatformEvidence(store, input) {
+    if (store.findEntitlementTransactionByPlatformEvidence !== undefined) {
+        return store.findEntitlementTransactionByPlatformEvidence(input);
+    }
+    const transactions = await store.listEntitlementTransactions();
+    return transactions.find((transaction) => {
+        const identity = getEntitlementPlatformEvidenceIdentity(transaction);
+        return identity !== undefined
+            && identity.source === input.source
+            && identity.target === input.target
+            && identity.platformEvidenceId === input.platformEvidenceId;
+    });
+}
+function getEntitlementPlatformEvidenceIdentity(transaction) {
+    if (transaction.source !== 'purchase' && transaction.source !== 'ad_reward') {
+        return undefined;
+    }
+    const target = transaction.payload.target;
+    const platformEvidenceId = transaction.source === 'purchase'
+        ? transaction.payload.platformTransactionId
+        : transaction.payload.platformImpressionId;
+    if (typeof target !== 'string'
+        || target.length === 0
+        || typeof platformEvidenceId !== 'string'
+        || platformEvidenceId.length === 0) {
+        return undefined;
+    }
+    return {
+        source: transaction.source,
+        target,
+        platformEvidenceId,
+    };
+}
+async function recordedEntitlementMatchesRetry(store, result, identity) {
+    const transaction = await store.getEntitlementTransaction(result.ledgerEntryId);
+    return transaction !== undefined && matchesEntitlementRetry(transaction, identity);
+}
+function matchesEntitlementRetry(transaction, identity) {
+    return transaction.source === identity.source
+        && transaction.playerId === identity.playerId
+        && transaction.idempotencyKey === identity.idempotencyKey
+        && transaction.grantId === identity.grantId
+        && transaction.payload.target === identity.target;
+}
+function resolveEvidenceVerificationTimeout(timeoutMs) {
+    const resolved = timeoutMs ?? 10000;
+    if (!Number.isFinite(resolved) || resolved <= 0) {
+        throw new Error('evidenceVerificationTimeoutMs 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.`);
+    }
+}
 async function recordLeaderboardScoreWithStore(input, context) {
     return context.store.recordLeaderboardScore(assertRecordLeaderboardScoreRequest(input), {
         recordedAt: context.now(),
@@ -379,12 +790,21 @@ function createEntitlementTransaction(grant) {
         idempotencyKey: grant.idempotencyKey,
         grantedAt: grant.grantedAt,
         payload: grant.payload,
+        ...(grant.evidenceVerificationId === undefined
+            ? {}
+            : { evidenceVerificationId: grant.evidenceVerificationId }),
     };
     return assertProductGrantTransaction(grant.grant === undefined ? baseTransaction : { ...baseTransaction, grant: grant.grant });
 }
 function createEntitlementIdempotencyKey(grant) {
     return createCompositeKey([grant.source, grant.playerId, grant.idempotencyKey]);
 }
+function createEntitlementEvidenceKey(grant) {
+    return createCompositeKey([grant.source, grant.evidenceVerificationId]);
+}
+function createEntitlementPlatformEvidenceKey(identity) {
+    return createCompositeKey([identity.source, identity.target, identity.platformEvidenceId]);
+}
 function createEntitlementLedgerEntryId(grant) {
     return [
         'ledger',

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { ProductGrant } from '@mpgd/catalog';
-import type { LeaderboardScoreInput, LogicalAdPlacementId, LogicalProductId, PlatformTarget } from '@mpgd/platform';
+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 PurchaseIdempotencyKey = string;
@@ -14,6 +15,7 @@ export interface VerifyPurchaseRequest {
   readonly platformTransactionId: string;
   readonly idempotencyKey: PurchaseIdempotencyKey;
   readonly purchasedAt: string;
+  readonly evidence?: PlatformEvidenceEnvelope;
 }
 export interface VerifyPurchaseResponse {
   readonly verified: boolean;
@@ -28,12 +30,13 @@ export interface ClaimAdRewardRequest {
   readonly platformImpressionId?: string;
   readonly idempotencyKey: AdRewardIdempotencyKey;
   readonly completedAt: string;
+  readonly evidence?: PlatformEvidenceEnvelope;
 }
 export interface ClaimAdRewardResponse {
   readonly granted: boolean;
   readonly ledgerEntryId?: string;
   readonly alreadyProcessed: boolean;
-  readonly reason?: 'UNKNOWN_PLACEMENT' | 'NOT_REWARDED_PLACEMENT';
+  readonly reason?: string;
 }
 export interface RecordLeaderboardScoreRequest extends LeaderboardScoreInput {
   readonly target: GameServicesLedgerTarget;
@@ -54,6 +57,7 @@ export interface EntitlementLedgerGrant {
   readonly grantedAt: string;
   readonly grant?: ProductGrant;
   readonly payload: EntitlementLedgerPayload;
+  readonly evidenceVerificationId?: string;
 }
 export interface EntitlementLedgerResult {
   readonly ledgerEntryId: string;
@@ -68,6 +72,7 @@ export interface ProductGrantTransaction {
   readonly grantedAt: string;
   readonly grant?: ProductGrant;
   readonly payload: EntitlementLedgerPayload;
+  readonly evidenceVerificationId?: string;
 }
 export interface LeaderboardScoreTransaction extends RecordLeaderboardScoreRequest {
   readonly ledgerEntryId: string;

package/dist/types.js

@@ -6,6 +6,7 @@ export function assertVerifyPurchaseRequest(input) {
     assertNonEmptyString(input.platformTransactionId, 'platformTransactionId');
     assertNonEmptyString(input.idempotencyKey, 'idempotencyKey');
     assertNonEmptyString(input.purchasedAt, 'purchasedAt');
+    assertOptionalEvidenceEnvelope(input.evidence);
     return input;
 }
 export function assertVerifyPurchaseResponse(input) {
@@ -24,6 +25,7 @@ export function assertClaimAdRewardRequest(input) {
     assertOptionalNonEmptyString(input.platformImpressionId, 'platformImpressionId');
     assertNonEmptyString(input.idempotencyKey, 'idempotencyKey');
     assertNonEmptyString(input.completedAt, 'completedAt');
+    assertOptionalEvidenceEnvelope(input.evidence);
     return input;
 }
 export function assertClaimAdRewardResponse(input) {
@@ -31,7 +33,7 @@ export function assertClaimAdRewardResponse(input) {
     assertBoolean(input.granted, 'granted');
     assertOptionalNonEmptyString(input.ledgerEntryId, 'ledgerEntryId');
     assertBoolean(input.alreadyProcessed, 'alreadyProcessed');
-    assertOptionalAdRewardReason(input.reason, 'reason');
+    assertOptionalNonEmptyString(input.reason, 'reason');
     return input;
 }
 export function assertRecordLeaderboardScoreRequest(input) {
@@ -64,6 +66,7 @@ export function assertEntitlementLedgerGrant(input) {
         assertProductGrant(input.grant);
     }
     assertPayload(input.payload);
+    assertOptionalNonEmptyString(input.evidenceVerificationId, 'evidenceVerificationId');
     return input;
 }
 export function assertEntitlementLedgerResult(input) {
@@ -84,6 +87,7 @@ export function assertProductGrantTransaction(input) {
         assertProductGrant(input.grant);
     }
     assertPayload(input.payload);
+    assertOptionalNonEmptyString(input.evidenceVerificationId, 'evidenceVerificationId');
     return input;
 }
 export function assertLeaderboardScoreTransaction(input) {
@@ -151,13 +155,6 @@ function assertProductGrant(input) {
     }
     throw new Error('grant.type must be currency or entitlement.');
 }
-function assertOptionalAdRewardReason(input, label) {
-    if (input !== undefined
-        && input !== 'UNKNOWN_PLACEMENT'
-        && input !== 'NOT_REWARDED_PLACEMENT') {
-        throw new Error(`${label} must be UNKNOWN_PLACEMENT or NOT_REWARDED_PLACEMENT.`);
-    }
-}
 function assertPayload(input) {
     assertRecord(input, 'payload');
     for (const [key, value] of Object.entries(input)) {
@@ -167,3 +164,11 @@ function assertPayload(input) {
         }
     }
 }
+function assertOptionalEvidenceEnvelope(input) {
+    if (input === undefined) {
+        return;
+    }
+    assertRecord(input, 'evidence');
+    assertNonEmptyString(input.schema, 'evidence.schema');
+    assertPayload(input.payload);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -37,10 +37,18 @@
       "types": "./dist/contract.d.ts",
       "default": "./dist/contract.js"
     },
+    "./evidence-verification": {
+      "types": "./dist/evidence-verification.d.ts",
+      "default": "./dist/evidence-verification.js"
+    },
     "./notification-delivery": {
       "types": "./dist/notification-delivery.d.ts",
       "default": "./dist/notification-delivery.js"
     },
+    "./platform-order": {
+      "types": "./dist/platform-order.d.ts",
+      "default": "./dist/platform-order.js"
+    },
     "./progress-link": {
       "types": "./dist/progress-link.d.ts",
       "default": "./dist/progress-link.js"
@@ -77,9 +85,9 @@
     "@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.5",
-    "@mpgd/catalog": "0.3.5",
-    "@mpgd/platform": "0.5.1"
+    "@mpgd/analytics": "0.3.6",
+    "@mpgd/catalog": "0.4.0",
+    "@mpgd/platform": "0.6.0"
   },
   "devDependencies": {
     "ttsc": "0.18.4",
@@ -95,6 +103,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/server.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-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/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-transport.test.ts"
   }
 }