@homie-rocks/studio 0.37.0 → 0.37.2

package/worker/purchase-mcp.mjs

@@ -0,0 +1,42 @@
+import { purchaseResponse } from './purchase-response.mjs';
+import { machineCapabilities } from './payment-capabilities.mjs';
+/** The SDK owns protocol negotiation, JSON-RPC errors and stateless HTTP transport. */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { machineResource } from './purchase-machine.mjs';
+export const purchaseSchema = {
+  type: 'object', required: ['kind', 'resource', 'version', 'buyer', 'claim', 'offerVersion'],
+  properties: {
+    kind: { type: 'string' }, resource: { type: 'string' }, version: { type: 'string' },
+    buyer: { type: 'string', pattern: '^[a-f0-9]{64}$', description: 'A random private buyer identifier.' },
+    claim: { type: 'string', pattern: '^[a-f0-9]{64}$', description: 'A new private random 32-byte hex secret for this purchase. Keep it to retrieve this order.' },
+    offerVersion: { type: 'string', description: 'The published immutable offer version.' },
+    quantity: { type: 'integer', minimum: 1, default: 1 }, game: { type: 'string' },
+  },
+};
+export async function purchaseMcp(request, env, url, cat) {
+  let delivery;
+  const capability = await machineCapabilities(env);
+  const methods = Object.fromEntries([...(capability.machine.card ? ['stripe'] : []), ...(capability.machine.tempo ? ['tempo'] : [])].map((method) => [method, { intents: ['charge'] }]));
+  const server = new Server({ name: 'Studio purchases', version: '1' }, {
+    capabilities: { tools: {}, experimental: { payment: { methods } } },
+  });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [{
+    name: 'purchase', description: 'Pay for the published offer and receive files, receipt and proof. Unpaid challenges expire after five minutes.', inputSchema: purchaseSchema,
+  }] }));
+  server.setRequestHandler(CallToolRequestSchema, async (input, extra) => {
+    if (input.params.name !== 'purchase') return { isError: true, content: [{ type: 'text', text: 'Unknown tool' }] };
+    const result = await machineResource(new Request(request.url, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input.params.arguments) }), env, url, cat, {
+      mcpInput: input.params.arguments, setDelivery: (data) => { delivery = data; }, extra: { ...extra, _meta: input.params._meta },
+    });
+    if (result instanceof Response) return { isError: true, content: [{ type: 'text', text: await result.text() }] };
+    return result;
+  });
+  const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+  await server.connect(transport);
+  const response = await transport.handleRequest(request);
+  if (!delivery) return response;
+  const envelope = await response.json();
+  return purchaseResponse(delivery, env, { mcp: true, envelope });
+}

package/worker/purchase-office-routes.mjs

@@ -0,0 +1,17 @@
+import { selling } from './extensions.mjs';
+const json = (v,status=200) => Response.json(v,{status});
+export async function officeRoutes(request, env, path, body) {
+  if (path === '/_studio/api/shop/readiness' && request.method === 'POST') return json(await selling.testPaymentExchange(env));
+  if (['/_studio/api/shop/retire', '/_studio/api/shop/reissue', '/_studio/api/shop/test-access', '/_studio/api/shop/sync-offers', '/_studio/api/shop/reconcile-payments'].includes(path) && request.method === 'POST') {
+    try { if (path.endsWith('/reconcile-payments')) { return json({ ok: true, ...await selling.reconcileRecordings(env, body.order ?? null, { payment: body.payment ?? null, cancel: body.cancel === true }) }); }
+      if (path.endsWith('/test-access')) return json(await selling.authorizePurchaseTest(env, body.order));
+      if (path.endsWith('/sync-offers')) return json(await selling.expirePurchaseCheckouts(env));
+      return json(path.endsWith('/retire') ? await selling.retireResource(env, body.kind, body.resource) : await selling.reissuePurchaseClaim(env, body)); }
+    catch (error) {
+      if (error.status === 403 || error.status === 401) return json({ ok: false, message: 'Reconnect the shop with Checkout Sessions and Subscriptions Write permissions, then retry. New sales remain closed if retirement began.' }, 503);
+      if (/no such table/.test(error.message)) return json({ ok: false, message: 'Deploy the purchase migrations first' }, 503);
+      throw error;
+    }
+  }
+  return null;
+}

