@homie-rocks/studio 0.34.0 → 0.35.1

package/lib/stripe-connect.mjs

@@ -0,0 +1,146 @@
+/** 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, redactStripe } 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; } };
+// Stripe CLI also prints login failures on stderr (stripe/stripe-cli pkg/cmd/root.go).
+// Never fall back to stdout: successful login output can contain credentials.
+const stripeReason = (result, call) => {
+  const message = (json(result?.stdout)?.error ?? json(result?.stderr)?.error)?.message
+    ?? (result?.code !== 0 ? result?.stderr?.trim() : null);
+  return typeof message === 'string' ? ` Stripe said: “${redactStripe(message).slice(0, 400)}” (${call}).` : '';
+};
+
+// 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.' + stripeReason(start, 'login'));
+      }
+      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.' + stripeReason(finished, 'login completion'));
+
+      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.' + stripeReason(probe, 'GET /v1/products'));
+    }
+    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 Object.assign(new Error('Stripe API operation failed'), { stripeReason: stripeReason(r, `${method} ${path.replace(/\/[^/]*_[A-Za-z0-9]+$/, '/…')}`) });
+      }
+      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 (e) {
+    const said = e?.stripeReason ?? '';
+    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.' + said);
+  } finally { lock.release(); }
+}

package/lib/template-history.json

@@ -1846,7 +1846,91 @@
      "## Art direction and models": "a48fff7bf0a5f2fc",
      "## Running live games (the back office)": "51ebf2ab756f6e4d",
      "## Servers and AI seats": "98d08705087a33ec",
-     "## Selling things (the shop)": "57c04f6526e16890",
+     "## 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"
+      }
+     }
+    }
+   }
+  },
+  "0.35.1": {
+   "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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.34.0",
+  "version": "0.35.1",
   "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

@@ -10,10 +10,12 @@ question by default. Guests can buy repeatedly and keep their purchases when sig
 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.
 
-A cart is one payment with several lines and quantities. Your office can refund a whole order or a line.
+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.
 
-`homie-studio shop connect` provides a local page for the key and webhook signing secret; both are part of payment setup, credentials stay in Worker secrets.
+`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.
+
+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.

package/shop/SHOP.md

@@ -104,21 +104,59 @@ One order stores every line and its item snapshot. `/api/shop/mine` lists the li
 
 `homie-studio shop init --supporter` writes an example item and `SELLING.md`, without a policy, cap or refund
 window. `shop check` validates settings; the build uses the same validation.
-`shop connect` opens a local page for the studio's Stripe key and webhook secret; `--live` selects live mode.
-Both restricted (`rk_`) and full secret (`sk_`) keys are accepted. A restricted key is useful: Checkout Sessions Write, Charges Write, PaymentIntents Read, Disputes Read;
-Webhook Endpoints Write lets the connect page create the webhook. The key and webhook signing secret are both
-part of working payment setup; without either, readiness names the missing step and opens no checkout.
-[Stripe fulfillment](https://docs.stripe.com/checkout/fulfillment) uses webhooks as well as the redirect.
-Credentials stay in Worker secrets. A preview normally has no database and cannot sell. A preview that you
-configure with a database, key and signing secret sells into that database.
-Stripe's agent tools can populate Products with `shop catalog` and read sales; secret-returning endpoint
-creation belongs on the connect page. Stripe approval links are handled by the owner.
-
-`shop`, `shop orders`, and `/_studio/office/shop` show readiness and sales. Office refunds are owner actions;
-`shop refund <order>` asks the owner to confirm. Stripe controls pending or held refunds.
-The office links Stripe's disputes and provides CSV exports. A dispute does not lock a player's account;
-a lost dispute revokes the order's entitlements. Referral statements record what the studio owes;
-the studio pays referrers directly and marks payment in its office.
+`shop connect` (MCP `stripe_login`) starts Stripe's official browser approval, sandbox/test first.
+If Stripe CLI is missing, the result gives `npm install -g @stripe/cli@latest` for the AI to run.
+The person never supplies a key to the AI. A studio-specific CLI profile avoids borrowing another studio's login.
+If the studio is not deployed yet, approval is retained: deploy with `studio_deploy` (and
+`cloudflare_login` first if needed), then rerun connect. Webhooks require the deployed HTTPS address.
+
+**The default is keyless.** Connect syncs one Product and Price for each shop.json item and one
+Payment Link for each paid item. Tip Prices use custom amounts; free orders stay local. It creates
+an account webhook at `<site>/api/shop/hook`, captures its signing secret without displaying it,
+and installs `STRIPE_WEBHOOK_SECRET` and `STRIPE_SHOP_LINKS` through Wrangler stdin. No Stripe
+API key goes into the Worker. Repeat connect after editing shop.json: changed prices get new
+Price versions, changed links get new versions, and removed objects are archived. Old paid orders
+keep their frozen item definitions. Receipts contain no credentials. Unchanged runs create nothing.
+
+With an existing account and deployed studio, the person approves Stripe CLI once; an already
+connected profile needs zero new approvals. An MCP-only grant is separate and is never extracted.
+The AI installs tooling, creates/syncs objects and stores the secret. New account verification,
+activation, administrator access settings and Cloudflare authorization are separate prerequisites.
+`shop connect --live` requires the owner's go-live request. `--renew` retries browser authorization.
+Never request a key from the person for the default flow.
+
+At purchase time, the Worker saves an opaque order reference and sends it as the link's
+`client_reference_id`. The buyer confirms quantity or tip amount on Stripe. A signed snapshot
+session must match the frozen link, revision, currency and allowed amount before granting. Reusing
+a link creates a distinct order for each Session. Returns without a webhook never grant goods.
+Refunds and disputes use durable financial snapshots in the existing meta table, without buyer/card
+data. They tolerate retries and arrivals before the payment event. Fully successful refunds revoke
+items; failed refunds restore the financial booking. A lost dispute revokes goods, never the account.
+
+| Need | Keyless behavior / fuller connection |
+|---|---|
+| Several different items in one payment | Buy separately. Stripe supports static multi-item links (up to 20 fixed-price lines), but they are not an arbitrary buyer cart. Dynamic carts use the keyed path. |
+| Reserve an optional spending allowance | Requires keyed Checkout; a reusable public link cannot atomically reserve this studio's local cap. No silent weakening of a configured cap. |
+| Expire an abandoned session | Stripe controls the lifetime; deactivating a link prevents new sessions, not existing sessions. Custom expiry/cancellation requires the keyed path. |
+| Refund in one tap / player self-refund | Owner uses Stripe Dashboard or asks their Stripe-connected AI. Signed events update books. Office shows guidance instead of a paid-order refund button. Free refunds remain local. |
+| Lost webhook | Remains pending. Stripe retries; the AI can use `stripe events resend <event> --webhook-endpoint <endpoint>` (within Stripe's resend window). No grant from a browser return. Automatic provider-read reconciliation needs a key. |
+| Free orders | Local, including free carts; no Stripe account, API key or webhook secret required. |
+| Exact local eligibility/sale/repeat enforcement | Local checks run before redirect, but a public link can be reused. Sync deactivates removed links; strict pre-payment enforcement of previously issued links requires keyed sessions. |
+| Managed Payments | Payment Links support managed_payments.enabled; connect uses it when the studio selects Stripe as seller, subject to Stripe eligibility and terms. |
+| Currency display | Payment Links always enable Stripe Adaptive Pricing. Bookkeeping uses integration currency; presentment details describe what the customer saw. |
+
+An existing `STRIPE_KEY` selects the fuller path automatically. Only if requested, explain:
+“The fuller connection adds combined carts, spending limits, automatic recovery and refunds here.”
+The explicit `shop connect --manual` path remains available, including `--live`, but requires the
+owner's existing Dashboard key step; it does not satisfy one approval. Never choose it automatically.
+Running default connect again saves links, removes the API key, and keeps signed-event fulfillment.
+When switching to spending restrictions, the AI must deactivate previously issued Payment Links through
+the approved CLI and resolve in-flight checkouts before relying on those restrictions; switching credentials
+does not cancel old Stripe sessions. The runtime OAuth finding and sources are in `docs/stripe-connect-research.md` in the source checkout.
+
+`shop`, `shop orders`, and `/_studio/office/shop` show readiness and sales. Stripe's optional MCP
+is useful for owner-requested refunds and analytics; honor its approval links. Do not create a
+secret-returning webhook through a conversation tool: the private connect process owns that call.
 
 ## Payment guarantees and schema
 
@@ -145,7 +183,7 @@ an untagged Dashboard refund revokes items only when the whole order is refunded
 Unneeded signed events are acknowledged without recording. A refund or dispute naming an unrecorded payment
 of this database recovers its Checkout Session first, regardless of event age.
 
-Sessions reserve the optional cap until Stripe confirms an outcome. With the default lifetime, a sessionless
+**With an API key**, sessions reserve the optional cap until Stripe confirms an outcome. With the default lifetime, a sessionless
 reservation ages out after 24 hours plus a one-minute margin; your `checkoutMinutes` changes that window.
 [Stripe session lifetime](https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-expires_at)
 and [expiring open sessions](https://docs.stripe.com/api/checkout/sessions/expire) define these provider bounds.
@@ -153,7 +191,7 @@ Replacing an open checkout expires only reservations at least a minute old; a na
 Unresolved orders become eligible for reconciliation after one minute, even with no cap. A buyer's next shop
 or owned-items request schedules up to three reads off the response path, with atomic claims and backoff up
 to an hour; an optional Worker cron invokes the same reconciliation across buyers. No cron is installed for you. To run it every five minutes, add `"triggers": { "crons": ["*/5 * * * *"] }` to the studio’s root `wrangler.jsonc`; deploy preserves its triggers.
