@mpgd/cli 0.45.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/cli",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "Gunshi CLI for mpgd-kit starter generation and target workflow orchestration.",
   "license": "MIT",
   "repository": {
@@ -58,9 +58,9 @@
     "undici": "^7.29.1",
     "vite": "8.1.3",
     "yauzl": "3.4.0",
-    "@mpgd/target-config": "0.22.0",
-    "@mpgd/catalog": "0.9.2",
-    "@mpgd/phaser-assets": "0.9.0"
+    "@mpgd/catalog": "0.9.3",
+    "@mpgd/phaser-assets": "0.9.0",
+    "@mpgd/target-config": "0.22.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -68,17 +68,19 @@
     "@types/yauzl": "3.4.0",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "@mpgd/adapter-ait": "0.15.1",
-    "@mpgd/adapter-browser": "0.10.1",
-    "@mpgd/adapter-capacitor": "0.9.1",
-    "@mpgd/adapter-devvit": "0.10.0",
-    "@mpgd/bridge": "0.12.2",
-    "@mpgd/analytics": "0.4.7",
-    "@mpgd/adapter-verse8": "0.5.0",
-    "@mpgd/game-services": "0.21.1",
-    "@mpgd/i18n": "0.6.12",
-    "@mpgd/game-runtime": "0.6.4",
-    "@mpgd/platform": "0.21.0"
+    "@mpgd/adapter-browser": "0.10.2",
+    "@mpgd/adapter-ait": "0.16.0",
+    "@mpgd/adapter-capacitor": "0.9.3",
+    "@mpgd/adapter-devvit": "0.11.0",
+    "@mpgd/adapter-verse8": "0.6.1",
+    "@mpgd/analytics": "0.4.8",
+    "@mpgd/capacitor-play-billing": "0.2.3",
+    "@mpgd/capacitor-storekit": "0.2.3",
+    "@mpgd/game-services": "0.23.0",
+    "@mpgd/bridge": "0.12.3",
+    "@mpgd/game-runtime": "0.6.6",
+    "@mpgd/i18n": "0.6.13",
+    "@mpgd/platform": "0.22.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/templates/phaser-game/apps/target-ait/src/main.ts

@@ -11,6 +11,7 @@ installAitHostBridge({
   appName: runtimeConfig.appName,
   adGroupIds: runtimeConfig.adGroupIds,
   adPlacementTypes: runtimeConfig.adPlacementTypes,
+  ...iapBridgeOptions(),
   ...identityBridgeOptions(),
 });
 
@@ -21,6 +22,22 @@ if (app !== null) {
   });
 }
 
