@mpgd/game-services 0.6.0 → 0.8.0

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);
+}