@homie-rocks/studio 0.33.1 → 0.35.0

package/lib/shop.mjs

@@ -6,7 +6,8 @@
  *   homie-studio shop init [--supporter] [--currency usd] [--price 500] [--managed]
  *                                           writes shop.json (a $5 Supporter pack with --supporter) and SELLING.md
  *   homie-studio shop check                 shop.json against the studio settings and provider requirements
- *   homie-studio shop connect [--managed] [--live]   a page on THIS computer (127.0.0.1, one use, ten minutes) where the owner
+ *   homie-studio shop connect             sync Payment Links and webhook with the approved Stripe CLI; no Worker API key
+ *   homie-studio shop connect --manual [--managed] [--live]   a fallback page on THIS computer (127.0.0.1, one use, ten minutes) where the owner
  *                                           pastes the studio's restricted Stripe key (the one thing only they can make);
  *                                           with it this process makes the webhook (0.24.3), and the key and the
  *                                           webhook's signing secret go straight to the Worker secrets STRIPE_KEY and
@@ -32,7 +33,7 @@ import { fileURLToPath } from 'node:url';
 import { askedFor, withKey } from './office.mjs';
 import { runner } from './cloudflare.mjs';
 import { listGames, readStudio, siteUrl } from './studio.mjs';
-import { POLICY_PRESETS, SHOP_FILE, audienceOf, checkShop, defaultTaxCode, money } from '../worker/shop-rules.mjs';
+import { SHOP_FILE, audienceOf, checkShop, defaultTaxCode, money } from '../worker/shop-rules.mjs';
 import {
   KEY_SHAPE, STRIPE_VERSION, StripeError, WEBHOOK_SECRET_SHAPE, createWebhookEndpoint, expireCheckoutSession, isPermissionError, listWebhookEndpoints, modeOf,
   stripeCall, updateWebhookEndpoint,
@@ -43,7 +44,7 @@ const SELLING = join(HERE, '..', 'shop', 'SELLING.md');
 /** The events the webhook endpoint listens to (the owner ticks these in Stripe). */
 export const HOOK_EVENTS = Object.freeze([
   'checkout.session.completed', 'checkout.session.async_payment_succeeded', 'checkout.session.async_payment_failed', 'checkout.session.expired',
-  'charge.refunded', 'refund.created', 'refund.updated', 'charge.dispute.created', 'charge.dispute.closed',
+  'charge.refunded', 'refund.created', 'refund.updated', 'refund.failed', 'charge.dispute.created', 'charge.dispute.closed',
 ]);
 /** The restricted key's permissions, as Stripe's key page names them. Nothing else. */
 export const KEY_PERMISSIONS = Object.freeze([
@@ -77,10 +78,10 @@ export function shopForBuild(root, { log = () => {} } = {}) {
 export function shopCheck(root) {
   const r = readShop(root);
   if (r.absent) return { ok: true, command: 'shop check', absent: true, message: 'No shop.json: this studio sells nothing (homie-studio shop init writes one).' };
-  return { ok: r.ok, command: 'shop check', policy: r.shop?.policy, capPerPlayerMonth: r.shop?.capPerPlayerMonth, refundDays: r.shop?.refundDays, errors: r.errors, warnings: r.warnings, items: r.shop?.items.map((i) => `${i.id} (${i.kind}, ${i.kind === 'tip' ? 'pay what you want' : money(i.price, r.shop.currency)})`) ?? [], till: r.shop?.till ?? null, why: r.ok ? undefined : `shop.json: ${r.errors.map((e) => `${e.at}: ${e.message}`).join('; ')}` };
+  return { ok: r.ok, command: 'shop check', policy: r.shop?.policy, capPerPlayerMonth: r.shop?.capPerPlayerMonth, refundDays: r.shop?.refundDays, errors: r.errors, warnings: r.warnings, items: r.shop?.items.map((i) => `${i.id} (${i.kind}, ${i.price === 'choose' ? 'pay what you want' : money(i.price, r.shop.currency)})`) ?? [], till: r.shop?.till ?? null, why: r.ok ? undefined : `shop.json: ${r.errors.map((e) => `${e.at}: ${e.message}`).join('; ')}` };
 }
 
-/** The Supporter pack the kit suggests first: deterministic, never pay-to-win, a badge on the profile and in rooms. */
+/** The Supporter pack the kit suggests first: a badge on the profile and in rooms; the studio can replace or edit it. */
 export function supporterItem({ price = 500, days = 365, name = 'Supporter' } = {}) {
   return { id: 'supporter', kind: 'supporter', name, price, days, gives: ['badge:supporter'], badge: 'Supporter', blurb: 'A Supporter badge on your account and beside your name in rooms, for a year. It changes nothing about how any game plays.' };
 }
@@ -91,7 +92,6 @@ export function shopInit(root, { supporter = false, currency = 'usd', price = 50
   const studio = readStudio(root);
   const shop = {
     till: managed ? 'stripe-managed' : 'stripe', currency: String(currency).toLowerCase(),
-    policy: { preset: 'protective', ...POLICY_PRESETS.protective },
     items: supporter ? [supporterItem({ price: Number(price) })] : [],
   };
   const r = checkShop(shop, { games: listGames(root).map((g) => g.id) });
@@ -99,7 +99,7 @@ export function shopInit(root, { supporter = false, currency = 'usd', price = 50
   writeFileSync(file, `${JSON.stringify(shop, null, 2)}\n`);
   const wrote = [SHOP_FILE];
   if (!existsSync(join(root, 'SELLING.md')) && existsSync(SELLING)) { writeFileSync(join(root, 'SELLING.md'), readFileSync(SELLING, 'utf8')); wrote.push('SELLING.md'); }
-  return { ok: true, command: 'shop init', wrote, till: shop.till, items: shop.items.map((i) => i.id), next: ['homie-studio shop check', 'npm run deploy (the shop stays closed until the key is in)', 'homie-studio shop connect (the owner pastes a restricted key into a page on this computer)'] };
+  return { ok: true, command: 'shop init', wrote, till: shop.till, items: shop.items.map((i) => i.id), next: ['homie-studio shop check', 'npm run deploy (paid sales wait for the Stripe connection)', 'homie-studio shop connect (approve Stripe in your browser; the result names any remaining step)'] };
 }
 
 /** The office's view of the live shop: open or what is missing, the last 30 days, links to Stripe. */
@@ -107,7 +107,10 @@ export async function shopStatus(root, { url } = {}) {
   const r = await withKey(root, url, (call) => call('/_studio/api/shop'));
   if (!r.ok) return { ok: false, command: 'shop', why: r.message ?? r.why ?? 'the studio did not answer' };
   const local = readShop(root);
-  return { ok: true, command: 'shop', ready: r.ready, mode: r.mode, missing: r.missing, totals: r.totals, stripe: r.stripe, hook: r.hook, till: r.shop?.till ?? null, items: r.shop?.items ?? [], local: { ok: local.ok, absent: Boolean(local.absent), errors: local.errors } };
+  const { stripeConnectionInfo } = await import('./stripe-connect.mjs');
+  const connection = r.mode === 'test' ? stripeConnectionInfo(root) : null;
+  const missing = [...(r.missing ?? []), ...(connection?.expired ? [{ id: 'stripe-expired', words: 'Stripe test credentials have expired. Run homie-studio shop connect --renew and approve Stripe again.' }] : [])];
+  return { ok: true, command: 'shop', ready: r.ready && !connection?.expired, mode: r.mode, missing, connection, totals: r.totals, stripe: r.stripe, hook: r.hook, till: r.shop?.till ?? null, items: r.shop?.items ?? [], local: { ok: local.ok, absent: Boolean(local.absent), errors: local.errors } };
 }
 
 export async function shopOrders(root, { url } = {}) {
@@ -162,8 +165,9 @@ export function connectPage({ nonce, site, studio, till = 'stripe', test = true
 <style>body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2.5rem auto;padding:0 1rem;color:#1b1b1b}h1{font-size:1.6rem}h2{font-size:1.1rem;margin-top:1.8rem}input[type=password]{width:100%;box-sizing:border-box;font:inherit;padding:.6rem;border:1px solid #999;border-radius:8px}label{display:block;margin:.8rem 0 .3rem;font-weight:600}fieldset{border:1px solid #ccc;border-radius:10px;padding:.6rem 1rem}fieldset label{font-weight:400;display:flex;gap:.6rem;align-items:flex-start}button{margin-top:1.2rem;font:inherit;font-weight:700;padding:.7rem 1.3rem;border:0;border-radius:8px;background:#1b1b1b;color:#fff}small{color:#555}code{font-size:.85em;background:#f2f2f2;padding:0 .25em;border-radius:4px}ol li,ul li{margin:.25rem 0}.box{background:#f6f6f2;border-radius:10px;padding:.8rem 1rem}details{margin-top:1rem}summary{cursor:pointer}</style>
 <h1>Connect ${esc(studio)}'s shop to your Stripe</h1>
 <p>Money goes straight from players to <b>your own Stripe account</b>. Homie never sees it and takes no cut. What you paste here goes from this page to Stripe (one check) and to your studio's Worker as a secret, and nowhere else: not to the chat, not to a file, not to a log.</p>
-<p class="box">${test ? '<b>Test mode first.</b> Use your Stripe sandbox or test mode (the key starts with <code>rk_test_</code>): nothing real is charged, and test cards work. Live keys only when you say the shop is ready to sell.' : '<b>Live mode.</b> Real cards, real money.'}</p>
-<h2>1. In Stripe: one restricted key</h2>
+<p class="box">${test ? '<b>Test mode first.</b> Use your Stripe sandbox or test mode (the key starts with <code>rk_test_</code> or <code>sk_test_</code>): nothing real is charged, and test cards work. Live keys only when you say the shop is ready to sell.' : '<b>Live mode.</b> Real cards, real money.'}</p>
+<h2>1. In Stripe: a key for this shop</h2>
+<p>You can use a restricted (<code>rk_</code>) or full secret (<code>sk_</code>) key. To choose a restricted key with just the permissions this shop uses:</p>
 <ol><li>Open <a href="${dash}/apikeys" target="_blank" rel="noopener">Developers → API keys</a> and press <b>Create restricted key</b>. If Stripe asks what the key is for, choose your own integration, <b>not</b> "Authorizing agent access" (Stripe holds an agent key's refunds for a second approval).</li>
 <li>Name it "${esc(studio)} shop" and give it exactly these permissions (leave everything else at None):<ul>${perms}</ul></li>
 <li>Create it and copy the key (it starts with <code>rk_</code>).</li></ol>
@@ -171,7 +175,7 @@ export function connectPage({ nonce, site, studio, till = 'stripe', test = true
 <p>With your key, this page makes the endpoint where Stripe tells your shop about payments (<code>${esc(hookUrlOf(site))}</code>, for ${HOOK_EVENTS.length} events), and its signing secret goes straight to your Worker. Nobody sees it. An older one this page made for the same address is turned off, never deleted.</p>
 <form method="post" action="/key"><input type="hidden" name="n" value="${esc(nonce)}">
 <h2>3. Paste the key here</h2>
-<label for="key">Restricted key</label><input id="key" name="key" type="password" autocomplete="off" placeholder="rk_test_…" required>
+<label for="key">Stripe key</label><input id="key" name="key" type="password" autocomplete="off" placeholder="rk_test_…" required>
 <details><summary>I made the webhook myself (or my key has no Webhook Endpoints permission)</summary>
 <ol><li>Open <a href="${dash}/workbench/webhooks" target="_blank" rel="noopener">Webhooks</a> and press <b>Create an event destination</b> (Your account, a Webhook endpoint).</li>
 <li>Endpoint URL: <code>${esc(hookUrlOf(site))}</code></li><li>Events: ${events}</li>
@@ -179,7 +183,7 @@ export function connectPage({ nonce, site, studio, till = 'stripe', test = true
 <label for="hook">Webhook signing secret</label><input id="hook" name="hook" type="password" autocomplete="off" placeholder="whsec_…"></details>
 <h2>4. Who is the seller?</h2>
 <fieldset>
-<label><input type="radio" name="till" value="stripe"${till !== 'stripe-managed' ? ' checked' : ''}> <span><b>You are</b> (standard Stripe). Stripe takes its usual card fee (in the US 2.9% + 30¢ a sale; in Canada 2.9% + CA$0.30). Stripe Tax is on: it works out and collects sales tax and VAT where you have told Stripe you are registered (0.5% a sale there). Registering and filing are yours, and some countries (the EU, the UK) expect a foreign seller to register from the first sale.</span></label>
+<label><input type="radio" name="till" value="stripe"${till !== 'stripe-managed' ? ' checked' : ''}> <span><b>You are</b> (standard Stripe). Stripe takes its usual card fee (in the US 2.9% + 30¢ a sale; in Canada 2.9% + CA$0.30). Set automaticTax: true in shop.json to enable Stripe Tax: it works out and collects sales tax and VAT where you have told Stripe you are registered (0.5% a sale there). Registering and filing are yours, and some countries (the EU, the UK) expect a foreign seller to register from the first sale.</span></label>
 <label><input type="radio" name="till" value="stripe-managed"${till === 'stripe-managed' ? ' checked' : ''}> <span><b>Stripe is</b> (Stripe Managed Payments). <b>3.5% more</b> a sale, on top of the card fee. Stripe becomes the seller of record: it registers for, collects, files and pays sales tax and VAT in 80+ countries, runs fraud checks, answers card disputes for you and handles buyers' payment questions. Statements read <code>LINK.COM*</code>. You still cover the money of a lost dispute, and Stripe may refund a buyer within 60 days. Turn it on in Stripe first (<a href="${dash}/settings/managed-payments" target="_blank" rel="noopener">Managed Payments</a>, after Stripe's eligibility review; Canada and the US are among the countries it serves).${test ? ' In test mode this page tries one test checkout with Managed Payments (expired at once) and says whether Stripe takes it.' : ''}</span></label>
 </fieldset>
 <button>Save to my Worker</button></form>
@@ -225,7 +229,7 @@ async function makeWebhook(env, site, { fetcher }) {
  * (there is no API to read it). Never in live mode.
  */
 async function probeManaged(env, shop, { fetcher }) {
-  const item = shop?.items?.find((i) => i.kind !== 'tip') ?? null;
+  const item = shop?.items?.find((i) => i.price !== 'choose') ?? null;
   try {
     const s = await stripeCall(env, 'POST', '/v1/checkout/sessions', {
       mode: 'payment', success_url: 'https://example.com/homie-shop-check', cancel_url: 'https://example.com/homie-shop-check',
@@ -240,11 +244,11 @@ async function probeManaged(env, shop, { fetcher }) {
 }
 
 /**
- * `homie-studio shop connect`: the page above on 127.0.0.1 (one use, ten minutes). The key goes to Stripe once (a
+ * `homie-studio shop connect --manual`: the fallback page above on 127.0.0.1 (one use, ten minutes). The key goes to Stripe once (a
  * read, then the webhook), and to `wrangler secret put` on its standard input; so does the webhook's signing secret,
  * which Stripe hands this process when it makes the endpoint. Nothing is printed or returned but ids and words.
  */
-export async function shopConnect(root, { managed = null, live = false, log = () => {}, port = 0, wait = 10 * 60_000, verify = true, fetcher = fetch } = {}) {
+export async function shopConnectManual(root, { managed = null, live = false, log = () => {}, port = 0, wait = 10 * 60_000, verify = true, fetcher = fetch } = {}) {
   const studio = readStudio(root);
   const site = siteUrl(root);
   if (!site) return { ok: false, command: 'shop connect', needs: 'deploy', why: 'the studio has no live address yet, and Stripe needs one to send payments to (the webhook): run npm run deploy first, then this' };
@@ -270,10 +274,9 @@ export async function shopConnect(root, { managed = null, live = false, log = ()
           const say = ({ status, text }) => { res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' }); res.end(text); };
           if (form.get('n') !== nonce || finished) { say(said(403, 'This page was used already.')); return; }
           if (busy) { say(said(409, 'Still saving the last press. Wait a moment.')); return; }
-          if (/^sk_live_/.test(key)) { say(said(400, 'That is a full secret key. The shop takes only a RESTRICTED key (rk_…) with the permissions on the page. Go back and make one.')); return; }
-          if (!KEY_SHAPE.test(key) || !/^rk_/.test(key)) { say(said(400, 'That does not look like a restricted key (rk_test_… or rk_live_…). Go back and try again.')); return; }
+          if (!KEY_SHAPE.test(key)) { say(said(400, 'That does not look like a Stripe key (rk_test_…, rk_live_…, sk_test_… or sk_live_…). Go back and try again.')); return; }
           // Test mode unless the owner's AI ran it with --live on purpose: a live key on the test page is refused.
-          if (modeOf(key) !== (live ? 'live' : 'test')) { say(said(400, live ? 'This page takes a LIVE restricted key (rk_live_…).' : 'This page is for TEST mode: paste a test key (rk_test_…). Live keys go in only when the shop is ready to sell for real (shop connect --live).')); return; }
+          if (modeOf(key) !== (live ? 'live' : 'test')) { say(said(400, live ? 'This page takes a LIVE Stripe key (rk_live_… or sk_live_…).' : 'This page is for TEST mode: paste a test key (rk_test_… or sk_test_…). Live keys go in only when the shop is ready to sell for real (shop connect --manual --live).')); return; }
           if (hook && !WEBHOOK_SECRET_SHAPE.test(hook)) { say(said(400, 'That does not look like a webhook signing secret (whsec_…). Go back and try again, or leave it empty and this page makes the webhook.')); return; }
           busy = true;
           try {
@@ -343,7 +346,8 @@ export function shopDisconnect(root) {
   const w = runner(root, studio.cloudflare?.accountId ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
   const a = w(['secret', 'delete', 'STRIPE_KEY'], { input: 'y\n' });
   const b = w(['secret', 'delete', 'STRIPE_WEBHOOK_SECRET'], { input: 'y\n' });
-  return a.code === 0 || b.code === 0 ? { ok: true, command: 'shop disconnect', message: 'The Stripe key and webhook secret are gone from the Worker: the shop is closed. Delete the restricted key in Stripe too (Developers → API keys).' } : { ok: false, command: 'shop disconnect', why: a.out.trim().split('\n').slice(-2).join(' ') };
+  const c = w(['secret', 'delete', 'STRIPE_SHOP_LINKS'], { input: 'y\n' });
+  return a.code === 0 || b.code === 0 || c.code === 0 ? { ok: true, command: 'shop disconnect', message: 'The Worker payment connection was removed. Ask your connected AI to deactivate existing Payment Links in Stripe too; already opened Stripe checkouts can still complete.' } : { ok: false, command: 'shop disconnect', why: a.out.trim().split('\n').slice(-2).join(' ') };
 }
 
 /** Lines for a person (the CLI's print). */
@@ -352,6 +356,7 @@ export function shopLines(r) {
   if (r.command === 'shop') {
     lines.push(r.ready ? `The shop is open${r.mode === 'test' ? ' in TEST MODE (no real money)' : ', live'} (till: ${r.till}).` : 'The shop is not selling yet:');
     for (const m of r.missing ?? []) lines.push(`  - ${m.words}`);
+    if (r.connection) lines.push(`Stripe test credentials expire ${r.connection.expiresAt}. Renew: ${r.connection.renew}`);
     if (r.totals) lines.push(`Last 30 days: ${r.totals.sales} sales, ${money(r.totals.paid, r.totals.currency)} before tax and fees; ${r.totals.refunds} refunded; ${r.totals.disputes} disputed.`);
     lines.push(`Webhook endpoint for Stripe: ${r.hook}`, `Payouts: ${r.stripe?.payouts}`);
     if (r.local && !r.local.ok) lines.push(`shop.json here: ${r.local.errors.map((e) => e.message).join('; ')}`);
@@ -373,6 +378,9 @@ export function shopLines(r) {
     if (r.sent) for (const s of r.sent) lines.push(`${s.via}: ${s.ok ? 'sent' : `not sent (${s.why ?? s.status})`}`);
     else for (const s of r.statements ?? []) lines.push(`${s.statement.referrer}: due ${s.statement.totals ? money(s.statement.totals.due, s.statement.currency) : 'see first page'} (${s.statement.lines.length} line(s)), signed`);
     if (!(r.sent ?? r.statements ?? []).length) lines.push(`No referral statements for ${r.period}.`);
-  } else lines.push(r.message ?? '');
+  } else { lines.push(r.message ?? r.why ?? (r.alreadyConnected ? 'Stripe test credentials are already installed.' : '')); for (const step of r.next ?? []) lines.push(step); if (r.fallback) lines.push(`Optional fallback, only if chosen: ${r.fallback}`); }
   return lines;
 }
+
+// Public entry point: browser pairing by default; the local key page is explicitly opt-in.
+export { shopConnect } from './stripe-connect.mjs';

package/lib/stripe-connect.mjs

@@ -0,0 +1,135 @@
+/** Stripe owns browser authorization. This module owns only secret transport and a non-secret receipt.
+ * See docs/stripe-connect-research.md: current CLI OAuth is NOT a Worker credential issuer. */
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { runner } from './cloudflare.mjs';
+import { lockDeploy } from './deploy-state.mjs';
+import { readStudio, siteUrl } from './studio.mjs';
+import { hookUrlOf, readShop, shopConnectManual } from './shop.mjs';
+import { syncPaymentLinks } from './shop-links.mjs';
+import { LINKS_STRIPE_VERSION, fullerReason } from '../worker/shop-links.mjs';
+import { formEncode } from '../worker/stripe.mjs';
+
+const hash = (s) => createHash('sha256').update(s).digest('hex');
+const failure = (needs, why, extra = {}) => ({ ok: false, command: 'shop connect', needs, why, ...extra });
+const receiptHome = () => join(homedir(), '.config', 'homie', 'stripe');
+const receiptDir = (root, storage) => join(storage, hash(realpathSync(root)).slice(0, 24));
+
+/** Local expiry evidence only; no account query and no credentials in the result. */
+export function stripeConnectionInfo(root, { storage = receiptHome(), now = Date.now } = {}) {
+  try {
+    const r = JSON.parse(readFileSync(join(receiptDir(root, storage), 'test.json'), 'utf8'));
+    if (r.url !== hookUrlOf(siteUrl(root)) || !Number.isFinite(Date.parse(r.expiresAt))) return null;
+    return { mode: 'test', expiresAt: r.expiresAt, expired: Date.parse(r.expiresAt) <= now(), renew: 'homie-studio shop connect --renew' };
+  } catch { return null; }
+}
+
+const json = (s) => { try { return JSON.parse(s); } catch { return null; } };
+// This output stays private, including CLI config, completion, errors and API responses.
+export function stripeProcess(args, { cwd, env = process.env } = {}) {
+  const childEnv = { ...env, CI: '1', NO_COLOR: '1' };
+  for (const k of Object.keys(childEnv)) if (k.startsWith('STRIPE_')) delete childEnv[k];
+  return new Promise((resolve) => {
+    const p = spawn('stripe', args, { cwd, env: childEnv, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '', stderr = '', ended = false;
+    const end = (r) => { if (!ended) { ended = true; clearTimeout(timer); resolve(r); } };
+    const timer = setTimeout(() => { p.kill(); end({ code: 1 }); }, 10 * 60_000);
+    p.stdout.on('data', (b) => { stdout += b; if (stdout.length > 4_000_000) p.kill(); });
+    p.stderr.on('data', (b) => { stderr += b; if (stderr.length > 1_000_000) p.kill(); });
+    p.on('error', (e) => end({ code: 1, missing: e.code === 'ENOENT' }));
+    p.on('close', (code) => end({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+  const p = spawn(cmd, args, { stdio: 'ignore', detached: true });
+  p.on('error', () => {}); p.unref();
+}
+
+const stripeURL = (s) => {
+  try { const u = new URL(s); return u.protocol === 'https:' && ['dashboard.stripe.com', 'access.stripe.com'].includes(u.hostname) && !u.username && !u.password && !u.port; } catch { return false; }
+};
+/** Accept only Stripe's known login continuations. Never execute next_step as shell text. */
+export function completionArgs(step) {
+  if (step === 'stripe login --complete-device') return ['login', '--complete-device'];
+  if (step === 'stripe login --complete-reauth') return ['login', '--complete-reauth'];
+  const m = /^stripe login --complete[ =](?:'([^']+)'|"([^"]+)"|(\S+))$/.exec(step ?? '');
+  const url = m && (m[1] || m[2] || m[3]);
+  return stripeURL(url) ? ['login', '--complete', url] : null;
+}
+
+export async function shopConnect(root, options = {}) {
+  if (options.manual) {
+    const result = await shopConnectManual(root, options);
+    if (result.ok) rmSync(join(receiptDir(root, options.storage ?? receiptHome()), 'test.json'), { force: true });
+    return result;
+  }
+  const { live = false, renew = false, log = () => {}, exec = stripeProcess, open = openBrowser,
+    storage = receiptHome(), wrangler = null } = options;
+  const mode = live ? 'live' : 'test';
+  const checked = readShop(root);
+  if (!checked.ok || checked.absent) return failure('shop', 'Create and check shop.json first: homie-studio shop init, then shop check.');
+  if (options.managed === true && checked.shop.till !== 'stripe-managed') return failure('shop-settings', 'For Managed Payments, set shop.json till to stripe-managed and deploy that choice before connecting. Stripe’s own eligibility and terms still apply.');
+  const id = hash(realpathSync(root)).slice(0, 24);
+  const profile = `homie-${id}`;
+  const dir = join(storage, id);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // Reuse the toolkit’s process-aware lock, in the private receipt folder. Dead processes do not strand setup.
+  const lock = lockDeploy(dir);
+  if (!lock.ok) return failure('busy', 'Stripe connection is already running for this studio. Wait for that command to finish.');
+  try {
+    const cli = (args) => exec(['--project-name', profile, ...args], { cwd: root });
+    const installed = await cli(['--version']);
+    if (installed.code !== 0) return failure('stripe-cli', 'Install Stripe’s official CLI, then run shop connect again.', { next: ['npm install -g @stripe/cli@latest'] });
+
+    // A read both checks existing credentials and lets Stripe refresh its OAuth session itself.
+    let probe = renew ? { code: 1 } : await cli(['get', '/v1/products', '-d', 'limit=1', ...(live ? ['--live'] : [])]);
+    if (probe.code !== 0 || !Array.isArray(json(probe.stdout)?.data)) {
+      const start = await cli(['login', '--non-interactive', ...(renew ? ['--new-session'] : [])]);
+      const login = json(start.stdout);
+      const complete = completionArgs(login?.next_step);
+      if (start.code !== 0 || !stripeURL(login?.browser_url) || !complete || !/^[a-zA-Z0-9 -]{1,100}$/.test(login?.verification_code ?? '')) {
+        return failure('stripe-login', 'Stripe could not start browser approval. Update the official Stripe CLI and try shop connect again. An account administrator may need to enable CLI access in Stripe’s MCP and CLI access settings.');
+      }
+      log(`Approve your studio’s Stripe account in your browser. Pairing code: ${login.verification_code}. ${login.browser_url}`);
+      open(login.browser_url);
+      const finished = await cli(complete);
+      if (finished.code !== 0) return failure('stripe-login', 'Stripe approval did not finish. Run shop connect again when ready.');
+
+      probe = await cli(['get', '/v1/products', '-d', 'limit=1', ...(live ? ['--live'] : [])]);
+      if (probe.code !== 0 || !Array.isArray(json(probe.stdout)?.data)) return failure('stripe-access', 'Stripe is signed in but cannot read Products in the requested mode. Review the account, sandbox and permissions in Stripe, then run shop connect --renew again.');
+    }
+    const site = siteUrl(root);
+    if (!site) return failure('deploy', 'Stripe is connected on this computer. Deploy the studio with studio_deploy (Cloudflare approval first if needed), then run shop connect again.', { mode, connected: true });
+    let target;
+    try { target = new URL(site); } catch { return failure('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.'); }
+    if (target.protocol !== 'https:' || target.username || target.password || /^(localhost|127\.|\[::1\])/.test(target.hostname)) return failure('deploy', 'Deploy the studio to a public HTTPS address, then run shop connect again.');
+    const api = async (method, path, params, idempotency) => {
+      const args = [method.toLowerCase(), path, '--stripe-version', LINKS_STRIPE_VERSION, ...(live ? ['--live'] : []), ...(idempotency ? ['--idempotency', idempotency] : [])];
+      for (const [k, v] of formEncode(params)) args.push('-d', `${k}=${v}`);
+      const r = await cli(args);
+      const body = json(r.stdout);
+      if (r.code !== 0 || !body || body.error) throw new Error('Stripe API operation failed');
+      return body;
+    };
+    const reason = fullerReason(checked.shop);
+    if (reason) return failure('fuller-checkout', reason, { mode, connected: true });
+    const studio = readStudio(root);
+    const w = wrangler ?? runner(root, studio.cloudflare?.accountId ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+    const receiptFile = join(dir, `${mode}.json`);
+    const receipt = existsSync(receiptFile) ? json(readFileSync(receiptFile, 'utf8')) : null;
+    const result = await syncPaymentLinks({ api, shop: checked.shop, slug: studio.slug, site: target.origin, mode, w, receipt,
+      saveReceipt: (record) => {
+        writeFileSync(`${receiptFile}.tmp`, JSON.stringify(record), { mode: 0o600 });
+        renameSync(`${receiptFile}.tmp`, receiptFile);
+      } });
+    return { ...result, profile };
+  } catch {
+    return failure('stripe-setup', 'Stripe setup could not finish. Check the studio’s Stripe session and Products, Prices, Payment Links and Webhook Endpoints write permissions, and the Cloudflare login, then run shop connect again. No credentials were printed.');
+  } finally { lock.release(); }
+}

package/lib/template-history.json

@@ -1822,6 +1822,90 @@
      }
     }
    }
+  },
+  "0.34.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "fc90f3609cad18ba"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": [
+      "57c04f6526e16890",
+      "6c30b932b0783495",
+      "9e020d69dd6a954e"
+     ],
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
+  },
+  "0.35.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "fc90f3609cad18ba"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "a7f290579585368c",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "9e020d69dd6a954e",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "7cad8fd10f62fef1"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.33.1",
+  "version": "0.35.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/shop/SELLING.md

@@ -1,97 +1,21 @@
-# Selling things in your games: what you are taking on
+# Your shop, your choices
 
-Plain words for a studio's owner, from the Homie studio kit. **This is not legal or tax advice.** If you will
-sell for real, ask an accountant where you must register for tax, and a lawyer anything this page leaves you
-unsure about.
+You sell with your own Stripe account. Money goes directly to you; Homie takes no cut.
+The studio is the seller and is responsible for the law where it sells and for Stripe's terms.
 
-## The short version
+Your `shop.json` chooses items, wording, prices, currency, tax integration, sale dates, entitlements,
+referral terms, optional spending caps and optional refund windows. Nothing requires an account or age
+question by default. Guests can buy repeatedly and keep their purchases when signing in later.
 
-You sell with **your own Stripe account**. Money goes straight from your players to you. Homie never sees it,
-never holds it, and takes no cut. That also means **you are the shop**: you set the prices, you answer refund
-requests, you deal with card disputes, and the tax on your sales is yours to handle.
+You can choose `policy.preset: "protective"` or `"adults-only"`, or set individual options.
+Without a preset the shop is open. SHOP.md describes each setting and the game cart API.
 
-## Who does what
+With the fuller checkout connection, a cart is one payment with several lines and quantities. Your office can refund a whole order or a line.
+A player can refund items within a window you set; a tip stays given unless you refund it.
+Stripe handles payments, receipts, payment limits, held refunds and disputes. Stripe Tax is optional;
+Managed Payments is another selectable integration. Your office links Stripe's own pages.
 
-| | You (the studio) | Stripe | Homie |
-|---|---|---|---|
-| Prices, what you sell | yes | | |
-| Taking the card, the receipt email | | yes | |
-| Refunds | yes: one tap in your office | carries them out | |
-| Card disputes (chargebacks) | yes: you answer them in Stripe and carry the loss if you lose | runs the process | |
-| Sales tax and VAT | yes, with Stripe Tax's help (or Managed Payments, below) | calculates and collects | |
-| Your players' data | yes: you are responsible for it | keeps the card and email | stores nothing |
-| Who may buy | your editable shop policy; protective defaults | provider terms | supplies presets |
+`homie-studio shop connect` opens Stripe's approval page if needed, then your AI syncs your products, prices, payment links and webhook. You never handle a key. The shop sends buyers to Stripe, where they confirm quantity or choose a tip; your Worker holds only the webhook signing secret and link settings. Buy different items separately. Refund in Stripe or ask your connected AI; signed events update your shop. A missing payment stays pending until Stripe resends its event. Free orders need no Stripe.
 
-## Refunds
-
-- A player can refund an **unused** item themselves within the optional refund window you set from their
-  account page. Set `policy.refundUsedItems` to include used items. Without a window, buyers ask you for a refund.
-  Fewer people turn to card disputes when a refund is easy.
-- Anything else, you refund with **one tap** on your office's shop page. Your AI can only *ask* you to refund; it
-  can never do it by itself.
-- Stripe does not give back its processing fee on a refund. That is the cost of a happy player.
-
-## Disputes (chargebacks)
-
-- A buyer's bank can reverse a payment. Stripe charges a dispute fee (about US$15) whether you win or lose, and
-  you lose the sale's money if the bank decides for the buyer. On a US$5 item one dispute costs more than the
-  sale, so consider your costs when setting prices. Homie imposes no price or earnings ceiling.
-- **A dispute never deletes or locks the player's account.** While it is open nothing changes. If you lose it,
-  that one item is taken back, as a refund would.
-
-## Tax
-
-You choose who the seller is when you connect your Stripe (`homie-studio shop connect` shows both):
-
-- **You are the seller** (`"till": "stripe"`): Stripe Tax is on. It works out and collects tax **only where you
-  have told Stripe you are registered**, and it does not file your returns. Some places expect a foreign seller
-  of digital goods to register from the first sale (the EU and the UK do). Cheapest; the most work.
-- **Stripe is the seller** (`"till": "stripe-managed"`, Stripe Managed Payments): **3.5% more** a sale. Stripe's
-  Link, LLC becomes the seller of record and registers, collects, files and pays sales tax and VAT in 80+
-  countries, runs fraud checks and answers disputes for you. You still carry the money of a lost dispute, and
-  Stripe may refund a buyer within 60 days. You turn it on in Stripe first (after Stripe's eligibility review).
-
-## Kids
-
-Your shop starts with the `protective` preset in shop.json. It requires an account and a neutral age question,
-blocks purchases under 13, uses a parent's checkout for teens, closes shops on kids servers and kids studios,
-hides advantages on beginner and kids servers, refuses paid randomness, countdowns and virtual-currency items,
-and sends TV shoppers to a phone. Existing shops without a policy keep these protections.
-
-These are **your settings**: read and edit `policy` in shop.json. `adults-only` also blocks teens;
-`custom` enables all policies. You can override individual rules without changing the others. SHOP.md lists
-every setting. No spending cap or refund window applies unless you set one; existing written values stay yours.
-
-As the seller, you are responsible for the law and your payment provider's terms wherever you sell, including
-rules protecting children. Choosing a preset does not establish compliance. This is information, not legal advice.
-
-## Referrals
-
-If another studio (or homie.rocks, or a creator) sends you a new player who buys something, you owe them the
-referral share you published in `shop.json` (10% if you kept the suggestion; 0 if you turn it off). Your office
-shows what you owe and to whom, and signs a monthly statement for each. **They invoice you, and you pay them
-yourself.** Nothing moves through Homie.
-
-## What you do, and what your AI does
-
-Your AI sets the shop up with Stripe's own tools for AI (Stripe's agent plugin: its MCP server and skills). It
-makes your products in Stripe, checks your tax settings, makes the webhook, and answers "how are sales?" by reading
-your Stripe. What stays yours, in Stripe's own pages:
-
-- making the Stripe account, and later activating it (your business details, bank account and identity checks);
-- one sign-in page that lets your AI use Stripe's tools: give it your **sandbox** (test) first;
-- one restricted key you make in Stripe and paste into a page on your own computer (never into a chat);
-- approving anything Stripe asks you to confirm (a refund your AI asked Stripe for, for example), and every refund
-  in your office.
-
-If your AI's app cannot use Stripe's sign-in page, Stripe offers an "Agent" key for it instead. From 31 October 2026
-Stripe's tools for AI accept only those (or the sign-in page). The shop's own key is a different, ordinary
-restricted key; never make that one an Agent key, or Stripe will hold every refund for a second approval.
-
-## Before the first real sale
-
-1. Make (or pick) your Stripe account, verify it, and add a bank account.
-2. Test everything in **test mode** first: buy your own item with a Stripe test card, refund it from the office.
-3. Fill in your public business details in Stripe (name, support email, the refund page `/shop/refunds/`).
-4. Talk to an accountant about where you must register for tax, or choose Managed Payments.
-5. Then, and only then, connect a live key (`homie-studio shop connect --live`).
+The fuller connection adds combined carts, spending limits, custom checkout expiry, automatic recovery and refunds in the office. An existing Worker key selects it; your AI explains it only if you ask for those features. The optional manual setup remains available, but is not the default.
+The scaffold has no policy, cap or refund window. Test mode is available before choosing live mode.