@aglyn/plugins-commerce 1.0.0-beta.221 → 1.0.0-beta.223

package/src/lib/model/commerce-gift-cards.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-gift-cards.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Gift-card hold arithmetic (AGL-2449).\n *\n * A gift card is CASH, and until this module existed it was the one limited\n * resource in the order path with no reserve at all. `cart-checkout.ts` read\n * `balanceCents` with a plain `.get()`, minted a Stripe coupon for that much,\n * and the webhook decremented the card minutes later with a bare\n * `FieldValue.increment(-N)`. The increment is atomic, so nothing was ever\n * LOST — but nothing ever CHECKED either, so two checkouts entering the same\n * code both read $50, both got $50 off, and the card settled at `-$50`. The\n * merchant shipped $100 of goods against a $50 card, and the outstanding\n * liability total went negative — the exact corruption `redeemExistingOrRecord`\n * already reasons about for a DELETED card, arriving through a live one.\n *\n * The stock fix (AGL-2320) could not be copied here: stock is decremented after\n * the money has moved and therefore cannot refuse, so it locks and reports the\n * shortfall. A gift card is applied BEFORE Stripe is contacted, so this door can\n * still say no — and refusing is the only thing that actually keeps the money.\n *\n * So the balance is HELD at checkout and SETTLED at the webhook, both in one\n * transaction against one document. Holds live in a map on the card itself\n * keyed by Stripe session id, which is what keeps this to a single-document\n * transaction: no fan-out, no second collection, no index.\n *\n * ## Why holds expire rather than being swept\n *\n * An abandoned checkout must not stand a customer's money off indefinitely, and\n * a sweep job is the wrong instrument: `process-abandoned.ts` is the only\n * existing sweep and it returns 501 when SMTP is unconfigured, so a\n * release that depended on it would not run at all for a self-hosted store with\n * no mail transport. Instead every hold carries `expiresAtMs` and EVERY read\n * prunes, so the release is a consequence of the next read rather than of a job\n * that may never run. A card nobody touches again holds nothing that matters,\n * because nobody is reading it either.\n *\n * The TTL matches Stripe's Checkout Session lifetime rather than something\n * shorter. A hold that lapsed while its session was still payable would reopen\n * the very window this closes — the shopper pays a session whose hold has\n * evaporated and the balance is spent twice again.\n */\n\n/** One in-flight claim on a card's balance, keyed by Stripe session id. */\nexport interface GiftCardHold {\n  cents: number\n  expiresAtMs: number\n}\n\n/**\n * Why a card cannot be redeemed for now (AGL-3363): the payment that bought\n * it drew an issuer's early fraud warning, a Radar review, or a dispute; or\n * part of it was refunded outside the console and the refund could not be\n * matched to the order's lines (`refund-review`).\n */\nexport type GiftCardFreezeReason =\n  | 'early-fraud-warning'\n  | 'radar-review'\n  | 'dispute'\n  | 'refund-review'\n\n/** Why a card's balance was taken back rather than spent. */\nexport type GiftCardVoidReason = 'refund' | 'dispute-lost'\n\n/** `hosts/{hostId}/giftCards/{code}` doc, as far as redemption cares. */\nexport interface HostGiftCard {\n  balanceCents?: number\n  /** Session id → hold. Absent on every card issued before AGL-2449. */\n  holds?: Record<string, GiftCardHold>\n  voidedAtMs?: number\n  voidedReason?: GiftCardVoidReason\n  /** Set while the purchase is under a fraud signal; nothing can redeem it. */\n  frozenAtMs?: number\n  frozenReason?: GiftCardFreezeReason\n}\n\n/*==========================================\n * GIFT CARDS ARE A CASH-OUT (AGL-3363).\n *\n * Buying store credit with a stolen card and spending it before the\n * chargeback lands is the standard way to turn card data into goods. Three\n * rules, all shared by every door that sells or redeems a card:\n *\n * 1. A PURCHASE HAS A CEILING. One checkout may buy at most\n *    {@link GIFT_CARD_PURCHASE_LIMITS} of gift cards — lower while the\n *    workspace is young, when a stolen-card storefront is likeliest — and\n *    one visitor may buy gift cards only so many times a day. A real shop's\n *    holiday order ($100 cards for a team) sits well inside both.\n * 2. A SIGNAL FREEZES. An early fraud warning, a Radar review or a dispute\n *    on the purchase freezes every card it issued (`frozenAtMs`): its balance\n *    stays, and nothing can redeem it until the merchant releases it or the\n *    dispute is won.\n * 3. A REVERSAL VOIDS. A refund of the purchase, or a lost dispute, zeroes\n *    what is left on its cards — the same zeroing the console's Void button\n *    does, never a delete (AGL-1767).\n *=========================================*/\n\nexport const GIFT_CARD_PURCHASE_LIMITS = {\n  /** Gift-card value one checkout may buy. */\n  perOrderCents: 500_000,\n  /** …while the workspace is young (`isYoungWorkspace`). */\n  perOrderCentsYoung: 50_000,\n  /** Checkouts buying gift cards, per visitor address per day. */\n  perVisitorDaily: 5,\n  /** …while the workspace is young. */\n  perVisitorDailyYoung: 2,\n} as const\n\n/** The refusal a checkout gives past the per-order ceiling, or null. */\nexport function giftCardPurchaseRefusal(input: {\n  giftCardCents: number\n  young: boolean\n}): string | null {\n  const ceiling = input.young\n    ? GIFT_CARD_PURCHASE_LIMITS.perOrderCentsYoung\n    : GIFT_CARD_PURCHASE_LIMITS.perOrderCents\n  if (!(input.giftCardCents > ceiling)) return null\n  // The ceiling is not named: a shopper who is testing it must not be told\n  // where it is. A real buyer of a large gift order is sent to the shop.\n  return (\n    'This order has more in gift cards than can be bought in one online ' +\n    'checkout. Please contact the shop to complete it.'\n  )\n}\n\n/** Is the card frozen by a fraud signal on the payment that bought it? */\nexport function isGiftCardFrozen(card: HostGiftCard | undefined): boolean {\n  return Number(card?.frozenAtMs) > 0\n}\n\n/**\n * Stripe Checkout Sessions expire 24h after creation, so a hold outlives any\n * session that can still be paid. See the module docblock for why a shorter\n * TTL is not the safer choice it looks like.\n */\nexport const GIFT_CARD_HOLD_TTL_MS = 24 * 60 * 60 * 1000\n\n/** One money figure off an untrusted document, as whole non-negative cents. */\nfunction cents(value: unknown): number {\n  const number = Math.round(Number(value))\n  return Number.isFinite(number) && number > 0 ? number : 0\n}\n\n/**\n * The card's holds with the lapsed ones dropped.\n *\n * Total, not a filter over a trusted shape: a hold whose `expiresAtMs` is\n * absent or non-numeric is treated as EXPIRED rather than eternal, so a\n * malformed row releases the money instead of stranding it. The one direction\n * that cannot be wrong is the one that keeps a customer from spending their own\n * balance forever.\n */\nexport function pruneGiftCardHolds(\n  holds: Record<string, GiftCardHold> | undefined,\n  nowMs: number,\n): Record<string, GiftCardHold> {\n  const live: Record<string, GiftCardHold> = {}\n  for (const [sessionId, hold] of Object.entries(holds ?? {})) {\n    const expiresAtMs = Number(hold?.expiresAtMs)\n    if (!Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs) continue\n    const amount = cents(hold?.cents)\n    if (amount > 0) live[sessionId] = { cents: amount, expiresAtMs }\n  }\n  return live\n}\n\n/**\n * What a NEW checkout may apply: the balance less every hold still standing.\n *\n * Never negative. A card whose holds already exceed its balance (possible only\n * on a card voided mid-flight, where the console zeroes `balanceCents` while\n * holds stand) reads as empty rather than as a debt to be collected.\n */\nexport function giftCardAvailableCents(\n  card: HostGiftCard | undefined,\n  nowMs: number,\n): number {\n  // A frozen card offers nothing to a NEW checkout (AGL-3363). Settlement of\n  // a hold placed before the freeze is left alone: that shopper has paid.\n  if (isGiftCardFrozen(card)) return 0\n  const held = Object.values(pruneGiftCardHolds(card?.holds, nowMs)).reduce(\n    (sum, hold) => sum + hold.cents,\n    0,\n  )\n  return Math.max(0, cents(card?.balanceCents) - held)\n}\n\n/**\n * What settling `sessionId` should actually take off the card.\n *\n * Capped at the live balance, not at the hold, and that is the point of the\n * function. The hold is what this session RESERVED; the balance is what the\n * card can still give up. They diverge when the card was voided or hand-adjusted\n * between the hold and the payment, and in that window paying out the hold would\n * drive the balance negative — reintroducing the corrupted liability aggregate\n * from the other side.\n *\n * A session with no hold settles ZERO. That is the redelivery case (the first\n * delivery consumed it) and the pre-AGL-2449 case (a session that predates\n * holds), and both must be no-ops rather than a second decrement.\n */\nexport function giftCardSettlementCents(\n  card: HostGiftCard | undefined,\n  sessionId: string,\n  // Deliberately unused, and kept so this reads as the sibling of\n  // `giftCardAvailableCents` at every call site. The asymmetry IS the rule\n  // below: availability is a question about now, settlement is not.\n  _nowMs: number,\n): number {\n  // NOT pruned: a hold that lapsed while its session sat unpaid is still owed\n  // once that session is paid. Expiry governs what a NEW checkout may claim,\n  // never whether a completed payment is honoured — dropping it here would take\n  // the discount from the shopper and give nothing back to the merchant.\n  const hold = (card?.holds ?? {})[sessionId]\n  return Math.min(cents(hold?.cents), cents(card?.balanceCents))\n}\n"],"names":["GIFT_CARD_PURCHASE_LIMITS","perOrderCents","perOrderCentsYoung","perVisitorDaily","perVisitorDailyYoung","giftCardPurchaseRefusal","input","ceiling","young","giftCardCents","isGiftCardFrozen","card","Number","frozenAtMs","GIFT_CARD_HOLD_TTL_MS","cents","value","number","Math","round","isFinite","pruneGiftCardHolds","holds","nowMs","live","sessionId","hold","Object","entries","expiresAtMs","amount","giftCardAvailableCents","held","values","reduce","sum","max","balanceCents","giftCardSettlementCents","_nowMs","min"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GAED,yEAAyE,GAiCzE;;;;;;;;;;;;;;;;;;;2CAmB2C,GAE3C,OAAO,MAAMA,4BAA4B;IACvC,0CAA0C,GAC1CC,eAAe;IACf,wDAAwD,GACxDC,oBAAoB;IACpB,8DAA8D,GAC9DC,iBAAiB;IACjB,mCAAmC,GACnCC,sBAAsB;AACxB,EAAU;AAEV,sEAAsE,GACtE,OAAO,SAASC,wBAAwBC,KAGvC;IACC,MAAMC,UAAUD,MAAME,KAAK,GACvBR,0BAA0BE,kBAAkB,GAC5CF,0BAA0BC,aAAa;IAC3C,IAAI,CAAEK,CAAAA,MAAMG,aAAa,GAAGF,OAAM,GAAI,OAAO;IAC7C,yEAAyE;IACzE,uEAAuE;IACvE,OACE,wEACA;AAEJ;AAEA,wEAAwE,GACxE,OAAO,SAASG,iBAAiBC,IAA8B;IAC7D,OAAOC,OAAOD,wBAAAA,KAAME,UAAU,IAAI;AACpC;AAEA;;;;CAIC,GACD,OAAO,MAAMC,wBAAwB,KAAK,KAAK,KAAK,KAAI;AAExD,6EAA6E,GAC7E,SAASC,MAAMC,KAAc;IAC3B,MAAMC,SAASC,KAAKC,KAAK,CAACP,OAAOI;IACjC,OAAOJ,OAAOQ,QAAQ,CAACH,WAAWA,SAAS,IAAIA,SAAS;AAC1D;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASI,mBACdC,KAA+C,EAC/CC,KAAa;IAEb,MAAMC,OAAqC,CAAC;IAC5C,KAAK,MAAM,CAACC,WAAWC,KAAK,IAAIC,OAAOC,OAAO,CAACN,gBAAAA,QAAS,CAAC,GAAI;QAC3D,MAAMO,cAAcjB,OAAOc,wBAAAA,KAAMG,WAAW;QAC5C,IAAI,CAACjB,OAAOQ,QAAQ,CAACS,gBAAgBA,eAAeN,OAAO;QAC3D,MAAMO,SAASf,MAAMW,wBAAAA,KAAMX,KAAK;QAChC,IAAIe,SAAS,GAAGN,IAAI,CAACC,UAAU,GAAG;YAAEV,OAAOe;YAAQD;QAAY;IACjE;IACA,OAAOL;AACT;AAEA;;;;;;CAMC,GACD,OAAO,SAASO,uBACdpB,IAA8B,EAC9BY,KAAa;IAEb,2EAA2E;IAC3E,wEAAwE;IACxE,IAAIb,iBAAiBC,OAAO,OAAO;IACnC,MAAMqB,OAAOL,OAAOM,MAAM,CAACZ,mBAAmBV,wBAAAA,KAAMW,KAAK,EAAEC,QAAQW,MAAM,CACvE,CAACC,KAAKT,OAASS,MAAMT,KAAKX,KAAK,EAC/B;IAEF,OAAOG,KAAKkB,GAAG,CAAC,GAAGrB,MAAMJ,wBAAAA,KAAM0B,YAAY,IAAIL;AACjD;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASM,wBACd3B,IAA8B,EAC9Bc,SAAiB,EACjB,gEAAgE;AAChE,yEAAyE;AACzE,kEAAkE;AAClEc,MAAc;;IAEd,4EAA4E;IAC5E,2EAA2E;IAC3E,8EAA8E;IAC9E,uEAAuE;IACvE,MAAMb,OAAO,SAACf,wBAAAA,KAAMW,KAAK,mBAAI,CAAC,EAAE,CAACG,UAAU;IAC3C,OAAOP,KAAKsB,GAAG,CAACzB,MAAMW,wBAAAA,KAAMX,KAAK,GAAGA,MAAMJ,wBAAAA,KAAM0B,YAAY;AAC9D"}
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-gift-cards.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Gift-card hold arithmetic (AGL-2449).\n *\n * A gift card is CASH, and until this module existed it was the one limited\n * resource in the order path with no reserve at all. `cart-checkout.ts` read\n * `balanceCents` with a plain `.get()`, minted a Stripe coupon for that much,\n * and the webhook decremented the card minutes later with a bare\n * `FieldValue.increment(-N)`. The increment is atomic, so nothing was ever\n * LOST — but nothing ever CHECKED either, so two checkouts entering the same\n * code both read $50, both got $50 off, and the card settled at `-$50`. The\n * merchant shipped $100 of goods against a $50 card, and the outstanding\n * liability total went negative — the exact corruption `redeemExistingOrRecord`\n * already reasons about for a DELETED card, arriving through a live one.\n *\n * The stock fix (AGL-2320) could not be copied here: stock is decremented after\n * the money has moved and therefore cannot refuse, so it locks and reports the\n * shortfall. A gift card is applied BEFORE Stripe is contacted, so this door can\n * still say no — and refusing is the only thing that actually keeps the money.\n *\n * So the balance is HELD at checkout and SETTLED at the webhook, both in one\n * transaction against one document. Holds live in a map on the card itself\n * keyed by Stripe session id, which is what keeps this to a single-document\n * transaction: no fan-out, no second collection, no index.\n *\n * ## Why holds expire rather than being swept\n *\n * An abandoned checkout must not stand a customer's money off indefinitely, and\n * a sweep job is the wrong instrument: `process-abandoned.ts` is the only\n * existing sweep and it returns 501 when SMTP is unconfigured, so a\n * release that depended on it would not run at all for a self-hosted store with\n * no mail transport. Instead every hold carries `expiresAtMs` and EVERY read\n * prunes, so the release is a consequence of the next read rather than of a job\n * that may never run. A card nobody touches again holds nothing that matters,\n * because nobody is reading it either.\n *\n * The TTL matches Stripe's Checkout Session lifetime rather than something\n * shorter. A hold that lapsed while its session was still payable would reopen\n * the very window this closes — the shopper pays a session whose hold has\n * evaporated and the balance is spent twice again.\n */\n\n/** One in-flight claim on a card's balance, keyed by Stripe session id. */\nexport interface GiftCardHold {\n  cents: number\n  expiresAtMs: number\n}\n\n/**\n * Why a card cannot be redeemed for now (AGL-3363): the payment that bought\n * it drew an issuer's early fraud warning, a Radar review, or a dispute; or\n * part of it was refunded outside the console and the refund could not be\n * matched to the order's lines (`refund-review`).\n */\nexport type GiftCardFreezeReason =\n  | 'early-fraud-warning'\n  | 'radar-review'\n  | 'dispute'\n  | 'refund-review'\n\n/** Why a card's balance was taken back rather than spent. */\nexport type GiftCardVoidReason = 'refund' | 'dispute-lost'\n\n/** `hosts/{hostId}/giftCards/{code}` doc, as far as redemption cares. */\nexport interface HostGiftCard {\n  balanceCents?: number\n  /** Session id → hold. Absent on every card issued before AGL-2449. */\n  holds?: Record<string, GiftCardHold>\n  voidedAtMs?: number\n  voidedReason?: GiftCardVoidReason\n  /** Set while the purchase is under a fraud signal; nothing can redeem it. */\n  frozenAtMs?: number\n  frozenReason?: GiftCardFreezeReason\n}\n\n/*==========================================\n * GIFT CARDS ARE A CASH-OUT (AGL-3363).\n *\n * Buying store credit with a stolen card and spending it before the\n * chargeback lands is the standard way to turn card data into goods. Three\n * rules, all shared by every door that sells or redeems a card:\n *\n * 1. A PURCHASE HAS A CEILING. One checkout may buy at most\n *    {@link GIFT_CARD_PURCHASE_LIMITS} of gift cards — lower while the\n *    workspace is young, when a stolen-card storefront is likeliest — and\n *    one visitor may buy gift cards only so many times a day. A real shop's\n *    holiday order ($100 cards for a team) sits well inside both.\n * 2. A SIGNAL FREEZES. An early fraud warning, a Radar review or a dispute\n *    on the purchase freezes every card it issued (`frozenAtMs`): its balance\n *    stays, and nothing can redeem it until the merchant releases it or the\n *    dispute is won.\n * 3. A REVERSAL VOIDS. A refund of the purchase, or a lost dispute, zeroes\n *    what is left on its cards — the same zeroing the console's Void button\n *    does, never a delete (AGL-1767).\n *=========================================*/\n\nexport const GIFT_CARD_PURCHASE_LIMITS = {\n  /** Gift-card value one checkout may buy. */\n  perOrderCents: 500_000,\n  /** …while the workspace is young (`isYoungWorkspace`). */\n  perOrderCentsYoung: 50_000,\n  /** Checkouts buying gift cards, per visitor address per day. */\n  perVisitorDaily: 5,\n  /** …while the workspace is young. */\n  perVisitorDailyYoung: 2,\n} as const\n\n/** The refusal a checkout gives past the per-order ceiling, or null. */\nexport function giftCardPurchaseRefusal(input: {\n  giftCardCents: number\n  young: boolean\n}): string | null {\n  const ceiling = input.young\n    ? GIFT_CARD_PURCHASE_LIMITS.perOrderCentsYoung\n    : GIFT_CARD_PURCHASE_LIMITS.perOrderCents\n  if (!(input.giftCardCents > ceiling)) return null\n  // The ceiling is not named: a shopper who is testing it must not be told\n  // where it is. A real buyer of a large gift order is sent to the shop.\n  return (\n    'This order has more in gift cards than can be bought in one online ' +\n    'checkout. Please contact the shop to complete it.'\n  )\n}\n\n/** Is the card frozen by a fraud signal on the payment that bought it? */\nexport function isGiftCardFrozen(card: HostGiftCard | undefined): boolean {\n  return Number(card?.frozenAtMs) > 0\n}\n\n/**\n * Stripe Checkout Sessions expire 24h after creation, so a hold outlives any\n * session that can still be paid. See the module docblock for why a shorter\n * TTL is not the safer choice it looks like.\n */\nexport const GIFT_CARD_HOLD_TTL_MS = 24 * 60 * 60 * 1000\n\n/** One money figure off an untrusted document, as whole non-negative cents. */\nfunction cents(value: unknown): number {\n  const number = Math.round(Number(value))\n  return Number.isFinite(number) && number > 0 ? number : 0\n}\n\n/**\n * The card's holds with the lapsed ones dropped.\n *\n * Total, not a filter over a trusted shape: a hold whose `expiresAtMs` is\n * absent or non-numeric is treated as EXPIRED rather than eternal, so a\n * malformed row releases the money instead of stranding it. The one direction\n * that cannot be wrong is the one that keeps a customer from spending their own\n * balance forever.\n */\nexport function pruneGiftCardHolds(\n  holds: Record<string, GiftCardHold> | undefined,\n  nowMs: number,\n): Record<string, GiftCardHold> {\n  const live: Record<string, GiftCardHold> = {}\n  for (const [sessionId, hold] of Object.entries(holds ?? {})) {\n    const expiresAtMs = Number(hold?.expiresAtMs)\n    if (!Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs) continue\n    const amount = cents(hold?.cents)\n    if (amount > 0) live[sessionId] = { cents: amount, expiresAtMs }\n  }\n  return live\n}\n\n/**\n * What a NEW checkout may apply: the balance less every hold still standing.\n *\n * Never negative. A card whose holds already exceed its balance (possible only\n * on a card voided mid-flight, where the console zeroes `balanceCents` while\n * holds stand) reads as empty rather than as a debt to be collected.\n */\nexport function giftCardAvailableCents(\n  card: HostGiftCard | undefined,\n  nowMs: number,\n): number {\n  // A frozen card offers nothing to a NEW checkout (AGL-3363). Settlement of\n  // a hold placed before the freeze is left alone: that shopper has paid.\n  if (isGiftCardFrozen(card)) return 0\n  const held = Object.values(pruneGiftCardHolds(card?.holds, nowMs)).reduce(\n    (sum, hold) => sum + hold.cents,\n    0,\n  )\n  return Math.max(0, cents(card?.balanceCents) - held)\n}\n\n/**\n * What settling `sessionId` should actually take off the card.\n *\n * Capped at the live balance, not at the hold, and that is the point of the\n * function. The hold is what this session RESERVED; the balance is what the\n * card can still give up. They diverge when the card was voided or hand-adjusted\n * between the hold and the payment, and in that window paying out the hold would\n * drive the balance negative — reintroducing the corrupted liability aggregate\n * from the other side.\n *\n * A session with no hold settles ZERO. That is the redelivery case (the first\n * delivery consumed it) and the pre-AGL-2449 case (a session that predates\n * holds), and both must be no-ops rather than a second decrement.\n */\nexport function giftCardSettlementCents(\n  card: HostGiftCard | undefined,\n  sessionId: string,\n  // Deliberately unused, and kept so this reads as the sibling of\n  // `giftCardAvailableCents` at every call site. The asymmetry IS the rule\n  // below: availability is a question about now, settlement is not.\n  _nowMs: number,\n): number {\n  // NOT pruned: a hold that lapsed while its session sat unpaid is still owed\n  // once that session is paid. Expiry governs what a NEW checkout may claim,\n  // never whether a completed payment is honoured — dropping it here would take\n  // the discount from the shopper and give nothing back to the merchant.\n  const hold = (card?.holds ?? {})[sessionId]\n  return Math.min(cents(hold?.cents), cents(card?.balanceCents))\n}\n\n/*==========================================\n * ISSUING A CARD (AGL-2226, AGL-3551).\n *\n * A card is issued, never written: by hand from the Gift cards card, or one\n * card per row from an import, both through `issueGiftCard`\n * (`server/gift-card-issue.ts`). These are the rules both doors share.\n *=========================================*/\n\n/** The most one card may be issued for, by hand or from a file. */\nexport const GIFT_CARD_ISSUE_MAX_CENTS = 100_000\n\n/** The currency every card is held in: the store charges in US dollars. */\nexport const GIFT_CARD_CURRENCY = 'USD'\n\n/**\n * A code as the store keeps it: upper case, with no spaces — a code another\n * platform printed in groups (`ABCD EFGH 1234`) is the same code joined.\n */\nexport function giftCardCodeOf(value: unknown): string {\n  return String(value ?? '')\n    .trim()\n    .replace(/\\s+/g, '')\n    .toUpperCase()\n}\n\n/** The shortest code a card may carry: anything shorter can be guessed at a checkout. */\nexport const GIFT_CARD_CODE_MIN = 8\nexport const GIFT_CARD_CODE_MAX = 40\n\n/** Why a code cannot be a card's code, or `null`. A code is the card's document id and spends it. */\nexport function giftCardCodeProblem(code: string): string | null {\n  if (code.length < GIFT_CARD_CODE_MIN || code.length > GIFT_CARD_CODE_MAX || !/^[A-Z0-9][A-Z0-9_-]*$/.test(code)) {\n    return (\n      `A gift card code is ${GIFT_CARD_CODE_MIN} to ${GIFT_CARD_CODE_MAX} letters, digits, ` +\n      'hyphens or underscores. Leave the code blank and a new one is made.'\n    )\n  }\n  return null\n}\n\n/** Why a card cannot be issued for this many cents, or `null`. */\nexport function giftCardAmountProblem(amountCents: number): string | null {\n  if (!Number.isInteger(amountCents) || amountCents <= 0) return 'A gift card is issued for more than $0.'\n  if (amountCents > GIFT_CARD_ISSUE_MAX_CENTS) {\n    return `A gift card may be issued for at most $${(GIFT_CARD_ISSUE_MAX_CENTS / 100).toLocaleString('en-US')}.`\n  }\n  return null\n}\n\n/**\n * Whether anybody has spent from a card: a redemption settled on it\n * (`lastUsedAtMs`, a balance below what it was issued for), or a checkout\n * holding part of it — expired holds included, because a lapsed hold is\n * still settled when its session is paid (`giftCardSettlementCents`).\n */\nexport function giftCardRedeemed(\n  card: (HostGiftCard & { initialCents?: number; lastUsedAtMs?: number }) | undefined,\n): boolean {\n  if (!card) return false\n  if (Number(card.lastUsedAtMs) > 0) return true\n  if (Object.keys(card.holds ?? {}).length) return true\n  const initial = Number(card.initialCents)\n  return Number.isFinite(initial) && cents(card.balanceCents) < initial\n}\n"],"names":["GIFT_CARD_PURCHASE_LIMITS","perOrderCents","perOrderCentsYoung","perVisitorDaily","perVisitorDailyYoung","giftCardPurchaseRefusal","input","ceiling","young","giftCardCents","isGiftCardFrozen","card","Number","frozenAtMs","GIFT_CARD_HOLD_TTL_MS","cents","value","number","Math","round","isFinite","pruneGiftCardHolds","holds","nowMs","live","sessionId","hold","Object","entries","expiresAtMs","amount","giftCardAvailableCents","held","values","reduce","sum","max","balanceCents","giftCardSettlementCents","_nowMs","min","GIFT_CARD_ISSUE_MAX_CENTS","GIFT_CARD_CURRENCY","giftCardCodeOf","String","trim","replace","toUpperCase","GIFT_CARD_CODE_MIN","GIFT_CARD_CODE_MAX","giftCardCodeProblem","code","length","test","giftCardAmountProblem","amountCents","isInteger","toLocaleString","giftCardRedeemed","lastUsedAtMs","keys","initial","initialCents"],"mappings":"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"}