+/**
+ * The IAP products come from the catalog (`platformProductIds.ait`) at build
+ * time, so the wrapper and the game agree on every SKU. The host bridge still
+ * sells nothing until the game supplies its server hooks (`prepareIap`,
+ * `verifyIapProductGrant`, `readIapEntitlements`, see the mpgd-kit
+ * APPS_IN_TOSS_PRODUCTION_EVIDENCE guide): without them every purchase and
+ * every `commerce.v2.*` method fails closed, and the grant callback only ever
+ * confirms through the game backend.
+ */
+function iapBridgeOptions(): Pick<
+  InstallAitHostBridgeOptions,
+  'iapProducts' | 'prepareIap' | 'verifyIapProductGrant' | 'readIapEntitlements'
+> {
+  return runtimeConfig.iapProducts.length === 0 ? {} : { iapProducts: runtimeConfig.iapProducts };
+}
+
 function identityBridgeOptions(): Pick<InstallAitHostBridgeOptions, 'dependencies'> {
   return import.meta.env.VITE_MPGD_AIT_MOCK_IDENTITY === '1'
     ? {

package/templates/phaser-game/apps/target-ait/src/runtime-config.types.ts

@@ -6,6 +6,8 @@ declare module 'virtual:mpgd-ait-runtime-config' {
       string,
       import('@mpgd/adapter-ait/ad-config').AitAdPlacementType
     >>;
+    /** Catalog products sold on Apps in Toss (`platformProductIds.ait`), read at build time. */
+    readonly iapProducts: readonly import('@mpgd/adapter-ait').AitIapProductConfig[];
   }>;
 
   export default runtimeConfig;

package/templates/phaser-game/apps/target-ait/vite.config.ts

@@ -1,11 +1,14 @@
 import { readFileSync } from 'node:fs';
 
+import type { AitIapProductConfig } from '@mpgd/adapter-ait';
 import { extractAitAdBridgeConfig, type AitAdBridgeConfig } from '@mpgd/adapter-ait/ad-config';
+import { extractAitIapProductConfig } from '@mpgd/adapter-ait/iap-config';
 import ttsc from '@ttsc/unplugin/vite';
 import { defineConfig, type Plugin } from 'vite';
 
 const aitAppName = process.env.MPGD_AIT_APP_NAME?.trim() || '__GAME_NAME__';
 const aitAdConfig = readAitAdConfig(process.env.MPGD_AD_PLACEMENTS_FILE);
+const aitIapProducts = readAitIapProducts(process.env.MPGD_PRODUCT_CATALOG_FILE);
 
 export default defineConfig(({ command, isPreview }) => {
   const enableLocalAitMock = command === 'serve'
@@ -29,6 +32,7 @@ export default defineConfig(({ command, isPreview }) => {
         appName: aitAppName,
         adGroupIds: aitAdConfig.adGroupIds,
         adPlacementTypes: aitAdConfig.adPlacementTypes,
+        iapProducts: aitIapProducts,
       }),
       ...(command === 'build'
         ? [ttsc({ project: 'tsconfig.json', plugins: false })]
@@ -46,6 +50,7 @@ function createAitRuntimeConfigPlugin(input: Readonly<{
   readonly appName: string;
   readonly adGroupIds: Readonly<Record<string, string>>;
   readonly adPlacementTypes: AitAdBridgeConfig['adPlacementTypes'];
+  readonly iapProducts: readonly AitIapProductConfig[];
 }>): Plugin {
   const publicId = 'virtual:mpgd-ait-runtime-config';
   const resolvedId = `\0${publicId}`;
@@ -76,3 +81,25 @@ function readAitAdConfig(path: string | undefined): AitAdBridgeConfig {
 
   return extractAitAdBridgeConfig(parsed, path);
 }
+
+/**
+ * The Apps in Toss SKUs come from the product catalog (`platformProductIds.ait`)
+ * so the wrapper and the game share one source; without a configured catalog
+ * file the wrapper sells nothing and the host bridge fails every purchase closed.
+ */
+function readAitIapProducts(path: string | undefined): readonly AitIapProductConfig[] {
+  if (path === undefined || path.trim().length === 0) {
+    return [];
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+  } catch (error) {
+    throw new Error(`AIT product catalog file is unreadable or invalid JSON: ${path}`, {
+      cause: error,
+    });
+  }
+
+  return extractAitIapProductConfig(parsed, { sourceLabel: path });
+}

package/templates/phaser-game/apps/target-devvit/README.md

@@ -113,9 +113,16 @@ deployed-app log inspection. See the official
 register it once in the developer's global Codex configuration:
 
 ```sh
-codex mcp add devvit -- npx -y @devvit/mcp
+codex mcp add devvit -- mise --no-config exec node@22 -- npx -y @devvit/mcp@0.0.27
 ```
 
+The server needs Node 22: `@devvit/mcp` 0.0.27 depends on `better-sqlite3`
+11.9.1, which ships prebuilt binaries for Node 22 but not 24 and does not
+build on 26. `--no-config` keeps mise from passing your mise-managed
+environment to the server. Without mise, register `npx -y @devvit/mcp@0.0.27`
+only if the MCP client's `PATH` resolves `npx` from Node 22. Running
+`codex mcp add devvit` again replaces an older registration.
+
 Restart Codex or begin a new task after registering it. Use `devvit_search`
 before broad Devvit documentation exploration. Use the experimental
 `devvit_logs` tool for a deployed app and subreddit when diagnosing production

package/templates/phaser-game/apps/target-devvit/package.json

@@ -21,7 +21,8 @@
   "dependencies": {
     "@devvit/web": "0.14.1",
     "@mpgd/adapter-devvit": "__MPGD_DEPENDENCY_VERSION_ADAPTER_DEVVIT__",
-    "@mpgd/bridge": "__MPGD_DEPENDENCY_VERSION_BRIDGE__"
+    "@mpgd/bridge": "__MPGD_DEPENDENCY_VERSION_BRIDGE__",
+    "@mpgd/catalog": "__MPGD_DEPENDENCY_VERSION_CATALOG__"
   },
   "devDependencies": {
     "@devvit/start": "0.14.1",

package/templates/phaser-game/apps/target-devvit/src/server/index.ts

@@ -1,20 +1,49 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 
-import { context, createServer, getServerPort, reddit, redis } from '@devvit/web/server';
+import { context, createServer, getServerPort, payments, reddit, redis } from '@devvit/web/server';
 import type { UiResponse } from '@devvit/web/shared';
+import {
+  createDevvitCommerceBridgeProducts,
+  createDevvitCommerceV2BridgeHandler,
+} from '@mpgd/adapter-devvit/server';
 import { createBridgeRpcRouter, defaultBridgeRpcEndpoint } from '@mpgd/bridge/orpc';
 import { createBridgeRpcNodeHandler } from '@mpgd/bridge/orpc/node';
+import type { ProductCatalog } from '@mpgd/catalog';
+import productCatalogJson from '@mpgd/catalog/catalog.json';
 
+import devvitManifest from '../../devvit.json';
 import { createDevvitBridgeHandler } from './bridge.js';
 
 const maxRequestBodySize = 1_048_576;
 const gameName = '__GAME_NAME__';
 const gameTitle = __GAME_TITLE_TS_LITERAL__;
+/**
+ * Commerce v2 opt-in: the catalog's Reddit SKUs (`platformProductIds.reddit`),
+ * the `payments` plugin (`permissions.payments` in devvit.json), and a
+ * fulfillment endpoint (`payments.endpoints.fulfillOrder`, the handler that
+ * writes the backend ledger entry) must all be present. Otherwise the bridge
+ * keeps every `commerce.v2.*` method failing closed with
+ * `COMMERCE_V2_UNAVAILABLE`, so no checkout opens for an order nothing could
+ * grant. The handler only lists orders and products; the grant stays with the
+ * fulfillment handler's ledger entry.
+ */
+const commerceProducts = createDevvitCommerceBridgeProducts(productCatalogJson as ProductCatalog);
+const fulfillOrderEndpoint = (devvitManifest as {
+  readonly payments?: { readonly endpoints?: { readonly fulfillOrder?: unknown } };
+}).payments?.endpoints?.fulfillOrder;
+const commerceEnabled = devvitManifest.permissions.payments === true
+  && typeof fulfillOrderEndpoint === 'string'
+  && fulfillOrderEndpoint.trim().length > 0
+  && commerceProducts.length > 0;
+const commerce = commerceEnabled
+  ? createDevvitCommerceV2BridgeHandler({ payments, products: commerceProducts })
+  : undefined;
 const handleBridgeRequest = createDevvitBridgeHandler({
   redis,
   currentPlayerId,
   currentDisplayName,
   storageKeyNamespace: gameName,
+  ...(commerce === undefined ? {} : { commerce }),
 });
 const bridgeRpcHandler = createBridgeRpcNodeHandler(createBridgeRpcRouter(handleBridgeRequest), {
   maxBodySize: maxRequestBodySize,
@@ -122,6 +151,11 @@ server.on('error', (error) => {
 
 server.listen(port, () => {
   console.log(`devvit server listening on ${port}`);
+  console.log(
+    commerceEnabled
+      ? `devvit commerce v2 serving ${commerceProducts.length} catalog product(s) over the payments plugin`
+      : 'devvit commerce v2 disabled: needs permissions.payments, payments.endpoints.fulfillOrder, and reddit SKUs in the catalog',
+  );
 });
 
 function errorMessage(error: unknown): string {

package/templates/phaser-game/package.json

@@ -66,6 +66,8 @@
     "@mpgd/adapter-verse8": "__MPGD_DEPENDENCY_VERSION_ADAPTER_VERSE8__",
     "@mpgd/analytics": "__MPGD_DEPENDENCY_VERSION_ANALYTICS__",
     "@mpgd/bridge": "__MPGD_DEPENDENCY_VERSION_BRIDGE__",
+    "@mpgd/capacitor-play-billing": "__MPGD_DEPENDENCY_VERSION_CAPACITOR_PLAY_BILLING__",
+    "@mpgd/capacitor-storekit": "__MPGD_DEPENDENCY_VERSION_CAPACITOR_STOREKIT__",
     "@mpgd/catalog": "__MPGD_DEPENDENCY_VERSION_CATALOG__",
     "@mpgd/game-services": "__MPGD_DEPENDENCY_VERSION_GAME_SERVICES__",
     "@mpgd/i18n": "__MPGD_DEPENDENCY_VERSION_I18N__",

package/templates/phaser-game/src/main.ts

@@ -112,7 +112,14 @@ async function bootstrap(options: { readonly monetization?: StarterMonetizationP
     });
     gameRuntime = ownedRuntime;
     const gameServices = ownedRuntime.services;
-    await ownedRuntime.reconcile();
+    try {
+      await ownedRuntime.reconcile();
+    } catch (error) {
+      // A journal the platform storage cannot read must not stop the game:
+      // recovery runs again on resume, and purchases and rewarded ads fail
+      // closed until the journal is readable.
+      console.error('[game-services] startup recovery failed', error);
+    }
 
     await analytics.track({
       name: 'game_started',

package/templates/phaser-game/src/platform/buildGateways/ait.ts

@@ -3,6 +3,15 @@ import type { PlatformGateway } from '@mpgd/platform';
 
 import type { RuntimeConfig } from '../runtimeDetector';
 
+/**
+ * Apps in Toss gateway over the wrapper's host bridge. Commerce lives on the
+ * host side: the wrapper (`apps/target-ait`) installs the IAP products from
+ * the catalog's `platformProductIds.ait` entries and serves the six
+ * `commerce.v2.*` methods plus the `commerceV2` event channel, so the gateway
+ * exposes `commerceV2` whenever the installed bridge has that channel. The
+ * host's grant callback only confirms through the game backend; nothing is
+ * granted from this side.
+ */
 export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
   return createAitPlatformGateway({
     appVersion: runtime.appVersion,

package/templates/phaser-game/src/platform/buildGateways/aitSandbox.ts

@@ -3,6 +3,13 @@ import type { PlatformGateway } from '@mpgd/platform';
 
 import type { RuntimeConfig } from '../runtimeDetector';
 
+/**
+ * Local Apps in Toss playtest. The sandbox bridge keeps its build-id gate: only
+ * the `ait-sandbox` build (`pnpm dev:ait`) gets the `commerceV2` channel and
+ * the evidence-only v2 stub; any other build id gets no channel, so the
+ * gateway offers no `commerceV2` and the v2 methods answer
+ * `COMMERCE_V2_UNAVAILABLE`.
+ */
 export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
   return createAitPlatformGateway({
     appVersion: runtime.appVersion,

package/templates/phaser-game/src/platform/buildGateways/capacitorAndroid.ts

@@ -1,12 +1,61 @@
-import { createCapacitorPlatformGateway } from '@mpgd/adapter-capacitor';
+import {
+  createCapacitorPlatformGateway,
+  type CapacitorServiceProvider,
+} from '@mpgd/adapter-capacitor';
+import {
+  createCapacitorPlayBillingServiceProvider,
+  type PlayBillingCommerceProductMapping,
+} from '@mpgd/capacitor-play-billing';
+import type { ProductCatalog } from '@mpgd/catalog';
+import productCatalogJson from '@mpgd/catalog/catalog.json';
 import type { PlatformGateway } from '@mpgd/platform';
 
+import { resolvePlayBillingAccountBinding } from '../commerceAccountBinding';
+import { resolveStarterStoreProducts } from '../commerceProducts';
 import type { RuntimeConfig } from '../runtimeDetector';
 
+const productCatalog = productCatalogJson as ProductCatalog;
+
+/**
+ * Android gateway with the Google Play Billing commerce v2 service provider
+ * (`@mpgd/capacitor-play-billing`) registered for the catalog products that
+ * name a Play SKU. The provider serves the `commerce.v2.*` and v1 `commerce.*`
+ * bridge methods and never grants: the game-services reconciler verifies each
+ * purchase through the backend ledger. A shell built without the native
+ * plugin (`mpgd target init capacitor --providers play-billing` installs it)
+ * still runs; the store then answers `configuration-required`.
+ */
 export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
-  return createCapacitorPlatformGateway({
+  let gateway: PlatformGateway | undefined;
+  const providers = createStoreProviders(runtime, () => gateway);
+  gateway = createCapacitorPlatformGateway({
     target: 'android',
     appVersion: runtime.appVersion,
     buildId: runtime.buildId,
+    providers,
   });
+  return gateway;
+}
+
+function createStoreProviders(
+  runtime: RuntimeConfig,
+  resolveGateway: () => PlatformGateway | undefined,
+): readonly CapacitorServiceProvider[] {
+  // Play sells one-time products only (RFC D-02); a subscription stays off the store.
+  const products = resolveStarterStoreProducts(productCatalog, runtime.configTarget)
+    .flatMap((product): PlayBillingCommerceProductMapping[] =>
+      product.kind === 'subscription' ? [] : [{ ...product, kind: product.kind }]);
+  if (products.length === 0) {
+    return [];
+  }
+  return [
+    createCapacitorPlayBillingServiceProvider({
+      products,
+      // The backend's resolveObfuscatedAccountId must derive the same value; see commerceAccountBinding.ts.
+      accountBinding: async () => {
+        const gateway = resolveGateway();
+        return gateway === undefined ? undefined : resolvePlayBillingAccountBinding(gateway);
+      },
+    }),
+  ];
 }

package/templates/phaser-game/src/platform/buildGateways/capacitorIos.ts

@@ -1,12 +1,61 @@
-import { createCapacitorPlatformGateway } from '@mpgd/adapter-capacitor';
+import {
+  createCapacitorPlatformGateway,
+  type CapacitorServiceProvider,
+} from '@mpgd/adapter-capacitor';
+import { createCapacitorStoreKitServiceProvider } from '@mpgd/capacitor-storekit';
+import type { ProductCatalog } from '@mpgd/catalog';
+import productCatalogJson from '@mpgd/catalog/catalog.json';
 import type { PlatformGateway } from '@mpgd/platform';
 
+import { resolveStoreKitAppAccountToken } from '../commerceAccountBinding';
+import { resolveStarterStoreProducts } from '../commerceProducts';
 import type { RuntimeConfig } from '../runtimeDetector';
 
+const productCatalog = productCatalogJson as ProductCatalog;
+
+/**
+ * iOS gateway with the StoreKit commerce v2 service provider
+ * (`@mpgd/capacitor-storekit`) registered for the catalog products that name
+ * an App Store product id. The provider serves the `commerce.v2.*` and v1
+ * `commerce.*` bridge methods and never grants or finishes on its own: the
+ * game-services reconciler verifies the signed transaction through the
+ * backend ledger and only then finishes it. A shell built without the native
+ * plugin (`mpgd target init capacitor --providers storekit` installs it)
+ * still runs; the store then answers `configuration-required`.
+ */
 export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
-  return createCapacitorPlatformGateway({
+  let gateway: PlatformGateway | undefined;
+  const providers = createStoreProviders(runtime, () => gateway);
+  gateway = createCapacitorPlatformGateway({
     target: 'ios',
     appVersion: runtime.appVersion,
     buildId: runtime.buildId,
+    providers,
   });
+  return gateway;
+}
+
+function createStoreProviders(
+  runtime: RuntimeConfig,
+  resolveGateway: () => PlatformGateway | undefined,
+): readonly CapacitorServiceProvider[] {
+  // StoreKit sells one-time products only (RFC D-02); a subscription stays off the store.
+  const products = resolveStarterStoreProducts(productCatalog, runtime.configTarget)
+    .filter((product) => product.kind !== 'subscription');
+  if (products.length === 0) {
+    return [];
+  }
+  return [
+    createCapacitorStoreKitServiceProvider({
+      products,
+      // The backend's resolveAppAccountToken must derive the same value; see commerceAccountBinding.ts.
+      getAppAccountToken: async () => {
+        const gateway = resolveGateway();
+        if (gateway === undefined) {
+          throw new Error('The iOS gateway is not ready for a StoreKit purchase.');
+        }
+        return resolveStoreKitAppAccountToken(gateway);
+      },
+    }),
+  ];
 }

package/templates/phaser-game/src/platform/buildGateways/microsoftStore.ts

@@ -1,37 +1,73 @@
 import { createBrowserPlatformGateway } from '@mpgd/adapter-browser';
 import {
-  createMicrosoftStoreCommerceAdapter,
-  withMicrosoftStoreCommerceAdapter,
+  createMicrosoftStoreCommerceProvider,
+  withMicrosoftStoreCommerceProvider,
+  type MicrosoftStoreCommerceProduct,
 } from '@mpgd/adapter-browser/microsoft-store';
+import { resolveProductPlatformId, type ProductCatalog } from '@mpgd/catalog';
+import productCatalogJson from '@mpgd/catalog/catalog.json';
 import type { PlatformGateway } from '@mpgd/platform';
 
 import type { RuntimeConfig } from '../runtimeDetector';
 
+const productCatalog = productCatalogJson as ProductCatalog;
 const browser = createBrowserPlatformGateway();
 const base: PlatformGateway = { ...browser, target: 'microsoft-store' };
-const commerce = createMicrosoftStoreCommerceAdapter({
-  getRecoveryScope: () => 'configuration-required',
-  products: [],
-  authority: {
-    async getAvailability() {
-      return 'configuration-required';
-    },
-    async claimRecoveryOwnership() {
-      return { status: 'denied' } as const;
-    },
-    async hasRecoveryOwnership() {
-      return { status: 'denied' } as const;
-    },
-    async verifyAndGrant() {
-      return { status: 'failed' };
-    },
-    async getEntitlements() {
-      return [];
-    },
-  },
-});
 
-/** Configure Store products, authenticated recovery scope, and authority before checkout. */
-export async function createBuildGateway(_runtime: RuntimeConfig): Promise<PlatformGateway> {
-  return withMicrosoftStoreCommerceAdapter(base, commerce);
+/**
+ * Microsoft Store products from the catalog: the Partner Center add-on
+ * product id is `platformProductIds['microsoft-store']`, and the Digital
+ * Goods API currently sells consumables only. Title, description, and price
+ * are replaced by the Store's own details when the catalog loads.
+ */
+function resolveMicrosoftStoreProducts(target: string): readonly MicrosoftStoreCommerceProduct[] {
+  return productCatalog.products.flatMap((product) => {
+    const inAppOfferToken = resolveProductPlatformId(product, target);
+    return inAppOfferToken === undefined || product.type !== 'consumable'
+      ? []
+      : [
+          {
+            info: {
+              id: product.id,
+              type: product.type,
+              title: product.id,
+              description: '',
+              price: { formatted: '', currencyCode: 'USD' },
+            },
+            inAppOfferToken,
+          },
+        ];
+  });
+}
+
+/**
+ * Commerce v2 over the Digital Goods path (`createMicrosoftStoreCommerceProvider`)
+ * installed as `commerceV2` with the v1 wrapper. The purchase authority stays
+ * `configuration-required` until the game points it at its backend: the
+ * authority's ledger entry is the only settlement, and the reconciler still
+ * verifies it through game-services before anything is granted.
+ */
+export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
+  const commerce = createMicrosoftStoreCommerceProvider({
+    getRecoveryScope: () => 'configuration-required',
+    products: resolveMicrosoftStoreProducts(runtime.configTarget),
+    authority: {
+      async getAvailability() {
+        return 'configuration-required';
+      },
+      async claimRecoveryOwnership() {
+        return { status: 'denied' } as const;
+      },
+      async hasRecoveryOwnership() {
+        return { status: 'denied' } as const;
+      },
+      async verifyAndGrant() {
+        return { status: 'failed' };
+      },
+      async getEntitlements() {
+        return [];
+      },
+    },
+  });
+  return withMicrosoftStoreCommerceProvider(base, commerce);
 }

package/templates/phaser-game/src/platform/buildGateways/reddit.ts

@@ -1,11 +1,46 @@
-import { createDevvitPlatformGateway } from '@mpgd/adapter-devvit';
+import {
+  createDevvitCommerceProducts,
+  createDevvitPlatformGateway,
+  type DevvitGatewayCommerceOptions,
+} from '@mpgd/adapter-devvit';
+import { createDevvitWebPaymentsClient } from '@mpgd/adapter-devvit/web';
+import type { ProductCatalog } from '@mpgd/catalog';
+import productCatalogJson from '@mpgd/catalog/catalog.json';
 import type { PlatformGateway } from '@mpgd/platform';
 
 import type { RuntimeConfig } from '../runtimeDetector';
 
+const productCatalog = productCatalogJson as ProductCatalog;
+
+/**
+ * Reddit gateway with the Devvit commerce v2 provider installed when the
+ * catalog names Reddit SKUs (`platformProductIds.reddit`, the same key the
+ * Devvit server reads, whatever the deployment target is called). The webview
+ * only opens the checkout; the paid-order list comes from the server bridge,
+ * which serves it only after the Devvit server opted in
+ * (`permissions.payments` plus the same catalog SKUs), and the grant comes
+ * from the fulfillment handler's ledger entry. Without SKUs the gateway
+ * offers no `commerceV2` at all.
+ */
 export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
+  const commerce = createCommerceOptions();
   return createDevvitPlatformGateway({
     appVersion: runtime.appVersion,
     buildId: runtime.buildId,
+    ...(commerce === undefined ? {} : { commerce }),
   });
 }
+
+function createCommerceOptions(): DevvitGatewayCommerceOptions | undefined {
+  const products = createDevvitCommerceProducts(productCatalog);
+  if (products.length === 0) {
+    return undefined;
+  }
+  return {
+    products,
+    client: createDevvitWebPaymentsClient(),
+    onCheckoutError: (error) => {
+      console.warn('[devvit] checkout answered without a usable result.', error);
+    },
+  };
+}

package/templates/phaser-game/src/platform/buildGateways/verse8.ts

@@ -1,10 +1,30 @@
-import { createVerse8PlatformGateway } from '@mpgd/adapter-verse8';
-import { resolveAdPlacementPlatformId, type AdPlacements } from '@mpgd/catalog';
+import {
+  createVerse8CommerceProducts,
+  createVerse8PlatformGateway,
+  type Verse8CommerceOptions,
+} from '@mpgd/adapter-verse8';
+import {
+  resolveAdPlacementPlatformId,
+  type AdPlacements,
+  type ProductCatalog,
+} from '@mpgd/catalog';
+import productCatalogJson from '@mpgd/catalog/catalog.json';
 import adPlacementsJson from '@mpgd/catalog/placements.json';
 import type { PlatformGateway } from '@mpgd/platform';
 
 import type { RuntimeConfig } from '../runtimeDetector';
+import { resolveStarterVerse8Agent8Client } from '../verse8Agent8Client';
 
+const productCatalog = productCatalogJson as ProductCatalog;
+
+/**
+ * Verse8 gateway. VXShop and the commerce v2 provider are installed only when
+ * the game provides its authenticated Agent8 client (`verse8Agent8Client.ts`)
+ * and the catalog names VXShop product ids (`platformProductIds.verse8`):
+ * `vxShop.purchases` reads the purchases the Agent8 server recorded, which is
+ * the server-push lookup the reconciler verifies through the backend ledger.
+ * The VXShop dialog callback never grants.
+ */
 export async function createBuildGateway(runtime: RuntimeConfig): Promise<PlatformGateway> {
   const adPlacements = adPlacementsJson as AdPlacements;
   const placementIds = new Map(
@@ -19,10 +39,28 @@ export async function createBuildGateway(runtime: RuntimeConfig): Promise<Platfo
         : [[placement.id, platformPlacementId] as const];
     }),
   );
+  const vxShop = createVxShopOptions(runtime);
 
   return createVerse8PlatformGateway({
     resolveAdPlacementId(placementId) {
       return placementIds.get(placementId);
     },
+    ...(vxShop === undefined ? {} : { vxShop }),
   });
 }
+
+function createVxShopOptions(runtime: RuntimeConfig): Verse8CommerceOptions | undefined {
+  const agent8 = resolveStarterVerse8Agent8Client();
+  const products = createVerse8CommerceProducts(productCatalog, runtime.configTarget);
+  if (agent8 === undefined || products.length === 0) {
+    return undefined;
+  }
+  return {
+    purchaseEventAuthority: 'agent8-server',
+    products,
+    loadEntitlements: async () => (await agent8.getCommerceSnapshot()).entitlements,
+    purchases: {
+      listPurchases: () => agent8.listPurchases(),
+    },
+  };
+}