@mpgd/adapter-devvit 0.10.1 → 0.12.0

package/README.md

@@ -0,0 +1,32 @@
+# @mpgd/adapter-devvit
+
+Reddit Devvit Web platform adapter for mpgd games.
+
+| Entry point | Purpose |
+| --- | --- |
+| `@mpgd/adapter-devvit` | `createDevvitPlatformGateway`, the oRPC bridge and sandbox bridge, the commerce provider and catalog helpers |
+| `@mpgd/adapter-devvit/payments` | `normalizeDevvitCommerceProducts` and the checkout types |
+| `@mpgd/adapter-devvit/server` | `createDevvitCommerceV2BridgeHandler`, payment-order normalizers, durable post operations, Redis stores |
+| `@mpgd/adapter-devvit/web` | Webview helpers, including `createDevvitWebPaymentsClient()` over `purchase()` from `@devvit/web/client` |
+| `@mpgd/adapter-devvit/surface`, `/view-mode` | Inline and expanded view-mode helpers |
+
+## Commerce
+
+The gateway has at most one commerce surface, `gateway.commerce`, a commerce v2 `CommerceProvider`
+(`createDevvitCommerceProvider`). `createDevvitPlatformGateway({ commerce: { products, client } })`
+installs it and reports its block as `getCapabilities().commerce`; without the option the gateway
+sells nothing, has no `commerce`, and reports `createUnsupportedCommerceCapabilities()`. Reddit
+settles a purchase on the server, so only the backend ledger the fulfillment handler writes grants
+anything. Games purchase through `@mpgd/game-services`; see the
+[Devvit commerce guide](../../docs/DEVVIT_COMMERCE.md).
+
+## Migrating from v1
+
+| Removed | Replacement |
+| --- | --- |
+| `createDevvitCommerceAdapter`, `withDevvitCommerceAdapter`, `CreateDevvitCommerceAdapterInput` | `createDevvitPlatformGateway({ commerce })` or `createDevvitCommerceProvider` |
+| v1 `gateway.commerce` (`getProducts`, `purchase`, `restore`, `getEntitlements`) | `gateway.commerce`, the provider (absent when nothing is sold) |
+| `gateway.commerceV2` | `gateway.commerce` |
+| `DevvitPaymentsClient.getEntitlements()` | The backend ledger (`listActiveEntitlementTransactions` on the server); the client is only `purchase(sku)` |
+| `capabilities.nativeIap`, `capabilities.subscriptionIap` | `capabilities.commerce` |
+| Bridge methods `commerce.getProducts`, `commerce.purchase`, `commerce.restore`, `commerce.getEntitlements` | `UNSUPPORTED_METHOD`; the six `commerce.v2.*` methods |

package/dist/catalog-products.d.ts

@@ -0,0 +1,48 @@
+import type { ProductInfo, ProductType } from '@mpgd/platform';
+import { type DevvitCommerceProduct } from './payments.js';
+/** The catalog target whose `platformProductIds` entry is the Devvit SKU. */
+export declare const defaultDevvitCatalogTarget = "reddit";
+/**
+* The product catalog fields this module reads (`ProductCatalog` from
+* `@mpgd/catalog` fits). Structural so the adapter adds no catalog dependency.
+*/
+export interface DevvitCatalogProductLike {
+  readonly id: string;
+  readonly type: ProductType;
+  readonly platformProductIds: Readonly<Partial<Record<string, string>>>;
+}
+export interface DevvitCatalogLike {
+  readonly products: readonly DevvitCatalogProductLike[];
+}
+/** A logical product paired with its Devvit SKU, as the server bridge handler takes it. */
+export interface DevvitCatalogBridgeProduct {
+  readonly productId: string;
+  readonly sku: string;
+}
+export interface CreateDevvitCommerceProductsOptions {
+  /** Defaults to `reddit`. */
+  readonly target?: string;
+  /**
+  * Static product info for the webview provider's `fetchProducts`. Devvit
+  * prices live products in Reddit Gold on the server (`payments.getProducts`),
+  * so the default lists the logical id as title with a Reddit Gold price
+  * placeholder; a game that wants localized copy supplies its own.
+  */
+  readonly describe?: (product: DevvitCatalogProductLike, sku: string) => Pick<ProductInfo, 'title' | 'description' | 'price'>;
+}
+/**
+* The `{ productId, sku }` pairs `createDevvitCommerceV2BridgeHandler` takes,
+* read from the catalog's `platformProductIds[target]` entries. The catalog is
+* the single source of the Devvit SKUs and its rules apply, as
+* `resolveProductPlatformId` reads them: the SKU is trimmed, and a product
+* without an entry, or with a blank one, is not sold on Reddit. A subscription
+* is skipped because Devvit sells one-time goods only. Duplicate product ids
+* and SKUs are rejected.
+*/
+export declare function createDevvitCommerceBridgeProducts(catalog: DevvitCatalogLike, target?: string): readonly DevvitCatalogBridgeProduct[];
+/**
+* The webview products for `createDevvitPlatformGateway({ commerce: { products } })`,
+* derived from the same catalog entries as `createDevvitCommerceBridgeProducts`,
+* so the webview and the server agree on every SKU.
+*/
+export declare function createDevvitCommerceProducts(catalog: DevvitCatalogLike, options?: CreateDevvitCommerceProductsOptions): readonly DevvitCommerceProduct[];