package/src/lib/model/commerce-orders.d.ts

@@ -808,17 +808,6 @@ export declare function formatOrderNumber(order: Pick<HostOrder, 'number'>, docI
  * into the v1 shape for display; already-shaped orders pass through.
  */
 export declare function liftLegacyOrder(raw: Partial<HostOrder>): HostOrder;
-/**
- * An orders-console row: the stored doc plus the Firestore id the collection
- * hook attaches. `createdAt` is typed structurally rather than against the
- * Firestore SDK — this module is pure and installs no client.
- */
-export interface OrderExportRow extends Partial<HostOrder> {
-    $id?: string;
-    createdAt?: {
-        toDate?: () => Date;
-    } | null;
-}
 /**
  * Does this order contain `productId`?
  *
@@ -997,51 +986,5 @@ export declare function summarizeOrderWindow(orders: readonly (Partial<HostOrder
     nowMs: number;
     days?: number;
 }): OrderWindowSummary;
-/**
- * Header for {@link buildOrdersCsv}. The original seven columns (AGL-96) keep
- * their names AND their positions, so a saved import mapping — by name or by
- * index — still resolves; the four reconciliation columns are appended.
- */
-export declare const ORDERS_CSV_HEADER: string;
-/**
- * The orders console's `orders.csv` (AGL-1747).
- *
- * ## What was wrong
- *
- * The export read `amountCents`, `feeCents` and `productId` — the legacy
- * Commerce Starter flat fields (AGL-90) — and nothing else. Checked writer by
- * writer, only the two buy-now-shaped Stripe paths write them:
- *
- * | Order path | `amountCents` | `productId` |
- * | -- | -- | -- |
- * | buy-now (`commerce-order`, `billing-webhook.ts`) | yes | yes |
- * | cart (`commerce-cart`, `billing-webhook.ts`) | yes | **no** |
- * | POS cash and POS card (`pos-order.ts`) | **no** | **no** |
- * | draft (`draft-order.ts`, paid by `commerce-draft`) | **no** | **no** |
- *
- * So every POS and draft order exported as `$0.00` and every cart order
- * exported with a blank product, each beside a plausible date, email and order
- * id — nothing in the file signals that the number is missing rather than
- * genuinely zero. The console screen was right the whole time: the table row
- * beside the export button, the detail dialog, the analytics card and lifetime
- * purchases all read `totals` with the flat field only as a fallback. The
- * export was the sole reader that had the precedence backwards, and a CSV is
- * the artefact that reaches a bookkeeper.
- *
- * ## What "correct" means
- *
- * Per AGL-1711's lesson, the useful test is not "do the parts sum" but "does
- * each column match what was actually charged" — a total-only assertion passes
- * against a row whose every component is wrong. The spec therefore pins each
- * cell of a worked example individually.
- *
- * ## Refunds
- *
- * `amountUsd` stays gross, which is what it has always meant, and the appended
- * `refundedUsd`/`netUsd` carry the rest. A refunded order previously exported
- * at its gross with nothing beside it to say so — the same class of error, in
- * that the file understated nothing but overstated revenue.
- */
-export declare function buildOrdersCsv(orders: OrderExportRow[], productNames?: Record<string, string>): string;
 /** Appends a timeline event immutably (webhook + console share this). */
 export declare function appendOrderEvent(order: Pick<HostOrder, 'timeline'>, event: string, detail?: string, atMs?: number): OrderTimelineEvent[];

package/src/lib/model/commerce-orders.js

@@ -926,86 +926,6 @@ const ORDER_WINDOW_DAY_MS = 24 * 60 * 60 * 1000;
         aovDeltaPct: deltaPct(aovCents, priorAovCents)
     };
 }
