@homie-rocks/studio 0.33.1 → 0.35.0

package/worker/shop-rules.mjs

@@ -5,15 +5,12 @@ export const TILLS = Object.freeze(['stripe', 'stripe-managed', 'off']);
 export const POLICY_PRESETS = Object.freeze({
   protective: Object.freeze({ withdrawalAcknowledgement: true, childAge: 13, adultAge: 18, requireAccount: true, ageQuestion: true, children: 'deny', teens: 'parent',
     kidsStudio: false, kidsServer: false, beginnerAdvantages: false, kidsAdvantages: false,
-    paidRandomRewards: false, countdownOffers: false, virtualCurrency: false, supporterAdvantages: false,
     repeatPurchases: false, refundUsedItems: false, televisionCheckout: false }),
   'adults-only': Object.freeze({ withdrawalAcknowledgement: true, childAge: 13, adultAge: 18, requireAccount: true, ageQuestion: true, children: 'deny', teens: 'deny',
     kidsStudio: false, kidsServer: false, beginnerAdvantages: false, kidsAdvantages: false,
-    paidRandomRewards: false, countdownOffers: false, virtualCurrency: false, supporterAdvantages: false,
     repeatPurchases: false, refundUsedItems: false, televisionCheckout: false }),
-  custom: Object.freeze({ withdrawalAcknowledgement: true, childAge: 13, adultAge: 18, requireAccount: false, ageQuestion: false, children: 'allow', teens: 'allow',
+  custom: Object.freeze({ withdrawalAcknowledgement: false, childAge: 13, adultAge: 18, requireAccount: false, ageQuestion: false, children: 'allow', teens: 'allow',
     kidsStudio: true, kidsServer: true, beginnerAdvantages: true, kidsAdvantages: true,
-    paidRandomRewards: true, countdownOffers: true, virtualCurrency: true, supporterAdvantages: true,
     repeatPurchases: true, refundUsedItems: true, televisionCheckout: true }),
 });
 export const ITEM_ID = /^[^\u0000-\u001f\u007f]+$/;
@@ -50,38 +47,28 @@ export function amountError(amount, currency) {
   return null;
 }
 
+/** Round a decimal rate times integer money exactly, including exponent notation. */
+export function referralShare(amount, rate) {
+  const [digits, exponent = '0'] = String(rate).toLowerCase().split('e');
+  const [whole, fraction = ''] = digits.split('.');
+  const scale = fraction.length - Number(exponent);
+  let numerator = BigInt(whole + fraction), denominator = 1n;
+  if (scale > 0) denominator = 10n ** BigInt(scale); else numerator *= 10n ** BigInt(-scale);
+  const share = Number((2n * BigInt(amount) * numerator + denominator) / (2n * denominator));
+  if (!Number.isSafeInteger(share)) throw new RangeError('Referral share exceeds safe integer arithmetic');
+  return share;
+}
+
 /** Checkout wording is shared by validation and the request path. */
 export function checkoutMessage(shop, studio = 'this studio', parent = false) {
   return `${parent ? "This is for your child's account. " : ''}Delivered at once to the player's account on ${studio}. ${shop.policy.withdrawalAcknowledgement ? 'By paying you ask for it now, which ends the 14-day withdrawal right;' : 'Your statutory rights still apply.'} ${shop.refundDays === null ? (shop.policy.withdrawalAcknowledgement ? 'ask the studio about refunds.' : 'Ask the studio about refunds.') : `${shop.policy.refundUsedItems ? 'an item' : 'an unused item'} can still be refunded within ${shop.refundDays} days.`}`;
 }
 
-/** Content patterns used only when the studio's paidRandomRewards policy refuses them. */
-const RANDOM_WORDS = /\b(?:chance|chances|odds|random|randomi[sz]ed|randomly|crates?|box|boxes|lootbox(?:es)?|loot|mystery|gacha|spins?|roll|rolls|lottery|raffle|sweepstakes?|jackpot|surprise|blind ?bag|drop ?rate|pity)\b/i;
-/** Fields that only exist to make an item random. */
-const RANDOM_FIELDS = new Set(['odds', 'chance', 'chances', 'random', 'pool', 'drops', 'droptable', 'loottable', 'weights', 'rarityweights', 'probability', 'probabilities']);
-/** Fields that only exist to pressure: a clock on an offer. */
-const PRESSURE_FIELDS = new Set(['countdown', 'timer', 'hurry', 'limitedtime', 'flash', 'flashsale', 'expiresin', 'urgency', 'scarcity', 'onlyleft']);
-const CURRENCY_KEYS = /^(?:gems?|coins?|currency|credits?|points|tokens|bucks|diamonds|crystals|vbucks|robux):/i;
-
 const numeric = (value) => typeof value === 'number' ? value : typeof value === 'string' && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(value) ? Number(value) : NaN;
 
 const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const oneLine = (v, max = Infinity) => String(v ?? '').replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
 
-/** Every string in a value, with the key path it sits at (to name where a forbidden word is). */
-function strings(v, at = '', out = []) {
-  if (typeof v === 'string') out.push([at, v]);
-  else if (Array.isArray(v)) v.forEach((x, i) => strings(x, `${at}[${i}]`, out));
-  else if (isObj(v)) for (const [k, x] of Object.entries(v)) { out.push([`${at}${at ? '.' : ''}${k}`, k]); strings(x, `${at}${at ? '.' : ''}${k}`, out); }
-  return out;
-}
-/** Every key in a value, lower-cased, with its path. */
-function keys(v, at = '', out = []) {
-  if (Array.isArray(v)) v.forEach((x, i) => keys(x, `${at}[${i}]`, out));
-  else if (isObj(v)) for (const [k, x] of Object.entries(v)) { const p = `${at}${at ? '.' : ''}${k}`; out.push([p, k.toLowerCase().replace(/[^a-z]/g, '')]); keys(x, p, out); }
-  return out;
-}
-
 /** "2026-11-01" or an ISO time: its ms, or null. */
 function dateOf(v) {
   if (v === undefined || v === null || v === '') return null;
@@ -107,15 +94,15 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
   const warnings = [];
   const err = (at, message) => errors.push({ at, message });
   if (!isObj(raw)) return { ok: false, shop: null, errors: [{ at: '', message: 'shop.json is a JSON object: { "till": "stripe", "currency": "usd", "items": [...] }' }], warnings };
-  const preset = raw.policy?.preset ?? 'protective';
+  const preset = raw.policy?.preset ?? 'custom';
   if (!Object.hasOwn(POLICY_PRESETS, preset)) err('policy.preset', 'choose protective, adults-only or custom');
   if (raw.policy !== undefined && !isObj(raw.policy)) err('policy', 'policy is an object with a named preset and editable rules');
-  const policy = { preset, ...(Object.hasOwn(POLICY_PRESETS, preset) ? POLICY_PRESETS[preset] : POLICY_PRESETS.protective) };
+  const policy = { preset, ...(Object.hasOwn(POLICY_PRESETS, preset) ? POLICY_PRESETS[preset] : POLICY_PRESETS.custom) };
   for (const key of Object.keys(POLICY_PRESETS.protective)) {
     if (raw.policy?.[key] === undefined) continue;
     const value = raw.policy[key];
     if (['childAge', 'adultAge'].includes(key)) {
-      if (!Number.isSafeInteger(value) || value < 1) err(`policy.${key}`, 'use a positive whole age in years');
+      if (!Number.isSafeInteger(value) || value < 0) err(`policy.${key}`, 'use a nonnegative whole age in years');
       else policy[key] = value;
       continue;
     }
@@ -123,13 +110,6 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
     else policy[key] = value;
   }
   if (policy.childAge >= policy.adultAge) err('policy.adultAge', 'adultAge must be greater than childAge');
-  for (const [at, text] of strings(raw.items)) {
-    if (!policy.paidRandomRewards && RANDOM_WORDS.test(text)) err(`items.${at}`, `The studio's policy.paidRandomRewards setting refuses paid randomness: "${oneLine(text, 40)}".`);
-  }
-  for (const [at, k] of keys(raw.items)) {
-    if (!policy.paidRandomRewards && RANDOM_FIELDS.has(k)) err(`items.${at}`, "The studio's policy.paidRandomRewards setting refuses odds, drops or a random pool.");
-    if (!policy.countdownOffers && PRESSURE_FIELDS.has(k)) err(`items.${at}`, "The studio's policy.countdownOffers setting refuses countdown fields.");
-  }
   const till = raw.till === undefined ? 'stripe' : String(raw.till);
   if (!TILLS.includes(till)) err('till', 'till is "stripe" (your own Stripe: you are the seller), "stripe-managed" (Stripe Managed Payments: Stripe is the seller of record and files the tax, for 3.5% more) or "off"');
   const currency = raw.currency === undefined ? 'usd' : String(raw.currency).toLowerCase();
@@ -141,6 +121,11 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
     if (at.endsWith('Days') && value !== null && (!Number.isSafeInteger(Math.round(value * 86400000)) || !Number.isSafeInteger(Math.round(value * 86400000) + Date.now()) || !Number.isFinite(new Date(Math.round(value * 86400000) + Date.now()).getTime()))) err(at, 'duration rounded to milliseconds must remain within safe arithmetic and the JavaScript timestamp range');
     return value;
   };
+  // Stripe permits 30 minutes to 24 hours; 24 hours is its default.
+  // https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-expires_at
+  const checkoutMinutes = numeric(raw.checkoutMinutes ?? 1440);
+  if (!Number.isSafeInteger(checkoutMinutes * 60) || checkoutMinutes < 30 || checkoutMinutes > 1440) err('checkoutMinutes', 'Stripe accepts 30 to 1440 minutes (24 hours), in whole seconds.');
+  const requestBytes = optionalNumber(raw.requestBytes, 'requestBytes');
   const refundDays = optionalNumber(raw.refundDays, 'refundDays');
   const cap = optionalNumber(raw.capPerPlayerMonth, 'capPerPlayerMonth');
   // 600 new buyers per hour allows a school or venue to arrive together without disabling flood protection.
@@ -151,8 +136,8 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
   const purchaseAttemptsPerAddressPerMinute = numeric(raw.purchaseAttemptsPerAddressPerMinute ?? 600);
   if (!Number.isSafeInteger(purchaseAttemptsPerAddressPerMinute) || purchaseAttemptsPerAddressPerMinute < 1) err('purchaseAttemptsPerAddressPerMinute', 'use a positive whole number for address flood protection');
   if (!Number.isSafeInteger(purchaseAttemptsPerMinute) || purchaseAttemptsPerMinute < 1) err('purchaseAttemptsPerMinute', 'use a positive whole number for the studio account rate limit');
-  if (raw.supportHomie !== undefined && Number(raw.supportHomie) !== 0) err('supportHomie', 'Homie takes no cut; this adapter does not transfer a share to Homie');
 
+  for (const key of ['automaticTax', 'referralNewPlayersOnly']) if (raw[key] !== undefined && typeof raw[key] !== 'boolean') err(key, 'use a boolean');
   const items = [];
   const list = Array.isArray(raw.items) ? raw.items : [];
   if (raw.items !== undefined && !Array.isArray(raw.items)) err('items', 'items is a list');
@@ -164,9 +149,7 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
     if (!id.trim() || !ITEM_ID.test(id)) err(`${at}.id`, 'id is nonempty text without control characters');
     else if (seen.has(id)) err(`${at}.id`, `two items are called "${id}"`);
     seen.add(id);
-    const kind = String(it.kind ?? '');
-    if (!kind.trim()) err(`${at}.kind`, 'an item needs a kind chosen by the studio');
-    if (!policy.virtualCurrency && ['gems', 'coins', 'currency'].includes(kind)) err(`${at}.kind`, "The studio's policy.virtualCurrency setting refuses currency items.");
+    const kind = String(it.kind ?? 'item');
     const name = oneLine(it.name);
     if (!name) err(`${at}.name`, 'an item needs a name the buyer reads');
     const blurb = oneLine(it.blurb ?? it.description);
@@ -174,8 +157,8 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
     if ([...name].length > 5000) err(`${at}.name`, 'Stripe product names allow at most 5000 characters. Shorten the name.');
     if ([...blurb].length > 40000) err(`${at}.blurb`, 'Stripe product descriptions allow at most 40000 characters. Shorten the description.');
     let price = null; let min = null; let max = null;
-    if (kind === 'tip') {
-      if (it.price !== 'choose' && it.price !== undefined) err(`${at}.price`, 'a tip\'s price is "choose" (pay what you want between min and max)');
+    const chosen = it.price === 'choose' || kind === 'tip' && it.price === undefined;
+    if (chosen) {
       min = numeric(it.min ?? 0); max = optionalNumber(it.max, `${at}.max`);
       const why = amountError(min, currency);
       if (why) err(`${at}.min`, why);
@@ -185,7 +168,7 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
       if (why) err(`${at}.price`, why);
       else price = numeric(it.price);
     }
-    const charge = kind === 'tip' ? min : price;
+    const charge = chosen ? min : price;
     if (currencyScale(currency) === 1000 && charge % 10) warnings.push({ at: `${at}.price`, message: 'This three-decimal amount uses the smallest minor unit. Confirm support with your Stripe payment method; Stripe decides acceptance (https://docs.stripe.com/currencies).' });
     if (charge > 0 && charge < minimumCharge(currency)) warnings.push({ at: `${at}.price`, message: `Stripe's minimum for settlement in ${currency.toUpperCase()} is ${money(minimumCharge(currency), currency)}. Your settlement currency and payment method determine the actual minimum at checkout.` });
     if (cap !== null && price !== null && price > cap) warnings.push({ at: `${at}.price`, message: 'This price exceeds the studio capPerPlayerMonth setting; raise or remove that setting to allow a purchase.' });
@@ -193,12 +176,11 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
     if (it.gives !== undefined && !Array.isArray(it.gives)) err(`${at}.gives`, 'gives is a list of entitlement keys the game reads: ["skin:ember"]');
     for (const g of gives) {
       if (!g.trim() || !ENTITLEMENT_KEY.test(g)) err(`${at}.gives`, `"${oneLine(g, 40)}" is not a key: use nonempty text without control characters`);
-      else if (!policy.virtualCurrency && CURRENCY_KEYS.test(g)) err(`${at}.gives`, `"${g}" is a currency refused by the studio policy.virtualCurrency setting`);
     }
     let days = null;
     if (it.days !== undefined && it.days !== null) {
       days = numeric(it.days);
-      if (!(days > 0 && Number.isFinite(days) && Number.isSafeInteger(Math.round(days * 86400000)) && Number.isSafeInteger(Math.round(days * 86400000) + Date.now()) && Number.isFinite(new Date(Math.round(days * 86400000) + Date.now()).getTime()))) { err(`${at}.days`, 'days is a positive duration with whole milliseconds within safe arithmetic and the JavaScript timestamp range (omit for forever)'); days = null; }
+      if (!(days >= 0 && Number.isFinite(days) && Number.isSafeInteger(Math.round(days * 86400000)) && Number.isSafeInteger(Math.round(days * 86400000) + Date.now()) && Number.isFinite(new Date(Math.round(days * 86400000) + Date.now()).getTime()))) { err(`${at}.days`, 'days is a nonnegative duration with whole milliseconds within safe arithmetic and the JavaScript timestamp range (omit for forever)'); days = null; }
     }
     const starts = dateOf(it.starts);
     const ends = dateOf(it.ends);
@@ -211,16 +193,15 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
     }
     if (it.taxCode !== undefined && !TAX_CODE.test(String(it.taxCode))) err(`${at}.taxCode`, 'taxCode is a Stripe product tax code such as "txcd_10000000"');
     const advantage = it.advantage === true;
-    if (advantage && kind === 'supporter' && !policy.supporterAdvantages) err(`${at}.advantage`, 'the studio policy.supporterAdvantages setting refuses an advantage in a supporter pack');
     const badge = gives.find((g) => g.startsWith('badge:'));
     for (const key of Object.keys(it)) {
       if (!['id', 'kind', 'name', 'blurb', 'description', 'price', 'min', 'max', 'gives', 'badge', 'days', 'starts', 'ends', 'game', 'taxCode', 'advantage'].includes(key)) warnings.push({ at: `${at}.${key}`, message: 'This field is not published by the shop. Describe any buyer-facing meaning in blurb so buyers can read it.' });
     }
     items.push({
       id, kind, name, ...(blurb ? { blurb } : {}),
-      ...(kind === 'tip' ? { price: 'choose', min, max } : { price }),
+      ...(chosen ? { price: 'choose', min, max } : { price }),
       gives, ...(badge ? { badge: badgeWord(badge, it) } : {}),
-      ...(days ? { days } : {}), ...(Number.isFinite(starts) ? { starts: new Date(starts).toISOString() } : {}), ...(Number.isFinite(ends) ? { ends: new Date(ends).toISOString() } : {}),
+      ...(days !== null ? { days } : {}), ...(Number.isFinite(starts) ? { starts: new Date(starts).toISOString() } : {}), ...(Number.isFinite(ends) ? { ends: new Date(ends).toISOString() } : {}),
       ...(it.game ? { game: String(it.game) } : {}), ...(it.taxCode ? { taxCode: String(it.taxCode) } : {}),
       advantage,
     });
@@ -231,14 +212,14 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
     const r = raw.referrals;
     if (!isObj(r)) err('referrals', 'referrals is { "rate": 0.10, "windowDays": 30, "capPerPlayer": 1000, "holdDays": 30, "minimumInvoice": 2500 } (or leave it out: nobody is paid for sending players)');
     else {
-      const rate = optionalNumber(r.rate ?? 0.10, 'referrals.rate', { integer: false });
+      const rate = optionalNumber(r.rate ?? 0, 'referrals.rate', { integer: false });
       const windowDays = optionalNumber(r.windowDays, 'referrals.windowDays');
       const capPerPlayer = optionalNumber(r.capPerPlayer, 'referrals.capPerPlayer');
       const holdDays = optionalNumber(r.holdDays, 'referrals.holdDays');
       const minimumInvoice = optionalNumber(r.minimumInvoice, 'referrals.minimumInvoice');
-      const accept = Array.isArray(r.accept) ? r.accept.map(String) : ['stripe-invoice'];
+      const accept = Array.isArray(r.accept) ? r.accept.map(String) : [];
       const billing = r.billingEmail === undefined ? null : String(r.billingEmail);
-      if (billing !== null && !/^[^\s@<>()",;:]{1,64}@[A-Za-z0-9.-]{1,190}\.[A-Za-z]{2,24}$/.test(billing)) err('referrals.billingEmail', 'billingEmail is where referrers send their invoices (an address the studio reads)');
+      if (billing !== null && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(billing)) err('referrals.billingEmail', 'billingEmail is where referrers send their invoices (an address the studio reads)');
       referrals = { rate, windowDays, capPerPlayer, holdDays, minimumInvoice, basis: 'pre-tax', accept, ...(billing ? { billingEmail: billing } : {}) };
     }
   }
@@ -254,7 +235,7 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
   const finalTill = kids ? 'off' : TILLS.includes(till) ? till : 'off';
   if (kids && till !== 'off') warnings.push({ at: 'till', message: 'studio.json says "audience": "kids": the studio sells nothing in its games (the till is off under policy.kidsStudio).' });
   const shop = {
-    v: 1, policy, guestBuyersPerAddressPerHour, purchaseAttemptsPerMinute, purchaseAttemptsPerAddressPerMinute, till: finalTill, currency: CURRENCY.test(currency) ? currency : 'usd', refundDays, capPerPlayerMonth: cap, items, referrals,
+    v: 1, policy, checkoutMinutes, requestBytes, automaticTax: raw.automaticTax === true, referralNewPlayersOnly: raw.referralNewPlayersOnly === true, guestBuyersPerAddressPerHour, purchaseAttemptsPerMinute, purchaseAttemptsPerAddressPerMinute, till: finalTill, currency: CURRENCY.test(currency) ? currency : 'usd', refundDays, capPerPlayerMonth: cap, items, referrals,
     open: finalTill !== 'off' && items.length > 0, ...(kids ? { audience: 'kids' } : {}), ...(catalog.length ? { catalog } : {}),
   };
   // https://docs.stripe.com/api/checkout/sessions/create#create_checkout_session-custom_text-submit-message
@@ -280,10 +261,10 @@ export function audienceOf(studio) {
 /* ------------------------------------------------------------------ who may buy */
 
 /** The neutral age question's answer as a band (never stored as a date): child (under 13), teen (13-17), adult. */
-export function bandOf(year, now = new Date(), policy = POLICY_PRESETS.protective) {
-  const y = Math.floor(Number(year));
+export function bandOf(year, now = new Date(), policy = POLICY_PRESETS.custom) {
+  const y = (typeof year === 'number' || typeof year === 'string' && /^\d+$/.test(year)) ? Number(year) : NaN;
   const thisYear = now.getUTCFullYear();
-  if (!(Number.isSafeInteger(y) && y >= thisYear - 120 && y <= thisYear)) return null;
+  if (!(Number.isSafeInteger(y) && y >= 0 && y <= thisYear)) return null;
   // The youngest a person born that year can be: a year of birth alone never makes a child look older.
   const age = thisYear - y - 1;
   return age < policy.childAge ? 'child' : age < policy.adultAge ? 'teen' : 'adult';
@@ -299,11 +280,11 @@ export function bandOf(year, now = new Date(), policy = POLICY_PRESETS.protectiv
  *   'age-question'  the studio requires an age band before checkout
  *   'no'            the studio denies this age band
  *   'ask-a-parent'  13-17: a link a parent opens on their own device and pays in their own name
- *   'checkout'      an adult: Stripe's own page, one purchase at a time
+ *   'checkout'      Stripe's own page, with the requested cart
  *   'not-yet' / 'over'  a season pass before it starts or after it ends
  *   'cap'           this month's cap is reached
  */
-export function wayFor(item, { open = true, kids = false, beginner = false, player = null, band = null, owned = false, spent = 0, cap = null, policy = POLICY_PRESETS.protective, now = Date.now() } = {}) {
+export function wayFor(item, { open = true, kids = false, beginner = false, player = null, band = null, owned = false, spent = 0, cap = null, policy = POLICY_PRESETS.custom, now = Date.now() } = {}) {
   if (!open) return 'closed';
   if (kids && !policy.kidsServer) return 'kids';
   if (item.advantage && ((beginner && !policy.beginnerAdvantages) || (kids && !policy.kidsAdvantages))) return 'beginner';
@@ -313,7 +294,7 @@ export function wayFor(item, { open = true, kids = false, beginner = false, play
   if (policy.requireAccount && (!player || player.guest)) return 'make-an-account';
   if (policy.ageQuestion && !band) return 'age-question';
   if ((band === 'child' && policy.children === 'deny') || (band === 'teen' && policy.teens === 'deny')) return 'no';
-  const price = item.kind === 'tip' ? item.min : item.price;
+  const price = item.price === 'choose' ? item.min : item.price;
   if (price > 0 && cap !== null && spent + price > cap) return 'cap';
   if ((band === 'teen' && policy.teens === 'parent') || (band === 'child' && policy.children === 'parent')) return 'ask-a-parent';
   return 'checkout';

package/worker/shop-store.mjs

@@ -124,6 +124,53 @@ CREATE TABLE referral_edition_lines (
 ) WITHOUT ROWID;
 `;
 
+export const SHOP_LINES_FILE = '0012_shop_lines.sql';
+export const SHOP_LINES = `-- Each checkout retains its item snapshots and independently refundable lines.
+CREATE TABLE shop_order_lines (
+  id TEXT PRIMARY KEY, order_id TEXT NOT NULL, position INTEGER NOT NULL,
+  item TEXT NOT NULL, quantity INTEGER NOT NULL, unit_amount INTEGER NOT NULL,
+  amount INTEGER NOT NULL, total INTEGER, snapshot TEXT, status TEXT NOT NULL DEFAULT 'started',
+  refund TEXT, refunded_at INTEGER, refunded_amount INTEGER NOT NULL DEFAULT 0, refunded_net INTEGER NOT NULL DEFAULT 0, UNIQUE(order_id, position)
+);
+INSERT INTO shop_order_lines (id, order_id, position, item, quantity, unit_amount, amount, total, status, refund, refunded_at)
+SELECT id || '_0', id, 0, item, 1, amount, amount, total, status, refund, refunded_at FROM shop_orders;
+-- Keep the released entitlement key and columns intact for rolling deploys and rollback.
+CREATE TABLE shop_entitlement_lines (
+  player TEXT NOT NULL, key TEXT NOT NULL, item TEXT NOT NULL, order_id TEXT NOT NULL,
+  line_id TEXT NOT NULL, quantity INTEGER NOT NULL,
+  starts_at INTEGER NOT NULL, ends_at INTEGER, state TEXT NOT NULL,
+  PRIMARY KEY (player, key, order_id, line_id)
+) WITHOUT ROWID;
+CREATE TRIGGER shop_entitlements_delete AFTER DELETE ON entitlements BEGIN
+  DELETE FROM shop_entitlement_lines WHERE player = OLD.player AND key = OLD.key AND order_id = OLD.order_id;
+END;
+CREATE TRIGGER shop_entitlements_adopt AFTER UPDATE OF player ON entitlements BEGIN
+  UPDATE shop_entitlement_lines SET player = NEW.player WHERE player = OLD.player AND key = OLD.key AND order_id = OLD.order_id;
+END;
+UPDATE shop_order_lines SET refunded_amount = COALESCE(total, amount), refunded_net = amount WHERE status = 'refunded';
+ALTER TABLE shop_parent_links ADD COLUMN cart TEXT;
+ALTER TABLE shop_orders ADD COLUMN whole_refund TEXT;
+ALTER TABLE shop_orders ADD COLUMN referral_terms TEXT;
+ALTER TABLE shop_orders ADD COLUMN checkout_player TEXT;
+UPDATE shop_orders SET checkout_player = player;
+CREATE TRIGGER shop_checkout_player_insert AFTER INSERT ON shop_orders BEGIN
+  UPDATE shop_orders SET checkout_player = NEW.player WHERE id = NEW.id;
+END;
+CREATE TRIGGER shop_forget_checkout_player AFTER UPDATE OF player ON shop_orders WHEN NEW.player IS NULL BEGIN
+  UPDATE shop_orders SET checkout_player = NULL WHERE id = NEW.id;
+END;
+ALTER TABLE referral_lines ADD COLUMN original_share INTEGER;
+UPDATE referral_lines SET original_share = share;
+ALTER TABLE shop_orders ADD COLUMN attention INTEGER NOT NULL DEFAULT 1;
+UPDATE shop_orders SET attention = 0 WHERE status = 'paid' AND EXISTS (SELECT 1 FROM entitlements WHERE order_id = shop_orders.id);
+ALTER TABLE shop_orders ADD COLUMN refunded_amount INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE shop_orders ADD COLUMN refunded_net INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE shop_orders ADD COLUMN refund_revision INTEGER NOT NULL DEFAULT 0;
+UPDATE shop_orders SET refunded_amount = COALESCE(total, amount), refunded_net = amount WHERE status = 'refunded';
+CREATE INDEX shop_orders_attention_player ON shop_orders (mode, player, status, updated_at, id) WHERE attention = 1;
+CREATE INDEX shop_orders_attention ON shop_orders (mode, status, updated_at, id) WHERE attention = 1;
+`;
+
 const DAY = 86_400_000;
 export const ORDER_ID = /^ord_[A-Za-z0-9]{20}$/;
 const PLAYER_ID = /^pl_[A-Za-z0-9_-]{22}$/;
@@ -145,6 +192,11 @@ export async function migrationNeeded(env) {
     [SHOP_RESERVATIONS_FILE, 'SELECT expires_at FROM shop_orders LIMIT 1'],
     [SHOP_STATEMENTS_FILE, 'SELECT issued FROM referral_editions LIMIT 1'],
     [SHOP_STATEMENTS_FILE, 'SELECT edition FROM referral_edition_lines LIMIT 1'],
+    [SHOP_LINES_FILE, 'SELECT snapshot, total, refunded_amount FROM shop_order_lines LIMIT 1'],
+    [SHOP_LINES_FILE, 'SELECT line_id, quantity FROM shop_entitlement_lines LIMIT 1'],
+    [SHOP_LINES_FILE, 'SELECT referral_terms, checkout_player, attention, refunded_amount, refund_revision FROM shop_orders LIMIT 1'],
+    [SHOP_LINES_FILE, 'SELECT cart FROM shop_parent_links LIMIT 1'],
+    [SHOP_LINES_FILE, 'SELECT original_share FROM referral_lines LIMIT 1'],
   ]) {
     try { await env.DB.prepare(query).first(); } catch { return file; }
   }
@@ -174,14 +226,24 @@ export async function setBand(env, player, band) {
 export async function ownsOf(env, player, now = Date.now()) {
   if (!PLAYER_ID.test(String(player ?? ''))) return [];
   try {
-    const { results } = await env.DB.prepare("SELECT key, item, ends_at, used_at FROM entitlements WHERE player = ?1 AND state = 'active' AND starts_at <= ?2 AND (ends_at IS NULL OR ends_at > ?2) ORDER BY starts_at").bind(player, now).all();
-    const out = new Map();
+    let results;
+    try {
+      ({ results } = await env.DB.prepare("SELECT l.key, l.item, l.ends_at, e.used_at, l.quantity FROM shop_entitlement_lines l JOIN entitlements e ON e.player = l.player AND e.key = l.key AND e.order_id = l.order_id WHERE l.player = ?1 AND l.state = 'active' AND e.state = 'active' AND l.starts_at <= ?2 AND (l.ends_at IS NULL OR l.ends_at > ?2) UNION ALL SELECT e.key, e.item, e.ends_at, e.used_at, 1 AS quantity FROM entitlements e WHERE e.player = ?1 AND e.state = 'active' AND e.starts_at <= ?2 AND (e.ends_at IS NULL OR e.ends_at > ?2) AND NOT EXISTS (SELECT 1 FROM shop_entitlement_lines l WHERE l.player = e.player AND l.key = e.key AND l.order_id = e.order_id)").bind(player, now).all());
+    } catch {
+      ({ results } = await env.DB.prepare("SELECT key, item, ends_at, used_at, 1 AS quantity FROM entitlements WHERE player = ?1 AND state = 'active' AND starts_at <= ?2 AND (ends_at IS NULL OR ends_at > ?2) ORDER BY starts_at").bind(player, now).all());
+    }
+    const out = new Map(), quantities = new Map();
     for (const r of results ?? []) {
+      quantities.set(r.key, (quantities.get(r.key) ?? 0n) + BigInt(r.quantity));
       const until = r.ends_at === null ? null : Number(r.ends_at);
       const prev = out.get(r.key);
       // Two orders of the same key: the one that lasts longest wins.
       if (!prev || (prev.until !== null && (until === null || until > prev.until))) out.set(r.key, { key: r.key, item: r.item, until, used: r.used_at !== null && r.used_at !== undefined });
     }
+    for (const value of out.values()) {
+      const quantity = quantities.get(value.key);
+      value.quantity = quantity <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(quantity) : String(quantity);
+    }
     return [...out.values()];
   } catch { return []; }
 }
@@ -191,7 +253,7 @@ export async function spentThisMonth(env, player, now = Date.now()) {
   // A Stripe session remains reserved until Stripe confirms its outcome. Test rows never consume a live cap.
   const d = new Date(now);
   const start = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
-  const r = await env.DB.prepare("SELECT COALESCE(SUM(amount), 0) AS n FROM shop_orders WHERE player = ?1 AND mode = ?4 AND ((status IN ('paid', 'disputed') AND paid_at >= ?2) OR (status IN ('started', 'processing') AND (session IS NOT NULL OR COALESCE(expires_at, created_at + 1860000) + 60000 > ?3)))").bind(player, start, now, String(env.STRIPE_KEY).includes('_live_') ? 'live' : 'test').first();
+  const r = await env.DB.prepare("SELECT COALESCE(SUM(amount - refunded_net), 0) AS n FROM shop_orders WHERE player = ?1 AND mode = ?4 AND ((status IN ('paid', 'disputed') AND paid_at >= ?2) OR (status IN ('started', 'processing') AND (session IS NOT NULL OR COALESCE(expires_at, created_at + 1860000) + 60000 > ?3)))").bind(player, start, now, String(env.STRIPE_KEY).includes('_live_') ? 'live' : 'test').first();
   return Number(r?.n) || 0;
 }
 
@@ -200,13 +262,40 @@ export async function orderById(env, id) {
   try { return await env.DB.prepare('SELECT * FROM shop_orders WHERE id = ?1').bind(id).first(); } catch { return null; }
 }
 
+export async function orderLines(env, id) {
+  const o = await orderById(env, id);
+  if (!o) return [];
+  const fallback = { id: id + '_0', order_id: id, position: 0, item: o.item, quantity: 1, unit_amount: o.amount, amount: o.amount, total: o.total, snapshot: null, status: o.status, refund: o.refund, refunded_at: o.refunded_at };
+  try {
+    let rows = (await env.DB.prepare('SELECT * FROM shop_order_lines WHERE order_id = ?1 ORDER BY position').bind(id).all()).results ?? [];
+    if (!rows.length) {
+      await env.DB.prepare('INSERT INTO shop_order_lines (id, order_id, position, item, quantity, unit_amount, amount, total, status, refund, refunded_at) VALUES (?1, ?2, 0, ?3, 1, ?4, ?4, ?5, ?6, ?7, ?8) ON CONFLICT DO NOTHING').bind(fallback.id, id, o.item, o.amount, o.total, o.status, o.refund, o.refunded_at).run();
+      rows = (await env.DB.prepare('SELECT * FROM shop_order_lines WHERE order_id = ?1 ORDER BY position').bind(id).all()).results ?? [];
+    }
+    // A released Worker may have paid or refunded after the step without touching its single line.
+    if (rows.length === 1 && !rows[0].snapshot && o.paid_at !== null) {
+      await env.DB.prepare("UPDATE shop_order_lines SET status = ?2, total = ?3, refund = ?4, refunded_at = ?5, refunded_amount = CASE WHEN ?2 = 'refunded' THEN COALESCE(?3, amount) ELSE refunded_amount END, refunded_net = CASE WHEN ?2 = 'refunded' THEN amount ELSE refunded_net END WHERE id = ?1 AND snapshot IS NULL").bind(rows[0].id, o.status, o.total, o.refund, o.refunded_at).run();
+      rows[0] = { ...rows[0], status: o.status, total: o.total, refund: o.refund, refunded_at: o.refunded_at };
+    }
+    return rows.map((line) => ['refunded', 'lost', 'disputed'].includes(o.status) && (line.status !== 'refunded' || o.status === 'refunded') ? { ...line, status: o.status } : line);
+  } catch (error) {
+    if (!/no such table/i.test(String(error.message))) throw error;
+    return [fallback];
+  }
+}
+
+export function lineView(r) {
+  const item = r.snapshot ? JSON.parse(r.snapshot) : null;
+  return { id: r.id, refundedAmount: Number(r.refunded_amount ?? 0), item: r.item, name: item?.name ?? r.item, kind: item?.kind ?? null, quantity: Number(r.quantity), unitAmount: Number(r.unit_amount), amount: Number(r.amount), total: r.total === null ? null : Number(r.total), status: r.status, refundedAt: r.refunded_at };
+}
+
 export const orderBySession = (env, session) => env.DB.prepare('SELECT * FROM shop_orders WHERE session = ?1').bind(String(session ?? '')).first();
 export const orderByPayment = (env, payment) => env.DB.prepare('SELECT * FROM shop_orders WHERE payment = ?1').bind(String(payment ?? '')).first();
 
 /** An order as the player, the office and the export see it (never a card, never an email). */
 export function orderView(r) {
   return {
-    id: r.id, item: r.item, game: r.game ?? null, amount: Number(r.amount), currency: r.currency, tax: r.tax === null ? null : Number(r.tax), total: r.total === null ? null : Number(r.total),
+    id: r.id, refundedAmount: Number(r.refunded_amount ?? 0), item: r.item, game: r.game ?? null, amount: Number(r.amount), currency: r.currency, tax: r.tax === null ? null : Number(r.tax), total: r.total === null ? null : Number(r.total),
     status: r.status, till: r.till, mode: r.mode, parent: Number(r.parent) === 1, via: r.via ?? null,
     createdAt: Number(r.created_at), paidAt: r.paid_at === null ? null : Number(r.paid_at), refundedAt: r.refunded_at === null ? null : Number(r.refunded_at),
   };
@@ -221,6 +310,7 @@ export function playerOrderStatus(row) {
 export async function shopDataOf(env, player) {
   try {
     const orders = ((await env.DB.prepare("SELECT * FROM shop_orders WHERE player = ?1 AND status != 'started' ORDER BY created_at").bind(player).all()).results ?? []).filter((r) => playerOrderStatus(r) !== 'started').map((r) => orderView({ ...r, status: playerOrderStatus(r) }));
+    for (const order of orders) order.lines = (await orderLines(env, order.id)).map(lineView);
     const owns = await ownsOf(env, player);
     const band = await bandOfPlayer(env, player);
     return { orders, owns, ageBand: band };
@@ -246,15 +336,17 @@ export function forgetPlayerShop(env, player) {
 }
 
 /** Grant an order's entitlements (idempotent on player, key and order). */
-export function grantStatements(env, order, item, now = Date.now()) {
+export function grantStatements(env, order, item, now = Date.now(), line = { id: order.id + '_0', quantity: 1 }) {
   const starts = item.starts ? Math.max(now, Date.parse(item.starts)) : now;
-  const ends = item.ends ? Date.parse(item.ends) : item.days ? starts + Math.round(item.days * DAY) : null;
-  return (item.gives ?? []).map((key) => env.DB.prepare("INSERT INTO entitlements (player, key, item, order_id, starts_at, ends_at, state, used_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'active', NULL) ON CONFLICT(player, key, order_id) DO UPDATE SET state = 'active'")
-    .bind(order.player, key, item.id, order.id, starts, ends));
+  const ends = item.ends ? Date.parse(item.ends) : item.days !== undefined && item.days !== null ? starts + Math.round(item.days * DAY) : null;
+  return (item.gives ?? []).flatMap((key) => [
+    env.DB.prepare("INSERT INTO entitlements (player, key, item, order_id, starts_at, ends_at, state, used_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'active', NULL) ON CONFLICT(player, key, order_id) DO UPDATE SET starts_at = MIN(starts_at, excluded.starts_at), ends_at = CASE WHEN ends_at IS NULL OR excluded.ends_at IS NULL THEN NULL ELSE MAX(ends_at, excluded.ends_at) END").bind(order.player, key, item.id, order.id, starts, ends),
+    env.DB.prepare("INSERT INTO shop_entitlement_lines (player, key, item, order_id, line_id, quantity, starts_at, ends_at, state) SELECT ?1, ?2, ?3, ?4, ?7, ?8, ?5, ?6, 'active' WHERE NOT EXISTS (SELECT 1 FROM entitlements WHERE player = ?1 AND key = ?2 AND order_id = ?4 AND state != 'active') ON CONFLICT DO NOTHING").bind(order.player, key, item.id, order.id, starts, ends, line.id, line.quantity),
+  ]);
 }
 
 export const revokeStatement = (env, orderId) => env.DB.prepare("UPDATE entitlements SET state = 'revoked' WHERE order_id = ?1").bind(orderId);
-export const restoreStatement = (env, orderId) => env.DB.prepare("UPDATE entitlements SET state = 'active' WHERE order_id = ?1").bind(orderId);
+export const restoreStatement = (env, orderId) => env.DB.prepare("UPDATE entitlements SET state = 'active' WHERE order_id = ?1 AND EXISTS (SELECT 1 FROM shop_orders WHERE id = ?1 AND status = 'paid') AND EXISTS (SELECT 1 FROM shop_order_lines WHERE order_id = ?1 AND status != 'refunded') AND (NOT EXISTS (SELECT 1 FROM shop_entitlement_lines l WHERE l.order_id = ?1 AND l.key = entitlements.key) OR EXISTS (SELECT 1 FROM shop_entitlement_lines l WHERE l.order_id = ?1 AND l.key = entitlements.key AND l.state = 'active'))").bind(orderId);
 
 /** The badge a player shows in rooms (a supporter's), from what they own: the first live badge key, or null. */
 export async function badgeOf(env, player, shop) {