@mpgd/cli 0.46.1 → 0.47.0

package/templates/phaser-game/src/platform/commerceAccountBinding.ts

@@ -0,0 +1,79 @@
+import type { IdentitySession, PlatformGateway } from '@mpgd/platform';
+import type { StorePurchaseAccountBinding } from '@mpgd/platform/commerce';
+
+/**
+ * Reference account binding of the native store providers. Google Play's
+ * obfuscated account id and StoreKit's app account token must be stable,
+ * non-identifying, and derived the same way by the game backend
+ * (`resolveObfuscatedAccountId` of the Play verifier,
+ * `resolveAppAccountToken` of the App Store verifier), which is how the
+ * backend ties a store purchase to the player before it grants. This module
+ * derives both from a SHA-256 digest of the authenticated player id; a game
+ * with its own account scheme replaces these two functions and the backend
+ * resolvers together. Nothing here grants anything.
+ */
+export const starterAccountBindingDigestPrefix = 'mpgd-commerce-account:';
+
+/**
+ * The authenticated player id a purchase is bound to. Only an
+ * `authenticated` session whose trust is not `local` binds: a guest, a
+ * platform-anonymous session (the native shell's default
+ * `android-local-player` / `ios-local-player`), or a locally asserted id
+ * would give every install the same binding, and the backend binds the
+ * purchase to its own authenticated player id anyway.
+ */
+export async function resolveStarterCommercePlayerId(
+  gateway: Pick<PlatformGateway, 'identity'>,
+): Promise<string | undefined> {
+  let session: IdentitySession | undefined;
+  try {
+    session = await gateway.identity.getSession?.();
+  } catch {
+    return undefined;
+  }
+  if (session?.identityLevel !== 'authenticated' || session.trustLevel === 'local') {
+    return undefined;
+  }
+  const playerId = session.playerId?.trim();
+  return playerId === undefined || playerId.length === 0 ? undefined : playerId;
+}
+
+/** Google Play `obfuscatedAccountId`: 64 hex characters, within Play's 64-character limit. */
+export async function resolvePlayBillingAccountBinding(
+  gateway: Pick<PlatformGateway, 'identity'>,
+): Promise<StorePurchaseAccountBinding | undefined> {
+  const playerId = await resolveStarterCommercePlayerId(gateway);
+  if (playerId === undefined) {
+    return undefined;
+  }
+  return { kind: 'obfuscated-account-id', value: toHex(await digestPlayerId(playerId)) };
+}
+
+/** StoreKit `appAccountToken`: a non-nil UUID derived from the same digest. */
+export async function resolveStoreKitAppAccountToken(
+  gateway: Pick<PlatformGateway, 'identity'>,
+): Promise<string> {
+  const playerId = await resolveStarterCommercePlayerId(gateway);
+  if (playerId === undefined) {
+    throw new Error('A StoreKit purchase requires an authenticated player session.');
+  }
+  return toUuid(await digestPlayerId(playerId));
+}
+
+async function digestPlayerId(playerId: string): Promise<Uint8Array> {
+  const bytes = new TextEncoder().encode(`${starterAccountBindingDigestPrefix}${playerId}`);
+  return new Uint8Array(await crypto.subtle.digest('SHA-256', bytes));
+}
+
+function toHex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/** RFC 4122 layout (version 5 nibble, variant bits) over the first 16 digest bytes. */
+function toUuid(bytes: Uint8Array): string {
+  const uuid = bytes.slice(0, 16);
+  uuid[6] = ((uuid[6] ?? 0) & 0x0f) | 0x50;
+  uuid[8] = ((uuid[8] ?? 0) & 0x3f) | 0x80;
+  const hex = toHex(uuid);
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/templates/phaser-game/src/platform/commerceProducts.ts

@@ -0,0 +1,69 @@
+import {
+  resolveProductPlatformId,
+  type ProductCatalog,
+  type ProductCatalogEntry,
+} from '@mpgd/catalog';
+import type { CommerceReconcilerProduct } from '@mpgd/game-services';
+import type { PurchaseKind } from '@mpgd/platform/commerce';
+
+/**
+ * One catalog product mapped to the store SKU of a target, in the shape the
+ * Capacitor store providers take (`StoreCommerceProductMapping`): the catalog
+ * `platformProductIds[target]` entry is the single source of every SKU.
+ */
+export interface StarterStoreProductMapping {
+  readonly logicalId: ProductCatalogEntry['id'];
+  readonly storeSku: string;
+  readonly kind: PurchaseKind;
+}
+
+/** Commerce v2 purchase kind of a catalog product type. */
+export function purchaseKindOf(type: ProductCatalogEntry['type']): PurchaseKind {
+  switch (type) {
+    case 'consumable':
+      return 'consumable';
+    case 'non_consumable':
+      return 'durable';
+    case 'subscription':
+      return 'subscription';
+    default:
+      throw new TypeError(`Unknown catalog product type: ${String(type)}`);
+  }
+}
+
+/**
+ * The products sold on `target`: every catalog entry that names a platform
+ * product id for it. A product without one is not sold on that target, so a
+ * store provider never offers it.
+ */
+export function resolveStarterStoreProducts(
+  catalog: ProductCatalog,
+  target: string,
+): readonly StarterStoreProductMapping[] {
+  return catalog.products.flatMap((product) => {
+    const storeSku = resolveProductPlatformId(product, target);
+    return storeSku === undefined
+      ? []
+      : [{ logicalId: product.id, storeSku, kind: purchaseKindOf(product.type) }];
+  });
+}
+
+/**
+ * The catalog kinds and SKUs the commerce v2 reconciler resolves without a
+ * store read (`createGameServicesRuntime({ commerceProducts })`). Every
+ * product is listed so a purchase for an unsold product fails on the store
+ * answer, not on a missing kind.
+ */
+export function resolveStarterCommerceProducts(
+  catalog: ProductCatalog,
+  target: string,
+): readonly CommerceReconcilerProduct[] {
+  return catalog.products.map((product) => {
+    const storeSku = resolveProductPlatformId(product, target);
+    return {
+      logicalId: product.id,
+      kind: purchaseKindOf(product.type),
+      ...(storeSku === undefined ? {} : { storeSku }),
+    };
+  });
+}

package/templates/phaser-game/src/platform/gameServices.ts

@@ -1,4 +1,6 @@
 import type { AnalyticsSink } from '@mpgd/analytics';
+import type { ProductCatalog } from '@mpgd/catalog';
+import productCatalogJson from '@mpgd/catalog/catalog.json';
 import {
   createGameServicesRuntime,
   resolveGameServicesAuthorityMode,
@@ -11,7 +13,16 @@ import type { PlatformGateway } from '@mpgd/platform';
 import type { GameActionReconciliationPort } from '@mpgd/game-runtime/actions';
 import type { PurchasePresentationEvent } from '@mpgd/game-runtime/ads';
 
-/** Supply a game-owned durable encrypted journal and trusted recovery/native facts. */
+import { resolveStarterCommerceProducts } from './commerceProducts';
+import { createStorageMonetizationOperationStore } from './monetizationJournal';
+
+const productCatalog = productCatalogJson as ProductCatalog;
+
+/**
+ * Game-owned monetization ports. `operationStore` replaces the reference
+ * journal over platform storage with an encrypted, access-controlled one;
+ * `reconciliation` and `purchasePresentation` supply trusted native facts.
+ */
 export interface StarterMonetizationPorts {
   readonly operationStore: MonetizationOperationStore;
   readonly reconciliation?: GameActionReconciliationPort;
@@ -21,6 +32,13 @@ export interface StarterMonetizationPorts {
 export type StarterBackendMode = GameServicesRuntimeMode;
 export type StarterGameServices = GameServicesRuntime;
 
+/**
+ * Game-services runtime over the commerce v2 reconciler: every purchase is
+ * journaled in a durable `MonetizationOperationStore` (the reference journal
+ * over the platform storage adapter unless the game supplies its own) and
+ * verified through the backend ledger, with the catalog's kinds and SKUs for
+ * the gateway target resolved without a store read.
+ */
 export function createStarterGameServices(input: {
   readonly gateway: PlatformGateway;
   readonly playerId: string;
@@ -32,7 +50,9 @@ export function createStarterGameServices(input: {
   return createGameServicesRuntime({
     gateway: input.gateway,
     playerId: input.playerId,
-    ...(input.operationStore === undefined ? {} : { operationStore: input.operationStore }),
+    operationStore: input.operationStore
+      ?? createStorageMonetizationOperationStore({ storage: input.gateway.storage }),
+    commerceProducts: resolveStarterCommerceProducts(productCatalog, input.configTarget),
     ...(input.analytics === undefined ? {} : { analytics: input.analytics }),
     ...(input.analyticsSessionId === undefined
       ? {}

package/templates/phaser-game/src/platform/monetizationJournal.ts

@@ -0,0 +1,286 @@
+import {
+  isMonetizationOperationGranted,
+  isMonetizationOperationRecoverable,
+  type MonetizationOperationRecord,
+  type MonetizationOperationStore,
+} from '@mpgd/game-services';
+import type { StorageAdapter } from '@mpgd/platform';
+
+/** The storage key the journal document lives under. */
+export const defaultMonetizationJournalKey = 'mpgd:monetization-journal';
+/** Terminal records older than this are dropped on the next write (30 days). */
+export const defaultMonetizationJournalRetentionMs = 30 * 24 * 60 * 60 * 1000;
+/**
+ * At most this many terminal records without a ledger grant and without a
+ * store transaction are kept (the most recently settled): finished rewarded
+ * ads and cancelled or failed attempts the store never answered. Platform
+ * storage bounds one value (the Devvit bridge allows 256 KiB), so the
+ * document must not grow with every one of them. Open records are never
+ * dropped; granted purchases (`granted`, `finishing`, `finished` with a
+ * ledger entry) and purchases that still name a store transaction leave by
+ * age, or by the byte budget (`defaultMonetizationJournalMaxDocumentBytes`)
+ * when the document would not fit, so the revocation pass and
+ * `findByTransaction` keep them for the window whenever storage allows.
+ */
+export const defaultMonetizationJournalMaxTerminalRecords = 100;
+/**
+ * Upper bound of the serialized document (192 KiB, below the Devvit bridge's
+ * 256 KiB per value). When the records in the window would exceed it, the
+ * oldest terminal records leave first: ungranted ones without a store
+ * transaction, then ungranted ones that still name a store transaction, then
+ * granted purchases. Open records are never dropped.
+ */
+export const defaultMonetizationJournalMaxDocumentBytes = 192 * 1024;
+
+export interface CreateStorageMonetizationOperationStoreInput {
+  /** The platform storage adapter (`gateway.storage`); the host owns its durability. */
+  readonly storage: StorageAdapter;
+  /** Defaults to `mpgd:monetization-journal`. */
+  readonly key?: string;
+  /** Defaults to 30 days; `Infinity` keeps every terminal record within the count bound. */
+  readonly retentionMs?: number;
+  /** Defaults to 100 ungranted terminal records; `Infinity` keeps them all within the window. */
+  readonly maxTerminalRecords?: number;
+  /** Defaults to 192 KiB of serialized JSON; see `defaultMonetizationJournalMaxDocumentBytes`. */
+  readonly maxDocumentBytes?: number;
+  readonly now?: () => number;
+  /**
+   * Cross-context lock for the read-modify-write of the document; defaults to
+   * the Web Locks API (`navigator.locks`) when the host has it, so two tabs or
+   * PWA windows over the same storage cannot lose each other's writes. `null`
+   * keeps only the in-context queue.
+   */
+  readonly locks?: JournalLockManager | null;
+}
+
+/** The part of the Web Locks API (`LockManager`) the journal uses. */
+export interface JournalLockManager {
+  request<T>(name: string, callback: (lock: unknown) => Promise<T>): Promise<T>;
+}
+
+interface JournalDocument {
+  readonly version: 1;
+  readonly records: Readonly<Record<string, MonetizationOperationRecord>>;
+}
+
+/**
+ * The reference durable `MonetizationOperationStore` of the starter: one JSON
+ * document in the platform storage adapter, rewritten whole on every change
+ * so a record and its index can never disagree, terminal records bounded by
+ * age (and, without a ledger grant, by count; open records are always kept),
+ * with every operation
+ * serialized through one promise chain so the compare-and-swap of `replace`
+ * holds inside the WebView. It is crash recovery, not grant authority: the
+ * backend ledger still decides every grant. The platform storage is the
+ * host's; a game whose host cannot keep that storage private supplies an
+ * encrypted, access-controlled implementation through
+ * `bootstrapStarter({ monetization: { operationStore } })` instead.
+ *
+ * A document that cannot be parsed fails every call instead of being
+ * replaced: silently starting over would let a purchase be verified twice.
+ */
+export function createStorageMonetizationOperationStore(
+  input: CreateStorageMonetizationOperationStoreInput,
+): MonetizationOperationStore {
+  const key = input.key ?? defaultMonetizationJournalKey;
+  const retentionMs = input.retentionMs ?? defaultMonetizationJournalRetentionMs;
+  const maxTerminalRecords = input.maxTerminalRecords
+    ?? defaultMonetizationJournalMaxTerminalRecords;
+  const maxDocumentBytes = input.maxDocumentBytes ?? defaultMonetizationJournalMaxDocumentBytes;
+  const now = input.now ?? (() => Date.now());
+  const locks = input.locks === undefined ? readHostLockManager() : (input.locks ?? undefined);
+  const lockName = `mpgd-monetization-journal:${key}`;
+  let chain: Promise<unknown> = Promise.resolve();
+
+  const serialize = <T>(operation: () => Promise<T>): Promise<T> => {
+    const run = locks === undefined ? operation : () => locks.request(lockName, () => operation());
+    const next = chain.then(run, run);
+    chain = next.catch(() => undefined);
+    return next;
+  };
+
+  const load = async (): Promise<Map<string, MonetizationOperationRecord>> => {
+    const loaded = await input.storage.load({ key });
+    if (loaded === null || loaded.value === undefined || loaded.value === null) {
+      return new Map();
+    }
+    const document = loaded.value;
+    if (!isJournalDocument(document)) {
+      throw new Error(`Monetization journal at ${key} is unreadable; it was not replaced.`);
+    }
+    return new Map(Object.entries(document.records));
+  };
+
+  const save = async (records: Map<string, MonetizationOperationRecord>): Promise<void> => {
+    const cutoff = now() - retentionMs;
+    const terminal: [string, number][] = [];
+    const kept: Record<string, MonetizationOperationRecord> = {};
+    /** Terminal records the byte budget may drop, with their drop tier (lower leaves first). */
+    const droppable: [string, number, number][] = [];
+    for (const [recordKey, record] of records) {
+      const settledAt = terminalSettledAt(record);
+      if (settledAt === undefined) {
+        kept[recordKey] = record;
+      } else if (settledAt < cutoff) {
+        continue;
+      } else if (isMonetizationOperationGranted(record)) {
+        kept[recordKey] = record;
+        droppable.push([recordKey, settledAt, 2]);
+      } else if (holdsStoreTransaction(record)) {
+        // A rejected or failed purchase the store still lists: the reconciler's
+        // findByTransaction needs it, so the count bound does not drop it.
+        kept[recordKey] = record;
+        droppable.push([recordKey, settledAt, 1]);
+      } else {
+        terminal.push([recordKey, settledAt]);
+      }
+    }
+    // Newest first; the oldest terminal records beyond the bound are dropped.
+    terminal.sort((left, right) => right[1] - left[1]);
+    for (const [recordKey, settledAt] of terminal.slice(0, Math.max(0, maxTerminalRecords))) {
+      const record = records.get(recordKey);
+      if (record !== undefined) {
+        kept[recordKey] = record;
+        droppable.push([recordKey, settledAt, 0]);
+      }
+    }
+    // The document must fit the host's per-value limit, or every later write
+    // fails and monetization stops: the oldest record of the lowest tier leaves
+    // until it fits. Open records are never dropped.
+    droppable.sort((left, right) => left[2] - right[2] || left[1] - right[1]);
+    let size = documentBytes(kept);
+    for (const [recordKey] of droppable) {
+      if (size <= maxDocumentBytes) {
+        break;
+      }
+      delete kept[recordKey];
+      size = documentBytes(kept);
+    }
+    const document: JournalDocument = { version: 1, records: kept };
+    await input.storage.save({ key, value: document });
+  };
+
+  return {
+    reserve(record) {
+      return serialize(async () => {
+        const records = await load();
+        const existing = records.get(record.key);
+        if (existing !== undefined) {
+          return { created: false, record: clone(existing) };
+        }
+        records.set(record.key, clone(record));
+        await save(records);
+        return { created: true, record: clone(record) };
+      });
+    },
+    read(recordKey) {
+      return serialize(async () => {
+        const record = (await load()).get(recordKey);
+        return record === undefined ? undefined : clone(record);
+      });
+    },
+    replace(expectedRevision, record) {
+      return serialize(async () => {
+        const records = await load();
+        const existing = records.get(record.key);
+        if (
+          existing === undefined
+          || existing.revision !== expectedRevision
+          || record.revision !== expectedRevision + 1
+          || existing.playerId !== record.playerId
+          || existing.target !== record.target
+          || existing.deploymentTarget !== record.deploymentTarget
+          || existing.kind !== record.kind
+        ) {
+          throw new Error('Stale or conflicting monetization journal write.');
+        }
+        records.set(record.key, clone(record));
+        await save(records);
+      });
+    },
+    listRecoverable(playerId) {
+      return serialize(async () =>
+        [...(await load()).values()]
+          .filter((record) => record.playerId === playerId
+            && isMonetizationOperationRecoverable(record))
+          .map(clone));
+    },
+    listGranted(playerId) {
+      return serialize(async () =>
+        [...(await load()).values()]
+          .filter((record) => record.playerId === playerId
+            && isMonetizationOperationGranted(record))
+          .map(clone));
+    },
+    findByTransaction(lookup) {
+      return serialize(async () => {
+        const found = [...(await load()).values()].find(
+          (record) =>
+            record.kind === 'commerce-purchase'
+            && record.playerId === lookup.playerId
+            && record.target === lookup.target
+            && record.deploymentTarget === lookup.deploymentTarget
+            && record.store === lookup.store
+            && record.purchase?.transactionId === lookup.transactionId,
+        );
+        return found === undefined ? undefined : clone(found);
+      });
+    },
+  };
+}
+
+/**
+ * When a terminal record settled, or `undefined` for an open record (never
+ * dropped). A terminal record without a readable time sorts as the newest:
+ * only the count bound drops it.
+ */
+function terminalSettledAt(record: MonetizationOperationRecord): number | undefined {
+  if (isMonetizationOperationRecoverable(record)) {
+    return undefined;
+  }
+  const settledAt = record.kind === 'commerce-purchase'
+    ? record.updatedAt
+    : record.platformCompletedAt;
+  const time = settledAt === undefined ? Number.NaN : Date.parse(settledAt);
+  return Number.isFinite(time) ? time : Number.MAX_SAFE_INTEGER;
+}
+
+/** A commerce purchase record that names a store transaction (the store may still list it). */
+function holdsStoreTransaction(record: MonetizationOperationRecord): boolean {
+  return record.kind === 'commerce-purchase' && record.purchase?.transactionId !== undefined;
+}
+
+/** UTF-8 size of the document the records serialize to. */
+function documentBytes(records: Readonly<Record<string, MonetizationOperationRecord>>): number {
+  return new TextEncoder().encode(JSON.stringify({ version: 1, records })).length;
+}
+
+function readHostLockManager(): JournalLockManager | undefined {
+  const candidate = (globalThis as { readonly navigator?: { readonly locks?: unknown } })
+    .navigator?.locks;
+  return typeof candidate === 'object'
+    && candidate !== null
+    && typeof (candidate as { readonly request?: unknown }).request === 'function'
+    ? candidate as JournalLockManager
+    : undefined;
+}
+
+function isJournalDocument(value: unknown): value is JournalDocument {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const document = value as { readonly version?: unknown; readonly records?: unknown };
+  return document.version === 1
+    && typeof document.records === 'object'
+    && document.records !== null
+    && !Array.isArray(document.records)
+    && Object.values(document.records).every(
+      (record) => typeof record === 'object' && record !== null
+        && typeof (record as { readonly key?: unknown }).key === 'string'
+        && typeof (record as { readonly revision?: unknown }).revision === 'number',
+    );
+}
+
+function clone(record: MonetizationOperationRecord): MonetizationOperationRecord {
+  return structuredClone(record);
+}

package/templates/phaser-game/src/platform/verse8Agent8Client.ts

@@ -0,0 +1,23 @@
+import type { Verse8RecordedPurchase } from '@mpgd/adapter-verse8';
+import type { Entitlement } from '@mpgd/platform';
+
+/**
+ * The game-owned Agent8 remote client the Verse8 gateway reads commerce state
+ * through: two authenticated server methods exposed for the sender's own
+ * account (see docs/VERSE8_COMMERCE.md, "Iframe client boundary"). The
+ * starter installs no Agent8 browser SDK, so `resolveStarterVerse8Agent8Client`
+ * answers `undefined` until the game provides one; VXShop then stays off and
+ * the gateway offers no `commerceV2`, exactly as before. The client only
+ * reads: `$onItemPurchased` on the Agent8 server is the sole grant path.
+ */
+export interface StarterVerse8Agent8Client {
+  /** Server-owned balances and entitlements (`getSnapshot` of the Agent8 commerce service). */
+  getCommerceSnapshot(): Promise<{ readonly entitlements: readonly Entitlement[] }>;
+  /** The purchases `$onItemPurchased` recorded (`listPurchases` of the Agent8 commerce service). */
+  listPurchases(): Promise<readonly Verse8RecordedPurchase[]>;
+}
+
+/** Return the game's authenticated Agent8 client here to enable VXShop and commerce v2 on Verse8. */
+export function resolveStarterVerse8Agent8Client(): StarterVerse8Agent8Client | undefined {
+  return undefined;
+}