package/worker/purchase-office-script.mjs

@@ -0,0 +1,38 @@
+export const officeScript = String.raw`      if (s.purchases) {
+        top.appendChild(el('h3', null, 'Machine payment readiness'));
+        (s.purchases.missing || []).forEach(function (reason) { top.appendChild(el('p', null, reason)); });
+        var exchange = s.purchases.exchange;
+        if (exchange) top.appendChild(el('p', null, exchange.verified ? exchange.scope : exchange.reason));
+      }
+      var recoveries = (s.settlementRecovery || []).concat(s.paymentRecovery || []);
+      if (recoveries.length) {
+        top.appendChild(el('h3', null, 'Payment recovery'));
+        recoveries.forEach(function (job) {
+          top.appendChild(el('p', null, job.order_id + ' · ' + (job.network || 'Stripe') + ' · ' + job.state + (job.request_key ? ' · request ' + job.request_key : '') + (job.payment ? ' · payment ' + job.payment : '') + (job.started_at ? ' · since ' + new Date(job.started_at).toISOString() : '') + (job.error ? ' · ' + job.error : '')));
+          if (job.request_key && job.payment) {
+            var cancel = el('button', { type: 'button' }, 'Cancel if unpaid');
+            cancel.addEventListener('click', function () {
+              if (!confirm('Read this payment from Stripe and cancel it only if it has not succeeded? A paid order stays paid and can be refunded separately.')) return;
+              cancel.disabled = true;
+              api('POST', '/_studio/api/shop/reconcile-payments', { order: job.order_id, cancel: true }).then(function (result) { if (!result.ok) throw new Error(result.message || 'Reconciliation failed'); load(); }).catch(function (error) { cancel.disabled = false; toast(error.message); });
+            });
+            top.appendChild(cancel);
+          }
+          if (job.request_key && !job.payment) {
+            var payment = el('input', { placeholder: 'Existing Stripe PaymentIntent id', 'aria-label': 'Existing Stripe PaymentIntent id' });
+            var read = el('button', { type: 'button' }, 'Read this payment');
+            read.addEventListener('click', function () {
+              read.disabled = true;
+              api('POST', '/_studio/api/shop/reconcile-payments', { order: job.order_id, payment: payment.value.trim() }).then(function (result) { if (!result.ok) throw new Error(result.message || 'Read failed'); load(); }).catch(function (error) { read.disabled = false; toast(error.message); });
+            });
+            top.appendChild(payment); top.appendChild(read);
+          }
+        });
+        var reconcile = el('button', { type: 'button' }, 'Reconcile payments now');
+        reconcile.addEventListener('click', function () {
+          reconcile.disabled = true;
+          api('POST', '/_studio/api/shop/reconcile-payments', {}).then(function (result) { if (!result.ok) throw new Error(result.message || 'Reconciliation failed'); load(); }).catch(function (error) { reconcile.disabled = false; toast(error.message); });
+        });
+        top.appendChild(reconcile);
+      }
+`;

package/worker/purchase-office.mjs