package/dist/catalog-products.js

@@ -0,0 +1,78 @@
+import { normalizeDevvitCommerceProducts } from './payments.js';
+/** The catalog target whose `platformProductIds` entry is the Devvit SKU. */
+export const defaultDevvitCatalogTarget = 'reddit';
+/**
+ * The `{ productId, sku }` pairs `createDevvitCommerceV2BridgeHandler` takes,
+ * read from the catalog's `platformProductIds[target]` entries. The catalog is
+ * the single source of the Devvit SKUs and its rules apply, as
+ * `resolveProductPlatformId` reads them: the SKU is trimmed, and a product
+ * without an entry, or with a blank one, is not sold on Reddit. A subscription
+ * is skipped because Devvit sells one-time goods only. Duplicate product ids
+ * and SKUs are rejected.
+ */
+export function createDevvitCommerceBridgeProducts(catalog, target = defaultDevvitCatalogTarget) {
+    const skus = new Set();
+    const productIds = new Set();
+    const products = [];
+    for (const product of catalog.products) {
+        const sku = readSku(product, target);
+        if (sku === undefined || product.type === 'subscription') {
+            continue;
+        }
+        if (productIds.has(product.id)) {
+            throw new TypeError(`Duplicate Devvit logical product ID: ${product.id}`);
+        }
+        if (skus.has(sku)) {
+            throw new TypeError(`Duplicate Devvit product SKU: ${sku}`);
+        }
+        productIds.add(product.id);
+        skus.add(sku);
+        products.push(Object.freeze({ productId: product.id, sku }));
+    }
+    return Object.freeze(products);
+}
+/**
+ * The webview products for `createDevvitPlatformGateway({ commerce: { products } })`,
+ * derived from the same catalog entries as `createDevvitCommerceBridgeProducts`,
+ * so the webview and the server agree on every SKU.
+ */
+export function createDevvitCommerceProducts(catalog, options = {}) {
+    const target = options.target ?? defaultDevvitCatalogTarget;
+    const describe = options.describe ?? describeDevvitProduct;
+    const bridgeProducts = createDevvitCommerceBridgeProducts(catalog, target);
+    const byId = new Map(catalog.products.map((product) => [product.id, product]));
+    return normalizeDevvitCommerceProducts(bridgeProducts.map((bridgeProduct) => {
+        const product = byId.get(bridgeProduct.productId);
+        if (product === undefined) {
+            throw new TypeError(`Devvit product ${bridgeProduct.productId} is missing from the catalog.`);
+        }
+        return {
+            info: {
+                id: product.id,
+                type: product.type,
+                ...describe(product, bridgeProduct.sku),
+            },
+            sku: bridgeProduct.sku,
+        };
+    }));
+}
+function describeDevvitProduct(product) {
+    return {
+        title: product.id,
+        description: '',
+        price: { formatted: 'Reddit Gold', currencyCode: 'GOLD' },
+    };
+}
+/** The catalog's reading of a platform id: own key only, trimmed, blank as unsold. */
+function readSku(product, target) {
+    const identifiers = product.platformProductIds;
+    if (!Object.prototype.hasOwnProperty.call(identifiers, target)) {
+        return undefined;
+    }
+    const value = identifiers[target];
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const sku = value.trim();
+    return sku.length === 0 ? undefined : sku;
+}

