@mpgd/game-services 0.21.1 → 0.23.0

package/dist/server.js

@@ -3,16 +3,22 @@ import { BodyLimitHandlerPlugin, RPCHandler } from '@orpc/server/fetch';
 import { createAnalyticsReporter } from '@mpgd/analytics';
 import { resolveAdPlacementPlatformId, resolveCatalogCurrencies, resolveProductPlatformId, } from '@mpgd/catalog';
 import { gameServicesBackendEndpoints, } from './client.js';
+import { resolveCommerceStoreId, } from './commerce-evidence-registry.js';
+import { isEntitlementGrantReversed, readPurchaseLedgerStatuses, RevocationKeyConflictError, } from './commerce-ledger.js';
 import { gameServicesContract } from './contract.js';
 import { createRejectingGameServicesEvidenceVerifier, } from './evidence-verification.js';
-import { assertClaimAdRewardRequest, assertClaimAdRewardResponse, assertEntitlementLedgerGrant, assertEntitlementLedgerResult, assertGameServicesDeploymentTarget, assertLeaderboardScoreTransaction, assertProductGrantTransaction, assertPurchaseGrantFinalization, assertRecordLeaderboardScoreRequest, assertRecordLeaderboardScoreResponse, assertVerifyPurchaseRequest, assertVerifyPurchaseResponse, } from './types.js';
+import { assertClaimAdRewardRequest, assertClaimAdRewardResponse, assertEntitlementLedgerGrant, assertEntitlementLedgerResult, assertEntitlementLedgerRevocation, assertEntitlementRevocationTransaction, assertGameServicesDeploymentTarget, assertLeaderboardScoreTransaction, assertProductGrantTransaction, assertPurchaseGrantFinalization, assertRecordLeaderboardScoreRequest, assertRecordLeaderboardScoreResponse, assertVerifyPurchaseRequest, assertVerifyPurchaseResponse, } from './types.js';
 import { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
 export { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
+export { listActiveEntitlementTransactions, readPurchaseLedgerStatuses, revokeEntitlementGrant, RevocationKeyConflictError, } from './commerce-ledger.js';
 export class InMemoryGameServicesStore {
     entitlementTransactionsByKey = new Map();
     entitlementTransactionsByEvidence = new Map();
     entitlementTransactionsByPlatformEvidence = new Map();
     entitlementTransactionsById = new Map();
+    revocationsByKey = new Map();
+    revocationsByGrant = new Map();
+    revocationsByEvidence = new Map();
     leaderboardTransactionsByRun = new Map();
     leaderboardTransactionsById = new Map();
     async recordEntitlementGrant(input) {
@@ -71,6 +77,64 @@ export class InMemoryGameServicesStore {
     async listEntitlementTransactions() {
         return [...this.entitlementTransactionsById.values()];
     }
+    async getEntitlementTransactions(ledgerEntryIds) {
+        const found = [];
+        for (const ledgerEntryId of new Set(ledgerEntryIds)) {
+            const transaction = this.entitlementTransactionsById.get(ledgerEntryId);
+            if (transaction !== undefined) {
+                found.push(transaction);
+            }
+        }
+        return found;
+    }
+    async recordEntitlementRevocation(input) {
+        const revocation = assertEntitlementLedgerRevocation(input);
+        const key = createRevocationIdempotencyKey(revocation);
+        const byKey = this.revocationsByKey.get(key);
+        if (byKey !== undefined) {
+            if (byKey.revokesLedgerEntryId !== revocation.revokesLedgerEntryId) {
+                throw new RevocationKeyConflictError();
+            }
+            return assertEntitlementLedgerResult({
+                ledgerEntryId: byKey.ledgerEntryId,
+                alreadyProcessed: true,
+            });
+        }
+        const byGrant = this.revocationsByGrant.get(revocation.revokesLedgerEntryId);
+        if (byGrant !== undefined) {
+            return assertEntitlementLedgerResult({
+                ledgerEntryId: byGrant.ledgerEntryId,
+                alreadyProcessed: true,
+            });
+        }
+        if (revocation.evidenceVerificationId !== undefined
+            && this.revocationsByEvidence.has(revocation.evidenceVerificationId)) {
+            throw new EvidenceAlreadyProcessedError();
+        }
+        if (!this.entitlementTransactionsById.has(revocation.revokesLedgerEntryId)) {
+            // The D1 store's foreign key refuses the same write.
+            throw new Error('Entitlement revocation references an unknown grant.');
+        }
+        const transaction = assertEntitlementRevocationTransaction({
+            ...revocation,
+            ledgerEntryId: createRevocationLedgerEntryId(revocation),
+        });
+        this.revocationsByKey.set(key, transaction);
+        this.revocationsByGrant.set(revocation.revokesLedgerEntryId, transaction);
+        if (revocation.evidenceVerificationId !== undefined) {
+            this.revocationsByEvidence.set(revocation.evidenceVerificationId, transaction);
+        }
+        return assertEntitlementLedgerResult({
+            ledgerEntryId: transaction.ledgerEntryId,
+            alreadyProcessed: false,
+        });
+    }
+    async findEntitlementRevocations(input) {
+        const wanted = new Set(input.ledgerEntryIds);
+        return [...this.revocationsByGrant.values()]
+            .filter((revocation) => wanted.has(revocation.revokesLedgerEntryId))
+            .sort((left, right) => left.revokedAt.localeCompare(right.revokedAt));
+    }
     async recordLeaderboardScore(input, options = {}) {
         const request = assertRecordLeaderboardScoreRequest(input);
         const runKey = createLeaderboardRunKey(request);
@@ -141,6 +205,25 @@ export function createGameServicesBackend(input) {
         now,
         ...(input.analytics === undefined ? {} : { sink: input.analytics }),
     });
+    const registry = input.commerceEvidenceRegistry;
+    if (registry !== undefined && input.purchaseGrantFinalizer !== undefined) {
+        throw new Error('createGameServicesBackend: pass the v1 purchaseGrantFinalizer as the registry '
+            + 'unregistered.finalizer instead of next to commerceEvidenceRegistry; with a registry '
+            + 'the entries own finalization.');
+    }
+    // With a registry, purchase evidence is routed by schema and the registry's
+    // finalizer owns post-grant finalization; the configured verifier keeps
+    // serving rewarded ads. Without one, the v1 single verifier and finalizer
+    // serve every purchase unchanged.
+    const purchaseEvidenceVerifier = registry === undefined
+        ? evidenceVerifier
+        : {
+            verifyPurchase: (verificationInput) => registry.verifyPurchase(verificationInput),
+            verifyAdReward: (verificationInput) => evidenceVerifier.verifyAdReward(verificationInput),
+        };
+    const purchaseGrantFinalizer = registry === undefined
+        ? input.purchaseGrantFinalizer
+        : registry.finalizer;
     return {
         version,
         purchases: {
@@ -149,19 +232,21 @@ export function createGameServicesBackend(input) {
                     catalog: input.catalog,
                     store,
                     now,
-                    evidenceVerifier,
+                    evidenceVerifier: purchaseEvidenceVerifier,
                     evidenceVerificationTimeoutMs,
                     purchaseGrantFinalizationTimeoutMs,
                     deploymentTargetBindings,
-                    ...(input.purchaseGrantFinalizer === undefined
+                    ...(purchaseGrantFinalizer === undefined
                         ? {}
-                        : { purchaseGrantFinalizer: input.purchaseGrantFinalizer }),
+                        : { purchaseGrantFinalizer }),
+                    ...(registry === undefined ? {} : { registry }),
                 }, async (verification) => {
                     await analytics.track({
                         name: verification.verified ? 'purchase_granted'
                             : verification.disposition === 'pending' ? 'purchase_pending' : 'purchase_rejected',
                         properties: {
                             target: request.target,
+                            store: resolveCommerceStoreId(request),
                             playerId: request.playerId,
                             productId: request.productId,
                             ledgerEntryId: verification.ledgerEntryId,
@@ -175,6 +260,16 @@ export function createGameServicesBackend(input) {
                     });
                 });
             },
+            async getPurchaseLedgerStatus(request) {
+                return readPurchaseLedgerStatuses(store, request);
+            },
+            ...(registry === undefined
+                ? {}
+                : {
+                    async getCommerceCapabilities() {
+                        return registry.getCapabilities();
+                    },
+                }),
         },
         adRewards: {
             async claimAdReward(request) {
@@ -321,6 +416,22 @@ export function createGameServicesRouter(backend, options = {}) {
             verifyPurchase: contract.commerce.verifyPurchase.handler(({ input }) => {
                 return invoke(() => backend.purchases.verifyPurchase(input));
             }),
+            getPurchaseLedgerStatus: contract.commerce.getPurchaseLedgerStatus.handler(({ input }) => {
+                const read = backend.purchases.getPurchaseLedgerStatus;
+                if (read === undefined) {
+                    throw new ORPCError('NOT_FOUND', { message: 'This backend has no ledger status read.' });
+                }
+                return invoke(() => read.call(backend.purchases, input));
+            }),
+            getCapabilities: contract.commerce.getCapabilities.handler(() => {
+                const read = backend.purchases.getCommerceCapabilities;
+                if (read === undefined) {
+                    throw new ORPCError('NOT_FOUND', {
+                        message: 'This backend publishes no commerce capabilities.',
+                    });
+                }
+                return invoke(() => read.call(backend.purchases));
+            }),
         }),
         ads: contract.ads.router({
             claimReward: contract.ads.claimReward.handler(({ input }) => {
@@ -436,7 +547,9 @@ function resolveDeploymentTargetBindings(input) {
     return bindings;
 }
 function bindRequestDeploymentTarget(request, bindings) {
-    const deploymentTarget = bindings[request.target] ?? request.target;
+    const deploymentTarget = (Object.hasOwn(bindings, request.target)
+        ? bindings[request.target]
+        : undefined) ?? request.target;
     if (request.deploymentTarget !== undefined
         && request.deploymentTarget !== deploymentTarget) {
         throw new GameServicesRequestValidationError(`deploymentTarget must match the backend binding for ${request.target}.`);
@@ -445,14 +558,58 @@ function bindRequestDeploymentTarget(request, bindings) {
         ? request
         : { ...request, deploymentTarget };
 }
+/** The ledger targets a v1 backend (no registry) accepts: the platform targets with a ledger. */
+const gameServicesLedgerTargets = new Set([
+    'browser',
+    'microsoft-store',
+    'android',
+    'ios',
+    'ait',
+    'reddit',
+    'verse8',
+    'oneplay',
+]);
+/**
+ * A target or store the backend does not serve is a 400, as an unknown v1
+ * target was: without a registry the ledger targets are the known platform
+ * targets; with one, the store must be registered (or declared for the
+ * fallback) and the target a ledger target or a served store id.
+ */
+function assertServedPurchaseRequest(request, registry) {
+    if (registry === undefined) {
+        if (!gameServicesLedgerTargets.has(request.target)) {
+            throw new GameServicesRequestValidationError(`target ${request.target} is not a ledger target this backend serves.`);
+        }
+        return;
+    }
+    const store = resolveCommerceStoreId(request);
+    if (!registry.serves(request)) {
+        throw new GameServicesRequestValidationError(`store ${store} is not a store this backend serves for target ${request.target}.`);
+    }
+    // A served store's declared targets are the contract (a custom store may
+    // name a custom ledger target); a store without declared targets keeps the
+    // ledger target set and the served store ids.
+    const allowed = registry.allowedTargets(store);
+    if (allowed !== undefined) {
+        if (!allowed.has(request.target)) {
+            throw new GameServicesRequestValidationError(`target ${request.target} is not a ledger target of store ${store}.`);
+        }
+        return;
+    }
+    if (!gameServicesLedgerTargets.has(request.target) && !registry.stores.has(request.target)) {
+        throw new GameServicesRequestValidationError(`target ${request.target} is not a ledger target this backend serves.`);
+    }
+}
 async function verifyPurchaseWithStore(input, context, onDecision) {
     const request = bindRequestDeploymentTarget(assertVerifyPurchaseRequest(input), context.deploymentTargetBindings);
+    assertServedPurchaseRequest(request, context.registry);
     const retryIdentity = {
         source: 'purchase',
         playerId: request.playerId,
         idempotencyKey: request.idempotencyKey,
         grantId: request.productId,
         target: request.target,
+        store: resolveCommerceStoreId(request),
         ...(request.deploymentTarget === undefined
             ? {}
             : { deploymentTarget: request.deploymentTarget }),
@@ -472,6 +629,15 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
                 reason: 'IDEMPOTENCY_KEY_CONFLICT',
             });
         }
+        if (await isEntitlementGrantReversed(context.store, transaction.ledgerEntryId)) {
+            // A replayed key for a refunded grant is not a grant, as the lookup path answers.
+            return assertVerifyPurchaseResponse({
+                verified: false,
+                alreadyProcessed: false,
+                disposition: 'rejected',
+                reason: 'LEDGER_GRANT_REVERSED',
+            });
+        }
         const finalization = await finalizeExistingPurchaseGrant(request, transaction, context);
         return assertVerifyPurchaseResponse({
             verified: true,
@@ -509,6 +675,12 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
             timeoutMs: context.evidenceVerificationTimeoutMs,
         });
     }, context.evidenceVerificationTimeoutMs);
+    if (verification.status === 'settled') {
+        // A server-push lookup found the grant the host's fulfillment path wrote.
+        // Nothing is written; the entry is answered once it is checked against
+        // the requesting player, product, and target.
+        return completeSettledPurchase(request, verification, context);
+    }
     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.
@@ -527,6 +699,14 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
     }
     const verificationPayload = createVerificationPayload(verification, 'platformTransactionId');
     const platformTransactionId = resolvePlatformEvidenceId(verification, request.platformTransactionId);
+    const evidenceSchema = request.evidence?.schema;
+    // The store written is the one the registry routed to (an entry's own
+    // store, or a declared fallback store); a fallback serving undeclared
+    // stores and the v1 path record the request's resolved store.
+    const routed = context.registry?.route(request);
+    const verifiedStore = routed?.status === 'routed'
+        ? routed.entry.store
+        : resolveCommerceStoreId(request);
     const grant = await recordEntitlementGrantWithEvidence(context.store, {
         playerId: request.playerId,
         grantId: product.id,
@@ -538,6 +718,7 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
         payload: {
             ...verificationPayload,
             target: request.target,
+            store: verifiedStore,
             ...(request.deploymentTarget === undefined
                 ? {}
                 : { deploymentTarget: request.deploymentTarget }),
@@ -546,6 +727,7 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
             platformProductId,
             ...(platformTransactionId === undefined ? {} : { platformTransactionId }),
             purchasedAt: request.purchasedAt,
+            ...(evidenceSchema === undefined ? {} : { evidenceSchema }),
             evidenceVerificationId: verification.verificationId,
             evidenceVerifiedAt: verification.verifiedAt,
         },
@@ -557,11 +739,21 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
                 playerId: request.playerId,
                 grantId: request.productId,
                 target: request.target,
+                store: verifiedStore,
                 ...(request.deploymentTarget === undefined
                     ? {}
                     : { deploymentTarget: request.deploymentTarget }),
                 evidenceVerificationId: verification.verificationId,
             })) {
+            if (await isEntitlementGrantReversed(context.store, existingEvidence.ledgerEntryId)) {
+                // A refunded grant's evidence replayed under another key is not a grant.
+                return assertVerifyPurchaseResponse({
+                    verified: false,
+                    alreadyProcessed: false,
+                    disposition: 'rejected',
+                    reason: 'LEDGER_GRANT_REVERSED',
+                });
+            }
             const finalization = await finalizeExistingPurchaseGrant(request, existingEvidence, context);
             // A different idempotency key is evidence replay unless a configured finalizer can resume
             // the provider operation. Keep generic stores fail-closed while allowing Store consume
@@ -614,6 +806,47 @@ async function verifyPurchaseForRetry(request, retryIdentity, context) {
         ...(finalization === undefined ? {} : { finalization }),
     });
 }
+/**
+ * Answers a purchase a server-push lookup verifier found settled by an earlier
+ * ledger entry. The entry must be a purchase grant of the requesting player,
+ * product, and ledger target; a fulfillment path that bound the grant to a
+ * deployment target must agree with the request when both name one.
+ */
+async function completeSettledPurchase(request, decision, context) {
+    const settled = await context.store.getEntitlementTransaction(decision.ledgerEntryId);
+    if (settled === undefined
+        || settled.source !== 'purchase'
+        || settled.playerId !== request.playerId
+        || settled.grantId !== request.productId
+        || settled.payload.target !== (decision.ledgerTarget ?? request.target)
+        || (settled.payload.deploymentTarget !== undefined
+            && request.deploymentTarget !== undefined
+            && settled.payload.deploymentTarget !== request.deploymentTarget)) {
+        return assertVerifyPurchaseResponse({
+            verified: false,
+            alreadyProcessed: false,
+            disposition: 'rejected',
+            reason: 'LEDGER_GRANT_IDENTITY_MISMATCH',
+        });
+    }
+    if (await isEntitlementGrantReversed(context.store, settled.ledgerEntryId)) {
+        // `settled` is an open verifier contract; a reversed grant never settles
+        // a purchase, whichever verifier named it.
+        return assertVerifyPurchaseResponse({
+            verified: false,
+            alreadyProcessed: false,
+            disposition: 'rejected',
+            reason: 'LEDGER_GRANT_REVERSED',
+        });
+    }
+    const finalization = await finalizeExistingPurchaseGrant(request, settled, context);
+    return assertVerifyPurchaseResponse({
+        verified: true,
+        ledgerEntryId: settled.ledgerEntryId,
+        alreadyProcessed: true,
+        ...(finalization === undefined ? {} : { finalization }),
+    });
+}
 async function finalizeExistingPurchaseGrant(request, transaction, context) {
     if (context.purchaseGrantFinalizer === undefined) {
         return undefined;
@@ -630,6 +863,35 @@ async function finalizeExistingPurchaseGrant(request, transaction, context) {
         || platformProductId === undefined
         || typeof evidenceVerificationId !== 'string'
         || evidenceVerificationId.length === 0) {
+        // With a registry, a store nothing finalizes on the server (client,
+        // host, or none finish) has no pending finalization to report: the
+        // registry decides from the grant's recorded store and schema, never from
+        // the stand-in product. The v1 single finalizer keeps answering pending.
+        if (context.registry !== undefined) {
+            const recordedSchema = transaction.payload.evidenceSchema;
+            const supported = context.registry.finalizer.supportsPurchaseGrant?.({
+                request: typeof recordedSchema === 'string' && recordedSchema.length > 0
+                    ? { ...finalizationRequest, evidence: { schema: recordedSchema, payload: {} } }
+                    : finalizationRequest,
+                product: product ?? {
+                    id: request.productId,
+                    type: 'consumable',
+                    grant: transaction.grant ?? { type: 'entitlement', entitlement: request.productId },
+                    platformProductIds: {},
+                },
+                platformProductId: platformProductId ?? '',
+                evidenceVerificationId: typeof evidenceVerificationId === 'string'
+                    ? evidenceVerificationId
+                    : '',
+                evidencePayload: transaction.payload,
+                ledgerEntryId: transaction.ledgerEntryId,
+                alreadyProcessed: true,
+                timeoutMs: context.purchaseGrantFinalizationTimeoutMs,
+            });
+            if (supported === false) {
+                return undefined;
+            }
+        }
         return assertPurchaseGrantFinalization({
             status: 'pending',
             alreadyCompleted: false,
@@ -806,7 +1068,10 @@ async function claimAdRewardForRetry(request, retryIdentity, context) {
             disposition: verification.status === 'pending' ? 'pending' : 'rejected',
             reason: verification.status === 'pending'
                 ? (verification.reason ?? 'EVIDENCE_PENDING')
-                : verification.reason,
+                : verification.status === 'settled'
+                    // Only purchase verification reads a settled ledger entry.
+                    ? 'EVIDENCE_VERIFIER_ERROR'
+                    : verification.reason,
         });
     }
     // The client-reported impression id only becomes part of the globally unique platform
@@ -946,6 +1211,10 @@ function assertEvidenceVerificationDecision(decision) {
         }
         return decision;
     }
+    if (decision.status === 'settled') {
+        assertNonEmptyDecisionString(decision.ledgerEntryId, 'ledgerEntryId');
+        return decision;
+    }
     if (decision.status === 'pending') {
         if (decision.reason !== undefined) {
             assertNonEmptyDecisionString(decision.reason, 'reason');
@@ -1136,7 +1405,16 @@ function matchesEntitlementTransactionIdentity(transaction, identity) {
         && transaction.playerId === identity.playerId
         && transaction.grantId === identity.grantId
         && transaction.payload.target === identity.target
-        && transaction.payload.deploymentTarget === identity.deploymentTarget;
+        // Two stores sharing one ledger target never share a grant: a key reused
+        // with another store is a conflict, while a grant recorded before the
+        // store was written meets any store.
+        && (identity.store === undefined
+            || transaction.payload.store === undefined
+            || transaction.payload.store === identity.store)
+        // A grant written without a deployment target (a host fulfillment path)
+        // meets the request bound to one; two bound targets must agree.
+        && (transaction.payload.deploymentTarget === undefined
+            || transaction.payload.deploymentTarget === identity.deploymentTarget);
 }
 function resolveEvidenceVerificationTimeout(timeoutMs) {
     const resolved = timeoutMs ?? 10_000;
@@ -1166,6 +1444,16 @@ async function routeGameServicesRequest(endpoint, body, backend) {
     switch (endpoint) {
         case gameServicesBackendEndpoints.verifyPurchase:
             return okResponse(await backend.purchases.verifyPurchase(body));
+        case gameServicesBackendEndpoints.getPurchaseLedgerStatus:
+            if (backend.purchases.getPurchaseLedgerStatus === undefined) {
+                return errorResponse(404, 'UNKNOWN_ENDPOINT');
+            }
+            return okResponse(await backend.purchases.getPurchaseLedgerStatus(body));
+        case gameServicesBackendEndpoints.getCommerceCapabilities:
+            if (backend.purchases.getCommerceCapabilities === undefined) {
+                return errorResponse(404, 'UNKNOWN_ENDPOINT');
+            }
+            return okResponse(await backend.purchases.getCommerceCapabilities());
         case gameServicesBackendEndpoints.claimAdReward:
             return okResponse(await backend.adRewards.claimAdReward(body));
         case gameServicesBackendEndpoints.recordLeaderboardScore:
@@ -1219,6 +1507,16 @@ function createEntitlementEvidenceKey(grant) {
 function createEntitlementPlatformEvidenceKey(identity) {
     return createCompositeKey([identity.source, identity.target, identity.platformEvidenceId]);
 }
+function createRevocationIdempotencyKey(revocation) {
+    return createCompositeKey(['revoke', revocation.playerId, revocation.idempotencyKey]);
+}
+function createRevocationLedgerEntryId(revocation) {
+    return [
+        'revoke',
+        encodeIdSegment(revocation.playerId),
+        encodeIdSegment(revocation.idempotencyKey),
+    ].join('_');
+}
 function createEntitlementLedgerEntryId(grant) {
     return [
         'ledger',

package/dist/types.d.ts

@@ -1,9 +1,24 @@
 import type { ProductGrant } from '@mpgd/catalog';
 import type { LeaderboardScoreInput, LogicalAdPlacementId, LogicalProductId, PlatformEvidenceEnvelope, PlatformTarget } from '@mpgd/platform';
-import type { ClaimAdRewardResponse, PurchaseGrantFinalization, VerifyPurchaseResponse } from './operation-results.js';
-export type { ClaimAdRewardResponse, PurchaseGrantFinalization, PurchaseGrantFinalizationAction, VerifyPurchaseResponse, } from './operation-results.js';
+import type { StoreId } from '@mpgd/platform/commerce';
+import type { ClaimAdRewardResponse, PurchaseGrantFinalization, PurchaseLedgerStatusRequest, PurchaseLedgerStatusResponse, VerifyPurchaseResponse } from './operation-results.js';
+export type { ClaimAdRewardResponse, PurchaseGrantFinalization, PurchaseGrantFinalizationAction, PurchaseLedgerStatus, PurchaseLedgerStatusRequest, PurchaseLedgerStatusResponse, VerifyPurchaseResponse, } from './operation-results.js';
 export type { PlatformEvidenceEnvelope } from '@mpgd/platform';
-export type GameServicesStoreTarget = Extract<PlatformTarget, 'microsoft-store' | 'android' | 'ios' | 'ait' | 'oneplay'>;
+/**
+* The closed v1 purchase target list. The deployment target of a v1 verify
+* request names its store implicitly (`android` is Google Play, `ios` the App
+* Store, `ait` Apps in Toss); `resolveLegacyCommerceStoreId` is that mapping.
+*
+* @deprecated `VerifyPurchaseRequest.target` is open since commerce v2 C2
+* (`GameServicesStoreTarget` is `StoreId`); C4 removes this alias.
+*/
+export type GameServicesLegacyStoreTarget = Extract<PlatformTarget, 'microsoft-store' | 'android' | 'ios' | 'ait' | 'oneplay'>;
+/**
+* An open store or deployment target identifier (RFC "Open store ids"). The
+* request validator bounds its shape; the backend's commerce evidence
+* registry decides which stores it serves.
+*/
+export type GameServicesStoreTarget = StoreId;
 export type GameServicesAdRewardTarget = GameServicesLedgerTarget;
 export type GameServicesLeaderboardTarget = Extract<PlatformTarget, 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit'>;
 export type GameServicesLedgerTarget = Extract<PlatformTarget, 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8' | 'oneplay'>;
@@ -13,7 +28,17 @@ export type EntitlementIdempotencyKey = PurchaseIdempotencyKey | AdRewardIdempot
 export type EntitlementLedgerSource = 'purchase' | 'ad_reward' | 'admin';
 export type EntitlementLedgerPayload = Record<string, string | number | boolean>;
 export interface VerifyPurchaseRequest {
+  /** The ledger (deployment platform) target; see `store` for the store the purchase was made in. */
   readonly target: GameServicesStoreTarget;
+  /**
+  * The open store id the purchase was made in (RFC "Open store ids"), for
+  * example `google-play` or `credit-wallet`. A v1 request without it names
+  * its store through `target`: `android` is `google-play`, `ios` is
+  * `app-store`, `ait` is `apps-in-toss`, `reddit` is `devvit`, and every
+  * other target (`microsoft-store`, `verse8`, `oneplay`) is its own store id
+  * (`resolveLegacyCommerceStoreId`).
+  */
+  readonly store?: StoreId;
   /** Deployment config key used to resolve game-owned platform product identifiers. */
   readonly deploymentTarget?: string;
   readonly playerId: string;
@@ -62,6 +87,44 @@ export interface EntitlementLedgerResult {
   readonly ledgerEntryId: string;
   readonly alreadyProcessed: boolean;
 }
+/** Why a grant was reversed (RFC "Revocation and expiry entries"). */
+export type EntitlementRevocationReason = 'refund' | 'chargeback' | 'voided' | 'admin';
+/**
+* A `revoke` ledger entry: it references the grant it reverses and never
+* removes it, so the ledger stays append-only. Store notification handlers
+* (a Play voided purchase, an App Store refund, an Apps in Toss or Devvit
+* refunded order) write one through `revokeEntitlementGrant`; the entry's
+* `idempotencyKey` makes the notification replay-safe.
+*/
+export interface EntitlementLedgerRevocation {
+  readonly playerId: string;
+  /** The `ledgerEntryId` of the grant this entry reverses. */
+  readonly revokesLedgerEntryId: string;
+  readonly idempotencyKey: string;
+  readonly reason: EntitlementRevocationReason;
+  readonly revokedAt: string;
+  readonly payload: EntitlementLedgerPayload;
+  /** The notification's own authority identity, when the handler has one. */
+  readonly evidenceVerificationId?: string;
+}
+export interface EntitlementRevocationTransaction extends EntitlementLedgerRevocation {
+  readonly ledgerEntryId: string;
+}
+/**
+* A subscription `period` ledger entry: it extends an earlier grant with a
+* renewal period and its expiry. This is the shape only; no reference store
+* verifier writes one until a subscription verifier exists.
+*/
+export interface EntitlementLedgerPeriod {
+  readonly playerId: string;
+  /** The `ledgerEntryId` of the subscription grant this period extends. */
+  readonly extendsLedgerEntryId: string;
+  readonly idempotencyKey: string;
+  readonly periodIndex: number;
+  readonly startedAt: string;
+  readonly expiresAt: string;
+  readonly payload: EntitlementLedgerPayload;
+}
 export interface ProductGrantTransaction {
   readonly ledgerEntryId: string;
   readonly playerId: string;
@@ -83,6 +146,14 @@ export interface LeaderboardScoreTransaction extends RecordLeaderboardScoreReque
 */
 export declare function assertVerifyPurchaseRequest(input: VerifyPurchaseRequest): VerifyPurchaseRequest;
 export declare function assertVerifyPurchaseResponse(input: VerifyPurchaseResponse): VerifyPurchaseResponse;
+/** Bounds one ledger status read; a client asks for the grants of one journal window. */
+export declare const maxPurchaseLedgerStatusEntries = 256;
+/**
+* Validates an untrusted ledger status read. Failures throw
+* `GameServicesRequestValidationError` so transports can answer with a stable 400.
+*/
+export declare function assertPurchaseLedgerStatusRequest(input: PurchaseLedgerStatusRequest): PurchaseLedgerStatusRequest;
+export declare function assertPurchaseLedgerStatusResponse(input: PurchaseLedgerStatusResponse): PurchaseLedgerStatusResponse;
 export declare function assertPurchaseGrantFinalization(input: PurchaseGrantFinalization): PurchaseGrantFinalization;
 /**
 * Validates an untrusted ad reward claim. Failures throw
@@ -98,6 +169,11 @@ export declare function assertRecordLeaderboardScoreRequest(input: RecordLeaderb
 export declare function assertRecordLeaderboardScoreResponse(input: RecordLeaderboardScoreResponse): RecordLeaderboardScoreResponse;
 export declare function assertEntitlementLedgerGrant(input: EntitlementLedgerGrant): EntitlementLedgerGrant;
 export declare function assertEntitlementLedgerResult(input: EntitlementLedgerResult): EntitlementLedgerResult;
+export declare function assertEntitlementLedgerRevocation(input: EntitlementLedgerRevocation): EntitlementLedgerRevocation;
+export declare function assertEntitlementRevocationTransaction(input: EntitlementRevocationTransaction): EntitlementRevocationTransaction;
+export declare function assertEntitlementLedgerPeriod(input: EntitlementLedgerPeriod): EntitlementLedgerPeriod;
 export declare function assertProductGrantTransaction(input: ProductGrantTransaction): ProductGrantTransaction;
 export declare function assertLeaderboardScoreTransaction(input: LeaderboardScoreTransaction): LeaderboardScoreTransaction;
+/** A store id is a bounded kebab-case identifier such as `google-play` or `credit-wallet`. */
+export declare function assertCommerceStoreId(input: unknown, label?: string): asserts input is StoreId;
 export declare function assertGameServicesDeploymentTarget(input: unknown): asserts input is string;