-Every recorded payment checks Stripe’s refunds and dispute state, including payments recovered by an early refund or dispute event. The thanks page can verify a payment directly with the studio's key. Webhook events require Stripe's signature.
+With an API key, every recorded payment checks Stripe’s refunds and dispute state, including payments recovered by an early refund or dispute event. The thanks page can verify a payment directly with the studio's key. Webhook events require Stripe's signature.
 Test and live books stay separate. Owner release attempts to expire an open session, records who released it
 and when, and never prevents a later verified payment grant.
 

package/worker/shop-links.mjs

@@ -0,0 +1,46 @@
+/** Shared setup/runtime contract. Payment Links are public; credentials never enter this value. */
+import { KEY_SHAPE, modeOf } from './stripe.mjs';
+// Current documented Payment Link fields, isolated from the existing keyed transport version.
+export const LINKS_STRIPE_VERSION = '2026-09-30.endive';
+export const hasStripeKey = (env) => KEY_SHAPE.test(String(env?.STRIPE_KEY ?? ''));
+export function linkConfig(env) {
+  try { const c = JSON.parse(env?.STRIPE_SHOP_LINKS ?? 'null'); return c?.v === 1 && ['test', 'live'].includes(c.mode) && Array.isArray(c.items) ? c : null; } catch { return null; }
+}
+export const shopMode = (env) => hasStripeKey(env) ? modeOf(env.STRIPE_KEY) : linkConfig(env)?.mode ?? 'test';
+export function linkSettings(shop) {
+  return JSON.stringify({ currency: shop.currency, till: shop.till, automaticTax: shop.automaticTax, policy: shop.policy,
+    cap: shop.capPerPlayerMonth, checkoutMinutes: shop.checkoutMinutes, items: shop.items });
+}
+export function fullerReason(shop) {
+  if (shop.capPerPlayerMonth !== null) return 'Reserving a spending allowance before payment needs the fuller checkout connection.';
+  if (shop.checkoutMinutes !== 1440) return 'Choosing when abandoned checkouts expire needs the fuller checkout connection.';
+  return null;
+}
+export function paymentLinkURL(value) {
+  try { const u = new URL(value); return u.protocol === 'https:' && u.hostname === 'buy.stripe.com' && !u.username && !u.password && !u.port; } catch { return false; }
+}
+
+/** Only signed snapshot events call this. Store financial fields, never customer/card data.
+ * Existing meta is a durable KV table. One row per provider object avoids read/modify/write races.
+ * Terminal failed/canceled refunds beat stale succeeded snapshots (including same-second events).
+ */
+export async function rememberMoneyEvent(env, event) {
+  const o = event.data.object, mode = event.livemode ? 'live' : 'test';
+  const put = async (kind, value, rank) => {
+    if (!/^pi_\w+$/.test(value.payment_intent ?? '') || !/^(re|dp)_\w+$/.test(value.id ?? '')) return;
+    const key = `shop-money:${mode}:${value.payment_intent}:${kind}:${value.id}`;
+    const record = JSON.stringify({ ...value, at: event.created ?? 0, rank });
+    await env.DB.prepare(`INSERT INTO meta (key, value) VALUES (?1, ?2) ON CONFLICT(key) DO UPDATE SET value = excluded.value
+      WHERE json_extract(excluded.value, '$.rank') > json_extract(meta.value, '$.rank') OR
+      (json_extract(excluded.value, '$.rank') = json_extract(meta.value, '$.rank') AND json_extract(excluded.value, '$.at') >= json_extract(meta.value, '$.at'))`).bind(key, record).run();
+  };
+  const refund = (r) => put('refund', { id: r.id, payment_intent: r.payment_intent ?? o.payment_intent, amount: r.amount, currency: r.currency ?? o.currency, status: r.status, metadata: r.metadata?.line ? { line: r.metadata.line } : {} }, ['failed', 'canceled'].includes(r.status) ? 3 : r.status === 'succeeded' ? 2 : 1);
+  if (event.type.startsWith('refund.')) await refund(o);
+  if (event.type === 'charge.refunded') for (const r of o.refunds?.data ?? []) await refund(r);
+  if (event.type.startsWith('charge.dispute.')) await put('dispute', { id: o.id, payment_intent: o.payment_intent, status: o.status }, event.type.endsWith('.closed') ? 2 : 1);
+}
+export async function rememberedMoney(env, payment, mode) {
+  const prefix = `shop-money:${mode}:${payment}:`;
+  const rows = (await env.DB.prepare('SELECT value FROM meta WHERE key >= ?1 AND key < ?2').bind(prefix, prefix + '\uffff').all()).results ?? [];
+  return rows.map((r) => JSON.parse(r.value));
+}