@@ -0,0 +1,35 @@
+/** Optional resource rows in the existing shop office. */
+import { hasStripeKey, shopMode } from './shop-links.mjs';
+import { dashboardLink, refundPayment, cancelSubscription, redactStripe } from './stripe.mjs';
+import { currentPurchaseOrder, purchaseReadiness } from './purchase-owner.mjs';
+import { reconcileOrder } from './purchase-reconciliation.mjs';
+import { termsOf, byId } from './purchase-store.mjs';
+import { manualRefundDetails } from './payment-manual-refund.mjs';
+import { jobsSQL } from './payment-policy.mjs';
+import { money } from './shop-rules.mjs';
+export async function refundOrder(env, order, { reason = 'requested_by_customer', by = 'owner' } = {}) {
+  if (order.mode !== shopMode(env)) return { ok: false, error: 'mode', message: 'Reconnect the payment mode of this order.' };
+  if (!hasStripeKey(env)) return { ok: false, error: 'stripe-dashboard', message: 'Refund in Stripe or ask your connected AI. Its signed refund event updates this purchase.', url: dashboardLink(order.mode, 'payment', order.payment) };
+  let o;
+  try { o = await currentPurchaseOrder(env, order.id) ?? order; } catch (error) { return {ok:false,error:'stripe-retry',message:redactStripe(error.message,env)}; }
+  if (o.status === 'refunded') return { ok: true, order: o.id, status: 'succeeded', already: true };
+  if (!['paid','fulfilled'].includes(o.status)) return { ok: false, error: 'state', message: `This order is ${o.status}.` };
+  if (!o.payment) { const manual = await manualRefundDetails(env, o); return { ok: false, error: manual ? 'manual-refund-required' : 'no-payment', ...manual }; }
+  try {
+    const refund = await refundPayment(env, o.payment, { reason, metadata: { order: o.id, by } });
+    await reconcileOrder(env, o);
+    if (refund.status !== 'succeeded') return { ok: true, pending: true, order: o.id, status: refund.status };
+    if (o.subscription && termsOf(o).refundEndsSubscription === true) await cancelSubscription(env, o.subscription);
+    return { ok: true, order: o.id, refund: refund.id, status: refund.status, amount: refund.amount ?? o.amount, currency: o.currency };
+  } catch (error) { return { ok: false, error: 'stripe', message: redactStripe(error.message, env) }; }
+}
+export async function extendOffice(env, cat, origin, out) {
+  try {
+    out.purchases = await purchaseReadiness(env, origin, cat);
+    const rows = (await env.DB.prepare('SELECT o.*, r.manifest AS manifest FROM purchase_orders o JOIN resource_snapshots r ON r.hash=o.manifest_hash ORDER BY o.created_at DESC LIMIT 100').all()).results ?? [];
+    for (const r of rows) out.orders.push({ id: r.id, status: r.status, resourceKind: r.resource_kind, resource: r.resource_id, name: JSON.parse(r.manifest).name, shown: money(r.amount,r.currency), amount:r.amount, currency:r.currency, createdAt:r.created_at, mode:r.mode, player:{name:r.buyer_label}, stripe:r.payment ? dashboardLink(r.mode,'payment',r.payment):null, refundable:hasStripeKey(env) && ['paid','fulfilled'].includes(r.status), manualRefund:await manualRefundDetails(env,r) });
+    out.orders.sort((a,b)=>b.createdAt-a.createdAt);
+    out.paymentRecovery = (await env.DB.prepare(`SELECT id AS request_key, order_id, state, payment, error, attempts, updated_at FROM purchase_jobs WHERE ${jobsSQL('visible')} ORDER BY updated_at`).all()).results ?? [];
+    out.settlementRecovery = (await env.DB.prepare('SELECT order_id, network, state, reference, error, created_at, updated_at FROM purchase_settlements ORDER BY created_at').all()).results ?? [];
+  } catch (error) { if (!/no such table/.test(error.message)) throw error; out.purchases = {ready:false,missing:['Deploy the purchase migrations']}; }
+}

package/worker/purchase-owner.mjs

