@mpgd/game-services 0.21.1 → 0.22.0

package/dist/contract.d.ts

@@ -1,5 +1,6 @@
 import { type RouterContractClient } from '@orpc/contract';
-import type { ClaimAdRewardRequest, ClaimAdRewardResponse, RecordLeaderboardScoreRequest, RecordLeaderboardScoreResponse, VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.js';
+import type { CommerceServiceCapabilities } from '@mpgd/platform/commerce';
+import type { ClaimAdRewardRequest, ClaimAdRewardResponse, PurchaseLedgerStatusRequest, PurchaseLedgerStatusResponse, RecordLeaderboardScoreRequest, RecordLeaderboardScoreResponse, VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.js';
 export interface GameServicesHealthResponse {
   readonly ok: true;
   readonly service: 'game-services';
@@ -9,6 +10,8 @@ export declare const gameServicesContract: {
   health: import("@orpc/contract").ProcedureContract<import("@orpc/contract").Schema<void, void>, import("@orpc/contract").Schema<GameServicesHealthResponse, GameServicesHealthResponse>, object>;
   commerce: {
     verifyPurchase: import("@orpc/contract").ProcedureContract<import("@orpc/contract").Schema<VerifyPurchaseRequest, VerifyPurchaseRequest>, import("@orpc/contract").Schema<VerifyPurchaseResponse, VerifyPurchaseResponse>, object>;
+    getPurchaseLedgerStatus: import("@orpc/contract").ProcedureContract<import("@orpc/contract").Schema<PurchaseLedgerStatusRequest, PurchaseLedgerStatusRequest>, import("@orpc/contract").Schema<PurchaseLedgerStatusResponse, PurchaseLedgerStatusResponse>, object>;
+    getCapabilities: import("@orpc/contract").ProcedureContract<import("@orpc/contract").Schema<void, void>, import("@orpc/contract").Schema<CommerceServiceCapabilities, CommerceServiceCapabilities>, object>;
   };
   ads: {
     claimReward: import("@orpc/contract").ProcedureContract<import("@orpc/contract").Schema<ClaimAdRewardRequest, ClaimAdRewardRequest>, import("@orpc/contract").Schema<ClaimAdRewardResponse, ClaimAdRewardResponse>, object>;

package/dist/contract.js

@@ -7,6 +7,14 @@ export const gameServicesContract = oc.router({
         verifyPurchase: oc
             .input(orpcType())
             .output(orpcType()),
+        /** RFC "Revocation and expiry entries"; NOT_FOUND on a backend without the read. */
+        getPurchaseLedgerStatus: oc
+            .input(orpcType())
+            .output(orpcType()),
+        /** RFC "Provider capabilities endpoint"; NOT_FOUND on a backend without a registry. */
+        getCapabilities: oc
+            .input(orpcType())
+            .output(orpcType()),
     }),
     ads: oc.router({
         claimReward: oc

package/dist/evidence-verification.d.ts

@@ -10,6 +10,20 @@ export type EvidenceVerificationDecision = {
   * `null` explicitly suppresses the client-reported platform identity.
   */
   readonly platformEvidenceId?: string | null;
+} | {
+  /**
+  * An earlier ledger entry already grants this purchase: a server-push
+  * store's lookup verifier (RFC "Evidence registry") found the grant the
+  * host's fulfillment path wrote. The backend answers `verified` with
+  * that entry (`alreadyProcessed: true`) after checking it belongs to the
+  * requesting player, product, and target, and writes nothing new. Only
+  * purchase verification understands it; a rewarded-ad verifier that
+  * answers it is treated as a verifier error.
+  */
+  readonly status: 'settled';
+  readonly ledgerEntryId: string;
+  /** The ledger target the entry was written under when it is not the request's target. */
+  readonly ledgerTarget?: string;
 } | {
   readonly status: 'pending';
   readonly reason?: string;

package/dist/index.d.ts

@@ -6,6 +6,9 @@ export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
 export * from './client-reward-evidence.js';
+export * from './commerce-evidence-registry.js';
+export * from './commerce-ledger.js';
+export * from './commerce-reconciler.js';
 export * from './default-client-reward-evidence.js';
 export * from './admob-client-reward.js';
 export * from './contract.js';
@@ -15,6 +18,7 @@ export * from './google-play-purchase.js';
 export * from './google-play-publisher-client.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';
+export * from './monetization-operation-store.js';
 export * from './monetization-recovery.js';
 export * from './notification-delivery.js';
 export * from './platform-order.js';

package/dist/index.js

@@ -6,6 +6,9 @@ export * from './apps-in-toss-evidence-verification.js';
 export * from './apps-in-toss-partner-api.js';
 export * from './client.js';
 export * from './client-reward-evidence.js';
+export * from './commerce-evidence-registry.js';
+export * from './commerce-ledger.js';
+export * from './commerce-reconciler.js';
 export * from './default-client-reward-evidence.js';
 export * from './admob-client-reward.js';
 export * from './contract.js';
@@ -15,6 +18,7 @@ export * from './google-play-purchase.js';
 export * from './google-play-publisher-client.js';
 export * from './microsoft-store-identity.js';
 export * from './microsoft-store-purchase.js';
+export * from './monetization-operation-store.js';
 export * from './monetization-recovery.js';
 export * from './notification-delivery.js';
 export * from './platform-order.js';

package/dist/monetization-operation-store.d.ts

@@ -0,0 +1,20 @@
+import type { MonetizationOperationRecord, MonetizationOperationStore } from './monetization-recovery.js';
+/**
+* Whether a journal record still needs a reconcile pass. A game's durable
+* `MonetizationOperationStore.listRecoverable` applies this rule (or an
+* equivalent index): a v1 purchase or rewarded-ad record is open until it
+* holds a non-pending result with no pending finalization; a commerce v2
+* purchase record is open until its state is terminal (`finished`,
+* `cancelled`, `failed`, `rejected`, `revoked`). Terminal records stay
+* addressable by `read` for duplicate protection.
+*/
+export declare function isMonetizationOperationRecoverable(record: MonetizationOperationRecord): boolean;
+/** Whether a commerce v2 record holds a ledger grant the revocation pass should keep checking. */
+export declare function isMonetizationOperationGranted(record: MonetizationOperationRecord): boolean;
+/**
+* Session-only journal: the compare-and-swap semantics of a durable store
+* without the durability. It backs the commerce reconciler of a client that
+* was given no `operationStore`, and tests. It is not crash recovery: a game
+* supplies a durable, encrypted, access-controlled implementation.
+*/
+export declare function createInMemoryMonetizationOperationStore(): MonetizationOperationStore;

package/dist/monetization-operation-store.js

@@ -0,0 +1,80 @@
+import { isTerminalCommercePurchaseState } from '@mpgd/platform/commerce';
+/**
+ * Whether a journal record still needs a reconcile pass. A game's durable
+ * `MonetizationOperationStore.listRecoverable` applies this rule (or an
+ * equivalent index): a v1 purchase or rewarded-ad record is open until it
+ * holds a non-pending result with no pending finalization; a commerce v2
+ * purchase record is open until its state is terminal (`finished`,
+ * `cancelled`, `failed`, `rejected`, `revoked`). Terminal records stay
+ * addressable by `read` for duplicate protection.
+ */
+export function isMonetizationOperationRecoverable(record) {
+    if (record.kind === 'commerce-purchase') {
+        return !isTerminalCommercePurchaseState(record.state);
+    }
+    if (record.result === undefined || record.result.status === 'pending') {
+        return true;
+    }
+    return record.kind === 'purchase' && record.response?.finalization?.status === 'pending';
+}
+/** Whether a commerce v2 record holds a ledger grant the revocation pass should keep checking. */
+export function isMonetizationOperationGranted(record) {
+    return record.kind === 'commerce-purchase'
+        && record.ledgerEntryId !== undefined
+        && (record.state === 'granted' || record.state === 'finishing' || record.state === 'finished');
+}
+/**
+ * Session-only journal: the compare-and-swap semantics of a durable store
+ * without the durability. It backs the commerce reconciler of a client that
+ * was given no `operationStore`, and tests. It is not crash recovery: a game
+ * supplies a durable, encrypted, access-controlled implementation.
+ */
+export function createInMemoryMonetizationOperationStore() {
+    const records = new Map();
+    const clone = (record) => structuredClone(record);
+    return {
+        async reserve(record) {
+            const existing = records.get(record.key);
+            if (existing !== undefined) {
+                return { created: false, record: clone(existing) };
+            }
+            records.set(record.key, clone(record));
+            return { created: true, record: clone(record) };
+        },
+        async read(key) {
+            const record = records.get(key);
+            return record === undefined ? undefined : clone(record);
+        },
+        async replace(expectedRevision, record) {
+            const existing = records.get(record.key);
+            if (existing === undefined
+                || existing.revision !== expectedRevision
+                || record.revision !== expectedRevision + 1
+                || existing.playerId !== record.playerId
+                || existing.target !== record.target
+                || existing.kind !== record.kind) {
+                throw new Error('Stale or conflicting monetization journal write.');
+            }
+            records.set(record.key, clone(record));
+        },
+        async listRecoverable(playerId) {
+            return [...records.values()]
+                .filter((record) => record.playerId === playerId && isMonetizationOperationRecoverable(record))
+                .map(clone);
+        },
+        async listGranted(playerId) {
+            return [...records.values()]
+                .filter((record) => record.playerId === playerId && isMonetizationOperationGranted(record))
+                .map(clone);
+        },
+        async findByTransaction(input) {
+            const found = [...records.values()].find((record) => record.kind === 'commerce-purchase'
+                && record.playerId === input.playerId
+                && record.target === input.target
+                && record.deploymentTarget === input.deploymentTarget
+                && record.store === input.store
+                && record.purchase?.transactionId === input.transactionId);
+            return found === undefined ? undefined : clone(found);
+        },
+    };
+}

package/dist/monetization-recovery.d.ts

@@ -1,5 +1,6 @@
 import type { PurchaseResult, RewardedAdResult } from '@mpgd/platform';
 import { type CreateGameServicesClientInput } from './client.js';
+import { type CommercePurchaseOperationRecord, type CommerceReconciler } from './commerce-reconciler.js';
 import type { GameServicesOperationClient, GameServicesPurchaseInput, GameServicesPurchaseResult, GameServicesRewardedAdInput, GameServicesRewardedAdResult } from './operations.js';
 import type { ClaimAdRewardRequest, ClaimAdRewardResponse, VerifyPurchaseRequest, VerifyPurchaseResponse } from './types.js';
 interface OperationIdentity {
@@ -12,7 +13,8 @@ interface OperationIdentity {
   /** Fixed when a platform result is first journaled, before backend dispatch. */
   readonly platformCompletedAt?: string;
 }
-export type MonetizationOperationRecord = (OperationIdentity & {
+/** The v1 purchase and rewarded-ad journal records. */
+export type LegacyMonetizationOperationRecord = (OperationIdentity & {
   readonly kind: 'purchase';
   readonly input: GameServicesPurchaseInput;
   readonly platform?: PurchaseResult;
@@ -27,6 +29,13 @@ export type MonetizationOperationRecord = (OperationIdentity & {
   readonly response?: ClaimAdRewardResponse;
   readonly result?: GameServicesRewardedAdResult;
 });
+/**
+* Every record kind the journal holds. `commerce-purchase` records are the
+* commerce v2 reconciler's (`./commerce-reconciler`); their open state is
+* `state`, not `result`, and `isMonetizationOperationRecoverable` applies the
+* rule for every kind.
+*/
+export type MonetizationOperationRecord = LegacyMonetizationOperationRecord | CommercePurchaseOperationRecord;
 /** Games must supply a durable, atomic implementation; an in-memory map is not recovery. */
 export interface MonetizationOperationStore {
   /** Atomically insert or return the existing operation for this global key. */
@@ -39,6 +48,25 @@ export interface MonetizationOperationStore {
   replace(expectedRevision: number, record: MonetizationOperationRecord): Promise<void>;
   /** Return only unresolved operations; keep terminal records addressable by read for deduplication. */
   listRecoverable(playerId: string): Promise<readonly MonetizationOperationRecord[]>;
+  /**
+  * Commerce v2 records in `granted`, `finishing`, or `finished` kept within
+  * the journal retention window, for the reconciler's revocation pass. A
+  * store without it only reports reversals of grants seen in this session.
+  */
+  listGranted?(playerId: string): Promise<readonly MonetizationOperationRecord[]>;
+  /**
+  * The commerce v2 record, terminal or not, whose `purchase.transactionId`
+  * is this store transaction. With it a transaction the store lists again
+  * after a restart (an owned durable, a rejected or finished purchase) meets
+  * its own record instead of being verified again under a derived key.
+  */
+  findByTransaction?(input: {
+    readonly playerId: string;
+    readonly target: string;
+    readonly deploymentTarget: string;
+    readonly store: string;
+    readonly transactionId: string;
+  }): Promise<MonetizationOperationRecord | undefined>;
 }
 export interface CreateRecoverableMonetizationClientInput extends CreateGameServicesClientInput {
   readonly operationStore: MonetizationOperationStore;
@@ -46,13 +74,40 @@ export interface CreateRecoverableMonetizationClientInput extends CreateGameServ
 export interface MonetizationOperationSummary {
   readonly kind: MonetizationOperationRecord['kind'];
   readonly idempotencyKey: string;
-  readonly status: 'pending' | 'granted' | 'rejected' | 'cancelled' | 'failed' | 'skipped' | 'unavailable' | 'action-required';
+  /**
+  * RFC "Purchase lifecycle" mapping for a commerce v2 record: `granted`
+  * covers `granted`, `finishing`, and `finished`; `pending` covers
+  * `launched`, `pending`, `purchased`, and `verifying`; `revoked` is a
+  * reversed grant.
+  */
+  readonly status: 'pending' | 'granted' | 'rejected' | 'cancelled' | 'failed' | 'skipped' | 'unavailable' | 'action-required' | 'revoked';
   readonly finalizationPending: boolean;
 }
 export interface RecoverableMonetizationClient extends GameServicesOperationClient {
+  /**
+  * Replays a platform purchase callback into a v1 journal record.
+  *
+  * @deprecated For a gateway with a commerce v2 provider the reconciler
+  * learns the result from the provider itself: this call then runs one
+  * reconcile pass and returns the journaled result for the key, ignoring
+  * `platform`. Removed with the v1 adapter in C4.
+  */
   recoverPurchaseResult(idempotencyKey: string, platform: PurchaseResult): Promise<GameServicesPurchaseResult>;
   recoverRewardResult(idempotencyKey: string, platform: RewardedAdResult): Promise<GameServicesRewardedAdResult>;
+  /**
+  * Startup and app-resume recovery: resumes v1 records and, with a commerce
+  * v2 provider, starts or runs the reconciler (subscribe, read available
+  * purchases, send saved verify requests, finish granted purchases).
+  */
   reconcile(): Promise<readonly MonetizationOperationSummary[]>;
+  /**
+  * The manual restore trigger of the commerce v2 reconciler
+  * (`provider.restorePurchases` when offered, then a pass). Without a v2
+  * provider it is `reconcile()`.
+  */
+  restorePurchases(): Promise<readonly MonetizationOperationSummary[]>;
+  /** Present when the gateway exposes `commerceV2`. */
+  readonly commerceReconciler?: CommerceReconciler;
 }
 /**
 * Client-side recovery coordinates UI callbacks and authoritative backend calls.

package/dist/monetization-recovery.js

@@ -1,6 +1,7 @@
 import { isAuthoritativeMicrosoftStoreCompletion } from './authoritative-purchase.js';
-import { createGameServicesClient } from './client.js';
+import { createGameServicesClient, } from './client.js';
 import { resolveClientRewardClaim } from './client-reward-evidence.js';
+import { summarizeCommercePurchaseOperation, toGameServicesPurchaseResult, } from './commerce-reconciler.js';
 import { createDefaultClientRewardEvidenceRegistry } from './default-client-reward-evidence.js';
 import { forwardGameServicesProgress, observeGameServicesOperation, } from './operation-progress.js';
 /**
@@ -20,6 +21,18 @@ export function createRecoverableMonetizationClient(input) {
     const unjournaledRewardResponses = new Map();
     const unjournaledPurchaseResults = new Map();
     const unjournaledRewardResults = new Map();
+    // One commerce v2 client over the durable journal: its reconciler is the
+    // purchase path for a gateway with a v2 provider, and v1 records keep the
+    // per-operation client below.
+    const commerceClient = input.gateway.commerceV2 === undefined
+        ? undefined
+        : createGameServicesClient({ ...input, operationStore: store });
+    const commerceReconciler = commerceClient?.commerceReconciler;
+    // The per-operation clients below resume v1 records only: they see a gateway
+    // without the v2 provider, so they never build a second reconciler over the
+    // journal or reopen the store UI for a platform result already recorded.
+    const { commerceReconciler: _sharedReconciler, operationStore: _journal, onCommerceEvent: _onCommerceEvent, commerceProducts: _commerceProducts, ...legacyClientInput } = input;
+    const { commerceV2: _commerceV2, ...legacyGateway } = input.gateway;
     async function serializeOperation(key, task) {
         const previous = inFlight.get(key) ?? Promise.resolve();
         const running = previous.catch(() => undefined).then(task);
@@ -50,6 +63,9 @@ export function createRecoverableMonetizationClient(input) {
         }
     }
     async function purchase(operation, options) {
+        if (commerceClient !== undefined) {
+            return commerceClient.purchase(operation, options);
+        }
         const key = operationKey(input.target, 'purchase', operation.idempotencyKey);
         return serializeOperation(key, async () => {
             const reserved = await store.reserve({
@@ -160,10 +176,10 @@ export function createRecoverableMonetizationClient(input) {
             return pendingPurchase();
         }
         const client = createGameServicesClient({
-            ...input,
+            ...legacyClientInput,
             requestNow: () => record.platformCompletedAt ?? observedAt(),
             gateway: {
-                ...input.gateway,
+                ...legacyGateway,
                 commerce: {
                     ...input.gateway.commerce,
                     async purchase(request) {
@@ -315,10 +331,10 @@ export function createRecoverableMonetizationClient(input) {
             return pendingReward();
         }
         const client = createGameServicesClient({
-            ...input,
+            ...legacyClientInput,
             requestNow: () => record.platformCompletedAt ?? observedAt(),
             gateway: {
-                ...input.gateway,
+                ...legacyGateway,
                 ads: {
                     ...input.gateway.ads,
                     async showRewarded(request) {
@@ -406,6 +422,16 @@ export function createRecoverableMonetizationClient(input) {
         return serializeOperation(key, async () => {
             const found = await store.read(key);
             if (found?.kind !== 'purchase') {
+                if (commerceReconciler !== undefined) {
+                    // Deprecated thin wrapper: the v2 reconciler learns the result from
+                    // the provider, so the platform callback is not replayed.
+                    await commerceReconciler.reconcile();
+                    const journaled = await commerceReconciler.read(idempotencyKey);
+                    if (journaled === undefined) {
+                        throw new Error('No reserved purchase operation matches this platform callback.');
+                    }
+                    return toGameServicesPurchaseResult(journaled);
+                }
                 throw new Error('No reserved purchase operation matches this platform callback.');
             }
             assertOwner(found, 'purchase', idempotencyKey, found.input.productId);
@@ -501,12 +527,69 @@ export function createRecoverableMonetizationClient(input) {
         }
         return !hasRequest || prior !== undefined;
     }
+    function ownsRecord(record) {
+        return record?.playerId === input.playerId && record.target === input.target
+            && record.deploymentTarget === (input.deploymentTarget ?? input.target);
+    }
+    function summarizeCommerceRecord(record) {
+        return {
+            kind: record.kind,
+            idempotencyKey: record.idempotencyKey,
+            status: summarizeCommercePurchaseOperation(record),
+            finalizationPending: record.state === 'finishing',
+        };
+    }
+    /** Runs the v2 trigger and reports every record it found open before the pass, at its state after it. */
+    async function reconcileCommerce(run) {
+        if (commerceReconciler === undefined) {
+            return [];
+        }
+        const openBefore = (await commerceReconciler.listRecoverable()).map((record) => record.idempotencyKey);
+        await run(commerceReconciler);
+        const seen = new Set();
+        const summaries = [];
+        for (const key of [
+            ...openBefore,
+            ...(await commerceReconciler.listRecoverable()).map((record) => record.idempotencyKey),
+        ]) {
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            const latest = await commerceReconciler.read(key);
+            if (latest !== undefined) {
+                summaries.push(summarizeCommerceRecord(latest));
+            }
+        }
+        return summaries;
+    }
+    async function restorePurchases() {
+        if (commerceReconciler === undefined) {
+            return reconcile();
+        }
+        return [
+            ...(await reconcileLegacy()),
+            ...(await reconcileCommerce((reconciler) => reconciler.restorePurchases())),
+        ];
+    }
     async function reconcile() {
+        return [
+            ...(await reconcileLegacy()),
+            ...(await reconcileCommerce(async (reconciler) => {
+                if (reconciler.started) {
+                    await reconciler.reconcile();
+                }
+                else {
+                    await reconciler.start();
+                }
+            })),
+        ];
+    }
+    async function reconcileLegacy() {
         const pending = await store.listRecoverable(input.playerId);
         const summaries = [];
         for (const record of pending) {
-            if (record?.playerId !== input.playerId || record.target !== input.target
-                || record.deploymentTarget !== (input.deploymentTarget ?? input.target)) {
+            if (!ownsRecord(record)) {
                 continue;
             }
             if (record.kind !== 'purchase' && record.kind !== 'rewarded-ad') {
@@ -527,6 +610,9 @@ export function createRecoverableMonetizationClient(input) {
                     catch {
                         throw new OperationReadError();
                     }
+                    if (latest.kind === 'commerce-purchase') {
+                        throw new Error('Monetization operation kind conflicts with its journal key.');
+                    }
                     assertOwner(latest, latest.kind, latest.input.idempotencyKey, latest.kind === 'purchase' ? latest.input.productId : latest.input.placementId);
                     if (latest.kind === 'purchase') {
                         const result = await resumePurchase(latest);
@@ -558,7 +644,15 @@ export function createRecoverableMonetizationClient(input) {
         }
         return summaries;
     }
-    return { purchase, claimRewardedAd, recoverPurchaseResult, recoverRewardResult, reconcile };
+    return {
+        purchase,
+        claimRewardedAd,
+        recoverPurchaseResult,
+        recoverRewardResult,
+        reconcile,
+        restorePurchases,
+        ...(commerceReconciler === undefined ? {} : { commerceReconciler }),
+    };
 }
 class OperationReadError extends Error {
 }

package/dist/operation-results.d.ts

@@ -15,6 +15,20 @@ export interface PurchaseGrantFinalization {
   readonly alreadyCompleted: boolean;
   readonly reason?: string;
 }
+/** Whether a ledger grant is still active, or which entry reversed it (RFC "Revocation and expiry entries"). */
+export interface PurchaseLedgerStatus {
+  readonly ledgerEntryId: string;
+  readonly status: 'active' | 'reversed' | 'unknown';
+  readonly reversedBy?: string;
+}
+export interface PurchaseLedgerStatusRequest {
+  readonly ledgerEntryIds: readonly string[];
+  /** The player whose grants are read; another player's entry answers `unknown`. */
+  readonly playerId: string;
+}
+export interface PurchaseLedgerStatusResponse {
+  readonly statuses: readonly PurchaseLedgerStatus[];
+}
 export interface ClaimAdRewardResponse {
   readonly granted: boolean;
   /** Explicit non-grant decision; older servers may omit this field. */

package/dist/operations.d.ts

@@ -13,7 +13,8 @@ export interface GameServicesPurchaseInput {
   readonly idempotencyKey: string;
 }
 export interface GameServicesPurchaseResult {
-  readonly status: 'granted' | 'cancelled' | 'pending' | 'failed' | 'rejected';
+  /** `revoked` is reported only for a journaled commerce v2 purchase whose ledger grant was reversed. */
+  readonly status: 'granted' | 'cancelled' | 'pending' | 'failed' | 'rejected' | 'revoked';
   readonly purchase: PurchaseResult;
   readonly verification?: VerifyPurchaseResponse;
   readonly ledgerEntryId?: string;

package/dist/platform-order.d.ts

@@ -1,4 +1,8 @@
+import type { ProductCatalog } from '@mpgd/catalog';
 import type { PlatformEvidenceEnvelope } from '@mpgd/platform';
+import { type RevokeEntitlementGrantResult } from './commerce-ledger.js';
+import type { GameServicesStore } from './server.js';
+import type { EntitlementLedgerGrant, VerifyPurchaseRequest } from './types.js';
 export type PlatformOrderTarget = 'reddit';
 export interface FulfillPlatformOrderInput {
   readonly target: PlatformOrderTarget;
@@ -20,3 +24,46 @@ 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;
+export interface CreatePlatformOrderLedgerGrantInput {
+  readonly order: FulfillPlatformOrderInput;
+  /** The catalog product the order's `platformSku` resolves to for the order target. */
+  readonly product: ProductCatalog['products'][number];
+  readonly grantedAt: string;
+  readonly deploymentTarget?: string;
+}
+/**
+* The ledger grant a Devvit fulfillment handler writes for a paid order
+* (`normalizeDevvitFulfillmentOrder`), under the platform order key
+* `reddit:<orderId>` and in the shape the `devvit.order.v1` lookup verifier
+* reads (target `reddit`, store `devvit`, the order id as the platform
+* transaction id). Its evidence identity equals the one
+* `createDevvitPaymentOrderEvidenceVerifier` issues, so a fulfillment that
+* went through `verifyPurchase` and one that wrote the ledger directly
+* dedupe on the same order.
+*/
+export declare function createPlatformOrderLedgerGrant(input: CreatePlatformOrderLedgerGrantInput): EntitlementLedgerGrant;
+/**
+* The verify request a fulfillment handler sends when the backend verifies
+* the order through the `devvit.payment-order.v1` registry entry instead of
+* writing the ledger directly: the platform order key, the order id as the
+* platform transaction id, and the handler's own envelope as evidence.
+*/
+export declare function createPlatformOrderVerifyRequest(input: {
+  readonly order: FulfillPlatformOrderInput;
+  readonly productId: VerifyPurchaseRequest['productId'];
+  readonly deploymentTarget?: string;
+}): VerifyPurchaseRequest;
+export type RevokePlatformOrderResult = RevokeEntitlementGrantResult;
+/**
+* Writes the `revoke` entry for a refunded order (`normalizeDevvitRefundOrder`):
+* the grant written for the same order id under the order target is
+* reversed once, under the key `reddit:<orderId>:refund`. Answers
+* `grant_not_found` when no grant for that order exists (the refund arrived
+* before, or without, a fulfillment) and `grant_mismatch` when the grant
+* belongs to another player.
+*/
+export declare function revokePlatformOrder(input: {
+  readonly store: GameServicesStore;
+  readonly order: RefundPlatformOrderInput;
+  readonly revokedAt?: string;
+}): Promise<RevokePlatformOrderResult>;

package/dist/platform-order.js

@@ -1,3 +1,5 @@
+import { createServerPushLedgerGrant, devvitCommerceStoreId, findPurchaseGrantByPlatformEvidence, } from './commerce-evidence-registry.js';
+import { revokeEntitlementGrant } from './commerce-ledger.js';
 export function createPlatformOrderIdempotencyKey(input) {
     assertPlatformOrderTarget(input.target);
     assertIdentifier(input.orderId, 'orderId');
@@ -67,3 +69,87 @@ function assertRecord(input, label) {
         throw new TypeError(`${label} must be an object.`);
     }
 }
+/**
+ * The ledger grant a Devvit fulfillment handler writes for a paid order
+ * (`normalizeDevvitFulfillmentOrder`), under the platform order key
+ * `reddit:<orderId>` and in the shape the `devvit.order.v1` lookup verifier
+ * reads (target `reddit`, store `devvit`, the order id as the platform
+ * transaction id). Its evidence identity equals the one
+ * `createDevvitPaymentOrderEvidenceVerifier` issues, so a fulfillment that
+ * went through `verifyPurchase` and one that wrote the ledger directly
+ * dedupe on the same order.
+ */
+export function createPlatformOrderLedgerGrant(input) {
+    const order = assertFulfillPlatformOrderInput(input.order);
+    return createServerPushLedgerGrant({
+        store: devvitCommerceStoreId,
+        target: order.target,
+        ...(input.deploymentTarget === undefined ? {} : { deploymentTarget: input.deploymentTarget }),
+        playerId: order.playerId,
+        product: input.product,
+        platformProductId: order.platformSku,
+        transactionId: order.orderId,
+        purchasedAt: order.paidAt,
+        grantedAt: input.grantedAt,
+        evidence: order.evidence,
+        idempotencyKey: createPlatformOrderIdempotencyKey(order),
+        evidenceVerificationId: createPlatformOrderEvidenceVerificationId(order),
+    });
+}
+/**
+ * The verify request a fulfillment handler sends when the backend verifies
+ * the order through the `devvit.payment-order.v1` registry entry instead of
+ * writing the ledger directly: the platform order key, the order id as the
+ * platform transaction id, and the handler's own envelope as evidence.
+ */
+export function createPlatformOrderVerifyRequest(input) {
+    const order = assertFulfillPlatformOrderInput(input.order);
+    return {
+        target: order.target,
+        store: devvitCommerceStoreId,
+        ...(input.deploymentTarget === undefined ? {} : { deploymentTarget: input.deploymentTarget }),
+        playerId: order.playerId,
+        productId: input.productId,
+        platformTransactionId: order.orderId,
+        idempotencyKey: createPlatformOrderIdempotencyKey(order),
+        purchasedAt: order.paidAt,
+        evidence: order.evidence,
+    };
+}
+/**
+ * Writes the `revoke` entry for a refunded order (`normalizeDevvitRefundOrder`):
+ * the grant written for the same order id under the order target is
+ * reversed once, under the key `reddit:<orderId>:refund`. Answers
+ * `grant_not_found` when no grant for that order exists (the refund arrived
+ * before, or without, a fulfillment) and `grant_mismatch` when the grant
+ * belongs to another player.
+ */
+export async function revokePlatformOrder(input) {
+    const order = assertRefundPlatformOrderInput(input.order);
+    const grant = await findPurchaseGrantByPlatformEvidence(input.store, {
+        target: order.target,
+        platformEvidenceId: order.orderId,
+    });
+    if (grant === undefined) {
+        return { status: 'grant_not_found' };
+    }
+    return revokeEntitlementGrant(input.store, {
+        playerId: order.playerId,
+        revokesLedgerEntryId: grant.ledgerEntryId,
+        idempotencyKey: `${createPlatformOrderIdempotencyKey(order)}:refund`,
+        reason: 'refund',
+        revokedAt: input.revokedAt ?? order.refundedAt,
+        evidenceVerificationId: `${createPlatformOrderEvidenceVerificationId(order)}:refund`,
+        payload: {
+            target: order.target,
+            store: devvitCommerceStoreId,
+            platformTransactionId: order.orderId,
+            platformProductId: order.platformSku,
+            refundedAt: order.refundedAt,
+            evidenceSchema: order.evidence.schema,
+        },
+    });
+}
+function createPlatformOrderEvidenceVerificationId(order) {
+    return `devvit:payment-order:${order.orderId}`;
+}