package/worker/shop-page.mjs

@@ -211,7 +211,7 @@ export const SHOP_JS = String.raw`(function () {
       if (i.way === 'cap' && i.retryWay) { act.appendChild(el('span', { class: 'why' }, WAY.cap)); i.way = i.retryWay; }
       if (i.way === 'checkout') {
         var amount = null;
-        if (i.price === 'choose') {
+        if (i.price === 'choose' && !s.keyless) {
           amount = el('input', { type: 'number', 'aria-label': 'How much in ' + s.currency.toUpperCase(), min: String(i.min / s.currencyScale), step: String(s.amountStep / s.currencyScale), value: String(i.min / s.currencyScale) });
           if (i.max !== null) amount.setAttribute('max', String(i.max / s.currencyScale));
           act.appendChild(amount);
@@ -228,7 +228,8 @@ export const SHOP_JS = String.raw`(function () {
         var quantity = el('input', { type: 'number', min: '1', step: '1', value: '1', 'aria-label': 'Quantity' });
         var add = el('button', { type: 'button', class: 'plain' }, 'Add to cart');
         add.onclick = function () { cart.push({ item: i.id, name: i.name, quantity: Number(quantity.value), amount: amount ? units(amount.value, s.currencyScale) : undefined }); drawCart(); };
-        act.appendChild(quantity); act.appendChild(add);
+        if (!s.keyless) { act.appendChild(quantity); act.appendChild(add); }
+        else if (i.price !== 0) act.appendChild(el('p', { class: 'note' }, i.price === 'choose' ? 'Choose your amount on Stripe.' : 'Confirm quantity on Stripe. Buy different items separately.'));
       } else if (i.way === 'owned') {
         act.appendChild(el('span', { class: 'owned' }, 'Yours ✓'));
       } else if (i.way === 'make-an-account') {
@@ -524,6 +525,7 @@ export const OFFICE_SHOP_SCRIPT = String.raw`(function () {
       [['Payments', s.stripe.payments], ['Refunds', s.stripe.refunds], ['Disputes', s.stripe.disputes], ['Payouts', s.stripe.payouts], ['Balance', s.stripe.balance], ['Tax', s.stripe.tax]].concat(s.stripe.managedPayments ? [['Managed Payments', s.stripe.managedPayments]] : []).forEach(function (l) { links.appendChild(link(l[1], l[0])); });
       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.'));
       var ord = $('#orders'); ord.textContent = '';
       if (!s.orders.length) ord.appendChild(el('p', { class: 'empty' }, 'No orders yet.'));
@@ -651,7 +653,7 @@ export async function officeShopPage(cat) {
 <div class="game" style="padding:6px 16px 12px"><h3>Orders</h3><div id="orders"></div></div>
 <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. Refund is one tap here (your AI can only ask, and you confirm). 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>`;
+<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 }), {
     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'` },
   });