@@ -0,0 +1,243 @@
+import { hasStripeKey, shopMode } from './shop-links.mjs';
+import { hostedReadiness } from './purchase-hosted-readiness.mjs';
+import { listOffers } from './resource-kinds.mjs';
+import { orderFact, recordOrderState } from './purchase-core.mjs';
+import { machineCapabilities } from './payment-capabilities.mjs';
+/** Studio licences use the shop's Stripe, order book, webhook and refund office. */
+
+import { canonicalJson } from './referrals.mjs';
+
+import {
+  cancelSubscription,
+  closeCheckoutSession,
+  retrieveCheckoutSession,
+  stripeCall,
+  modeOf,
+} from "./stripe.mjs";
+
+import {
+  json,
+  byId,
+  idOf,
+  safeId,
+  validBuyer,
+  termsOf,
+  purchasedResource,
+  listedRelease,
+  recurringReady,
+  expireUnpaidMachineOrders,
+} from "./purchase-store.mjs";
+import {
+  reconcilePurchaseSession,
+  reconcileSubscription,
+  reconcileOrder,
+} from "./purchase-reconciliation.mjs";
+/** Owner-authenticated office calls this after matching the payer's Stripe receipt. */
+export async function reissuePurchaseClaim(env, body) {
+  if (
+    !validBuyer(body.claimHash) ||
+    !/^ord_[A-Za-z0-9]{20}$/.test(body.order ?? "") ||
+    body.receiptVerified !== true
+  )
+    return {
+      ok: false,
+      message:
+        "Verify the Stripe receipt, then supply order, claimHash and receiptVerified: true",
+    };
+  const o = await byId(env, body.order);
+  if (o && o.mode !== shopMode(env))
+    return {
+      ok: false,
+      message: "Reconnect the purchase payment mode before reissue",
+    };
+  if (!o?.session && !o?.payment)
+    return { ok: false, message: "No provider payment to verify" };
+  const receipt = o.session
+    ? await retrieveCheckoutSession(env, o.session)
+    : await stripeCall(
+        env,
+        "GET",
+        `/v1/payment_intents/${encodeURIComponent(o.payment)}`,
+      );
+  if (
+    receipt.metadata?.order !== o.id ||
+    receipt.metadata?.homie !== "purchase-v1" ||
+    (o.session && (idOf(receipt.customer) ?? null) !== o.customer)
+  )
+    return {
+      ok: false,
+      message: "Stripe receipt does not match this purchase",
+    };
+  if (body.buyer && o.subscription)
+    return {
+      ok: false,
+      message:
+        "A subscription cannot move its payer through claim reissue. Cancel billing in Stripe and have the new studio approve its own Checkout.",
+    };
+  if (body.buyer && (!termsOf(o).transferable || !validBuyer(body.buyer)))
+    return {
+      ok: false,
+      message: "These licence terms do not permit this transfer",
+    };
+  await orderFact(env, o.id, 'details', {claim_hash: body.claimHash, buyer: body.buyer ?? o.buyer})
+    .run();
+  return {
+    ok: true,
+    order: o.id,
+    message:
+      "Claim reissued. Earlier download credentials and claims are revoked. The buyer retries the purchase.",
+  };
+}
+
+export async function refundPurchasePayment(env, order) {
+  const o = await byId(env, order.id);
+  if (!o?.subscription) return false;
+  await env.DB.prepare(
+    "UPDATE purchase_payment_facts SET state = 'refunded' WHERE payment = ?1 AND order_id = ?2",
+  )
+    .bind(o.payment, o.id)
+    .run();
+  await reconcileSubscription(env, o);
+  return true;
+}
+
+/** Owner-only status probe; player readiness never depends on resource permissions. */
+export async function purchaseReadiness(env, origin, catalogue = {}) {
+  const missing = [];
+  const recurring = (await listOffers(env,origin)).some((r)=>r.offer.billing !== 'one-time');
+  if (recurring && !(await recurringReady(env)))
+    missing.push(
+      "Reconnect the shop to verify subscription permissions and webhook events",
+    );
+  if (!env.PURCHASE_RATE_LIMITER)
+    missing.push("Deploy the Cloudflare purchase rate limiting binding");
+  if (!env.PURCHASE_SIGNING_KEYS)
+    missing.push("Create the separate purchase signing key");
+  const machine = await machineCapabilities(env);
+  if (!machine.ready) missing.push(...Object.values(machine.reasons));
+  const { dryPaymentExchange } = await import('./payment-dry-exchange.mjs');
+  let exchange = machine.ready ? await dryPaymentExchange(env, origin, catalogue) : { verified: false, reason: 'Configure machine payments before running the dry exchange.' };
+  if (shopMode(env) === 'test') {
+    const cached = await env.DB.prepare("SELECT value FROM meta WHERE key = 'purchase-test-exchange'").first();
+    const sandbox = cached ? JSON.parse(cached.value) : null;
+    if (sandbox && sandbox.nextCheckAt > Date.now()) exchange.sandbox = sandbox;
+    // Readiness is the current read-only exchange, not a permanent historical probe result.
+  }
+  if (machine.ready && !exchange.verified) missing.push(exchange.reason);
+  const fallback = await hostedReadiness(env, catalogue, recurring);
+  return { ready: !missing.length, missing, machine: { ...machine, ready: !missing.length }, fallback, exchange };
+}
+
+/** Close new sales immediately, then cancel every recurring contract; retries resume safely. */
+export async function retireResource(env, kind, resource) {
+  if (!safeId(resource)) return { ok: false, message: "Name the resource to retire" };
+  await env.DB.prepare(
+    "INSERT OR IGNORE INTO resource_retirements (resource,retired_at) VALUES (?1,?2)",
+  )
+    .bind(`${shopMode(env)}:${kind}:${resource}`, Date.now())
+    .run();
+  await expirePurchaseCheckouts(env, kind, resource);
+  let after = "";
+  let canceled = 0;
+  const pending = [];
+  for (;;) {
+    const rows =
+      (
+        await env.DB.prepare(
+          "SELECT id AS order_id, subscription FROM purchase_orders WHERE item = ?1 AND mode = ?3 AND subscription IS NOT NULL AND id > ?2 ORDER BY id LIMIT 100",
+        )
+          .bind(`${kind}:${resource}`, after, shopMode(env))
+          .all()
+      ).results ?? [];
+    if (!rows.length) break;
+    for (const row of rows) {
+      if (hasStripeKey(env)) { await cancelSubscription(env, row.subscription); canceled++; }
+      else {
+        const saved = await env.DB.prepare('SELECT value FROM meta WHERE key = ?1').bind(`purchase-subscription:${row.subscription}`).first();
+        if (saved && JSON.parse(saved.value).status === 'canceled') canceled++;
+        else pending.push(row.subscription);
+      }
+      after = row.order_id;
+    }
+  }
+  if (pending.length) return {ok:false,needs:'stripe-cancellation',newSalesClosed:true,subscriptions:pending,
+    message:'Ask the connected AI to cancel these subscriptions in your Stripe account, resend their signed subscription events if needed, then retry retirement. Paid-period downloads remain available.',
+    next:pending.map(id=>({method:'DELETE',path:`/v1/subscriptions/${id}`}))};
+  return {
+    ok: true,
+    canceled,
+    message:
+      "New sales are closed and subscriptions canceled. Keep paid-period downloads available and publish the withdrawal.",
+  };
+}
+
+/** Owner approval binds a test delivery to the secret claim, not a public order identifier. */
+export async function authorizePurchaseTest(env, order) {
+  const o = await byId(env, order);
+  if (!o || o.mode !== "test" || shopMode(env) !== "test")
+    return { ok: false, message: "Only a current test order can be approved" };
+  await env.DB.prepare("INSERT OR REPLACE INTO purchase_test_approvals (order_id,value) VALUES (?1,?2)")
+    .bind(o.id, o.claim_hash)
+    .run();
+  return {
+    ok: true,
+    message:
+      "This owner-approved test claim can download while the shop stays in test mode",
+  };
+}
+/** Called on retirement and after deployment, including withdrawal, supersession and price changes. */
+export async function expirePurchaseCheckouts(env, kind = null, resource = null) {
+  let after = "";
+  let expired = 0;
+  for (;;) {
+    const rows =
+      (
+        await env.DB.prepare(
+          "SELECT id, session FROM purchase_orders WHERE status = 'started' AND mode = ?1 AND id > ?2 ORDER BY id LIMIT 100",
+        )
+          .bind(shopMode(env), after)
+          .all()
+      ).results ?? [];
+    if (!rows.length) break;
+    for (const row of rows) {
+      after = row.id;
+      const o = await byId(env, row.id);
+      const p = purchasedResource(o);
+      if (resource && (resource !== p.id || kind !== o.resource_kind)) continue;
+      const listed = resource
+        ? null
+        : await listedRelease(env, "https://studio.invalid", o.resource_kind, p.id, p.version);
+      if (
+        Date.now() < o.created_at + (o.session ? 86400000 : 300000) &&
+        listed &&
+        canonicalJson(listed.offer) === canonicalJson(JSON.parse(o.offer))
+      )
+        continue;
+      // A keyless completion can precede its invoice. Wait for signed facts; no provider read.
+      if (row.session && !hasStripeKey(env)) continue;
+      const session = row.session ? await closeCheckoutSession(env, row.session) : { status: "expired" };
+      if (session.status === "complete")
+        await reconcilePurchaseSession(env, session);
+      else {
+        await orderFact(env, o.id, 'expired', {})
+          .run();
+
+        expired++;
+      }
+    }
+  }
+  const cleaned = await expireUnpaidMachineOrders(env);
+  return { ok: true, expired, cleaned };
+}
+
+/** Owner actions refresh recurring state just as a buyer grant does. */
+export async function currentPurchaseOrder(env, id) {
+  const { reconcileRecordings } = await import('./payment-recovery.mjs');
+  await reconcileRecordings(env, id);
+  let o = await byId(env, id);
+  if (o && o.mode === shopMode(env)) {
+    await reconcileOrder(env, o);
+    o = await byId(env, id);
+  }
+  return o;
+}