-/**
- * Header for {@link buildOrdersCsv}. The original seven columns (AGL-96) keep
- * their names AND their positions, so a saved import mapping — by name or by
- * index — still resolves; the four reconciliation columns are appended.
- */ export const ORDERS_CSV_HEADER = 'date,product,amountUsd,feeUsd,customerEmail,coupon,orderId,' + 'status,channel,refundedUsd,netUsd';
-/**
- * The orders console's `orders.csv` (AGL-1747).
- *
- * ## What was wrong
- *
- * The export read `amountCents`, `feeCents` and `productId` — the legacy
- * Commerce Starter flat fields (AGL-90) — and nothing else. Checked writer by
- * writer, only the two buy-now-shaped Stripe paths write them:
- *
- * | Order path | `amountCents` | `productId` |
- * | -- | -- | -- |
- * | buy-now (`commerce-order`, `billing-webhook.ts`) | yes | yes |
- * | cart (`commerce-cart`, `billing-webhook.ts`) | yes | **no** |
- * | POS cash and POS card (`pos-order.ts`) | **no** | **no** |
- * | draft (`draft-order.ts`, paid by `commerce-draft`) | **no** | **no** |
- *
- * So every POS and draft order exported as `$0.00` and every cart order
- * exported with a blank product, each beside a plausible date, email and order
- * id — nothing in the file signals that the number is missing rather than
- * genuinely zero. The console screen was right the whole time: the table row
- * beside the export button, the detail dialog, the analytics card and lifetime
- * purchases all read `totals` with the flat field only as a fallback. The
- * export was the sole reader that had the precedence backwards, and a CSV is
- * the artefact that reaches a bookkeeper.
- *
- * ## What "correct" means
- *
- * Per AGL-1711's lesson, the useful test is not "do the parts sum" but "does
- * each column match what was actually charged" — a total-only assertion passes
- * against a row whose every component is wrong. The spec therefore pins each
- * cell of a worked example individually.
- *
- * ## Refunds
- *
- * `amountUsd` stays gross, which is what it has always meant, and the appended
- * `refundedUsd`/`netUsd` carry the rest. A refunded order previously exported
- * at its gross with nothing beside it to say so — the same class of error, in
- * that the file understated nothing but overstated revenue.
- */ export function buildOrdersCsv(orders, productNames = {}) {
-    const escape = (cell)=>/[",\n]/.test(cell) ? `"${cell.replace(/"/g, '""')}"` : cell;
-    return [
-        ORDERS_CSV_HEADER,
-        ...orders.map((order)=>{
-            var _order_lineItems, _ref, _ref1, _ref2, _ref3, _order_productId, _ref4, _ref5, _ref6, _ref7, _order_refundedCents, _order_customerEmail, _order_couponCode, _order_$id, _lifted_channel;
-            var _order_createdAt_toDate, _order_createdAt, _lineItems_, _lifted_totals, _lifted_totals1;
-            const lifted = liftLegacyOrder(order);
-            // The STORED line items, not the lifted ones: `liftLegacyOrder` gives a
-            // legacy flat row a synthetic line named "Product", which would shadow
-            // the real name the `productNames` lookup still recovers for those rows.
-            const lineItems = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
-            // A cart order has several lines and no single product; name the first
-            // and count the rest, the way the table row renders it. `serverTimestamp`
-            // reads back null until the write lands, so `createdAtMs` — which every
-            // modern writer sets alongside it — covers the local snapshot.
-            const date = (_ref = (_order_createdAt = order.createdAt) == null ? void 0 : (_order_createdAt_toDate = _order_createdAt.toDate) == null ? void 0 : _order_createdAt_toDate.call(_order_createdAt)) != null ? _ref : order.createdAtMs ? new Date(order.createdAtMs) : null;
-            const product = (_ref1 = (_ref2 = (_ref3 = (_lineItems_ = lineItems[0]) == null ? void 0 : _lineItems_.name) != null ? _ref3 : productNames[(_order_productId = order.productId) != null ? _order_productId : '']) != null ? _ref2 : order.productId) != null ? _ref1 : '';
-            const totalCents = Number((_ref4 = (_ref5 = (_lifted_totals = lifted.totals) == null ? void 0 : _lifted_totals.totalCents) != null ? _ref5 : order.amountCents) != null ? _ref4 : 0);
-            const feeCents = Number((_ref6 = (_ref7 = (_lifted_totals1 = lifted.totals) == null ? void 0 : _lifted_totals1.feeCents) != null ? _ref7 : order.feeCents) != null ? _ref6 : 0);
-            const refundedCents = Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0);
-            return [
-                date ? date.toISOString() : '',
-                lineItems.length > 1 ? `${product} +${lineItems.length - 1} more` : product,
-                usd(totalCents),
-                usd(feeCents),
-                (_order_customerEmail = order.customerEmail) != null ? _order_customerEmail : '',
-                (_order_couponCode = order.couponCode) != null ? _order_couponCode : '',
-                (_order_$id = order.$id) != null ? _order_$id : '',
-                lifted.status,
-                (_lifted_channel = lifted.channel) != null ? _lifted_channel : 'online',
-                usd(refundedCents),
-                usd(totalCents - refundedCents)
-            ].map((cell)=>escape(String(cell))).join(',');
-        })
-    ].join('\n');
-}
 /** Appends a timeline event immutably (webhook + console share this). */ export function appendOrderEvent(order, event, detail, atMs = Date.now()) {
     var _order_timeline;
     return [