package/dist/commerce-provider.d.ts

@@ -40,7 +40,7 @@ export type DevvitOrdersChangeListener = (change?: DevvitOrdersChange) => void;
 export interface CreateDevvitCommerceProviderInput {
   readonly products: readonly DevvitCommerceProduct[];
   /** Opens the Reddit checkout (`purchase()` from `@devvit/payments/client`). */
-  readonly client: Pick<DevvitPaymentsClient, 'purchase'>;
+  readonly client: DevvitPaymentsClient;
   readonly orders: DevvitOrderSource;
   /** Defaults to `devvit`; conformance vectors name their fixture store. */
   readonly store?: StoreId;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { type CreateDevvitCommerceProviderInput, type DevvitOrderSource } from '
 export * from './commerce-contract.js';
 export * from './commerce-provider.js';
 export * from './payments.js';
+export * from './catalog-products.js';
 export declare const defaultDevvitRpcEndpoint = "/api/mpgd/rpc";
 /** Bridge error of `createDevvitOrpcBridge` when the oRPC request itself failed. */
 export declare const devvitBridgeNetworkErrorCode: 'DEVVIT_BRIDGE_NETWORK_ERROR';
@@ -35,15 +36,17 @@ export interface DevvitPlatformGatewayOptions {
   readonly fallbackBridge?: DevvitBridge;
   readonly rpcEndpoint?: BridgeRpcEndpoint;
   /**
-  * Installs the commerce v2 provider (`createDevvitCommerceProvider`) as
-  * `commerceV2`, with the `commerce` capability block and `nativeIap` and
-  * `subscriptionIap` derived from it. Absent, the gateway offers no
-  * `commerceV2`; the v1 `commerce` surface is the bridge's either way.
+  * Installs the commerce provider (`createDevvitCommerceProvider`) as the
+  * gateway's `commerce`, and its capability block as the snapshot's
+  * `commerce`. Absent, the gateway sells nothing: it has no `commerce` and
+  * reports `createUnsupportedCommerceCapabilities()`, whatever the server
+  * snapshot says.
   *
-  * Not yet usable in production before C2: the backend lookup verifier for
-  * `devvit.order.v1` does not exist yet, so a verify request for a Devvit
-  * purchase is refused today instead of answering `pending`, and no journal
-  * record can reach `granted`. Enable it once the backend can answer.
+  * A purchase is granted by the backend ledger only: the fulfillment handler
+  * writes the ledger entry, and the backend's `devvit.order.v1` lookup
+  * verifier answers the reconciler's verify request from it. Owned
+  * entitlements come from that ledger through `@mpgd/game-services`, not
+  * from the payments client.
   */
   readonly commerce?: DevvitGatewayCommerceOptions;
 }

package/dist/index.js

@@ -1,12 +1,14 @@
-import { bridgeStorageLoadProtocol, commerceV2UnavailableBridgeErrorCode, createBridgeError, createCommerceV2UnavailableBridgeError, decodeBridgeStorageLoadData, } from '@mpgd/bridge';
+import { bridgeStorageLoadProtocol, commerceV2UnavailableBridgeErrorCode, createBridgeError, createCommerceV2UnavailableBridgeError, createNotificationsV2UnavailableBridgeError, decodeBridgeStorageLoadData, isBridgeNotificationsV2Method, } from '@mpgd/bridge';
 import { createBridgeOrpcClient, defaultBridgeRpcEndpoint, } from '@mpgd/bridge/orpc';
-import { PlatformOperationError, } from '@mpgd/platform';
-import { assertCommerceBridgeGetAvailablePurchasesResult, assertCommerceBridgeGetCapabilitiesResult, CommerceError, commerceProtocol, deriveLegacyCommerceCapabilities, isCommerceErrorCode, } from '@mpgd/platform/commerce';
+import { createUnsupportedCommerceCapabilities, PlatformOperationError, } from '@mpgd/platform';
+import { assertCommerceBridgeGetAvailablePurchasesResult, assertCommerceBridgeGetCapabilitiesResult, CommerceError, commerceProtocol, isCommerceErrorCode, } from '@mpgd/platform/commerce';
+import { withShareIntentCheck } from '@mpgd/platform/routes';
 import { assertDevvitOrderEvidence } from './commerce-contract.js';
 import { createDevvitCommerceProvider, } from './commerce-provider.js';
 export * from './commerce-contract.js';
 export * from './commerce-provider.js';
 export * from './payments.js';
+export * from './catalog-products.js';
 export const defaultDevvitRpcEndpoint = defaultBridgeRpcEndpoint;
 /** Bridge error of `createDevvitOrpcBridge` when the oRPC request itself failed. */
 export const devvitBridgeNetworkErrorCode = 'DEVVIT_BRIDGE_NETWORK_ERROR';
@@ -44,7 +46,7 @@ export function createDevvitPlatformGateway(input) {
         }
         return response.data;
     }