package/worker/purchase-pricing.mjs

@@ -0,0 +1,8 @@
+import { currencyScale } from './shop-rules.mjs';
+export function priceWords(s, quantity = 1) {
+  if (!s) return 'Free';
+  const currency = String(s.currency).toUpperCase();
+  const digits = Math.log10(currencyScale(s.currency));
+  const shown = new Intl.NumberFormat('en', { style: 'currency', currency, currencyDisplay: 'code' }).format(s.amount * quantity / 10 ** digits);
+  return `${shown}${s.billing === 'one-time' ? ' once' : ` per ${s.billing}`} ${s.taxBehavior === 'inclusive' ? 'including tax' : (s.automaticTax || s.taxBehavior === 'exclusive') ? 'before final tax calculation' : 'total'} · per ${s.scope}${quantity > 1 ? ` · ${quantity} units` : ''}`;
+}

package/worker/purchase-problem.mjs

@@ -0,0 +1,4 @@
+const titles = { 400: 'Bad Request', 401: 'Unauthorized', 402: 'Payment Required', 403: 'Forbidden', 404: 'Not Found', 405: 'Method Not Allowed', 409: 'Conflict', 410: 'Gone', 413: 'Content Too Large', 429: 'Too Many Requests', 500: 'Internal Server Error', 503: 'Service Unavailable' };
+export function problem(status, detail, extra = {}) {
+  return Response.json({ type: 'about:blank', title: titles[status] ?? 'Error', status, detail, ok: false, message: detail, ...extra }, { status, headers: { 'content-type': 'application/problem+json', 'cache-control': 'no-store' } });
+}