@mpgd/adapter-devvit 0.11.0 → 0.12.1

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

@@ -41,9 +41,8 @@ export interface CreateDevvitCommerceProductsOptions {
 */
 export declare function createDevvitCommerceBridgeProducts(catalog: DevvitCatalogLike, target?: string): readonly DevvitCatalogBridgeProduct[];
 /**
-* The webview products for `createDevvitPlatformGateway({ commerce: { products } })`
-* and `createDevvitCommerceAdapter`, derived from the same catalog entries as
-* `createDevvitCommerceBridgeProducts`, so the webview and the server agree on
-* every SKU.
+* 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

@@ -32,10 +32,9 @@ export function createDevvitCommerceBridgeProducts(catalog, target = defaultDevv
     return Object.freeze(products);
 }
 /**
- * The webview products for `createDevvitPlatformGateway({ commerce: { products } })`
- * and `createDevvitCommerceAdapter`, derived from the same catalog entries as
- * `createDevvitCommerceBridgeProducts`, so the webview and the server agree on
- * every SKU.
+ * 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;

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

@@ -36,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,7 +1,8 @@
-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';
@@ -45,7 +46,7 @@ export function createDevvitPlatformGateway(input) {
         }
         return response.data;
     }
-    const commerceV2 = input.commerce === undefined
+    const commerce = input.commerce === undefined
         ? undefined
         : createDevvitCommerceProvider({
             ...input.commerce,
@@ -54,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', {}),
@@ -72,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),
@@ -287,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,
@@ -301,6 +308,7 @@ export function createDevvitSandboxBridge() {
                         socialShare: false,
                         haptics: false,
                         localizedContent: true,
+                        commerce: createUnsupportedCommerceCapabilities(),
                     });
                 case 'identity.getPlayer':
                     return ok(input, {
@@ -334,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':
@@ -385,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/web.d.ts

@@ -39,8 +39,8 @@ export interface DevvitOrderResultEventLike {
   readonly errorCode?: number | undefined;
   readonly errorMessage?: string | undefined;
 }
-/** The checkout half of `DevvitPaymentsClient`; the v2 provider needs nothing else. */
-export type DevvitWebPaymentsClient = Pick<DevvitPaymentsClient, 'purchase'>;
+/** 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-devvit",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Reddit Devvit Web platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -55,13 +55,13 @@
   ],
   "dependencies": {
     "@devvit/web": "0.14.1",
-    "@mpgd/game-services": "0.23.0",
-    "@mpgd/bridge": "0.12.3",
-    "@mpgd/platform": "0.22.0"
+    "@mpgd/bridge": "0.13.1",
+    "@mpgd/platform": "0.23.1",
+    "@mpgd/game-services": "0.24.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "ttsc": "0.30.4",
+    "ttsc": "0.32.1",
     "typescript": "7.0.2",
     "vitest": "^4.0.0"
   },