-    const commerceV2 = input.commerce === undefined
+    const commerce = input.commerce === undefined
         ? undefined
         : createDevvitCommerceProvider({
             ...input.commerce,
@@ -53,14 +55,20 @@ export function createDevvitPlatformGateway(input) {
     return {
         target: 'reddit',
         async getCapabilities() {
-            const capabilities = { ...await request('runtime.getCapabilities', {}) };
-            if (commerceV2 === undefined) {
-                return capabilities;
+            const { nativeIap: _nativeIap, subscriptionIap: _subscriptionIap, commerce: _serverCommerce, ...capabilities } = await request('runtime.getCapabilities', {});
+            const availability = capabilities.providerAvailability;
+            if (typeof availability === 'object' && availability !== null && !Array.isArray(availability)) {
+                const { nativeIap: _retiredNativeIap, subscriptionIap: _retiredSubscriptionIap, ...current } = availability;
+                capabilities.providerAvailability = current;
             }
             // The webview provider owns the block: the server snapshot stays honest
-            // about the server, and the flags derive from the block it reports.
-            const commerce = await commerceV2.getCapabilities();
-            return { ...capabilities, ...deriveLegacyCommerceCapabilities(commerce), commerce };
+            // about the server, and a gateway without a provider sells nothing.
+            return {
+                ...capabilities,
+                commerce: commerce === undefined
+                    ? createUnsupportedCommerceCapabilities()
+                    : await commerce.getCapabilities(),
+            };
         },
         identity: {
             getPlayer: () => request('identity.getPlayer', {}),
@@ -71,21 +79,17 @@ export function createDevvitPlatformGateway(input) {
             getLaunchIntent: () => request('presentation.getLaunchIntent', {}),
             requestGameSurface: (payload) => request('presentation.requestGameSurface', payload),
         },
-        sharing: {
+        // The bridge's host may build a share URL from the link, so it only ever
+        // sees an intent the ShareIntent contract accepts, with the link normalized.
+        sharing: withShareIntentCheck({
             share: (payload) => request('share.share', payload),
             readInboundShare: () => request('share.readInboundShare', {}),
-        },
+        }),
         notifications: {
             getStatus: (topic) => request('notifications.getStatus', { topic }),
             requestSubscription: (topic) => request('notifications.requestSubscription', { topic }),
         },
-        commerce: {
-            getProducts: () => request('commerce.getProducts', {}),
-            purchase: (payload) => request('commerce.purchase', payload),
-            restore: () => request('commerce.restore', {}),
-            getEntitlements: () => request('commerce.getEntitlements', {}),
-        },
-        ...(commerceV2 === undefined ? {} : { commerceV2 }),
+        ...(commerce === undefined ? {} : { commerce }),
         ads: {
             preload: (payload) => request('ads.preload', payload),
             showRewarded: (payload) => request('ads.showRewarded', payload),
@@ -286,10 +290,14 @@ export function createDevvitSandboxBridge() {
     const storage = new Map();
     return {
         async request(input) {
+            // Notifications v2 arrives with the Devvit provider (P3); until then
+            // every v2 method answers the dedicated code.
+            if (isBridgeNotificationsV2Method(input.method)) {
+                return createNotificationsV2UnavailableBridgeError(input, 'Devvit sandbox bridge');
+            }
             switch (input.method) {
                 case 'runtime.getCapabilities':
                     return ok(input, {
-                        nativeIap: false,
                         nativeAds: false,
                         rewardedAds: false,
                         interstitialAds: false,
@@ -300,6 +308,7 @@ export function createDevvitSandboxBridge() {
                         socialShare: false,
                         haptics: false,
                         localizedContent: true,
+                        commerce: createUnsupportedCommerceCapabilities(),
                     });
                 case 'identity.getPlayer':
                     return ok(input, {
@@ -333,18 +342,6 @@ export function createDevvitSandboxBridge() {
                     return ok(input, 'approval-required');
                 case 'notifications.requestSubscription':
                     return ok(input, 'unavailable');
-                case 'commerce.getProducts':
-                case 'commerce.getEntitlements':
-                    return ok(input, []);
-                case 'commerce.purchase':
-                    return ok(input, {
-                        status: 'cancelled',
-                        entitlementIds: [],
-                    });
-                case 'commerce.restore':
-                    return ok(input, {
-                        restoredEntitlements: [],
-                    });
                 case 'ads.preload':
                     return ok(input, {});
                 case 'leaderboard.open':
@@ -384,7 +381,7 @@ export function createDevvitSandboxBridge() {
                         saved: key !== undefined,
                     });
                 }
-                // Commerce v2 providers arrive with the B-phase PRs (B6 for Devvit).
+                // The sandbox sells nothing: every commerce method fails closed.
                 case 'commerce.v2.getCapabilities':
                 case 'commerce.v2.fetchProducts':
                 case 'commerce.v2.requestPurchase':

package/dist/payments.d.ts

@@ -1,4 +1,4 @@
-import type { CommerceAdapter, Entitlement, PlatformEvidenceEnvelope, PlatformGateway, ProductInfo, PurchaseResult } from '@mpgd/platform';
+import type { PlatformEvidenceEnvelope, ProductInfo, PurchaseResult } from '@mpgd/platform';
 /**
 * Why a Devvit checkout ended without an order (`OrderResultEvent` with
 * `STATUS_ERROR` or `STATUS_CANCELLED`). `code` is a commerce v2 error code
@@ -19,20 +19,18 @@ export interface DevvitCheckoutResult {
   /** Read by the commerce v2 provider for a `cancelled` or `failed` checkout. */
   readonly error?: DevvitCheckoutFailure;
 }
+/**
+* The checkout half of the Reddit payments client: the commerce v2 provider
+* opens the checkout through it and needs nothing else. Owned entitlements are
+* not read from the client; the backend ledger answers them through
+* `@mpgd/game-services`, and the paid orders come from the server bridge.
+*/
 export interface DevvitPaymentsClient {
   purchase(sku: string): Promise<DevvitCheckoutResult>;
-  getEntitlements(): Promise<readonly Entitlement[]>;
 }
 export interface DevvitCommerceProduct {
   readonly info: ProductInfo;
   readonly sku: string;
 }
-export interface CreateDevvitCommerceAdapterInput {
-  readonly products: readonly DevvitCommerceProduct[];
-  readonly client: DevvitPaymentsClient;
-  readonly onCheckoutError?: (error: unknown) => void;
-}
-export declare function createDevvitCommerceAdapter(input: CreateDevvitCommerceAdapterInput): CommerceAdapter;
-export declare function withDevvitCommerceAdapter(gateway: PlatformGateway, commerce: CommerceAdapter): PlatformGateway;
 /** Frozen copies of the configured products; duplicate ids or SKUs and blank SKUs are rejected. */
 export declare function normalizeDevvitCommerceProducts(input: readonly DevvitCommerceProduct[]): readonly DevvitCommerceProduct[];

package/dist/payments.js

@@ -1,58 +1,3 @@
-export function createDevvitCommerceAdapter(input) {
-    const products = normalizeDevvitCommerceProducts(input.products);
-    const productsById = new Map(products.map((product) => [product.info.id, product]));
-    return {
-        async getProducts() {
-            return products.map((product) => product.info);
-        },
-        async purchase(request) {
-            const product = productsById.get(request.productId);
-            if (product === undefined) {
-                return failedPurchase();
-            }
-            try {
-                // Reddit's platform order ID is authoritative. Do not attach client operation
-                // metadata whose identifiers can exceed Devvit's metadata constraints.
-                const result = await input.client.purchase(product.sku);
-                return {
-                    status: result.status,
-                    ...(result.orderId === undefined ? {} : { transactionId: result.orderId }),
-                    // Devvit server fulfillment and a subsequent entitlement read are authoritative.
-                    entitlementIds: [],
-                    ...(result.evidence === undefined ? {} : { evidence: result.evidence }),
-                };
-            }
-            catch (error) {
-                input.onCheckoutError?.(error);
-                return failedPurchase();
-            }
-        },
-        async restore() {
-            return { restoredEntitlements: await input.client.getEntitlements() };
-        },
-        async getEntitlements() {
-            return input.client.getEntitlements();
-        },
-    };
-}
-export function withDevvitCommerceAdapter(gateway, commerce) {
-    if (gateway.target !== 'reddit') {
-        throw new TypeError('Devvit commerce can only be installed on a reddit gateway.');
-    }
-    if ('getTargetRuntime' in gateway && typeof gateway.getTargetRuntime === 'function') {
-        throw new TypeError('Devvit commerce must be installed before target availability is applied.');
-    }
-    return {
-        ...gateway,
-        async getCapabilities() {
-            return {
-                ...await gateway.getCapabilities(),
-                nativeIap: true,
-            };
-        },
-        commerce,
-    };
-}
 /** Frozen copies of the configured products; duplicate ids or SKUs and blank SKUs are rejected. */
 export function normalizeDevvitCommerceProducts(input) {
     const productIds = new Set();
@@ -75,9 +20,3 @@ export function normalizeDevvitCommerceProducts(input) {
         });
     }));
 }
-function failedPurchase() {
-    return Object.freeze({
-        status: 'failed',
-        entitlementIds: [],
-    });
-}

package/dist/server/index.d.ts

@@ -1,4 +1,5 @@
 export * from './commerce-bridge.js';
+export { createDevvitCommerceBridgeProducts, defaultDevvitCatalogTarget, type DevvitCatalogBridgeProduct, type DevvitCatalogLike, type DevvitCatalogProductLike, } from '../catalog-products.js';
 export * from './payment-order.js';
 export * from './post-operation.js';
 export * from './redis-post-operation-store.js';

package/dist/server/index.js

@@ -1,4 +1,5 @@
 export * from './commerce-bridge.js';
+export { createDevvitCommerceBridgeProducts, defaultDevvitCatalogTarget, } from '../catalog-products.js';
 export * from './payment-order.js';
 export * from './post-operation.js';
 export * from './redis-post-operation-store.js';

package/dist/web.d.ts

@@ -1,4 +1,5 @@
 import type { ShareResult } from '@mpgd/platform';
+import type { DevvitCheckoutResult, DevvitPaymentsClient } from './payments.js';
 import { type DevvitSurfaceOptions, type DevvitSurfaceResult } from './surface.js';
 import { type DevvitPreviewViewModeOptions, type DevvitPreviewViewModeResult, type DevvitViewModeOptions, type DevvitViewModeResult } from './view-mode.js';
 export type { DevvitSurfaceClient, DevvitSurfaceMode, DevvitSurfaceOptions, DevvitSurfaceResult, } from './surface.js';
@@ -30,3 +31,30 @@ export declare function requestDevvitExpandedMode(event: MouseEvent, entry: stri
 * completed sharing. Devvit does not report a completion callback.
 */
 export declare function presentDevvitShareSheet(options: DevvitShareSheetOptions): Promise<ShareResult>;
+/** `OrderResultEvent` of `@devvit/payments/client`, as the webview reads it. */
+export interface DevvitOrderResultEventLike {
+  /** `OrderResultStatus`: 0 cancelled, 1 success, 2 error (or its name). */
+  readonly status: number | string;
+  readonly orderId?: string | undefined;
+  readonly errorCode?: number | undefined;
+  readonly errorMessage?: string | undefined;
+}
+/** The checkout client `createDevvitWebPaymentsClient` returns; the v2 provider needs nothing else. */
+export type DevvitWebPaymentsClient = DevvitPaymentsClient;
+/**
+* Maps one Reddit checkout answer to the adapter's `DevvitCheckoutResult`:
+* `STATUS_SUCCESS` with an order id is `completed` (the order id is Reddit's;
+* the backend ledger decides the grant), `STATUS_SUCCESS` without one is
+* `pending` so the reconciler resolves it from the paid-order list,
+* `STATUS_CANCELLED` is `cancelled`, and `STATUS_ERROR` is `failed` with the
+* platform code kept as `storeCode`. An unknown status is `pending`: an order
+* may exist and nothing is granted or dropped on the client.
+*/
+export declare function toDevvitCheckoutResult(event: DevvitOrderResultEventLike): DevvitCheckoutResult;
+/**
+* `purchase()` from `@devvit/payments/client` (re-exported by
+* `@devvit/web/client`) as the checkout client of `createDevvitPlatformGateway({
+* commerce: { client } })`. One SKU per checkout, no client metadata: Reddit's
+* order id is the only identity the purchase carries.
+*/
+export declare function createDevvitWebPaymentsClient(): DevvitWebPaymentsClient;

package/dist/web.js

@@ -65,3 +65,67 @@ function isAbortError(error) {
             && error !== null
             && error.name === 'AbortError';
 }
+const successStatuses = new Set([1, 'STATUS_SUCCESS', 'SUCCESS']);
+const cancelledStatuses = new Set([
+    0,
+    'STATUS_CANCELLED',
+    'CANCELLED',
+]);
+const errorStatuses = new Set([2, 'STATUS_ERROR', 'ERROR']);
+/**
+ * Maps one Reddit checkout answer to the adapter's `DevvitCheckoutResult`:
+ * `STATUS_SUCCESS` with an order id is `completed` (the order id is Reddit's;
+ * the backend ledger decides the grant), `STATUS_SUCCESS` without one is
+ * `pending` so the reconciler resolves it from the paid-order list,
+ * `STATUS_CANCELLED` is `cancelled`, and `STATUS_ERROR` is `failed` with the
+ * platform code kept as `storeCode`. An unknown status is `pending`: an order
+ * may exist and nothing is granted or dropped on the client.
+ */
+export function toDevvitCheckoutResult(event) {
+    const orderId = typeof event.orderId === 'string' && event.orderId.trim().length > 0
+        ? event.orderId.trim()
+        : undefined;
+    if (successStatuses.has(event.status)) {
+        return orderId === undefined ? { status: 'pending' } : { status: 'completed', orderId };
+    }
+    if (cancelledStatuses.has(event.status)) {
+        return {
+            status: 'cancelled',
+            ...(orderId === undefined ? {} : { orderId }),
+            error: { code: 'USER_CANCELLED', storeCode: 'DEVVIT_CHECKOUT_CANCELLED', retryable: false },
+        };
+    }
+    if (errorStatuses.has(event.status)) {
+        const storeCode = event.errorCode === undefined
+            ? 'DEVVIT_CHECKOUT_FAILED'
+            : String(event.errorCode);
+        return {
+            status: 'failed',
+            ...(orderId === undefined ? {} : { orderId }),
+            error: {
+                code: storeCode,
+                storeCode,
+                ...(typeof event.errorMessage === 'string' && event.errorMessage.length > 0
+                    ? { message: event.errorMessage }
+                    : {}),
+            },
+        };
+    }
+    return { status: 'pending', ...(orderId === undefined ? {} : { orderId }) };
+}
+/**
+ * `purchase()` from `@devvit/payments/client` (re-exported by
+ * `@devvit/web/client`) as the checkout client of `createDevvitPlatformGateway({
+ * commerce: { client } })`. One SKU per checkout, no client metadata: Reddit's
+ * order id is the only identity the purchase carries.
+ */
+export function createDevvitWebPaymentsClient() {
+    return {
+        async purchase(sku) {
+            if (typeof sku !== 'string' || sku.trim().length === 0) {
+                throw new TypeError('Devvit checkout requires a non-empty SKU.');
+            }
+            return toDevvitCheckoutResult(await browserClient.purchase(sku));
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-devvit",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Reddit Devvit Web platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -55,9 +55,9 @@
   ],
   "dependencies": {
     "@devvit/web": "0.14.1",
-    "@mpgd/bridge": "0.12.3",
-    "@mpgd/platform": "0.22.0",
-    "@mpgd/game-services": "0.22.0"
+    "@mpgd/game-services": "0.24.0",
+    "@mpgd/platform": "0.23.0",
+    "@mpgd/bridge": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",