@mpgd/game-services 0.21.1 → 0.23.0

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

package/dist/runtime.d.ts

@@ -3,6 +3,7 @@ import type { PlatformGateway, PlatformTarget } from '@mpgd/platform';
 import { type GameServicesBackendApi, type GameServicesBackendTransport, type GameServicesClient, type GameServicesHeaderResolver } from './client.js';
 import type { GameServicesLedgerTarget } from './types.js';
 import type { ClientRewardEvidenceRegistry } from './client-reward-evidence.js';
+import type { CommerceReconcilerProduct } from './commerce-reconciler.js';
 import { type MonetizationOperationStore, type RecoverableMonetizationClient } from './monetization-recovery.js';
 export type GameServicesAuthorityMode = 'production' | 'non-production';
 export type GameServicesRuntimeMode = 'disabled' | 'local' | 'http' | 'orpc';
@@ -34,6 +35,12 @@ interface CreateGameServicesRuntimeCommonInput {
   /** Durable, compare-and-swap journal for purchase and rewarded-ad recovery. */
   readonly operationStore?: MonetizationOperationStore;
   readonly rewardEvidenceRegistry?: ClientRewardEvidenceRegistry;
+  /**
+  * Catalog kinds and store SKUs the commerce v2 reconciler resolves without a
+  * store read (`CommerceReconcilerProduct`), for example derived from the
+  * product catalog's `platformProductIds` for the gateway target.
+  */
+  readonly commerceProducts?: readonly CommerceReconcilerProduct[];
 }
 export type CreateGameServicesRuntimeInput = CreateGameServicesRuntimeCommonInput & ({
   readonly transport?: 'http';

package/dist/runtime.js

@@ -62,17 +62,29 @@ export function createGameServicesRuntime(input) {
             : { analyticsSessionId: input.analyticsSessionId }),
         ...(input.now === undefined ? {} : { now: input.now }),
         ...(input.rewardEvidenceRegistry === undefined ? {} : { rewardEvidenceRegistry: input.rewardEvidenceRegistry }),
+        ...(input.commerceProducts === undefined ? {} : { commerceProducts: input.commerceProducts }),
     };
-    const client = createGameServicesClient(clientInput);
     const monetizationRecovery = input.operationStore === undefined
         ? undefined
         : createRecoverableMonetizationClient({ ...clientInput, operationStore: input.operationStore });
+    // The recovery client owns the reconciler over the durable journal; the
+    // plain client shares it instead of journaling in memory.
+    const client = createGameServicesClient({
+        ...clientInput,
+        ...(monetizationRecovery?.commerceReconciler === undefined
+            ? {}
+            : { commerceReconciler: monetizationRecovery.commerceReconciler }),
+    });
     let routedClient = client;
     if (monetizationRecovery !== undefined) {
         routedClient = {
             ...client,
             purchase: monetizationRecovery.purchase,
             claimRewardedAd: monetizationRecovery.claimRewardedAd,
+            // The recovery client owns the reconciler over the durable journal.
+            ...(monetizationRecovery.commerceReconciler === undefined
+                ? {}
+                : { commerceReconciler: monetizationRecovery.commerceReconciler }),
         };
     }
     return {

package/dist/server.d.ts

@@ -1,10 +1,12 @@
 import { type AnalyticsSink } from '@mpgd/analytics';
 import { type AdPlacements, type ProductCatalog } from '@mpgd/catalog';
 import { type GameServicesBackendApi, type GameServicesBackendTransport, type GameServicesBackendTransportRequest, type GameServicesBackendTransportResponse } from './client.js';
+import { type CommerceEvidenceRegistry } from './commerce-evidence-registry.js';
 import { type GameServicesHealthResponse } from './contract.js';
 import { type GameServicesEvidenceVerifier, type GameServicesPurchaseGrantFinalizer } from './evidence-verification.js';
-import { type ClaimAdRewardRequest, type ClaimAdRewardResponse, type EntitlementLedgerGrant, type EntitlementLedgerResult, type GameServicesAdRewardTarget, type GameServicesStoreTarget, type LeaderboardScoreTransaction, type ProductGrantTransaction, type RecordLeaderboardScoreRequest, type RecordLeaderboardScoreResponse, type VerifyPurchaseRequest, type VerifyPurchaseResponse } from './types.js';
+import { type ClaimAdRewardRequest, type ClaimAdRewardResponse, type EntitlementLedgerGrant, type EntitlementLedgerResult, type EntitlementLedgerRevocation, type EntitlementRevocationTransaction, type GameServicesAdRewardTarget, type GameServicesStoreTarget, type LeaderboardScoreTransaction, type ProductGrantTransaction, type PurchaseLedgerStatusRequest, type RecordLeaderboardScoreRequest, type RecordLeaderboardScoreResponse, type VerifyPurchaseRequest, type VerifyPurchaseResponse } from './types.js';
 export { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
+export { listActiveEntitlementTransactions, readPurchaseLedgerStatuses, revokeEntitlementGrant, RevocationKeyConflictError, type RevokeEntitlementGrantResult, } from './commerce-ledger.js';
 type CorsHeaders = Record<string, string>;
 export interface CreateGameServicesBackendInput {
   readonly catalog: ProductCatalog;
@@ -21,6 +23,16 @@ export interface CreateGameServicesBackendInput {
   readonly purchaseGrantFinalizationTimeoutMs?: number;
   readonly purchaseGrantFinalizer?: GameServicesPurchaseGrantFinalizer;
   /**
+  * The commerce v2 evidence registry (RFC "Evidence registry"). With it,
+  * purchase evidence is routed by `evidence.schema` to the registered
+  * verifier and finalizer, `purchaseGrantFinalizer` is not consulted for
+  * purchases, `evidenceVerifier` serves rewarded ads only, and the backend
+  * publishes `getCommerceCapabilities`. Without it the backend keeps the v1
+  * behaviour: one `evidenceVerifier` and one `purchaseGrantFinalizer` for
+  * every purchase, and no capabilities endpoint.
+  */
+  readonly commerceEvidenceRegistry?: CommerceEvidenceRegistry;
+  /**
   * Receives unexpected (non-validation) failures such as store errors before the
   * transport answers with the generic `INTERNAL_ERROR` code. Defaults to `console.error`.
   * The hook is diagnostics only: if it throws or returns a rejecting promise, the failure
@@ -55,6 +67,26 @@ export interface GameServicesStore {
   findEntitlementTransactionByPlatformEvidence?(input: EntitlementPlatformEvidenceIdentity): Promise<ProductGrantTransaction | undefined>;
   getEntitlementTransaction(ledgerEntryId: string): Promise<ProductGrantTransaction | undefined>;
   listEntitlementTransactions(): Promise<readonly ProductGrantTransaction[]>;
+  /** The grants with the given ids (at most `ledgerReadChunkSize` per call), any order. */
+  getEntitlementTransactions?(ledgerEntryIds: readonly string[]): Promise<readonly ProductGrantTransaction[]>;
+  /**
+  * Appends a `revoke` entry (RFC "Revocation and expiry entries"). A grant is
+  * reversed once: a second revocation of the same grant, under any key,
+  * answers the first entry with `alreadyProcessed: true`, as does a replay of
+  * the same `(playerId, idempotencyKey)`; a key reused for another grant
+  * throws `RevocationKeyConflictError`, a reused `evidenceVerificationId`
+  * throws `EvidenceAlreadyProcessedError`, and an unknown grant throws.
+  * Optional: a store without it answers every ledger status read as
+  * `active` and refuses `revokeEntitlementGrant`.
+  */
+  recordEntitlementRevocation?(input: EntitlementLedgerRevocation): Promise<EntitlementLedgerResult>;
+  /**
+  * The revocations that reverse any of the given grant entries (at most
+  * `ledgerReadChunkSize` per call), oldest first.
+  */
+  findEntitlementRevocations?(input: {
+    readonly ledgerEntryIds: readonly string[];
+  }): Promise<readonly EntitlementRevocationTransaction[]>;
   recordLeaderboardScore(input: RecordLeaderboardScoreRequest, options?: {
     readonly recordedAt?: string;
   }): Promise<RecordLeaderboardScoreResponse>;
@@ -87,6 +119,9 @@ export declare class InMemoryGameServicesStore implements GameServicesStore {
   private readonly entitlementTransactionsByEvidence;
   private readonly entitlementTransactionsByPlatformEvidence;
   private readonly entitlementTransactionsById;
+  private readonly revocationsByKey;
+  private readonly revocationsByGrant;
+  private readonly revocationsByEvidence;
   private readonly leaderboardTransactionsByRun;
   private readonly leaderboardTransactionsById;
   recordEntitlementGrant(input: EntitlementLedgerGrant): Promise<EntitlementLedgerResult>;
@@ -102,6 +137,11 @@ export declare class InMemoryGameServicesStore implements GameServicesStore {
   findEntitlementTransactionByPlatformEvidence(input: EntitlementPlatformEvidenceIdentity): Promise<ProductGrantTransaction | undefined>;
   getEntitlementTransaction(ledgerEntryId: string): Promise<ProductGrantTransaction | undefined>;
   listEntitlementTransactions(): Promise<readonly ProductGrantTransaction[]>;
+  getEntitlementTransactions(ledgerEntryIds: readonly string[]): Promise<readonly ProductGrantTransaction[]>;
+  recordEntitlementRevocation(input: EntitlementLedgerRevocation): Promise<EntitlementLedgerResult>;
+  findEntitlementRevocations(input: {
+    readonly ledgerEntryIds: readonly string[];
+  }): Promise<readonly EntitlementRevocationTransaction[]>;
   recordLeaderboardScore(input: RecordLeaderboardScoreRequest, options?: {
     readonly recordedAt?: string;
   }): Promise<RecordLeaderboardScoreResponse>;
@@ -121,6 +161,8 @@ export declare function createGameServicesRouter(backend: GameServicesBackendApi
   health: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<void, void>, import("@orpc/contract").Schema<GameServicesHealthResponse, GameServicesHealthResponse>, object>;
   commerce: {
     verifyPurchase: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<VerifyPurchaseRequest, VerifyPurchaseRequest>, import("@orpc/contract").Schema<VerifyPurchaseResponse, VerifyPurchaseResponse>, object>;
+    getPurchaseLedgerStatus: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<PurchaseLedgerStatusRequest, PurchaseLedgerStatusRequest>, import("@orpc/contract").Schema<import("./operation-results.js").PurchaseLedgerStatusResponse, import("./operation-results.js").PurchaseLedgerStatusResponse>, object>;
+    getCapabilities: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<void, void>, import("@orpc/contract").Schema<import("@mpgd/platform/commerce").CommerceServiceCapabilities, import("@mpgd/platform/commerce").CommerceServiceCapabilities>, object>;
   };
   ads: {
     claimReward: import("@orpc/server").ImplementedProcedure<GameServicesOrpcContext & object, object, import("@orpc/contract").Schema<ClaimAdRewardRequest, ClaimAdRewardRequest>, import("@orpc/contract").Schema<ClaimAdRewardResponse, ClaimAdRewardResponse>, object>;