@mpgd/adapter-devvit 0.9.19 → 0.10.0

package/dist/index.js

@@ -1,7 +1,15 @@
-import { bridgeStorageLoadProtocol, createBridgeError, createCommerceV2UnavailableBridgeError, decodeBridgeStorageLoadData, } from '@mpgd/bridge';
+import { bridgeStorageLoadProtocol, commerceV2UnavailableBridgeErrorCode, createBridgeError, createCommerceV2UnavailableBridgeError, decodeBridgeStorageLoadData, } 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 { 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 const defaultDevvitRpcEndpoint = defaultBridgeRpcEndpoint;
+/** Bridge error of `createDevvitOrpcBridge` when the oRPC request itself failed. */
+export const devvitBridgeNetworkErrorCode = 'DEVVIT_BRIDGE_NETWORK_ERROR';
 export class DevvitBridgeError extends Error {
     code;
     requestId;
@@ -36,10 +44,23 @@ export function createDevvitPlatformGateway(input) {
         }
         return response.data;
     }
+    const commerceV2 = input.commerce === undefined
+        ? undefined
+        : createDevvitCommerceProvider({
+            ...input.commerce,
+            orders: createDevvitBridgeOrderSource(request),
+        });
     return {
         target: 'reddit',
         async getCapabilities() {
-            return { ...await request('runtime.getCapabilities', {}) };
+            const capabilities = { ...await request('runtime.getCapabilities', {}) };
+            if (commerceV2 === undefined) {
+                return capabilities;
+            }
+            // 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 };
         },
         identity: {
             getPlayer: () => request('identity.getPlayer', {}),
@@ -64,6 +85,7 @@ export function createDevvitPlatformGateway(input) {
             restore: () => request('commerce.restore', {}),
             getEntitlements: () => request('commerce.getEntitlements', {}),
         },
+        ...(commerceV2 === undefined ? {} : { commerceV2 }),
         ads: {
             preload: (payload) => request('ads.preload', payload),
             showRewarded: (payload) => request('ads.showRewarded', payload),
@@ -94,6 +116,135 @@ export function createDevvitPlatformGateway(input) {
         },
     };
 }
+/**
+ * The webview provider's order source over the server bridge: the paid orders
+ * the server lists as available purchases, mapped back to orders (the
+ * provider rebuilds the purchases under its own store id), and the
+ * availability the server reports. `COMMERCE_V2_UNAVAILABLE` from a bridge
+ * without the commerce handler is `configuration-required`; another bridge
+ * failure that is retryable (or the transport failing) keeps the availability
+ * the server last answered for the capability read (`temporarily-unavailable`
+ * before any answer; a non-retryable failure or an invalid answer fails
+ * closed) and is
+ * a `CommerceError` for a list read (`NETWORK` for a transport failure,
+ * otherwise `UNKNOWN` with the bridge code as `storeCode`).
+ */
+export function createDevvitBridgeOrderSource(request) {
+    /** The availability the server last answered; kept across transient read failures. */
+    let lastAvailability;
+    return {
+        async listPaidOrders() {
+            let data;
+            try {
+                data = await request('commerce.v2.getAvailablePurchases', {});
+            }
+            catch (error) {
+                throw toCommerceError(error);
+            }
+            let purchases;
+            try {
+                purchases = assertCommerceBridgeGetAvailablePurchasesResult(data).purchases;
+            }
+            catch (error) {
+                throw new CommerceError('INVALID_RESPONSE', {
+                    message: 'Devvit server bridge returned invalid data for commerce.v2.getAvailablePurchases.',
+                    cause: error,
+                });
+            }
+            const orders = [];
+            for (const purchase of purchases) {
+                let environment;
+                let delivered;
+                try {
+                    const evidence = assertDevvitOrderEvidence(purchase.evidence);
+                    environment = evidence.environment;
+                    delivered = evidence.status === undefined ? undefined : evidence.status === 'DELIVERED';
+                }
+                catch {
+                    // The server listed an order under another evidence schema; the
+                    // order itself is still the server's word.
+                    environment = undefined;
+                }
+                orders.push({
+                    orderId: purchase.transactionId,
+                    sku: purchase.storeSku,
+                    ...(purchase.purchasedAt === undefined ? {} : { paidAt: purchase.purchasedAt }),
+                    ...(environment === undefined ? {} : { environment }),
+                    ...(delivered === undefined ? {} : { delivered }),
+                });
+            }
+            return orders;
+        },
+        async getAvailability() {
+            let data;
+            try {
+                data = await request('commerce.v2.getCapabilities', { protocol: commerceProtocol });
+            }
+            catch (error) {
+                if (error instanceof DevvitBridgeError
+                    && error.code === commerceV2UnavailableBridgeErrorCode) {
+                    // The server does not serve commerce v2: fail closed, whatever it answered before.
+                    lastAvailability = undefined;
+                    return 'configuration-required';
+                }
+                if (isTransientBridgeFailure(error)) {
+                    // A retryable failure keeps the last answer the server gave, so one
+                    // timed-out read does not hide the shop; the first read fails closed.
+                    return lastAvailability ?? 'temporarily-unavailable';
+                }
+                // Anything else is not transient: fail closed and forget the old answer.
+                lastAvailability = undefined;
+                return 'temporarily-unavailable';
+            }
+            try {
+                lastAvailability = assertCommerceBridgeGetCapabilitiesResult(data).capabilities.availability;
+                return lastAvailability;
+            }
+            catch {
+                // The server answered something the contract rejects: fail closed.
+                lastAvailability = undefined;
+                return 'temporarily-unavailable';
+            }
+        },
+    };
+}
+/**
+ * A bridge failure as a commerce error: a closed server
+ * (`COMMERCE_V2_UNAVAILABLE`) is `CONFIGURATION_REQUIRED`, a transport failure
+ * (`DEVVIT_BRIDGE_NETWORK_ERROR`) is `NETWORK`, a v2 code is kept, and any
+ * other bridge code is `UNKNOWN` with the code as `storeCode`.
+ */
+/** A retryable bridge error, or the oRPC transport failing: the server may answer again shortly. */
+function isTransientBridgeFailure(error) {
+    if (error instanceof DevvitBridgeError) {
+        return error.retryable || error.code === devvitBridgeNetworkErrorCode;
+    }
+    return error instanceof PlatformOperationError && error.retryable;
+}
+function toCommerceError(error) {
+    if (error instanceof CommerceError) {
+        return error;
+    }
+    if (error instanceof DevvitBridgeError || error instanceof PlatformOperationError) {
+        const code = error.code === commerceV2UnavailableBridgeErrorCode
+            ? 'CONFIGURATION_REQUIRED'
+            : error.code === devvitBridgeNetworkErrorCode
+                ? 'NETWORK'
+                : isCommerceErrorCode(error.code)
+                    ? error.code
+                    : 'UNKNOWN';
+        return new CommerceError(code, {
+            message: error.message,
+            retryable: code === 'NETWORK' ? true : error.retryable,
+            ...(code === error.code ? {} : { storeCode: error.code }),
+            cause: error,
+        });
+    }
+    return new CommerceError('UNKNOWN', {
+        message: `Devvit server bridge request failed: ${errorMessage(error)}`,
+        cause: error,
+    });
+}
 export function createDevvitOrpcBridge(input = {}) {
     const client = input.client ?? createBridgeOrpcClient({
         url: input.endpoint ?? defaultDevvitRpcEndpoint,
@@ -105,7 +256,7 @@ export function createDevvitOrpcBridge(input = {}) {
                 return await client.request(bridgeRequest);
             }
             catch (error) {
-                return createBridgeError(bridgeRequest.id, 'DEVVIT_BRIDGE_NETWORK_ERROR', `Devvit oRPC bridge request failed: ${errorMessage(error)}`, true);
+                return createBridgeError(bridgeRequest.id, devvitBridgeNetworkErrorCode, `Devvit oRPC bridge request failed: ${errorMessage(error)}`, true);
             }
         },
     };

package/dist/payments.d.ts

@@ -1,8 +1,23 @@
 import type { CommerceAdapter, Entitlement, PlatformEvidenceEnvelope, PlatformGateway, 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
+* when the client could classify the failure, otherwise the platform's own
+* code (`String(errorCode)`), which the v2 provider keeps as `storeCode`.
+*/
+export interface DevvitCheckoutFailure {
+  readonly code: string;
+  readonly storeCode?: string;
+  readonly message?: string;
+  readonly retryable?: boolean;
+}
 export interface DevvitCheckoutResult {
   readonly status: PurchaseResult['status'];
+  /** `OrderResultEvent.orderId`: present once Reddit created the order. */
   readonly orderId?: string;
   readonly evidence?: PlatformEvidenceEnvelope;
+  /** Read by the commerce v2 provider for a `cancelled` or `failed` checkout. */
+  readonly error?: DevvitCheckoutFailure;
 }
 export interface DevvitPaymentsClient {
   purchase(sku: string): Promise<DevvitCheckoutResult>;
@@ -19,3 +34,5 @@ export interface CreateDevvitCommerceAdapterInput {
 }
 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,5 +1,5 @@
 export function createDevvitCommerceAdapter(input) {
-    const products = normalizeProducts(input.products);
+    const products = normalizeDevvitCommerceProducts(input.products);
     const productsById = new Map(products.map((product) => [product.info.id, product]));
     return {
         async getProducts() {
@@ -53,7 +53,8 @@ export function withDevvitCommerceAdapter(gateway, commerce) {
         commerce,
     };
 }
-function normalizeProducts(input) {
+/** Frozen copies of the configured products; duplicate ids or SKUs and blank SKUs are rejected. */
+export function normalizeDevvitCommerceProducts(input) {
     const productIds = new Set();
     const skus = new Set();
     return Object.freeze(input.map((product) => {

package/dist/server/commerce-bridge.d.ts

@@ -0,0 +1,111 @@
+import { type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
+import { type StoreId } from '@mpgd/platform/commerce';
+/**
+* Host side of commerce v2 for Devvit: the server bridge serves the six
+* `commerce.v2.*` methods from the Devvit `payments` plugin
+* (`@devvit/payments/server`, re-exported by `@devvit/web/server`). The
+* plugin runs in the request context of the authenticated Reddit user:
+* Reddit documents server-side `payments.getOrders()` as the current user's
+* orders, newest first (Devvit docs, "Manage Payments", "Check orders"),
+* which the fulfillment handler's own user binding backs. The checkout is a webview
+* effect, so `requestPurchase` is answered by the client provider, never
+* here. This module imports no Devvit SDK; the plugin surface it needs is
+* the structural `DevvitServerPaymentsLike`.
+*/
+/** Bridge error for a commerce v2 payload the typia assert rejected. */
+export declare const devvitCommerceV2InvalidPayloadBridgeErrorCode: 'COMMERCE_V2_INVALID_PAYLOAD';
+/** Bridge error for `finishTransaction`: the Devvit profile has nothing to finish. */
+export declare const devvitCommerceV2MethodUnsupportedBridgeErrorCode: 'COMMERCE_V2_METHOD_UNSUPPORTED';
+/** Bridge error for `requestPurchase` reaching the server: the checkout opens in the webview. */
+export declare const devvitCommerceCheckoutClientOnlyBridgeErrorCode: 'DEVVIT_COMMERCE_CHECKOUT_CLIENT_ONLY';
+/** Bridge error when the payments plugin fails; retryable. */
+export declare const devvitPaymentsUnavailableBridgeErrorCode: 'DEVVIT_PAYMENTS_UNAVAILABLE';
+/** `Order.status` as `@devvit/protos` encodes it (`OrderStatus` enum) or as the handler types spell it. */
+export type DevvitPaymentsOrderStatusLike = number | string;
+/** The fields of a `@devvit/payments` `Order` the handler reads. */
+export interface DevvitPaymentsOrderLike {
+  readonly id: string;
+  readonly status: DevvitPaymentsOrderStatusLike;
+  readonly createdAt?: string | null | undefined;
+  readonly updatedAt?: string | null | undefined;
+  readonly products: readonly {
+    readonly sku: string;
+  }[];
+  readonly environment?: number | string | undefined;
+}
+/** The fields of a `@devvit/payments` `Product` the handler reads. */
+export interface DevvitPaymentsProductLike {
+  readonly sku: string;
+  readonly name: string;
+  readonly description: string;
+  readonly price?: {
+    readonly amount: number;
+    readonly currency: number | string;
+  } | undefined;
+  readonly accountingType: number | string;
+}
+/** The subset of the Devvit `payments` plugin the handler calls (`PaymentsClient` fits). */
+export interface DevvitServerPaymentsLike {
+  getOrders(filters: {
+    readonly limit: number;
+    readonly cursor?: string;
+    /** `OrderStatus` hint; `@devvit/payments` 0.14 ignores it, so the handler filters itself. */
+    readonly status?: number;
+  }): Promise<{
+    readonly orders: readonly DevvitPaymentsOrderLike[];
+    readonly pageInfo?: {
+      readonly hasNextPage: boolean;
+      readonly endCursor: string;
+    } | undefined;
+  }>;
+  getProducts(filters?: {
+    readonly skus?: readonly string[];
+  }): Promise<{
+    readonly products: readonly DevvitPaymentsProductLike[];
+  }>;
+}
+export interface DevvitCommerceBridgeProduct {
+  readonly productId: string;
+  readonly sku: string;
+}
+export interface CreateDevvitCommerceV2BridgeHandlerInput {
+  readonly payments: DevvitServerPaymentsLike;
+  /** The game's logical products and their Devvit SKUs; orders for other SKUs are not listed. */
+  readonly products: readonly DevvitCommerceBridgeProduct[];
+  /** Defaults to `devvit`. */
+  readonly store?: StoreId;
+  readonly warn?: ((message: string) => void) | undefined;
+}
+export interface DevvitCommerceV2BridgeHandler {
+  /** Answers one of the six `commerce.v2.*` methods; other methods are rejected. */
+  request(input: BridgeRequest): Promise<BridgeResponse>;
+}
+/**
+* Serves `commerce.v2.*` from the payments plugin:
+*
+* - `getCapabilities` answers the Devvit profile (`createDevvitCommerceCapabilities`).
+* - `fetchProducts` lists the configured SKUs from `payments.getProducts`
+*   (instant and consumable goods as `consumable`, durable goods as
+*   `durable`; time-limited goods are not listed) priced in Reddit Gold.
+* - `getAvailablePurchases` lists the authenticated user's `PAID` and
+*   `DELIVERED` orders for configured SKUs from `payments.getOrders` as
+*   `purchased` (the order id as `transactionId` and `token`,
+*   `devvit.order.v1` evidence whose `status` says which), bounded by
+*   `maximumDevvitAvailableOrders`. Reddit marks an order `DELIVERED` as soon
+*   as the fulfillment handler answered, so the delivered orders are the ones
+*   whose ledger entry exists; the webview provider lists only the `PAID`
+*   ones as available and reports both as events, so a session that lost its
+*   checkout result still finds the order. The scan reads pages of 64
+*   (newest first, as the Devvit docs describe) and stops after two
+*   consecutive pages without a paid or delivered order or after
+*   `maximumOrderPages`, warning when pages are left.
+* - `requestPurchase` is refused with `DEVVIT_COMMERCE_CHECKOUT_CLIENT_ONLY`,
+*   `finishTransaction` with `COMMERCE_V2_METHOD_UNSUPPORTED`, and
+*   `restorePurchases` answers `{ restored: false }`: the webview provider
+*   re-reads the list itself.
+*
+* Payloads and results are validated with the `@mpgd/platform/commerce`
+* asserts; a plugin failure crosses the bridge as the retryable
+* `DEVVIT_PAYMENTS_UNAVAILABLE`.
+*/
+export declare function createDevvitCommerceV2BridgeHandler(input: CreateDevvitCommerceV2BridgeHandlerInput): DevvitCommerceV2BridgeHandler;