@homie-rocks/studio 0.37.1 → 0.38.0

package/worker/purchase-store.mjs

@@ -0,0 +1,148 @@
+import { hasStripeKey, shopMode } from './shop-links.mjs';
+import { problem } from './purchase-problem.mjs';
+/** Resource purchases share the studio's Stripe webhook and refund office. */
+import { offerVersion } from "./purchase-core.mjs";
+
+import { canonicalJson } from "./referrals.mjs";
+
+import { modeOf } from "./stripe.mjs";
+
+import { digest, manifestHash } from "./purchase-crypto.mjs";
+import { resourceKind } from "./resource-kinds.mjs";
+
+export { PURCHASE_MIGRATION, PURCHASE_MIGRATION_FILE, PURCHASE_STATE, PURCHASE_STATE_FILE } from './purchase-schema.mjs';
+export const json = (body, status = 200) =>
+  status >= 400 ? problem(status, body.message ?? body.detail ?? "Purchase refused", body) : Response.json(body, {
+    status,
+    headers: {
+      "cache-control": "no-store, private",
+      "x-content-type-options": "nosniff",
+    },
+  });
+export const fail = problem;
+const orderQuery = "SELECT o.*, COALESCE(r.manifest,o.manifest) AS manifest FROM purchase_orders o LEFT JOIN resource_snapshots r ON r.hash = o.manifest_hash";
+export const byId = (env, id) => env.DB.prepare(`${orderQuery} WHERE o.id = ?1`).bind(id).first();
+export const byClaim = (env, hash) => env.DB.prepare(`${orderQuery} WHERE o.claim_hash = ?1`).bind(hash).first();
+export const idOf = (v) => (typeof v === "string" ? v : v?.id);
+export const safeId = (v) => /^[a-z0-9][a-z0-9-]{0,47}$/.test(v ?? "");
+export const versionOf = (v) =>
+  /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[A-Za-z0-9.-]{1,40})?$/.test(v ?? "");
+export const validBuyer = (v) => /^[a-f0-9]{64}$/.test(v ?? "");
+export const bearer = (r) =>
+  /^Bearer ([A-Za-z0-9_.-]+)$/.exec(r.headers.get("authorization") ?? "")?.[1];
+export const termsOf = (o) =>
+  o.offer ? JSON.parse(o.offer) : JSON.parse(o.manifest).sale;
+export const purchasedResource = (o) => ({
+  ...JSON.parse(o.manifest),
+  sale: termsOf(o),
+});
+export const active = (o) =>
+  ["paid", "fulfilled", "disputed"].includes(o.status) &&
+  (!o.subscription || Number(o.paid_until) > Date.now());
+
+export async function bodyOf(request) {
+  if (!request.headers.get("content-type")?.startsWith("application/json"))
+    throw new Error("Send JSON");
+  return JSON.parse(await limitedText(request));
+}
+export async function limitedText(request) {
+  const reader = request.body?.getReader();
+  if (!reader) throw new Error("Send JSON");
+  let size = 0;
+  const chunks = [];
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.length;
+    if (size > 16384) {
+      await reader.cancel();
+      throw new Error("Request too large");
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(size);
+  let at = 0;
+  for (const c of chunks) {
+    bytes.set(c, at);
+    at += c.length;
+  }
+  return new TextDecoder().decode(bytes);
+}
+export async function privateRelease(env, kind, id, version) {
+  if (!safeId(id) || !versionOf(version)) return null;
+  return resourceKind(kind).get(env,id,version);
+}
+export async function listedRelease(env, origin, kind, id, version) {
+  if (await env.DB.prepare("SELECT 1 FROM resource_retirements WHERE resource = ?1").bind(`${shopMode(env)}:${kind}:${id}`).first()) return null;
+  const adapter = resourceKind(kind);
+  const listed = (await adapter.list(env,origin)).find((r)=>r.id===id && r.version===version);
+  if (!listed) return null;
+  const resource = await privateRelease(env,kind,id,version);
+  return resource && {resource,offer:listed.offer};
+}
+export async function coveredPurchase(env, origin, order, wanted) {
+  const bought = purchasedResource(order);
+  if (bought.id !== wanted.id) return false;
+  const granted = await env.DB.prepare("SELECT manifest_hash FROM purchase_grants WHERE order_id = ?1 AND version = ?2").bind(order.id,wanted.version).first();
+  if (granted) return granted.manifest_hash === await manifestHash(wanted);
+  return resourceKind(order.resource_kind).covers(env,origin,bought,wanted);
+}
+
+export async function recurringReady(env) {
+  try {
+    const c = JSON.parse(env.PURCHASE_PAYMENT_CAPABILITIES ?? "{}");
+    return (
+      c.recurring === true &&
+      c.mode === shopMode(env) &&
+      c.key === (await digest(env.STRIPE_KEY))
+    );
+  } catch {
+    return false;
+  }
+}
+
+export async function deliveryAllowed(env, o) {
+  if (o.mode !== shopMode(env)) return false;
+  return (
+    o.mode === "live" ||
+    (
+      await env.DB.prepare("SELECT value FROM purchase_test_approvals WHERE order_id = ?1")
+        .bind(o.id)
+        .first()
+    )?.value === o.claim_hash
+  );
+}
+
+/** Immutable order creation is shared by machine payments and the human fallback. */
+export async function createPurchase(env, o) {
+  const resource = JSON.parse(o.manifest);
+  const kind = o.resource_kind;
+  const adapter = resourceKind(kind);
+  const offer = await offerVersion({ kind, id: resource.id, release: resource.version, manifest: o.manifest_hash }, JSON.parse(o.offer));
+  const now = Date.now();
+  await env.DB.batch([
+    env.DB.prepare("INSERT OR IGNORE INTO resource_snapshots (hash,manifest) VALUES (?1,?2)").bind(o.manifest_hash,o.manifest),
+    env.DB.prepare("INSERT INTO purchase_orders (id,resource_kind,resource_id,item,game,amount,currency,till,mode,status,created_at,updated_at,claim_hash,buyer,buyer_label,quantity,manifest,manifest_hash,offer_version,transport,accepted_at,terms_hash,quote_hash,offer,checkout_buyer) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,'started',?10,?10,?11,?12,?13,?14,'',?15,?16,?17,?10,?18,?19,?20,?12)").bind(o.id,kind,resource.id,o.item,o.game,o.amount,o.currency,o.till,o.mode,now,o.claim_hash,o.buyer,o.buyer_label,o.quantity,o.manifest_hash,offer.version,o.transport ?? 'checkout',await digest(canonicalJson(adapter.terms({...resource,sale:offer.terms}))),await adapter.quote(resource,o.quantity,o.game,offer.terms),o.offer),
+    env.DB.prepare("INSERT OR IGNORE INTO purchase_offers (version,value) VALUES (?1,?2)").bind(offer.version,JSON.stringify(offer)),
+  ]);
+}
+
+/** Verify deliverability before either payment adapter can create a charge. */
+export async function resourceAvailable(env, kind, resource) {
+  const adapter = resourceKind(kind);
+  for (const file of resource.files ?? []) {
+    const object = await adapter.readFile(env,file,{head:true});
+    if (!object || object.size !== file.bytes) return false;
+  }
+  return true;
+}
+
+/** Unpaid attempts have no durable entitlement; release their claims after expiry. */
+export async function expireUnpaidMachineOrders(env) {
+  const rows = (await env.DB.prepare(`SELECT id FROM purchase_orders WHERE transport = 'machine' AND status IN ('started','expired') AND created_at <= ?1 AND payment IS NULL AND NOT EXISTS (SELECT 1 FROM purchase_jobs j WHERE j.order_id = purchase_orders.id ) AND NOT EXISTS (SELECT 1 FROM purchase_settlements s WHERE s.order_id = purchase_orders.id) LIMIT 100`).bind(Date.now()-300000).all()).results ?? [];
+  for (const row of rows) await env.DB.batch([
+    env.DB.prepare("DELETE FROM purchase_jobs WHERE order_id = ?1 AND state = 'failed'").bind(row.id),
+    env.DB.prepare("DELETE FROM purchase_orders WHERE id = ?1 AND payment IS NULL AND status IN ('started','expired')").bind(row.id),
+  ]);
+  return rows.length;
+}

package/worker/purchases.mjs

@@ -0,0 +1,6 @@
+/** Public integration points for the shop, file router and studio tools. */
+export * from "./purchase-store.mjs";
+export * from "./purchase-reconciliation.mjs";
+export * from "./purchase-owner.mjs";
+export * from "./purchase-delivery.mjs";
+export * from "./purchase-routes.mjs";

package/worker/resource-kinds.mjs

@@ -0,0 +1,20 @@
+/** Application composition. New resource kinds implement this interface, not payment routes. */
+import { partResource } from './parts-resource.mjs';
+const kinds = new Map();
+export function registerResourceKind(kind, adapter) {
+  if (!/^[a-z][a-z0-9-]{0,47}$/.test(kind) || kinds.has(kind)) throw new Error('Invalid or duplicate resource kind');
+  for (const method of ['list','get','quote','terms','validate','termsUrl','readFile','covers']) if (typeof adapter[method] !== 'function') throw new Error(`Resource adapter needs ${method}`);
+  kinds.set(kind,Object.freeze({...adapter}));
+}
+export function resourceKind(kind) {
+  const adapter = kinds.get(kind);
+  if (!adapter) throw new Error(`Unknown resource kind: ${kind}`);
+  return adapter;
+}
+export const hasResourceKind = (kind) => kinds.has(kind);
+export async function listOffers(env,origin) {
+  const offers=[];
+  for (const [kind,adapter] of kinds) for (const offer of await adapter.list(env,origin)) offers.push({...offer,kind});
+  return offers;
+}
+registerResourceKind('part',partResource);

package/worker/selling/index.mjs

@@ -0,0 +1,8 @@
+/** The SDK graph is evaluated only when this selling Worker handles work. */
+export * from '../index.mjs';
+let loaded;
+export const loadSelling = () => loaded ??= import('./runtime.mjs');
+export default {
+  async fetch(request, env, ctx) { return (await loadSelling()).default.fetch(request, env, ctx); },
+  async scheduled(event, env, ctx) { return (await loadSelling()).default.scheduled(event, env, ctx); },
+};

package/worker/selling/runtime.mjs

@@ -0,0 +1,42 @@
+import { productDescription, entryDescription, discoveryRoutes } from '../parts-purchase-catalogue.mjs';
+import { officeScript } from '../purchase-office-script.mjs';
+import { officeRoutes } from '../purchase-office-routes.mjs';
+import { refundOrder, extendOffice } from '../purchase-office.mjs';
+import worker from '../index.mjs';
+export * from '../index.mjs';
+import { useSelling } from '../extensions.mjs';
+import { jobsSQL } from '../payment-policy.mjs';
+import { manualRefundDetails } from '../payment-manual-refund.mjs';
+import { confirmManualRefund } from '../payment-manual-refund.mjs';
+import { listOffers } from '../resource-kinds.mjs';
+import { orderFact } from '../purchase-core.mjs';
+import { byId as resourceOrder } from '../purchase-store.mjs';
+import { currentPurchaseOrder } from '../purchases.mjs';
+import { purchasePaymentEvent } from '../purchases.mjs';
+import { refundPurchasePayment } from '../purchases.mjs';
+import { purchaseReadiness } from '../purchases.mjs';
+import { purchaseRoutes } from '../purchase-routes.mjs';
+import { recordOrderState } from '../purchase-core.mjs';
+import { authorizePurchaseTest } from '../purchases.mjs';
+import { expirePurchaseCheckouts } from '../purchases.mjs';
+import { reissuePurchaseClaim } from '../purchases.mjs';
+import { retireResource } from '../purchases.mjs';
+import { reconcileRecordings } from '../payment-recovery.mjs';
+import { machineCapabilities } from '../payment-capabilities.mjs';
+import { paidFile } from '../parts-protected.mjs';
+import { priceWords } from '../purchase-pricing.mjs';
+import { purchaseDiscovery } from '../purchase-discovery.mjs';
+import { testPaymentExchange } from '../payment-test-exchange.mjs';
+useSelling({ enabled: true, productDescription, entryDescription, discoveryRoutes, officeScript, officeRoutes, refundOrder, extendOffice, testPaymentExchange, jobsSQL, manualRefundDetails, confirmManualRefund, listOffers, orderFact, resourceOrder, currentPurchaseOrder, purchasePaymentEvent, refundPurchasePayment, purchaseReadiness, purchaseRoutes, recordOrderState, authorizePurchaseTest, expirePurchaseCheckouts, reissuePurchaseClaim, retireResource, reconcileRecordings, machineCapabilities, paidFile, priceWords, purchaseDiscovery });
+export default { ...worker,
+  async scheduled(controller, env, ctx) {
+    await worker.scheduled(controller, env, ctx);
+    if (!env.PURCHASE_MACHINE_PAYMENTS || !env.DB) return;
+    const { refreshMachineCapabilities } = await import('../payment-capabilities.mjs');
+    const errors = [];
+    for (const step of [reconcileRecordings, refreshMachineCapabilities, expirePurchaseCheckouts]) {
+      try { await step(env); } catch (error) { errors.push(error); }
+    }
+    if (errors.length) throw new AggregateError(errors, 'Selling maintenance needs retry');
+  },
+};

package/worker/settlement-journal.mjs

@@ -0,0 +1,138 @@
+import { REPLAY_LIMIT_MS } from './payment-policy.mjs';
+/** Write-ahead settlement journal. Only protocol-validated operations enter this module. */
+import { digest } from "./purchase-crypto.mjs";
+
+import { modeOf } from './stripe.mjs';
+
+export { SETTLEMENT_SCHEMA } from './purchase-schema.mjs';
+
+export async function beginSettlement(env, order, network, payload) {
+  const { fromBlock: cursor, ...identity } = payload;
+  const id = await digest(JSON.stringify({ order: order.id, network, payload: identity }));
+  await env.DB.prepare("INSERT OR IGNORE INTO purchase_settlements (id,order_id,mode,network,payload,state,created_at,updated_at) VALUES (?1,?2,?3,?4,?5,'settling',?6,?6)")
+    .bind(id, order.id, order.mode, network, JSON.stringify({ ...payload, challengeId: order.challengeId }), Date.now()).run();
+  return id;
+}
+export async function finishSettlement(env, id, reference) {
+  if (!/^0x[0-9a-fA-F]{64}$/.test(reference)) throw new Error('Invalid settlement reference');
+  await env.DB.prepare("UPDATE purchase_settlements SET reference = ?2, state = 'settled', error = NULL, updated_at = ?3 WHERE id = ?1 AND state != 'complete'")
+    .bind(id, reference, Date.now()).run();
+}
+
+export function journalFacilitator(env, order, facilitator, rpc) {
+  return {
+    verify: (...args) => facilitator.verify(...args),
+    async settle(payload, requirements) {
+      // Capture the scan cursor before submitting; the authorization nonce identifies
+      // the transfer even if the facilitator's response disappears with this isolate.
+      const fromBlock = await rpc('eth_blockNumber', []);
+      const id = await beginSettlement(env, order, 'base', { payload, requirements, fromBlock });
+      const result = await facilitator.settle(payload, requirements);
+      if (result.success) await finishSettlement(env, id, result.transaction);
+      return result;
+    },
+  };
+}
+
+export function rpcFor(env, network, mode = modeOf(env.STRIPE_KEY)) {
+  const config = JSON.parse(env.PURCHASE_MACHINE_PAYMENTS ?? '{}')[mode] ?? {};
+  const url = config.rpc?.[network] ?? (network === 'base'
+    ? mode === 'live' ? 'https://mainnet.base.org' : 'https://sepolia.base.org'
+    : mode === 'live' ? 'https://rpc.tempo.xyz' : 'https://rpc.moderato.tempo.xyz');
+  return async (method, params) => {
+    const response = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }) });
+    const body = await response.json();
+    if (!response.ok || body.error) throw new Error(body.error?.message ?? `Chain RPC answered ${response.status}`);
+    return body.result;
+  };
+}
+
+/** The final, canonical signed transaction is durable before an RPC may broadcast it. */
+export async function journalTempoClient(env, order, chainId) {
+  const { createClient, custom, keccak256 } = await import('viem');
+  const { tempo, tempoModerato } = await import('viem/tempo/chains');
+  const rpc = rpcFor(env, 'tempo', order.mode);
+  return createClient({ chain: (chainId ?? (order.mode === 'live' ? tempo.id : tempoModerato.id)) === tempo.id ? tempo : tempoModerato, transport: custom({
+    async request({ method, params }) {
+      if (!['eth_sendRawTransaction', 'eth_sendRawTransactionSync'].includes(method)) return rpc(method, params);
+      const raw = params[0];
+      const reference = keccak256(raw);
+      const id = await beginSettlement(env, order, 'tempo', { raw, reference });
+      const result = await rpc(method, params);
+      await finishSettlement(env, id, reference);
+      return result;
+    },
+  }) });
+}
+
+/** Recover a fact from chain evidence, never from an unverified client receipt. */
+export async function findSettlement(env, job, { rpc = rpcFor(env, job.network, job.mode) } = {}) {
+  const payload = JSON.parse(job.payload);
+  let reference = job.reference ?? payload.reference;
+  if (!reference && job.network === 'base') {
+    const { keccak256, toHex } = await import('viem');
+    const auth = payload.payload.payload.authorization;
+    const topic = keccak256(toHex('AuthorizationUsed(address,bytes32)'));
+    const latest = BigInt(await rpc('eth_blockNumber', []));
+    const from = BigInt(payload.fromBlock);
+    const to = from + 1999n < latest ? from + 1999n : latest;
+    const logs = await rpc('eth_getLogs', [{ address: payload.requirements.asset, fromBlock: payload.fromBlock, toBlock: `0x${to.toString(16)}`, topics: [topic, `0x${auth.from.slice(2).padStart(64, '0')}`, auth.nonce] }]);
+    reference = logs[0]?.transactionHash;
+    if (!reference && to < latest) {
+      await env.DB.prepare('UPDATE purchase_settlements SET payload = ?2 WHERE id = ?1').bind(job.id, JSON.stringify({ ...payload, fromBlock: `0x${(to+1n).toString(16)}` })).run();
+      return { scanning: true };
+    }
+  }
+  if (!reference) return null;
+  const receipt = await rpc('eth_getTransactionReceipt', [reference]);
+  if (!receipt) return null;
+  if (receipt.status === '0x0') return { unpaid: true, reason: 'The settlement transaction reverted.' };
+  if (receipt.status !== '0x1') return null;
+  if (job.network === 'base') {
+    const { keccak256, toHex } = await import('viem');
+    const auth = payload.payload.payload.authorization;
+    const transfer = keccak256(toHex('Transfer(address,address,uint256)'));
+    const found = receipt.logs?.some((log) => log.address.toLowerCase() === payload.requirements.asset.toLowerCase() && log.topics[0] === transfer && log.topics[1]?.slice(-40).toLowerCase() === auth.from.slice(2).toLowerCase() && log.topics[2]?.slice(-40).toLowerCase() === auth.to.slice(2).toLowerCase() && BigInt(log.data) === BigInt(auth.value));
+    if (!found) throw new Error('Settlement receipt does not contain the accepted transfer');
+  }
+  // Tempo raw bytes are persisted only after mppx validates recipient, amount,
+  // token and challenge binding; a successful receipt proves those exact calls ran.
+  return reference;
+}
+
+/** Replaying the same authorization/raw transaction cannot transfer twice on chain. */
+export async function resumeSettlement(env, job, dependencies = {}) {
+  const rpc = dependencies.rpc ?? rpcFor(env, job.network, job.mode);
+  const found = await findSettlement(env, job, { rpc });
+  if (found?.scanning) return null;
+  if (found) return found;
+  const payload = JSON.parse(job.payload);
+  if (job.network === 'base') {
+    const finalBlock = await rpc('eth_getBlockByNumber', ['finalized', false]);
+    if (finalBlock?.timestamp && BigInt(finalBlock.timestamp) > BigInt(payload.payload.payload.authorization.validBefore))
+      return { unpaid: true, reason: 'The authorization expired without a transfer on the finalized chain.' };
+  }
+  if (Date.now() - job.created_at >= REPLAY_LIMIT_MS) return { manual: true, reason: 'Settlement deadline reached. Check the recorded transaction and payer before another payment; automatic broadcasting has stopped.' };
+  if (job.network === 'tempo') {
+    try { await rpc('eth_sendRawTransaction', [payload.raw]); }
+    catch { /* It may already be mined; the chain receipt decides. */ }
+  } else if (BigInt(payload.payload.payload.authorization.validBefore) > BigInt(Math.floor(Date.now() / 1000))) {
+    let facilitator = dependencies.facilitator;
+    if (!facilitator) {
+      const { HTTPFacilitatorClient } = await import('@x402/core/server');
+      const { createFacilitatorConfig } = await import('@coinbase/x402');
+      facilitator = new HTTPFacilitatorClient(job.mode === 'live' ? createFacilitatorConfig(env.CDP_API_KEY_ID, env.CDP_API_KEY_SECRET) : { url: 'https://x402.org/facilitator' });
+    }
+    const result = await facilitator.settle(payload.payload, payload.requirements);
+    if (result.success) return result.transaction;
+  }
+  const recovered = await findSettlement(env, job, { rpc });
+  if (recovered?.scanning) return null;
+  if (recovered) return recovered;
+  if (job.network === 'base') {
+    const finalBlock = await rpc('eth_getBlockByNumber', ['finalized', false]);
+    if (finalBlock?.timestamp && BigInt(finalBlock.timestamp) > BigInt(payload.payload.payload.authorization.validBefore))
+      return { unpaid: true, reason: 'The authorization expired without a transfer on the finalized chain.' };
+  }
+  return null;
+}

package/worker/shop-page.mjs

@@ -1,3 +1,4 @@
+import { selling } from './extensions.mjs';
 /**
  * The shop's pages (@homie-rocks/studio 0.24.0; worker/shop.mjs has the rules):
  *
@@ -527,14 +528,15 @@ export const OFFICE_SHOP_SCRIPT = String.raw`(function () {
       links.appendChild(link('/_studio/api/shop/orders.csv', 'CSV for your accountant'));
       top.appendChild(links);
       if (s.keyless) top.appendChild(el('p', { class: 'note' }, 'Refund in Stripe or ask your AI connected to Stripe. If a payment is missing here, ask your AI to resend its Stripe webhook.'));
-      if (s.totals) top.appendChild(el('p', { class: 'dim' }, 'Last 30 days: ' + s.totals.sales + ' sales, ' + cents(s.totals.paid, s.totals.currency) + ' before tax and fees; ' + s.totals.refunds + ' refunded (' + cents(s.totals.refunded, s.totals.currency) + '); ' + s.totals.disputes + ' disputed now, ' + s.totals.lost + ' lost.'));
+      for (const total of s.totalsByCurrency ?? (s.totals ? [s.totals] : [])) top.appendChild(el('p', { class: 'dim' }, 'Orders in the last 30 days: ' + total.sales + ' paid orders, ' + cents(total.paid, total.currency) + ' before tax and fees (subscription renewals are in Stripe); ' + total.refunds + ' refunded (' + cents(total.refunded, total.currency) + '); ' + total.disputes + ' disputed now, ' + total.lost + ' lost.'));
+      /* purchase-office */
       var ord = $('#orders'); ord.textContent = '';
       if (!s.orders.length) ord.appendChild(el('p', { class: 'empty' }, 'No orders yet.'));
       s.orders.forEach(function (o) {
         var row = el('div', { class: 'row' });
         row.appendChild(el('span', null, new Date(o.createdAt).toISOString().slice(0, 16).replace('T', ' ')));
         row.appendChild(el('b', null, o.name + ' · ' + o.shown));
-        row.appendChild(el('span', null, (o.player && o.player.name ? o.player.name : 'a deleted account') + (o.parent ? ' (a parent paid)' : '') + (o.via ? ' · sent by ' + o.via : '')));
+        row.appendChild(el('span', null, (o.player && o.player.name ? o.player.name : o.resourceKind ? 'a studio purchase' : 'a deleted account') + (o.parent ? ' (a parent paid)' : '') + (o.via ? ' · sent by ' + o.via : '')));
         row.appendChild(el('span', { class: 'st st-' + o.status }, o.status + (o.mode === 'test' ? ' · test' : '') + (o.note ? ' · ' + o.note : '')));
         if (o.stripe) row.appendChild(link(o.stripe, 'In Stripe'));
         if (o.dispute) row.appendChild(link(o.dispute, 'The dispute'));
@@ -644,8 +646,9 @@ let officeHash = null;
 /** /_studio/office/shop: the owner's shop. One inline script, allowed by its hash; connect only to this site. */
 export async function officeShopPage(cat) {
   const name = cat.studio?.name ?? 'Studio';
+  const script = OFFICE_SHOP_SCRIPT.replace('/* purchase-office */', selling.officeScript ?? '');
   if (!officeHash) {
-    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(OFFICE_SHOP_SCRIPT));
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(script));
     officeHash = `sha256-${btoa(String.fromCharCode(...new Uint8Array(digest)))}`;
   }
   const body = `<header class="top"><h1>${esc(name)} <small>Shop</small></h1><div class="links"><a href="/_studio/office">Office</a><a href="/_studio/stats">Stats</a></div></header>
@@ -655,7 +658,7 @@ export async function officeShopPage(cat) {
 <div class="game" style="padding:6px 16px 12px" id="referrals"></div>
 <div class="toast" id="toast" role="status" hidden></div>
 <p class="note">You are the seller. Money goes from players to your own Stripe account; Homie never sees it and takes nothing. Refunds are handled in Stripe or by your connected AI; shops with the fuller checkout connection also offer Refund here. A card dispute never touches the player's account: answer it in Stripe; if you lose it, that one item is taken back. Tax: when enabled, Stripe Tax works out and collects tax where you told Stripe you are registered${cat.shop?.till === 'stripe-managed' ? '; with Managed Payments Stripe is the seller of record and files it for you' : ''}. Payouts, the balance and receipts are Stripe's own pages, linked above. Referrals: you pay referrers yourself (they invoice you); nothing moves through Homie. This is not legal or tax advice.</p>`;
-  return new Response(shell(cat, `Shop · ${name}`, body, { script: OFFICE_SHOP_SCRIPT }), {
+  return new Response(shell(cat, `Shop · ${name}`, body, { script }), {
     headers: { ...PRIVATE, 'content-security-policy': `default-src 'none'; style-src 'unsafe-inline'; img-src data:; script-src '${officeHash}'; connect-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'` },
   });
 }

package/worker/shop-refunds.mjs

@@ -0,0 +1,22 @@
+import { hasStripeKey, rememberedMoney } from './shop-links.mjs';
+import { stripeCall } from './stripe.mjs';
+/** Stripe refunds, shared by player orders and licensed resources. */
+export async function paymentRefunds(env, payment, o) {
+  const refunds = new Map();
+  let cursor;
+  if (payment && !hasStripeKey(env)) {
+    for (const r of await rememberedMoney(env, payment, o.mode)) if (r.id.startsWith('re_')) {
+      if (r.currency !== o.currency) throw new Error('Refund currency mismatch');
+      refunds.set(r.id, r);
+    }
+  }
+  if (payment && hasStripeKey(env)) do {
+    const page = await stripeCall(env, 'GET', '/v1/refunds', { payment_intent: payment, limit: 100, ...(cursor ? { starting_after: cursor } : {}) });
+    if (!Array.isArray(page.data)) throw new Error('Stripe refund list is unavailable');
+    for (const refund of page.data) refunds.set(refund.id, refund);
+    const next = page.has_more ? page.data.at(-1)?.id : null;
+    if (page.has_more && (!next || next === cursor)) throw new Error('Stripe refund list is incomplete');
+    cursor = next;
+  } while (cursor);
+  return refunds;
+}

package/worker/shop-rules.mjs

@@ -235,7 +235,7 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
   const finalTill = kids ? 'off' : TILLS.includes(till) ? till : 'off';
   if (kids && till !== 'off') warnings.push({ at: 'till', message: 'studio.json says "audience": "kids": the studio sells nothing in its games (the till is off under policy.kidsStudio).' });
   const shop = {
-    v: 1, policy, checkoutMinutes, requestBytes, automaticTax: raw.automaticTax === true, referralNewPlayersOnly: raw.referralNewPlayersOnly === true, guestBuyersPerAddressPerHour, purchaseAttemptsPerMinute, purchaseAttemptsPerAddressPerMinute, till: finalTill, currency: CURRENCY.test(currency) ? currency : 'usd', refundDays, capPerPlayerMonth: cap, items, referrals,
+    v: 1, policy, purchasesTill: TILLS.includes(raw.purchasesTill ?? till) ? (raw.purchasesTill ?? till) : 'off', ...(/^https:\/\/billing\.stripe\.com\/p\/login\/[A-Za-z0-9_]+$/.test(raw.purchasesPortalLogin ?? '') ? { purchasesPortalLogin: raw.purchasesPortalLogin } : {}), checkoutMinutes, requestBytes, automaticTax: raw.automaticTax === true, referralNewPlayersOnly: raw.referralNewPlayersOnly === true, guestBuyersPerAddressPerHour, purchaseAttemptsPerMinute, purchaseAttemptsPerAddressPerMinute, till: finalTill, currency: CURRENCY.test(currency) ? currency : 'usd', refundDays, capPerPlayerMonth: cap, items, referrals,
     open: finalTill !== 'off' && items.length > 0, ...(kids ? { audience: 'kids' } : {}), ...(catalog.length ? { catalog } : {}),
   };
   // https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-custom_text-submit-message

package/worker/shop.mjs

@@ -1,3 +1,5 @@
+import { paymentRefunds } from './shop-refunds.mjs';
+import { selling } from './extensions.mjs';
 /**
  * THE SHOP (@homie-rocks/studio 0.24.0): a studio sells with ITS OWN Stripe account (shop/SHOP.md is the guide).
  * The studio is the seller; homie.rocks never sees, holds or moves its money, and Homie takes no cut.
@@ -215,6 +217,7 @@ export async function shopRoutes(request, env, ctx, url, { catalogueOf }) {
   if (path === '/api/referrals/statement') return receiveStatement(request, env, url);
   if (path === '/_homie/shop.js') return new Response(SHOP_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'public, max-age=300', 'x-content-type-options': 'nosniff' } });
   const shopPath = path === '/shop' || path === '/shop/' || path.startsWith('/shop/') || path === '/api/shop' || path.startsWith('/api/shop/') || path === '/api/player/owns';
+  if (selling.enabled && (path.startsWith('/api/purchases/') || path.startsWith('/purchases/'))) return selling.purchaseRoutes(request, env, url, await catalogueOf());
   if (!shopPath) return null;
   if (path === '/shop') return Response.redirect(`${url.origin}/shop/${url.search}`, 301);
   const cat = await catalogueOf();
@@ -737,6 +740,11 @@ async function hook(request, env, cat, shop, ready) {
   const ev = v.event;
   const obj = ev.data?.object ?? {};
   const needed = ['checkout.session.completed', 'checkout.session.async_payment_succeeded', 'checkout.session.async_payment_failed', 'checkout.session.expired', 'charge.refunded', 'refund.created', 'refund.updated', 'refund.failed', 'charge.dispute.created', 'charge.dispute.closed'];
+  if (selling.enabled) {
+    if (typeof ev.livemode === 'boolean' && ev.livemode !== (shopMode(env) === 'live')) return json({ ok: true, ignored: 'mode' });
+    const purchase = await selling.purchasePaymentEvent(env, ev);
+    if (purchase !== null) { await env.DB.prepare('INSERT INTO shop_events (id, type, at) VALUES (?1, ?2, ?3) ON CONFLICT(id) DO NOTHING').bind(ev.id, ev.type, Date.now()).run(); return json({ ok: true, did: purchase }); }
+  }
   if (!needed.includes(ev.type)) return json({ ok: true, did: 'ignored' });
   if (typeof ev.livemode === 'boolean' && (hasStripeKey(env) || linkConfig(env)) && ev.livemode !== (shopMode(env) === 'live')) return json({ ok: true, ignored: 'mode' });
   try {
@@ -946,22 +954,7 @@ async function syncRefunds(env, payment, freeOrder = null, freeLines = []) {
   const o = freeOrder ?? await orderByPayment(env, payment);
   if (!o) return 'unknown-order';
   const all = await orderLines(env, o.id);
-  const refunds = new Map();
-  let cursor;
-  if (payment && !hasStripeKey(env)) {
-    for (const r of await rememberedMoney(env, payment, o.mode)) if (r.id.startsWith('re_')) {
-      if (r.currency !== o.currency) throw new Error('Refund currency mismatch');
-      refunds.set(r.id, r);
-    }
-  }
-  if (payment && hasStripeKey(env)) do {
-    const page = await stripeCall(env, 'GET', '/v1/refunds', { payment_intent: payment, limit: 100, ...(cursor ? { starting_after: cursor } : {}) });
-    if (!Array.isArray(page.data)) throw new Error('Stripe refund list is unavailable');
-    for (const refund of page.data) refunds.set(refund.id, refund);
-    const next = page.has_more ? page.data.at(-1)?.id : null;
-    if (page.has_more && (!next || next === cursor)) throw new Error('Stripe refund list is incomplete');
-    cursor = next;
-  } while (cursor);
+  const refunds = await paymentRefunds(env, payment, o);
   const totals = new Map(all.map((line) => [line.id, 0]));
   let amount = 0;
   for (const refund of refunds.values()) {
@@ -1051,6 +1044,7 @@ export const REFUND_HELD = 'Stripe is holding this refund until a person approve
 
 /** Refund selected lines through Stripe, revoking each only after success. */
 export async function refundOrder(env, o, { reason = 'requested_by_customer', by = 'owner', line: lineId = null } = {}) {
+  if (o.resource_kind) return selling.refundOrder(env, o, { reason, by });
   if (o.status !== 'paid' && !(o.payment && ['started', 'processing', 'missing', 'released', 'expired', 'failed'].includes(o.status))) return { ok: false, error: 'state', message: `This order is ${o.status}.` };
   const lines = (await orderLines(env, o.id)).filter((l) => !lineId || l.id === lineId);
   if (!lines.length) return { ok: false, error: 'line', message: 'No such order line.' };
@@ -1105,7 +1099,7 @@ export function checkRefund(body) {
   if (!/^ord_[A-Za-z0-9]{20}$/.test(String(body.order ?? ''))) return { ok: false, error: 'bad-request', message: 'order is the order\'s id (ord_…, from the office\'s shop page or `homie-studio shop orders`)' };
   const reason = ['duplicate', 'fraudulent', 'requested_by_customer'].includes(body.reason) ? body.reason : 'requested_by_customer';
   const note = String(body.note ?? '').replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ').trim() || null;
-  return { ok: true, action: { op: 'refund', order: body.order, line: typeof body.line === 'string' ? body.line : null, reason, note } };
+  return { ok: true, action: { op: 'refund', order: body.order, line: typeof body.line === 'string' ? body.line : null, reason, note, ...(body.manualTransaction ? { manualTransaction: body.manualTransaction } : {}) } };
 }
 /** Explicit owner override of an unresolved reservation; the existing note records its actor and time. */
 export function checkRelease(body) {
@@ -1151,7 +1145,8 @@ export function describeRefund(cat, a, order = null) {
 
 /** Do the refund (the owner's tap, or the owner's yes to the AI's ask). */
 export async function performRefund(env, cat, a) {
-  let o = await orderById(env, a.order);
+  let o = await orderById(env, a.order) ?? await purchaseOrderIfPresent(env, a.order);
+  if (o?.resource_kind) return a.manualTransaction ? selling.confirmManualRefund(env, o, a.manualTransaction) : refundOrder(env, o, { reason: a.reason, by: 'owner' });
   if (!o) return { ok: false, error: 'order', message: 'No such order.' };
   if (hasStripeKey(env) && !o.payment && o.session && o.paid_at === null && !(await migrationNeeded(env))) {
     try {
@@ -1199,6 +1194,7 @@ export async function shopOffice(env, cat, origin, cursor = '', itemCursor = 0,
     releasable: hasStripeKey(env) && ['started', 'processing'].includes(r.status),
     refundable: (Number(r.amount) === 0 || hasStripeKey(env)) && ['paid', 'started', 'processing', 'missing', 'released', 'expired', 'failed'].includes(r.status) && (Number(r.amount) === 0 || Boolean(r.payment) || Boolean(r.session)),
   })));
+  if (selling.enabled) await selling.extendOffice(env, cat, origin, out);
   const { books, nextCursor } = await booksOf(env, { cursor });
   out.referrals = { nextCursor, owe: books, failures: await statementFailures(env), owedToUs: await statementsIn(env), invoice: dashboardLink(mode, 'invoices') };
   return out;
@@ -1254,3 +1250,7 @@ export async function roomBadge(env, cat, player, { kids = false } = {}) {
     return shop.items.find((i) => i.id === b.item)?.badge ?? b.key.slice(6);
   } catch { return null; }
 }
+
+export async function purchaseOrderIfPresent(env, id) {
+  try { return await selling.resourceOrder(env, id); } catch (error) { if (/no such table/.test(error.message)) return null; throw error; }
+}

package/worker/stripe.mjs

@@ -63,6 +63,7 @@ export class StripeError extends Error {
     const e = body?.error ?? {};
     super(e.message ? redactStripe(e.message).slice(0, 400) : `Stripe answered ${status}`);
     this.status = status;
+    this.statusCode = status;
     this.code = redactStripe(e.code ?? e.type ?? 'stripe');
     this.type = e.type ? redactStripe(e.type) : null;
     this.param = typeof e.param === 'string' ? redactStripe(e.param).slice(0, 120) : null;
@@ -93,7 +94,7 @@ export async function productIdOf(slug, item) {
 }
 
 /** One call with the studio's key. `idempotencyKey` makes a retried POST do the work once (Stripe keeps it 24 h). */
-export async function stripeCall(env, method, path, params = null, { idempotencyKey = null, fetcher = fetch, timeout = 15_000 } = {}) {
+export async function stripeCall(env, method, path, params = null, { idempotencyKey = null, fetcher = fetch, version = STRIPE_VERSION, timeout = 15_000 } = {}) {
   const key = String(env?.STRIPE_KEY ?? '');
   if (!KEY_SHAPE.test(key)) throw new StripeError(0, { error: { message: 'no Stripe key on this Worker', code: 'no-key' } });
   const body = params && method !== 'GET' ? formEncode(params).toString() : null;
@@ -103,7 +104,7 @@ export async function stripeCall(env, method, path, params = null, { idempotency
     method,
     headers: {
       authorization: `Bearer ${key}`,
-      'stripe-version': STRIPE_VERSION,
+      'stripe-version': version,
       ...(body !== null ? { 'content-type': 'application/x-www-form-urlencoded' } : {}),
       ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}),
     },
@@ -113,7 +114,11 @@ export async function stripeCall(env, method, path, params = null, { idempotency
   } catch (error) { throw new StripeError(502, { error: { message: redactStripe(error?.message ?? 'Stripe did not answer', env), code: 'network' } }); }
   let json = null;
   try { json = await res.json(); } catch { json = null; }
-  if (!res.ok) throw new StripeError(res.status, JSON.parse(redactStripe(JSON.stringify(json), env)));
+  if (!res.ok) {
+    const error = new StripeError(res.status, JSON.parse(redactStripe(JSON.stringify(json), env)));
+    error.idempotentReplayed = res.headers.get('idempotent-replayed') === 'true';
+    throw error;
+  }
   return json;
 }
 
@@ -189,3 +194,31 @@ export function dashboardLink(mode, kind, id = '') {
     default: return base;
   }
 }
+
+/** Stripe is authoritative; DELETE is idempotent even when a prior request already canceled it. */
+export async function cancelSubscription(env, id) {
+  try {
+    const sub = await stripeCall(env, 'GET', `/v1/subscriptions/${encodeURIComponent(id)}`);
+    if (sub.status === 'canceled') return sub;
+    return await stripeCall(env, 'DELETE', `/v1/subscriptions/${encodeURIComponent(id)}`);
+  } catch (error) { if (error.code === 'resource_missing') return { id, status: 'canceled' }; throw error; }
+}
+
+/** Expiration races with completion. Re-read after failure and accept only a terminal session. */
+export async function closeCheckoutSession(env, id) {
+  const session = await retrieveCheckoutSession(env, id);
+  if (session.status !== 'open') return session;
+  try { return await expireCheckoutSession(env, id, { idempotencyKey: `expire-${id}` }); }
+  catch (error) {
+    const current = await retrieveCheckoutSession(env, id);
+    if (['expired', 'complete'].includes(current.status)) return current;
+    throw error;
+  }
+}
+
+export async function refundPayment(env, payment, params = {}) {
+  const pi = await stripeCall(env, 'GET', `/v1/payment_intents/${encodeURIComponent(payment)}`, { expand: ['latest_charge'] });
+  if (pi.latest_charge?.refunded) return { id: null, status: 'succeeded', already: true };
+  try { return await createRefund(env, { payment_intent: payment }, { idempotencyKey: `purchase-refund-${payment}` }); }
+  catch (error) { if (error.code === 'charge_already_refunded') return { id: null, status: 'succeeded', already: true }; throw error; }
+}

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.37.1';
+export const STUDIO_VERSION_TAG = '0.38.0';