@simpleapps-com/augur-hooks 2.4.0 → 2026.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/EXPORTS.md +25 -65
  2. package/README.md +21 -246
  3. package/dist/checkout/create-checkout-provider.d.ts +25 -0
  4. package/dist/checkout/create-checkout-provider.d.ts.map +1 -0
  5. package/dist/checkout/index.cjs +123 -106
  6. package/dist/checkout/index.cjs.map +1 -1
  7. package/dist/checkout/index.d.ts +5 -293
  8. package/dist/checkout/index.d.ts.map +1 -0
  9. package/dist/checkout/index.js +99 -82
  10. package/dist/checkout/index.js.map +1 -1
  11. package/dist/checkout/{index.d.cts → types.d.ts} +18 -40
  12. package/dist/checkout/types.d.ts.map +1 -0
  13. package/dist/chunk-6Z6JGK2C.cjs.map +1 -1
  14. package/dist/chunk-QB7VB5FZ.cjs +523 -0
  15. package/dist/chunk-QB7VB5FZ.cjs.map +1 -0
  16. package/dist/{chunk-JNOHB4OP.js → chunk-UTDAFIQP.js} +234 -94
  17. package/dist/chunk-UTDAFIQP.js.map +1 -0
  18. package/dist/hooks/use-cart-actions.d.ts +68 -0
  19. package/dist/hooks/use-cart-actions.d.ts.map +1 -0
  20. package/dist/hooks/use-cart-initialization.d.ts +60 -0
  21. package/dist/hooks/use-cart-initialization.d.ts.map +1 -0
  22. package/dist/hooks/use-cart-pricing.d.ts +41 -0
  23. package/dist/hooks/use-cart-pricing.d.ts.map +1 -0
  24. package/dist/hooks/use-checkout-persistence.d.ts +40 -0
  25. package/dist/hooks/use-checkout-persistence.d.ts.map +1 -0
  26. package/dist/hooks/use-debounce.d.ts +6 -0
  27. package/dist/hooks/use-debounce.d.ts.map +1 -0
  28. package/dist/hooks/use-format-price.d.ts +29 -0
  29. package/dist/hooks/use-format-price.d.ts.map +1 -0
  30. package/dist/hooks/use-latest.d.ts +8 -0
  31. package/dist/hooks/use-latest.d.ts.map +1 -0
  32. package/dist/hooks/use-modal-lifecycle.d.ts +11 -0
  33. package/dist/hooks/use-modal-lifecycle.d.ts.map +1 -0
  34. package/dist/hooks/use-order-readiness.d.ts +47 -0
  35. package/dist/hooks/use-order-readiness.d.ts.map +1 -0
  36. package/dist/hooks/use-pagination-prefetch.d.ts +26 -0
  37. package/dist/hooks/use-pagination-prefetch.d.ts.map +1 -0
  38. package/dist/{use-order-readiness-DZTIfRzw.d.ts → hooks/use-payment-flow.d.ts} +23 -67
  39. package/dist/hooks/use-payment-flow.d.ts.map +1 -0
  40. package/dist/hooks/use-stock.d.ts +32 -0
  41. package/dist/hooks/use-stock.d.ts.map +1 -0
  42. package/dist/index.cjs +215 -178
  43. package/dist/index.cjs.map +1 -1
  44. package/dist/index.d.ts +32 -456
  45. package/dist/index.d.ts.map +1 -0
  46. package/dist/index.js +193 -156
  47. package/dist/index.js.map +1 -1
  48. package/dist/persistence/apply-limits.d.ts +8 -0
  49. package/dist/persistence/apply-limits.d.ts.map +1 -0
  50. package/dist/persistence/create-persister.d.ts +10 -0
  51. package/dist/persistence/create-persister.d.ts.map +1 -0
  52. package/dist/persistence/serializer.d.ts +11 -0
  53. package/dist/persistence/serializer.d.ts.map +1 -0
  54. package/dist/persistence/use-persistence.d.ts +59 -0
  55. package/dist/persistence/use-persistence.d.ts.map +1 -0
  56. package/dist/persistence/use-storage-monitor.d.ts +11 -0
  57. package/dist/persistence/use-storage-monitor.d.ts.map +1 -0
  58. package/dist/provider.d.ts +89 -0
  59. package/dist/provider.d.ts.map +1 -0
  60. package/dist/queries/batch-query.d.ts +23 -0
  61. package/dist/queries/batch-query.d.ts.map +1 -0
  62. package/dist/queries/cache-helper.d.ts +16 -0
  63. package/dist/queries/cache-helper.d.ts.map +1 -0
  64. package/dist/queries/index.d.ts +3 -0
  65. package/dist/queries/index.d.ts.map +1 -0
  66. package/dist/query-action-registry.d.ts +19 -0
  67. package/dist/query-action-registry.d.ts.map +1 -0
  68. package/dist/rules.d.ts +130 -0
  69. package/dist/rules.d.ts.map +1 -0
  70. package/dist/server.cjs.map +1 -1
  71. package/dist/server.d.ts +10 -12
  72. package/dist/server.d.ts.map +1 -0
  73. package/dist/stores/cart-store.d.ts +51 -0
  74. package/dist/stores/cart-store.d.ts.map +1 -0
  75. package/dist/stores/items-filters-store.d.ts +30 -0
  76. package/dist/stores/items-filters-store.d.ts.map +1 -0
  77. package/dist/types.d.ts +48 -0
  78. package/dist/types.d.ts.map +1 -0
  79. package/dist/web/use-image-with-fallback.d.ts +16 -0
  80. package/dist/web/use-image-with-fallback.d.ts.map +1 -0
  81. package/dist/web/use-mobile-detection.d.ts +28 -0
  82. package/dist/web/use-mobile-detection.d.ts.map +1 -0
  83. package/dist/web/use-mobile-optimized-intersection.d.ts +17 -0
  84. package/dist/web/use-mobile-optimized-intersection.d.ts.map +1 -0
  85. package/dist/web.cjs.map +1 -1
  86. package/dist/web.d.ts +4 -60
  87. package/dist/web.d.ts.map +1 -0
  88. package/dist/web.js.map +1 -1
  89. package/llms.txt +76 -54
  90. package/package.json +25 -14
  91. package/dist/batch-query-CTlvxSmL.d.cts +0 -165
  92. package/dist/batch-query-CTlvxSmL.d.ts +0 -165
  93. package/dist/chunk-F5DUFW57.cjs +0 -383
  94. package/dist/chunk-F5DUFW57.cjs.map +0 -1
  95. package/dist/chunk-JNOHB4OP.js.map +0 -1
  96. package/dist/index.d.cts +0 -456
  97. package/dist/server.d.cts +0 -44
  98. package/dist/use-order-readiness-DZTIfRzw.d.cts +0 -137
  99. package/dist/web.d.cts +0 -60
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/stores/cart-store.ts","../../utils/src/strings.ts","../src/rules.ts","../src/hooks/use-checkout-persistence.ts","../src/hooks/use-payment-flow.ts","../src/hooks/use-order-readiness.ts","../src/hooks/use-latest.ts"],"sourcesContent":["import { create } from \"zustand\";\nimport { devtools } from \"zustand/middleware\";\nimport type { TCartLine } from \"@simpleapps-com/augur-utils\";\nimport { quantityTotalFrom } from \"../rules\";\n\n/** Internal state shape for the cart Zustand store. */\ninterface CartState {\n /** P21 cart header UID; `undefined` when no cart exists. */\n cartHdrUid: number | string | undefined;\n /** Current line items in the cart. */\n cartLines: TCartLine[];\n /** Sum of `quantity` across all cart lines (auto-computed by `setCartLines`). */\n cartQuantityTotal: number;\n /** Number of distinct line items (auto-computed by `setCartLines`). */\n cartLineCount: number;\n setCartHdrUid: (cartHdrUid: number | string | undefined) => void;\n /** Replace all cart lines. Auto-recomputes `cartQuantityTotal` and `cartLineCount`. */\n setCartLines: (cartLines: TCartLine[]) => void;\n /** Reset the cart to its empty initial state. */\n clearCart: () => void;\n}\n\n/** Zustand store for cart state. Prefer the individual selector hooks below for optimal re-renders. */\nexport const useCartStore = create<CartState>()(\n devtools(\n (set) => ({\n cartHdrUid: undefined,\n cartLines: [],\n cartQuantityTotal: 0,\n cartLineCount: 0,\n\n setCartHdrUid: (cartHdrUid) => set({ cartHdrUid }, false, \"setCartHdrUid\"),\n\n setCartLines: (cartLines) => {\n const quantities = cartLines.map((line) => line.quantity || 0);\n const cartQuantityTotal = quantityTotalFrom(quantities, 0, 0);\n const cartLineCount = cartLines.length;\n set({ cartLines, cartQuantityTotal, cartLineCount }, false, \"setCartLines\");\n },\n\n clearCart: () =>\n set(\n { cartHdrUid: undefined, cartLines: [], cartQuantityTotal: 0, cartLineCount: 0 },\n false,\n \"clearCart\",\n ),\n }),\n { name: \"CartStore\", enabled: process.env[\"NODE_ENV\"] === \"development\" },\n ),\n);\n\n// Selector hooks -- only re-render when specific state changes\n\n/** Select the current cart header UID. */\nexport const useCartHdrUid = () => useCartStore((s) => s.cartHdrUid);\n/** Select the current cart line items array. */\nexport const useCartLines = (): TCartLine[] => useCartStore((s) => s.cartLines);\n/** Select the total quantity summed across all cart lines. */\nexport const useCartQuantityTotal = () => useCartStore((s) => s.cartQuantityTotal);\n/** Select the number of distinct line items in the cart. */\nexport const useCartLineCount = () => useCartStore((s) => s.cartLineCount);\n/** Get the `setCartHdrUid` action (stable reference). */\nexport const useSetCartHdrUid = () => useCartStore((s) => s.setCartHdrUid);\n/** Get the `setCartLines` action (stable reference). Also recomputes totals. */\nexport const useSetCartLines = () => useCartStore((s) => s.setCartLines);\n/** Get the `clearCart` action (stable reference). */\nexport const useClearCart = () => useCartStore((s) => s.clearCart);\n","//@ backend dafny\nimport {\n isAlnumChar,\n isBase64UrlChar,\n isDigit,\n isHexChar,\n isJsSpace,\n isLineTerminator,\n isLowerHexChar,\n isSnakeChar,\n isWordChar,\n lowerCode,\n} from \"./chars\";\n\n/* String scans and slices, verified with LemmaScript → Dafny (hand lemmas in strings.dfy;\n model: models/Utils.dfy; link: models/links/utils-strings.dfy). Recursive and\n expression-bodied so specs can use them, and each contract pins the result exactly, so\n an importer (which sees only the contract) knows what it returns. Two of them stand in\n for constructs lsc mistranslates: `prefix` for an unclamped `slice`, and the code-unit\n scans for \"\\r\" / \"\\n\" literals. */\n\n/**\n * The code unit at `i`, or -1 when `i` is outside `s`. JS `charCodeAt` gives NaN there,\n * which no code equals, so a scan's own bounds test would change no result and no test\n * could tell it from none (an equivalent mutant); with the bound here once, the boundary is\n * observable (tests pin -1) and the scans that use it carry no bound of their own. A code\n * unit is never negative, so -1 matches no `code` a caller passes (`requires code >= 0`).\n *\n * @ensures 0 ≤ i < |s| ⟹ result = s[i]; otherwise result = -1\n */\nexport function codeAt(s: string, i: number): number {\n //@ verify\n //@ ensures (i >= 0 && i < s.length) ==> \\result === s.charCodeAt(i)\n //@ ensures !(i >= 0 && i < s.length) ==> \\result === -1\n return i >= 0 && i < s.length ? s.charCodeAt(i) : -1;\n}\n\n/**\n * Every character of `s` from index `i` on is base64url.\n *\n * @ensures result ⟺ ∀ k ∈ [i, |s|). isBase64UrlChar(s[k])\n */\nexport function base64UrlFrom(s: string, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ decreases s.length - i\n //@ ensures \\result <==> forall(k: nat, (i <= k && k < s.length) ==> isBase64UrlChar(s.charCodeAt(k)))\n return i >= s.length || (isBase64UrlChar(s.charCodeAt(i)) && base64UrlFrom(s, i + 1));\n}\n\n/**\n * The base64url digit for `v` (RFC 4648 §5): A-Z a-z 0-9 - _.\n *\n * @ensures exactly the model's Base64UrlDigit\n */\nexport function base64UrlDigit(v: number): string {\n //@ verify\n //@ type v nat\n //@ requires v >= 0 && v < 64\n //@ ensures \\result === \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_\".slice(v, v + 1)\n return \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_\".slice(v, v + 1);\n}\n\n/**\n * Bytes from `i` on as unpadded base64url: each three as four digits, a last one or two as two or\n * three (JS `btoa` with `+/` as `-_` and the `=` dropped). One frame per three bytes: a JWT part\n * is a few hundred.\n *\n * @ensures exactly the model's Base64UrlFrom (links/utils-strings.dfy)\n */\nexport function encodeBase64UrlFrom(b: number[], i: number): string {\n //@ verify\n //@ type i nat\n //@ requires i >= 0 && forall(k: nat, k < b.length ==> (b[k] >= 0 && b[k] < 256))\n //@ decreases b.length - i\n //@ ensures i >= b.length ==> \\result === \"\"\n if (i >= b.length) return \"\";\n const x = b[i] as number;\n const first = base64UrlDigit(Math.floor(x / 4));\n if (i + 1 === b.length) return first + base64UrlDigit((x % 4) * 16);\n const y = b[i + 1] as number;\n const second = base64UrlDigit((x % 4) * 16 + Math.floor(y / 16));\n if (i + 2 === b.length) return first + second + base64UrlDigit((y % 16) * 4);\n const z = b[i + 2] as number;\n return (\n first +\n second +\n base64UrlDigit((y % 16) * 4 + Math.floor(z / 64)) +\n base64UrlDigit(z % 64) +\n encodeBase64UrlFrom(b, i + 3)\n );\n}\n\n/**\n * Every character of `s` from index `i` on is lowercase hex.\n *\n * @ensures result ⟺ ∀ k ∈ [i, |s|). isLowerHexChar(s[k])\n */\nexport function lowerHexFrom(s: string, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ decreases s.length - i\n //@ ensures \\result <==> forall(k: nat, (i <= k && k < s.length) ==> isLowerHexChar(s.charCodeAt(k)))\n return i >= s.length || (isLowerHexChar(s.charCodeAt(i)) && lowerHexFrom(s, i + 1));\n}\n\n/**\n * Every character of `s` from index `i` on is hex, either case.\n *\n * @ensures result ⟺ ∀ k ∈ [i, |s|). isHexChar(s[k])\n */\nexport function hexFrom(s: string, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ decreases s.length - i\n //@ ensures \\result <==> forall(k: nat, (i <= k && k < s.length) ==> isHexChar(s.charCodeAt(k)))\n return i >= s.length || (isHexChar(s.charCodeAt(i)) && hexFrom(s, i + 1));\n}\n\n/**\n * Every character of `s` from index `i` on is an ASCII digit (`\\d` without the `u` flag).\n *\n * @ensures result ⟺ ∀ k ∈ [i, |s|). isDigit(s[k])\n */\nexport function digitsFrom(s: string, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ decreases s.length - i\n //@ ensures \\result <==> forall(k: nat, (i <= k && k < s.length) ==> isDigit(s.charCodeAt(k)))\n return i >= s.length || (isDigit(s.charCodeAt(i)) && digitsFrom(s, i + 1));\n}\n\n/**\n * Every character of `s` from index `i` on is a word character (`\\w`: `[A-Za-z0-9_]`).\n *\n * @ensures result ⟺ ∀ k ∈ [i, |s|). isWordChar(s[k])\n */\nexport function wordCharsFrom(s: string, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ decreases s.length - i\n //@ ensures \\result <==> forall(k: nat, (i <= k && k < s.length) ==> isWordChar(s.charCodeAt(k)))\n return i >= s.length || (isWordChar(s.charCodeAt(i)) && wordCharsFrom(s, i + 1));\n}\n\n/**\n * Every character of `s` from index `i` on is a snake_case character (`[a-z0-9_]`).\n *\n * @ensures result ⟺ ∀ k ∈ [i, |s|). isSnakeChar(s[k])\n */\nexport function snakeCharsFrom(s: string, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ decreases s.length - i\n //@ ensures \\result <==> forall(k: nat, (i <= k && k < s.length) ==> isSnakeChar(s.charCodeAt(k)))\n return i >= s.length || (isSnakeChar(s.charCodeAt(i)) && snakeCharsFrom(s, i + 1));\n}\n\n/**\n * Every character of `s` from index `i` on is an ASCII letter or digit (`[A-Za-z0-9]`).\n *\n * @ensures result ⟺ ∀ k ∈ [i, |s|). isAlnumChar(s[k])\n */\nexport function alnumFrom(s: string, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ decreases s.length - i\n //@ ensures \\result <==> forall(k: nat, (i <= k && k < s.length) ==> isAlnumChar(s.charCodeAt(k)))\n return i >= s.length || (isAlnumChar(s.charCodeAt(i)) && alnumFrom(s, i + 1));\n}\n\n/**\n * Every character of `s` from index `i` on is an ASCII letter, digit or `-` (`[A-Za-z0-9-]`):\n * a domain label's tail, a service name's tail.\n *\n * @ensures result ⟺ ∀ k ∈ [i, |s|). isAlnumChar(s[k]) ∨ s[k] = \"-\" — the model's AlnumDashFrom\n */\nexport function alnumDashFrom(s: string, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ decreases s.length - i\n //@ ensures \\result <==> forall(k: nat, (i <= k && k < s.length) ==> (isAlnumChar(s.charCodeAt(k)) || s.charCodeAt(k) === 45))\n if (i >= s.length) return true;\n const c = s.charCodeAt(i);\n return (isAlnumChar(c) || c === 45) && alnumDashFrom(s, i + 1);\n}\n\n/**\n * The last index before `end` holding `code`, or -1 (JS `s.lastIndexOf(c)` at end = |s|).\n *\n * @ensures result = -1 ∨ (0 ≤ result < end ∧ s[result] = code ∧ no `code` in (result, end))\n */\nexport function lastIndexOfCode(s: string, code: number, end: number): number {\n //@ verify\n //@ type end nat\n //@ requires end <= s.length\n //@ decreases end\n //@ ensures \\result === -1 || (0 <= \\result && \\result < end)\n //@ ensures \\result >= 0 ==> s.charCodeAt(\\result) === code\n //@ ensures \\result >= 0 ==> forall(k: nat, (\\result < k && k < end) ==> s.charCodeAt(k) !== code)\n //@ ensures \\result === -1 ==> forall(k: nat, k < end ==> s.charCodeAt(k) !== code)\n if (end === 0) return -1;\n if (s.charCodeAt(end - 1) === code) return end - 1;\n return lastIndexOfCode(s, code, end - 1);\n}\n\n/**\n * No character of `s` from index `i` on is `code`.\n *\n * @ensures result ⟺ ∀ k ∈ [i, |s|). s[k] ≠ code\n */\nexport function lacksCode(s: string, code: number, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ requires i <= s.length\n //@ decreases s.length - i\n //@ ensures \\result <==> forall(k: nat, (i <= k && k < s.length) ==> s.charCodeAt(k) !== code)\n // `===`, not `>=`: past the end a read is NaN !== code, so `>=` vs `>` would be equivalent\n return i === s.length || (s.charCodeAt(i) !== code && lacksCode(s, code, i + 1));\n}\n\n/**\n * The end of the run of `code` starting at `i`: the first index ≥ i that isn't `code`\n * (skip spaces: `codeRunEnd(header, 32, i)`).\n *\n * @requires i ≤ |s|\n * @ensures i ≤ result ≤ |s| ∧ ∀ k ∈ [i, result). s[k] = code ∧ (result < |s| ⟹ s[result] ≠ code)\n * — exactly the run's end\n */\nexport function codeRunEnd(s: string, code: number, i: number): number {\n //@ verify\n //@ type i nat\n //@ requires 0 <= i && i <= s.length\n //@ requires code >= 0\n //@ decreases s.length - i\n //@ ensures i <= \\result && \\result <= s.length\n //@ ensures forall(k: nat, (i <= k && k < \\result) ==> s.charCodeAt(k) === code)\n //@ ensures \\result < s.length ==> s.charCodeAt(\\result) !== code\n return codeAt(s, i) === code ? codeRunEnd(s, code, i + 1) : i;\n}\n\n/**\n * The first index ≥ `from` holding `code`, or -1 (`indexOf` for one code unit, so \"\\n\" is\n * passed as 10, never as a literal).\n *\n * @ensures result = -1 ∨ (from ≤ result < |s| ∧ s[result] = code), with no `code` in\n * [from, result) — the first one; result = -1 ⟹ none from `from` on\n */\nexport function indexOfCode(s: string, code: number, from: number): number {\n //@ verify\n //@ type from nat\n //@ requires code >= 0\n //@ decreases s.length - from\n //@ ensures \\result === -1 || (from <= \\result && \\result < s.length)\n //@ ensures \\result >= 0 ==> s.charCodeAt(\\result) === code\n //@ ensures \\result >= 0 ==> forall(k: nat, (from <= k && k < \\result) ==> s.charCodeAt(k) !== code)\n //@ ensures \\result === -1 ==> forall(k: nat, (from <= k && k < s.length) ==> s.charCodeAt(k) !== code)\n const c = codeAt(s, from);\n if (c === code) return from;\n if (c === -1) return -1;\n return indexOfCode(s, code, from + 1);\n}\n\n/**\n * The first index ≥ `i` holding `a` or `b`, or |s| (a run either code ends: a path segment's\n * run to \"/\" or \"?\"). One scan: the lesser of two `indexOfCode` ends is the same index, but\n * its two sides are equal only when both are |s|, a boundary no test can observe.\n *\n * @requires i ≤ |s|\n * @ensures i ≤ result ≤ |s| ∧ ∀ k ∈ [i, result). s[k] ∉ {a, b} ∧ (result < |s| ⟹ s[result] ∈ {a, b})\n * — exactly the first such index\n */\nexport function eitherCodeEnd(s: string, a: number, b: number, i: number): number {\n //@ verify\n //@ type i nat\n //@ requires 0 <= i && i <= s.length\n //@ requires a >= 0 && b >= 0\n //@ decreases s.length - i\n //@ ensures i <= \\result && \\result <= s.length\n //@ ensures forall(k: nat, (i <= k && k < \\result) ==> (s.charCodeAt(k) !== a && s.charCodeAt(k) !== b))\n //@ ensures \\result < s.length ==> (s.charCodeAt(\\result) === a || s.charCodeAt(\\result) === b)\n const c = codeAt(s, i);\n if (c === -1 || c === a || c === b) return i;\n return eitherCodeEnd(s, a, b, i + 1);\n}\n\n/**\n * `s` without one trailing `code` (\"\\r\" before a \"\\n\", say); unchanged otherwise.\n *\n * @ensures s ends with code ⟹ result = s[0, |s| − 1)\n * @ensures otherwise result = s\n */\nexport function dropLast(s: string, code: number): string {\n //@ verify\n //@ requires code >= 0\n //@ ensures (s.length > 0 && s.charCodeAt(s.length - 1) === code) ==> \\result === s.slice(0, s.length - 1)\n //@ ensures !(s.length > 0 && s.charCodeAt(s.length - 1) === code) ==> \\result === s\n return codeAt(s, s.length - 1) === code ? s.slice(0, s.length - 1) : s;\n}\n\n/**\n * `s` without its leading `code` units (every one of them).\n *\n * @ensures exactly the model's LStripCode\n */\nexport function lStripCode(s: string, code: number): string {\n //@ verify\n //@ requires code >= 0\n //@ decreases s.length\n //@ ensures \\result.length <= s.length\n if (codeAt(s, 0) === code) return lStripCode(s.slice(1), code);\n return s;\n}\n\n/**\n * `s` without its trailing `code` units (every one of them).\n *\n * @ensures exactly the model's RStripCode\n */\nexport function rStripCode(s: string, code: number): string {\n //@ verify\n //@ requires code >= 0\n //@ decreases s.length\n //@ ensures \\result.length <= s.length\n if (codeAt(s, s.length - 1) === code) {\n return rStripCode(s.slice(0, s.length - 1), code);\n }\n return s;\n}\n\n/**\n * `s` without its leading and trailing `code` units, the middle kept (`/a/b/` with `/` →\n * `a/b`).\n *\n * @ensures exactly the model's StripCode — neither end is `code` (StripCodeTrims)\n */\nexport function stripCode(s: string, code: number): string {\n //@ verify\n //@ requires code >= 0\n //@ ensures \\result === rStripCode(lStripCode(s, code), code)\n return rStripCode(lStripCode(s, code), code);\n}\n\n/**\n * JS `s.startsWith(x, pos)`, which lsc mistranslates (it drops `pos`). Like JS, a `pos`\n * past the end counts as the end, so the empty string matches anywhere.\n *\n * @ensures pos ≤ |s| ⟹ (result ⟺ pos + |x| ≤ |s| ∧ s[pos, pos + |x|) = x) — so a true\n * result also gives the bounds for slicing after the match\n * @ensures pos > |s| ⟹ (result ⟺ x = \"\")\n */\nexport function startsWithAt(s: string, x: string, pos: number): boolean {\n //@ verify\n //@ type pos nat\n //@ requires pos >= 0\n //@ ensures pos <= s.length ==> (\\result <==> (pos + x.length <= s.length && s.slice(pos, pos + x.length) === x))\n //@ ensures pos > s.length ==> (\\result <==> x.length === 0)\n // Math.min, not a ternary: at pos = |s| both branches agree, so `<` vs `<=` is equivalent\n const at = Math.min(pos, s.length);\n // The slice is clamped to the end, so a too-long x differs by length: no separate fit test\n // (JS slice clamps too, which made one unobservable)\n return s.slice(at, Math.min(at + x.length, s.length)) === x;\n}\n\n/**\n * `s` with A-Z lowercased and every other character kept: what lsc's proofs take\n * `toLowerCase()` to be. JS's `toLowerCase()` also maps non-ASCII letters, some onto ASCII\n * (the Kelvin sign K, U+212A, becomes \"k\") or onto two characters (İ, U+0130), so a proved\n * function that lowercases MUST use this, or the runtime does what the proof says it\n * doesn't.\n *\n * @ensures result = s with A-Z lowercased — same length, every other character unchanged\n */\nexport function lowerAscii(s: string): string {\n //@ verify\n //@ decreases s.length\n //@ ensures \\result === s.toLowerCase()\n if (s.length === 0) return \"\";\n const c = s.charCodeAt(0);\n const head =\n c >= 65 && c <= 90 ? \"abcdefghijklmnopqrstuvwxyz\".slice(c - 65, c - 64) : s.slice(0, 1);\n return head + lowerAscii(s.slice(1));\n}\n\n/**\n * `lowerAscii` as a loop: a constant stack depth (and linear time) on long text, where the\n * recursive spec takes a frame and a slice per character.\n *\n * @ensures result = lowerAscii(s)\n */\nexport function lowerAsciiText(s: string): string {\n //@ verify\n //@ ensures \\result === lowerAscii(s)\n let out = \"\";\n let i = 0;\n while (i !== s.length) {\n //@ invariant 0 <= i && i <= s.length\n //@ invariant out + lowerAscii(s.slice(i)) === lowerAscii(s)\n //@ decreases s.length - i\n const c = s.charCodeAt(i);\n out =\n out +\n (c >= 65 && c <= 90 ? \"abcdefghijklmnopqrstuvwxyz\".slice(c - 65, c - 64) : s.slice(i, i + 1));\n i = i + 1;\n }\n return out;\n}\n\n/**\n * Whether `x` from index `k` matches `s` from `pos + k`, code by code, ASCII-lowered. A code\n * past the end of `s` is -1 (`codeAt`), which no code of `x` is, so there is no bound to\n * check (a `pos + |x| ≤ |s|` guard before a slice never changed the answer at runtime, where\n * `slice` clamps: an equivalent mutant, 2026-11-02).\n *\n * @ensures exactly the model's CaselessFrom\n */\nexport function caselessFrom(s: string, x: string, pos: number, k: number): boolean {\n //@ verify\n //@ type pos nat\n //@ type k nat\n //@ requires pos >= 0 && k >= 0 && k <= x.length\n //@ decreases x.length - k\n //@ ensures k === x.length ==> \\result\n if (k === x.length) return true;\n return lowerCode(codeAt(s, pos + k)) === x.charCodeAt(k) && caselessFrom(s, x, pos, k + 1);\n}\n\n/**\n * Whether the text of `s` at `pos`, ASCII-lowered, is `x` (`x` given lowercase): a case-free\n * `startsWith`; callers carry no length guard of their own. Only `pos ≤ |s|` is checked: it\n * decides an empty `x` past the end, the one case the code-by-code test can't see.\n *\n * @ensures result ⟺ pos + |x| ≤ |s| ∧ lowerAscii(s[pos, pos + |x|)) = x — Utils.StartsWithCaseless\n */\nexport function startsWithCaseless(s: string, x: string, pos: number): boolean {\n //@ verify\n //@ type pos nat\n //@ requires pos >= 0\n //@ ensures \\result <==> (pos + x.length <= s.length && s.slice(pos, pos + x.length).toLowerCase() === x)\n return pos <= s.length && caselessFrom(s, x, pos, 0);\n}\n\n/**\n * Whether `s` ends with `suffix` (JS one-argument `endsWith`, which lsc reads as its\n * two-argument form; moved from the augur-api generator 2026-11-01).\n *\n * @ensures result ⟺ |s| ≥ |suffix| ∧ s[|s| − |suffix|, |s|) = suffix — exactly the model's EndsWith\n */\nexport function endsWith(s: string, suffix: string): boolean {\n //@ verify\n //@ ensures \\result <==> (s.length >= suffix.length && s.slice(s.length - suffix.length) === suffix)\n // No length test: from max(|s| − |suffix|, 0), a too-long suffix compares unequal by length\n return s.slice(Math.max(s.length - suffix.length, 0)) === suffix;\n}\n\n/**\n * The order of `a` and `b` by UTF-16 code unit from index `i`, as a recursive spec: -1, 0\n * or 1 (JS `<` on strings; a proper prefix comes first). Locale-free, unlike `localeCompare`.\n *\n * @ensures result ∈ {-1, 0, 1} — exactly the model's CompareFrom\n */\nexport function compareFrom(a: string, b: string, i: number): number {\n //@ verify\n //@ type i nat\n //@ requires i >= 0\n //@ decreases a.length - i\n //@ ensures \\result === -1 || \\result === 0 || \\result === 1\n if (i >= a.length) return i >= b.length ? 0 : -1;\n if (i >= b.length) return 1;\n const x = a.charCodeAt(i);\n const y = b.charCodeAt(i);\n if (x < y) return -1;\n if (x > y) return 1;\n return compareFrom(a, b, i + 1);\n}\n\n/**\n * The order of two strings by UTF-16 code unit, for `sort` (what the default `sort` uses on\n * strings), so sorted output never depends on locale.\n *\n * @ensures result = compareFrom(a, b, 0)\n */\nexport function compareCodeUnits(a: string, b: string): number {\n //@ verify\n //@ ensures \\result === compareFrom(a, b, 0)\n return compareFrom(a, b, 0);\n}\n\n/**\n * JS `s.slice(0, n)`: at most `n` characters, clamped to the length. lsc reads a bare\n * `slice(0, n)` without JS's clamp, so use this instead.\n *\n * @ensures result = s[0, min(n, |s|))\n */\nexport function prefix(s: string, n: number): string {\n //@ verify\n //@ type n nat\n //@ requires n >= 0\n //@ ensures n < s.length ==> \\result === s.slice(0, n)\n //@ ensures n >= s.length ==> \\result === s\n // Math.min, not a ternary: JS slice already clamps, so a ternary's branch is unobservable\n return s.slice(0, Math.min(n, s.length));\n}\n\n/**\n * The end of the JS-whitespace (`\\s`) run starting at `i`: the first index ≥ i that is not\n * whitespace, or |s|.\n *\n * @ensures i ≤ result ≤ |s| ∧ s[i, result) all whitespace ∧ (result = |s| ∨ ¬space(s[result]))\n */\nexport function spaceRunEnd(s: string, i: number): number {\n //@ verify\n //@ type i nat\n //@ requires 0 <= i && i <= s.length\n //@ decreases s.length - i\n //@ ensures i <= \\result && \\result <= s.length\n //@ ensures forall(k: nat, (i <= k && k < \\result) ==> isJsSpace(s.charCodeAt(k)))\n //@ ensures \\result < s.length ==> !isJsSpace(s.charCodeAt(\\result))\n // codeAt is -1 at the end, which is no space: the bound needs no test of its own here\n if (!isJsSpace(codeAt(s, i))) return i;\n return spaceRunEnd(s, i + 1);\n}\n\n/**\n * A natural number written canonically (`^(0|[1-9][0-9]*)$`): the keys JS objects move\n * first, ahead of their source order.\n *\n * @ensures exactly the model's CanonicalNat, stated over the codes themselves so an importer\n * can use it (a contract naming `digitsFrom` can't be resolved there, models/LSC-GAPS.md)\n */\nexport function isCanonicalNat(s: string): boolean {\n //@ verify\n //@ ensures \\result <==> (s === \"0\" || (s.length > 0 && s.charCodeAt(0) >= 49 && s.charCodeAt(0) <= 57 && forall(k: nat, (1 <= k && k < s.length) ==> (s.charCodeAt(k) >= 48 && s.charCodeAt(k) <= 57))))\n if (s === \"0\") return true;\n const first = codeAt(s, 0);\n return first >= 49 && first <= 57 && digitsFrom(s, 1);\n}\n\n/**\n * The value of a run of decimal digits, most significant first (\"\" is 0).\n *\n * @requires ∀ k ∈ [0, |s|). isDigit(s[k])\n * @ensures exactly the model's DigitsValue (proved in links/utils-strings.dfy)\n */\nexport function digitsValue(s: string): number {\n //@ verify\n //@ requires forall(k: nat, k < s.length ==> (s.charCodeAt(k) >= 48 && s.charCodeAt(k) <= 57))\n //@ decreases s.length\n //@ ensures \\result >= 0\n if (s.length === 0) return 0;\n return digitsValue(s.slice(0, s.length - 1)) * 10 + (s.charCodeAt(s.length - 1) - 48);\n}\n\n/**\n * What a number from the environment means (owner 2026-11-04: a bad one fails at start):\n * \"default\" when unset (\"\": the wrapper reads a missing variable as \"\"), \"value\" when it is\n * a canonical natural number at least `min` (its value is `digitsValue(raw)`), and \"bad\"\n * otherwise: a sign, a space, a fraction, an exponent, hex, text, or below `min`.\n *\n * @ensures exactly the model's EnvNumberOf (proved in links/utils-strings.dfy)\n */\nexport function envNumberKind(raw: string, min: number): string {\n //@ verify\n //@ type min nat\n //@ ensures raw === \"\" ==> \\result === \"default\"\n //@ ensures (raw !== \"\" && !isCanonicalNat(raw)) ==> \\result === \"bad\"\n if (raw === \"\") return \"default\";\n if (!isCanonicalNat(raw)) return \"bad\";\n return digitsValue(raw) < min ? \"bad\" : \"value\";\n}\n\n/**\n * The first index ≥ `i` holding a line terminator, or |s|: where a regex `.+` started at `i`\n * stops.\n *\n * @ensures i ≤ result ≤ |s| ∧ no terminator in s[i, result) ∧ (result = |s| ∨ terminator at result)\n */\nexport function lineEnd(s: string, i: number): number {\n //@ verify\n //@ type i nat\n //@ requires 0 <= i && i <= s.length\n //@ decreases s.length - i\n //@ ensures i <= \\result && \\result <= s.length\n //@ ensures forall(k: nat, (i <= k && k < \\result) ==> !isLineTerminator(s.charCodeAt(k)))\n //@ ensures \\result < s.length ==> isLineTerminator(s.charCodeAt(\\result))\n if (i === s.length || isLineTerminator(s.charCodeAt(i))) return i;\n return lineEnd(s, i + 1);\n}\n\n/**\n * The largest p with lo ≤ p < hi whose character is not a line terminator, or -1: where a\n * backtracking regex `.` can start.\n *\n * @ensures result = -1 ∨ (lo ≤ result < hi ∧ ¬terminator(s[result]) ∧ only terminators in (result, hi))\n */\nexport function lastLineCharBelow(s: string, hi: number, lo: number): number {\n //@ verify\n //@ type hi nat\n //@ type lo nat\n //@ requires 0 <= lo && 0 <= hi && hi <= s.length\n //@ decreases hi\n //@ ensures \\result === -1 || (lo <= \\result && \\result < hi)\n //@ ensures \\result >= 0 ==> !isLineTerminator(s.charCodeAt(\\result))\n //@ ensures \\result >= 0 ==> forall(k: nat, (\\result < k && k < hi) ==> isLineTerminator(s.charCodeAt(k)))\n //@ ensures \\result === -1 ==> forall(k: nat, (lo <= k && k < hi) ==> isLineTerminator(s.charCodeAt(k)))\n if (hi <= lo) return -1;\n if (!isLineTerminator(s.charCodeAt(hi - 1))) return hi - 1;\n return lastLineCharBelow(s, hi - 1, lo);\n}\n\n/**\n * Nothing but JS whitespace (`s.trim() === \"\"`).\n *\n * @ensures exactly the model's Blank\n */\nexport function isBlank(s: string): boolean {\n //@ verify\n //@ ensures \\result <==> s.trim() === \"\"\n return s.trim() === \"\";\n}\n\n/**\n * The first index ≥ `i` where `x` occurs in `s`, or -1 (JS `s.indexOf(x, i)` for i ≤ |s|).\n *\n * @ensures result = -1 ∨ (i ≤ result ∧ s[result, result + |x|) = x) — and the first such\n * index: links/utils-strings.dfy proves it is exactly the model's IndexOfFrom (lsc can't\n * give the \"no earlier match\" quantifier a trigger)\n */\nexport function indexOfFrom(s: string, x: string, i: number): number {\n //@ verify\n //@ type i nat\n //@ requires i >= 0 && i <= s.length\n //@ decreases s.length - i\n //@ ensures \\result === -1 || (i <= \\result && \\result + x.length <= s.length)\n //@ ensures \\result >= 0 ==> s.slice(\\result, \\result + x.length) === x\n // A match here, else the end, else the next index: stopping at `i === |s|` (not \"x no\n // longer fits\") leaves no bound whose slip a later, harmless step would hide\n if (startsWithAt(s, x, i)) return i;\n if (i === s.length) return -1;\n return indexOfFrom(s, x, i + 1);\n}\n\n/**\n * `indexOfFrom` as a loop: the same answer at a constant stack depth, for text long enough that\n * one frame per character would overflow the stack (a rendered page, 50–60 KB with its inlined\n * stylesheet). Specs and links use `indexOfFrom`; runtime scans over long text use this.\n *\n * @ensures result = indexOfFrom(s, x, i)\n */\nexport function findFrom(s: string, x: string, i: number): number {\n //@ verify\n //@ type i nat\n //@ requires i >= 0 && i <= s.length\n //@ ensures \\result === indexOfFrom(s, x, i)\n let k = i;\n while (k !== s.length) {\n //@ invariant i <= k && k <= s.length\n //@ invariant indexOfFrom(s, x, k) === indexOfFrom(s, x, i)\n //@ decreases s.length - k\n if (startsWithAt(s, x, k)) return k;\n k = k + 1;\n }\n return startsWithAt(s, x, k) ? k : -1;\n}\n\n/**\n * `indexOfCode` as a loop: the same answer at a constant stack depth (see `findFrom`).\n *\n * @ensures result = indexOfCode(s, code, from)\n */\nexport function findCodeFrom(s: string, code: number, from: number): number {\n //@ verify\n //@ type from nat\n //@ requires code >= 0 && from >= 0\n //@ ensures \\result === indexOfCode(s, code, from)\n let k = from;\n while (k < s.length) {\n //@ invariant from <= k\n //@ invariant indexOfCode(s, code, k) === indexOfCode(s, code, from)\n //@ decreases s.length - k\n if (s.charCodeAt(k) === code) return k;\n k = k + 1;\n }\n return -1;\n}\n\n/**\n * How many times `x` occurs in `s` from `i` on, left to right without overlaps (repeated JS\n * `s.indexOf(x, at + x.length)`).\n *\n * @requires |x| > 0\n * @ensures result ≥ 0 — exactly the model's CountFrom (links/utils-strings.dfy)\n */\nexport function countFrom(s: string, x: string, i: number): number {\n //@ verify\n //@ type i nat\n //@ requires x.length > 0 && i >= 0 && i <= s.length\n //@ decreases s.length - i\n //@ ensures \\result >= 0\n const at = indexOfFrom(s, x, i);\n if (at === -1) return 0;\n return 1 + countFrom(s, x, at + x.length);\n}\n\n/**\n * `countFrom(s, x, 0)` as a loop: a constant stack depth on long text (see `findFrom`).\n *\n * @requires |x| > 0\n * @ensures result = countFrom(s, x, 0)\n */\nexport function countOf(s: string, x: string): number {\n //@ verify\n //@ requires x.length > 0\n //@ ensures \\result === countFrom(s, x, 0)\n let n = 0;\n let i = 0;\n let at = findFrom(s, x, 0);\n while (at !== -1) {\n //@ invariant 0 <= i && i <= s.length\n //@ invariant at === indexOfFrom(s, x, i)\n //@ invariant n + countFrom(s, x, i) === countFrom(s, x, 0)\n //@ decreases s.length - i\n n = n + 1;\n i = at + x.length;\n at = findFrom(s, x, i);\n }\n return n;\n}\n\n/**\n * The text before the first `code`, or all of it when there is none (JS `s.split(c)[0]`).\n *\n * @ensures result = s[0, first code) when s holds one, else s — the model's UntilCode\n */\nexport function untilCode(s: string, code: number): string {\n //@ verify\n //@ requires code >= 0\n //@ ensures \\result === (indexOfCode(s, code, 0) >= 0 && indexOfCode(s, code, 0) <= s.length ? s.slice(0, indexOfCode(s, code, 0)) : s)\n const k = indexOfCode(s, code, 0);\n return k >= 0 ? s.slice(0, k) : s;\n}\n\n/**\n * `s` from `i` on split at every `code` (JS `s.split(c)` at i = 0, for a one-character\n * separator): always at least one part.\n *\n * @ensures |result| ≥ 1 — exactly the model's SplitCodeFrom (links/utils-strings.dfy)\n */\nexport function splitCodeFrom(s: string, code: number, i: number): string[] {\n //@ verify\n //@ type i nat\n //@ requires code >= 0 && i >= 0 && i <= s.length\n //@ decreases s.length - i\n //@ ensures \\result.length > 0\n const k = indexOfCode(s, code, i);\n if (k === -1) return [s.slice(i)];\n return [s.slice(i, k), ...splitCodeFrom(s, code, k + 1)];\n}\n\n/**\n * Every run of JS whitespace in `s` from `i` on as one space (JS `s.replace(/\\s+/g, \" \")` at\n * i = 0).\n *\n * @ensures |result| ≤ |s| − i — exactly the model's CollapseSpacesFrom (links/utils-strings.dfy)\n */\nexport function collapseSpacesFrom(s: string, i: number): string {\n //@ verify\n //@ type i nat\n //@ requires 0 <= i && i <= s.length\n //@ decreases s.length - i\n //@ ensures \\result.length <= s.length - i\n if (i === s.length) return \"\";\n if (isJsSpace(s.charCodeAt(i))) return \" \" + collapseSpacesFrom(s, spaceRunEnd(s, i));\n return s.slice(i, i + 1) + collapseSpacesFrom(s, i + 1);\n}\n\n/**\n * `collapseSpacesFrom(s, 0)` at a constant stack depth (a page's text is tens of KB).\n *\n * @ensures result = collapseSpacesFrom(s, 0)\n */\nexport function collapseSpaces(s: string): string {\n //@ verify\n //@ ensures \\result === collapseSpacesFrom(s, 0)\n let out = \"\";\n let i = 0;\n while (i < s.length) {\n //@ invariant 0 <= i && i <= s.length\n //@ invariant out + collapseSpacesFrom(s, i) === collapseSpacesFrom(s, 0)\n //@ decreases s.length - i\n if (isJsSpace(s.charCodeAt(i))) {\n out = out + \" \";\n i = spaceRunEnd(s, i);\n } else {\n out = out + s.slice(i, i + 1);\n i = i + 1;\n }\n }\n return out;\n}\n\n/**\n * `n` spaces.\n *\n * @ensures result = \" \" repeated n times — the model's Spaces\n */\nexport function spaces(n: number): string {\n //@ verify\n //@ type n nat\n //@ requires n >= 0\n //@ decreases n\n //@ ensures \\result.length === n\n //@ ensures forall(k: nat, k < n ==> \\result.charCodeAt(k) === 32)\n if (n === 0) return \"\";\n return \" \" + spaces(n - 1);\n}\n\n/**\n * A line feed, `\"\\n\"`, for proved text that spans lines: lsc emits a `\"\\n\"` escape raw, which\n * Dafny cannot parse (models/LSC-GAPS.md), so the contract pins it by code unit and the body is\n * a template literal holding the line break itself.\n *\n * @ensures result = \"\\n\" — one code unit, 10\n */\nexport function lineFeed(): string {\n //@ verify\n //@ ensures \\result.length === 1 && \\result.charCodeAt(0) === 10\n return `\n`;\n}\n\n/**\n * `s` padded on the left with spaces to `width` (JS `s.padStart(width)`).\n *\n * @ensures result = Spaces(width − |s|) + s when width > |s|, else s\n */\nexport function padLeft(s: string, width: number): string {\n //@ verify\n //@ ensures width <= s.length ==> \\result === s\n // width > |s| ⟹ spaces(width − |s|) + s: a hand ensures in strings.dfy, so importers'\n // axioms name no helper (models/LSC-GAPS.md). Math.max, not a ternary: at width = |s|\n // both branches agree (spaces(0) is \"\"), so `>` vs `>=` would be equivalent.\n return spaces(Math.max(width - s.length, 0)) + s;\n}\n\n/**\n * `s` padded on the right with spaces to `width` (JS `s.padEnd(width)`).\n *\n * @ensures result = s + Spaces(width − |s|) when width > |s|, else s\n */\nexport function padRight(s: string, width: number): string {\n //@ verify\n //@ ensures width <= s.length ==> \\result === s\n // width > |s| ⟹ s + spaces(width − |s|): a hand ensures in strings.dfy, as padLeft's.\n return s + spaces(Math.max(width - s.length, 0));\n}\n\n/**\n * An optional part of a key: `tag` then `text`, or nothing when `text` is empty, so an absent\n * part never leaves a bare tag.\n *\n * @ensures result = \"\" when text = \"\", else tag + text — exactly the model's KeyPart\n */\nexport function keyPart(tag: string, text: string): string {\n //@ verify\n //@ ensures \\result === (text === \"\" ? \"\" : tag + text)\n return text === \"\" ? \"\" : tag + text;\n}\n\n/**\n * Two texts joined by one space: the one rule behind a loader key's `<column> <direction>`, a\n * sync line's `METHOD /path` and a field's description then note.\n *\n * @ensures result = a + \" \" + b — exactly the model's SpaceJoined\n */\nexport function spaceJoined(a: string, b: string): string {\n //@ verify\n //@ ensures \\result === a + \" \" + b\n return a + \" \" + b;\n}\n\n/**\n * Whether `x` occurs in `s` at some index ≥ `i` (JS `s.includes(x, i)` for i ≤ |s|).\n *\n * @ensures result ⟺ ∃ k. i ≤ k ≤ |s| ∧ startsWithAt(s, x, k) — exactly the model's\n * IncludesFrom: a hand lemma in strings.dfy (`includesFrom_exists`), so importers' axioms\n * name no helper (models/LSC-GAPS.md)\n */\nexport function includesFrom(s: string, x: string, i: number): boolean {\n //@ verify\n //@ type i nat\n //@ requires i >= 0\n //@ decreases s.length + 1 - i\n if (i > s.length) return false;\n if (startsWithAt(s, x, i)) return true;\n return includesFrom(s, x, i + 1);\n}\n\n/**\n * `s` with a-z uppercased and every other character kept, the mirror of `lowerAscii`: JS's\n * `toUpperCase()` also maps non-ASCII letters (ß becomes \"SS\").\n *\n * @ensures result = s with a-z uppercased — same length, every other character unchanged\n */\nexport function upperAscii(s: string): string {\n //@ verify\n //@ decreases s.length\n //@ ensures \\result === s.toUpperCase()\n if (s.length === 0) return \"\";\n const c = s.charCodeAt(0);\n const head =\n c >= 97 && c <= 122 ? \"ABCDEFGHIJKLMNOPQRSTUVWXYZ\".slice(c - 97, c - 96) : s.slice(0, 1);\n return head + upperAscii(s.slice(1));\n}\n","//@ backend dafny\nimport { indexOfCode } from \"@atlas/utils/strings\";\n\n/* The hooks' decisions, as pure functions verified with LemmaScript → Dafny (model:\n models/AugurHooks.dfy; link: models/links/augur-hooks-rules.dfy). The hooks keep the React\n state, timers and storage; a NaN or string uid is turned into a number or `undefined` by the\n caller before it gets here. */\n\n/**\n * The cart's quantity total: `acc` plus each quantity from index `i` on, added left to right as\n * `reduce` does (each line's quantity, null or NaN as 0, already taken by the caller).\n *\n * @ensures result = acc + Σ_{k ≥ i} quantities[k], the model's QuantityTotal at acc = i = 0\n */\nexport function quantityTotalFrom(quantities: number[], i: number, acc: number): number {\n //@ verify\n //@ type i nat\n //@ requires i >= 0 && i <= quantities.length\n //@ decreases quantities.length - i\n //@ ensures i === quantities.length ==> \\result === acc\n //@ ensures i < quantities.length ==> \\result === quantityTotalFrom(quantities, i + 1, acc + quantities[i])\n if (i === quantities.length) return acc;\n return quantityTotalFrom(quantities, i + 1, acc + (quantities[i] as number));\n}\n\n/**\n * A cart line's quantity with null as 0.\n *\n * @ensures result = q ?? 0, the model's QtyOrZero\n */\nexport function qtyOrZero(q: number | null): number {\n //@ verify\n //@ ensures q === null ==> \\result === 0\n //@ ensures q !== null ==> \\result === q\n if (q === null) return 0;\n return q;\n}\n\n/**\n * The first index from `i` whose item uid is `uid`, or −1 (JS `findIndex` at i = 0).\n *\n * @ensures exactly the model's IndexOfUid\n */\nexport function indexOfUidFrom(uids: number[], uid: number, i: number): number {\n //@ verify\n //@ type i nat\n //@ requires i >= 0 && i <= uids.length\n //@ decreases uids.length - i\n //@ ensures i === uids.length ==> \\result === -1\n //@ ensures i < uids.length && uids[i] === uid ==> \\result === i\n //@ ensures i < uids.length && uids[i] !== uid ==> \\result === indexOfUidFrom(uids, uid, i + 1)\n if (i === uids.length) return -1;\n if ((uids[i] as number) === uid) return i;\n return indexOfUidFrom(uids, uid, i + 1);\n}\n\n/**\n * Reversing an add keeps a matched line only while something is left of it.\n *\n * @ensures result ⟺ (current ?? 0) − q > 0, the model's ReverseAdd keep rule\n */\nexport function keepsAfterReverse(current: number | null, q: number): boolean {\n //@ verify\n //@ ensures \\result === (qtyOrZero(current) - q > 0)\n return qtyOrZero(current) - q > 0;\n}\n\n/**\n * requireCartUid: a missing or 0 uid refuses (null); the hooks throw on it.\n *\n * @ensures result = null ⟺ uid ∈ {undefined, 0}; otherwise result = uid\n */\nexport function requiredCartUid(uid: number | undefined): number | null {\n //@ verify\n //@ ensures uid === undefined ==> \\result === null\n //@ ensures uid !== undefined && uid === 0 ==> \\result === null\n //@ ensures uid !== undefined && uid !== 0 ==> \\result === uid\n if (uid === undefined) return null;\n if (uid === 0) return null;\n return uid;\n}\n\n/**\n * resolveCartHdrUid (checkout): a missing uid is 0; any other passes unchanged.\n *\n * @ensures result = uid ?? 0\n */\nexport function checkoutCartUid(uid: number | undefined): number {\n //@ verify\n //@ ensures uid === undefined ==> \\result === 0\n //@ ensures uid !== undefined ==> \\result === uid\n if (uid === undefined) return 0;\n return uid;\n}\n\n/**\n * The initial payment method: the site hook's non-empty answer, else credit card when payments\n * are configured, else invoice.\n *\n * @ensures exactly the model's DefaultPaymentMethod\n */\nexport function defaultPaymentMethodOf(\n fromHook: string | undefined,\n hasCallbacks: boolean,\n): string {\n //@ verify\n //@ ensures fromHook !== undefined && fromHook !== \"\" ==> \\result === fromHook\n //@ ensures (fromHook === undefined || fromHook === \"\") && hasCallbacks ==> \\result === \"credit-card\"\n //@ ensures (fromHook === undefined || fromHook === \"\") && !hasCallbacks ==> \\result === \"invoice\"\n if (fromHook !== undefined && fromHook !== \"\") return fromHook;\n return hasCallbacks ? \"credit-card\" : \"invoice\";\n}\n\n/** The default order gates' inputs, each already reduced to a flag by the caller. */\nexport interface ReadinessFlags {\n cartUidSet: boolean;\n editShippingInfo: boolean;\n editShippingMethods: boolean;\n editBillingInfo: boolean;\n editCc: boolean;\n hasShippingAddress: boolean;\n hasBillingAddress: boolean;\n methodSaved: boolean;\n showBillingSummary: boolean;\n processing: boolean;\n isCreditCard: boolean;\n hasAccountId: boolean;\n hasUnifiedBilling: boolean;\n isFreeShipping: boolean;\n hasShippingFee: boolean;\n}\n\n/**\n * The default gates: a cart, nothing being edited, both addresses, a saved method, the billing\n * summary shown, not processing, a completed card flow for credit card, and a fee unless\n * shipping is free.\n *\n * @ensures exactly the model's DefaultReady\n */\nexport function defaultReady(r: ReadinessFlags): boolean {\n //@ verify\n //@ ensures \\result === (nothingBusy(r) && detailsComplete(r) && paymentSettled(r))\n return nothingBusy(r) && detailsComplete(r) && paymentSettled(r);\n}\n\n/**\n * No section is being edited and no order is processing.\n *\n * @ensures result ⟺ ¬edit* ∧ ¬processing\n */\nfunction nothingBusy(r: ReadinessFlags): boolean {\n //@ verify\n //@ ensures \\result === (!r.editShippingInfo && !r.editShippingMethods && !r.editBillingInfo && !r.editCc && !r.processing)\n return (\n !r.editShippingInfo &&\n !r.editShippingMethods &&\n !r.editBillingInfo &&\n !r.editCc &&\n !r.processing\n );\n}\n\n/**\n * A cart, both addresses, a saved method and the billing summary shown.\n *\n * @ensures result ⟺ the cart and checkout details are all present\n */\nfunction detailsComplete(r: ReadinessFlags): boolean {\n //@ verify\n //@ ensures \\result === (r.cartUidSet && r.hasShippingAddress && r.hasBillingAddress && r.methodSaved && r.showBillingSummary)\n return (\n r.cartUidSet &&\n r.hasShippingAddress &&\n r.hasBillingAddress &&\n r.methodSaved &&\n r.showBillingSummary\n );\n}\n\n/**\n * A completed card flow for credit card, and a fee unless shipping is free.\n *\n * @ensures result ⟺ (card ⟹ account ∧ unified) ∧ (free ∨ fee)\n */\nfunction paymentSettled(r: ReadinessFlags): boolean {\n //@ verify\n //@ ensures \\result === ((!r.isCreditCard || (r.hasAccountId && r.hasUnifiedBilling)) && (r.isFreeShipping || r.hasShippingFee))\n return (\n (!r.isCreditCard || (r.hasAccountId && r.hasUnifiedBilling)) &&\n (r.isFreeShipping || r.hasShippingFee)\n );\n}\n\n/**\n * A site's own readiness answer wins; undefined defers to the default gates.\n *\n * @ensures result = custom ?? defaultReady\n */\nexport function orderReadyOf(custom: boolean | undefined, ready: boolean): boolean {\n //@ verify\n //@ ensures custom !== undefined ==> \\result === custom\n //@ ensures custom === undefined ==> \\result === ready\n if (custom !== undefined) return custom;\n return ready;\n}\n\n/** The pre-submit outcome: go ahead, the site cancelled it, or refused with a message. */\nexport type PreSubmit =\n { kind: \"ok\" } | { kind: \"cancelled\" } | { kind: \"refused\"; message: string };\n\n/**\n * runPreSubmitChecks: the site's validation error first (an empty one is no error), then its\n * beforeSubmit veto, then a missing shipping address.\n *\n * @ensures exactly the model's PreSubmitOutcome (an empty validation error as None)\n */\nexport function preSubmitOutcome(\n validateError: string | undefined,\n beforeSubmitFalse: boolean,\n hasShippingAddress: boolean,\n): PreSubmit {\n //@ verify\n //@ ensures validateError !== undefined && validateError !== \"\" ==> \\result.kind === \"refused\" && \\result.message === validateError\n //@ ensures (validateError === undefined || validateError === \"\") && beforeSubmitFalse ==> \\result.kind === \"cancelled\"\n //@ ensures (validateError === undefined || validateError === \"\") && !beforeSubmitFalse && !hasShippingAddress ==> \\result.kind === \"refused\" && \\result.message === \"Shipping address is required.\"\n //@ ensures (validateError === undefined || validateError === \"\") && !beforeSubmitFalse && hasShippingAddress ==> \\result.kind === \"ok\"\n if (validateError !== undefined && validateError !== \"\") {\n return { kind: \"refused\", message: validateError };\n }\n if (beforeSubmitFalse) return { kind: \"cancelled\" };\n if (!hasShippingAddress) return { kind: \"refused\", message: \"Shipping address is required.\" };\n return { kind: \"ok\" };\n}\n\n/**\n * A cookie entry's `split(\"=\")[1]`: the text between the first and second \"=\" (to the end with\n * no second), or \"\" with no \"=\". A token holding \"=\" is cut at it, as before.\n *\n * @ensures exactly the model's SecondEqualsField\n */\nexport function secondEqualsField(s: string): string {\n //@ verify\n //@ ensures indexOfCode(s, 61, 0) < 0 ==> \\result === \"\"\n //@ ensures indexOfCode(s, 61, 0) >= 0 && indexOfCode(s, 61, indexOfCode(s, 61, 0) + 1) < 0 ==> \\result === s.slice(indexOfCode(s, 61, 0) + 1)\n //@ ensures indexOfCode(s, 61, 0) >= 0 && indexOfCode(s, 61, indexOfCode(s, 61, 0) + 1) >= 0 ==> \\result === s.slice(indexOfCode(s, 61, 0) + 1, indexOfCode(s, 61, indexOfCode(s, 61, 0) + 1))\n const k = indexOfCode(s, 61, 0);\n if (k < 0) return \"\";\n const j = indexOfCode(s, 61, k + 1);\n if (j < 0) return s.slice(k + 1);\n return s.slice(k + 1, j);\n}\n\n/**\n * A saved checkout entry is expired once more than `ttl` ms have passed since it was saved.\n *\n * @ensures result ⟺ now − savedAt > ttl\n */\nexport function isExpired(now: number, savedAt: number, ttl: number): boolean {\n //@ verify\n //@ ensures \\result === (now - savedAt > ttl)\n return now - savedAt > ttl;\n}\n\n/**\n * A query is persisted iff it has a string head that is listed and it succeeded.\n *\n * @ensures exactly the model's ShouldPersist, with the listing already looked up\n */\nexport function shouldPersistOf(hasHead: boolean, succeeded: boolean, listed: boolean): boolean {\n //@ verify\n //@ ensures \\result === (hasHead && succeeded && listed)\n return hasHead && succeeded && listed;\n}\n\n/**\n * 2ⁿ.\n *\n * @ensures result = 2ⁿ, the model's Pow2\n */\nexport function pow2(n: number): number {\n //@ verify\n //@ type n nat\n //@ requires n >= 0\n //@ decreases n\n //@ ensures n === 0 ==> \\result === 1\n //@ ensures n > 0 ==> \\result === 2 * pow2(n - 1)\n if (n === 0) return 1;\n return 2 * pow2(n - 1);\n}\n\n/**\n * A stock fetch's retry delay: 1000 · 2ⁿ ms, at most 10 s (n ≥ 4 is always the cap).\n *\n * @ensures exactly the model's StockRetryDelay\n */\nexport function stockRetryDelay(attemptIndex: number): number {\n //@ verify\n //@ type attemptIndex nat\n //@ requires attemptIndex >= 0\n //@ ensures 1000 * pow2(attemptIndex) < 10000 ==> \\result === 1000 * pow2(attemptIndex)\n //@ ensures 1000 * pow2(attemptIndex) >= 10000 ==> \\result === 10000\n // The cap first, so a large n never recurses: 2⁴ · 1000 already exceeds it, 2³ · 1000 does not.\n if (attemptIndex >= 4) return 10000;\n return 1000 * pow2(attemptIndex);\n}\n\n/**\n * useStock fetches only when enabled (default true) and given a uid.\n *\n * @ensures exactly the model's StockEnabled\n */\nexport function stockEnabled(enabled: boolean | undefined, uidSet: boolean): boolean {\n //@ verify\n //@ ensures \\result === ((enabled === undefined || enabled === true) && uidSet)\n return (enabled === undefined || enabled === true) && uidSet;\n}\n","\"use client\";\n\nimport { useEffect, useRef } from \"react\";\nimport { isExpired } from \"../rules\";\n\n/** A single persisted field with its storage key and optional TTL. */\nexport interface CheckoutPersistField<T> {\n key: string;\n value: T;\n set: (value: T) => void;\n /** Valibot or custom validator. Return the parsed value or throw to reject. */\n validate?: (raw: unknown) => T;\n /** TTL in milliseconds. Default: 30 minutes. */\n ttl?: number;\n}\n\ninterface StorageEntry {\n value: unknown;\n savedAt: number;\n}\n\nconst DEFAULT_TTL = 30 * 60 * 1000; // 30 minutes\n\n/**\n * Saves a value to sessionStorage with a timestamp for TTL expiration.\n *\n * Fails silently on storage errors (private browsing, quota exceeded).\n */\nexport function saveToSession(key: string, value: unknown): void {\n try {\n const entry: StorageEntry = { value, savedAt: Date.now() };\n sessionStorage.setItem(key, JSON.stringify(entry));\n } catch {\n // sessionStorage unavailable (private browsing, quota)\n }\n}\n\n/**\n * Loads a value from sessionStorage, checking TTL and optionally validating.\n *\n * Returns null if missing, expired, invalid, or storage is unavailable.\n * Cleans up expired entries automatically.\n */\nexport function loadFromSession<T>(\n key: string,\n ttl: number = DEFAULT_TTL,\n validate?: (raw: unknown) => T,\n): T | null {\n try {\n const raw = sessionStorage.getItem(key);\n if (!raw) return null;\n\n const entry = JSON.parse(raw) as StorageEntry;\n if (isExpired(Date.now(), entry.savedAt, ttl)) {\n sessionStorage.removeItem(key);\n return null;\n }\n\n if (validate) {\n return validate(entry.value);\n }\n return entry.value as T;\n } catch {\n sessionStorage.removeItem(key);\n return null;\n }\n}\n\n/** Removes a checkout persistence key from sessionStorage. */\nexport function clearFromSession(key: string): void {\n try {\n sessionStorage.removeItem(key);\n } catch {\n // ignore\n }\n}\n\n/**\n * Hook that persists checkout state fields to sessionStorage and restores on mount.\n *\n * Each field is saved when its value changes and restored once on initial mount.\n * Validates restored values against an optional schema to guard against\n * corrupted or stale storage. Expired entries (past TTL) are discarded.\n */\nexport function useCheckoutPersistence(fields: CheckoutPersistField<unknown>[]): void {\n // Restore on mount (once). Capture fields in a ref so the effect has no deps.\n const fieldsRef = useRef(fields);\n fieldsRef.current = fields;\n\n useEffect(() => {\n for (const field of fieldsRef.current) {\n const restored = loadFromSession(field.key, field.ttl ?? DEFAULT_TTL, field.validate);\n if (restored !== null) {\n field.set(restored);\n }\n }\n }, []);\n\n // Save on change -- serialized values as dependency to avoid dynamic dep arrays; the\n // fields themselves are read through the ref (this render's array)\n const serialized = JSON.stringify(fields.map((f) => [f.key, f.value]));\n useEffect(() => {\n for (const field of fieldsRef.current) {\n if (field.value !== undefined && field.value !== null) {\n saveToSession(field.key, field.value);\n }\n }\n }, [serialized]);\n}\n\n/**\n * Clears all checkout persistence keys from sessionStorage.\n *\n * Call after successful order submission to prevent stale data on next checkout.\n */\nexport function clearCheckoutPersistence(keys: string[]): void {\n for (const key of keys) {\n clearFromSession(key);\n }\n}\n","import { useCallback, useEffect, useRef, useState } from \"react\";\nimport type { Dispatch, SetStateAction } from \"react\";\nimport type {\n TTransactionSetup,\n TCardInfo,\n TPaymentValidation,\n TAccountQuery,\n TBillingUpdate,\n} from \"@simpleapps-com/augur-utils\";\nimport { saveToSession, loadFromSession, clearFromSession } from \"./use-checkout-persistence\";\n\n/** Site-specific payment action callbacks injected into usePaymentFlow. */\nexport interface PaymentFlowCallbacks {\n /** Initialize a payment session. Returns transaction setup or undefined on failure. */\n transactionSetup: (params: { customerId: string }) => Promise<TTransactionSetup | undefined>;\n /** Retrieve card details after iframe entry. */\n cardInfo: (params: { transactionSetupId: string }) => Promise<TCardInfo | undefined>;\n /** Verify card is valid. */\n validatePayment: (params: {\n transactionSetupId: string;\n customerId: string;\n }) => Promise<TPaymentValidation | undefined>;\n /** Get payment account ID. */\n accountQuery: (params: {\n transactionSetupId: string;\n customerId: string;\n }) => Promise<TAccountQuery | undefined>;\n /** Send billing address to payment processor. */\n billingUpdate: (params: {\n transactionSetupId: string;\n address1: string;\n address2?: string;\n city: string;\n state: string;\n zip: string;\n }) => Promise<TBillingUpdate | undefined>;\n /** Optional toast notification callback. */\n toast?: {\n error?: (message: string) => void;\n };\n}\n\n/** Billing address shape accepted by the payment flow. */\nexport interface PaymentBillingAddress {\n address1: string;\n address2?: string;\n city: string;\n state: string;\n postalCode: string;\n}\n\ninterface UsePaymentFlowParams {\n callbacks: PaymentFlowCallbacks;\n customerId: string | number | undefined;\n billingAddress: PaymentBillingAddress | undefined;\n paymentMethod: string;\n shippingAccepted: boolean;\n /** Persist payment tokens to sessionStorage for cross-navigation recovery. */\n persistPayment?: boolean;\n}\n\n/** sessionStorage key for persisted payment tokens. */\nexport const PAYMENT_STORAGE_KEY = \"checkout:payment\";\n\n/** Shape of persisted payment data. Only token IDs, never card data (PCI-DSS). */\ninterface PersistedPayment {\n transactionSetupId: string;\n uiEndpoint: string;\n paymentAccountId: string;\n}\n\n/** State and setters returned by usePaymentFlow. */\ninterface PaymentFlow {\n isOpen: boolean;\n setIsOpen: Dispatch<SetStateAction<boolean>>;\n editCc: boolean;\n setEditCc: Dispatch<SetStateAction<boolean>>;\n unified: TTransactionSetup | null;\n unifiedCc: TCardInfo | null;\n unifiedResponse: boolean;\n unifiedBilling: boolean;\n unifiedPayment: TAccountQuery | null;\n capturedBin: string | null;\n handleBinCapture: (bin: string) => void;\n}\n\nfunction toastError(callbacks: PaymentFlowCallbacks, message: string): void {\n callbacks.toast?.error?.(message);\n}\n\n/** The account with the BIN captured from the iframe when the processor sent none. */\nfunction withCapturedBin(account: TAccountQuery, capturedBin: string | null): TAccountQuery {\n return capturedBin && !account.Bin ? { ...account, Bin: capturedBin } : account;\n}\n\n/** The tokens to persist: only when persisting is on and the processor returned an account ID. */\nfunction paymentToPersist(\n transactionSetupId: string,\n uiEndpoint: TTransactionSetup[\"uiEndpoint\"],\n account: TAccountQuery,\n persistPayment: boolean | undefined,\n): PersistedPayment | null {\n if (!persistPayment || !account.PaymentAccountID) return null;\n return {\n transactionSetupId,\n uiEndpoint,\n paymentAccountId: account.PaymentAccountID,\n };\n}\n\n/** A saved payment is restorable when all three tokens are present. */\nfunction isRestorable(saved: PersistedPayment | null | undefined): saved is PersistedPayment {\n return Boolean(saved?.transactionSetupId && saved.uiEndpoint && saved.paymentAccountId);\n}\n\n/**\n * Manages the full Element/Unified payment lifecycle:\n * transactionSetup -> cardInfo -> validatePayment -> accountQuery -> billingUpdate\n *\n * Accepts site-specific server action callbacks so the hook has no dependency\n * on any particular server action implementation.\n *\n * @example\n * ```tsx\n * import { usePaymentFlow } from \"@simpleapps-com/augur-hooks\";\n * import { transactionSetup, cardInfo, validatePayment, accountQuery, billingUpdate } from \"@/lib/actions/payments\";\n *\n * const payment = usePaymentFlow({\n * callbacks: { transactionSetup, cardInfo, validatePayment, accountQuery, billingUpdate },\n * customerId,\n * billingAddress,\n * paymentMethod: \"credit-card\",\n * shippingAccepted: true,\n * });\n * ```\n */\nexport function usePaymentFlow({\n callbacks,\n customerId,\n billingAddress,\n paymentMethod,\n shippingAccepted,\n persistPayment,\n}: UsePaymentFlowParams): PaymentFlow {\n const [isOpen, setIsOpen] = useState(false);\n const [unified, setUnified] = useState<TTransactionSetup | null>(null);\n const [unifiedCc, setUnifiedCc] = useState<TCardInfo | null>(null);\n const [unifiedResponse, setUnifiedResponse] = useState(false);\n const [unifiedBilling, setUnifiedBilling] = useState(false);\n const [unifiedPayment, setUnifiedPayment] = useState<TAccountQuery | null>(null);\n const [capturedBin, setCapturedBin] = useState<string | null>(null);\n const [editCc, setEditCc] = useState(false);\n\n const handleBinCapture = useCallback((bin: string) => {\n setCapturedBin(bin);\n }, []);\n\n // Ref ensures callbacks always read the latest customerId, avoiding stale\n // closures when React batches state updates (e.g., modal close + verify).\n const customerIdRef = useRef(customerId);\n customerIdRef.current = customerId;\n\n // @invariant verifyUnified runs at most once per transactionSetupId\n // (hasVerifiedRef.current ∈ {null} ∪ {setupId already verified}; a fresh\n // setupId ⇒ exactly one verify). Without this, the post-close verify effect\n // re-fires whenever the consumer's inline `callbacks` prop changes identity\n // (every parent render), spraying redundant validatePayment/cardInfo calls\n // at the payment gateway. Keyed by setupId, not a boolean, so a new setup\n // (edit-card) re-verifies while a restored setup is treated as done.\n const hasVerifiedRef = useRef<string | null>(null);\n\n // Step 1: Initialize payment session\n const postUnified = useCallback(async () => {\n if (!customerIdRef.current) return;\n try {\n const result = await callbacks.transactionSetup({\n customerId: String(customerIdRef.current),\n });\n if (!result) {\n toastError(callbacks, \"Unable to initialize payment. Please try again.\");\n return;\n }\n setUnified(result);\n } catch (error) {\n console.error(\"transactionSetup failed:\", error);\n toastError(callbacks, \"Unable to initialize payment. Please try again.\");\n }\n }, [callbacks]);\n\n // Step 2: Get card info after iframe entry (called by verifyUnified with its setup ID)\n const getCardInfo = useCallback(\n async (transactionSetupId: string) => {\n try {\n const result = await callbacks.cardInfo({ transactionSetupId });\n if (!result) {\n toastError(callbacks, \"Unable to verify card details. Please try again.\");\n return;\n }\n setUnifiedCc(result);\n } catch (error) {\n console.error(\"cardInfo failed:\", error);\n toastError(callbacks, \"Unable to verify card details. Please try again.\");\n }\n },\n [callbacks],\n );\n\n // Step 3: Validate payment\n const verifyUnified = useCallback(async () => {\n const transactionSetupId = unified?.transactionSetupId;\n if (!transactionSetupId || !customerIdRef.current) return;\n try {\n const result = await callbacks.validatePayment({\n transactionSetupId,\n customerId: String(customerIdRef.current),\n });\n if (result === undefined) {\n toastError(callbacks, \"Payment verification failed. Please try again.\");\n return;\n }\n setUnifiedResponse(result);\n if (result) {\n await getCardInfo(transactionSetupId);\n }\n } catch (error) {\n console.error(\"validatePayment failed:\", error);\n toastError(callbacks, \"Payment verification failed. Please try again.\");\n }\n }, [unified, getCardInfo, callbacks]);\n\n // Step 4: Get payment account info\n const getUnifiedPayment = useCallback(async () => {\n if (!unified?.transactionSetupId || !customerIdRef.current) return;\n try {\n const result = await callbacks.accountQuery({\n transactionSetupId: unified.transactionSetupId,\n customerId: String(customerIdRef.current),\n });\n if (!result) {\n toastError(callbacks, \"Unable to retrieve payment account. Please try again.\");\n return;\n }\n setUnifiedPayment(withCapturedBin(result, capturedBin));\n const toPersist = paymentToPersist(\n unified.transactionSetupId,\n unified.uiEndpoint,\n result,\n persistPayment,\n );\n if (toPersist) saveToSession(PAYMENT_STORAGE_KEY, toPersist);\n } catch (error) {\n console.error(\"accountQuery failed:\", error);\n toastError(callbacks, \"Unable to retrieve payment account. Please try again.\");\n }\n }, [unified, capturedBin, callbacks, persistPayment]);\n\n // Step 5: Update billing info (called by the billing effect with the setup ID and address)\n const updateUnifiedBilling = useCallback(\n async (transactionSetupId: string, address: PaymentBillingAddress) => {\n try {\n const result = await callbacks.billingUpdate({\n transactionSetupId,\n address1: address.address1,\n address2: address.address2,\n city: address.city,\n state: address.state,\n zip: address.postalCode,\n });\n if (!result) {\n toastError(callbacks, \"Billing update failed. Please try again.\");\n return;\n }\n setUnifiedBilling(true);\n void getUnifiedPayment();\n } catch (error) {\n console.error(\"billingUpdate failed:\", error);\n toastError(callbacks, \"Billing update failed. Please try again.\");\n }\n },\n [getUnifiedPayment, callbacks],\n );\n\n // Close payment modal if preconditions are lost\n useEffect(() => {\n if (isOpen && (!shippingAccepted || paymentMethod !== \"credit-card\")) {\n setIsOpen(false);\n }\n }, [isOpen, shippingAccepted, paymentMethod]);\n\n // Initialize payment setup when modal opens with no transaction\n useEffect(() => {\n if (isOpen && shippingAccepted && paymentMethod === \"credit-card\" && unified === null) {\n void postUnified();\n }\n }, [isOpen, shippingAccepted, paymentMethod, unified, postUnified]);\n\n // Verify payment after modal closes. Guard by transactionSetupId so the\n // effect verifies once per setup instead of re-firing on every parent render\n // (the consumer's inline `callbacks` prop churns verifyUnified's identity).\n useEffect(() => {\n const setupId = unified?.transactionSetupId;\n if (!isOpen && setupId && shippingAccepted && paymentMethod === \"credit-card\") {\n if (hasVerifiedRef.current === setupId) return;\n hasVerifiedRef.current = setupId;\n void verifyUnified();\n }\n }, [isOpen, unified, shippingAccepted, paymentMethod, verifyUnified]);\n\n // Trigger billing update when card verified + billing address ready (against the current\n // setup; there is nothing to update without one)\n const setupId = unified?.transactionSetupId;\n useEffect(() => {\n if (\n unifiedResponse &&\n billingAddress !== undefined &&\n unifiedCc?.transactionSetupId &&\n paymentMethod === \"credit-card\" &&\n setupId\n ) {\n void updateUnifiedBilling(setupId, billingAddress);\n }\n }, [\n unifiedResponse,\n billingAddress,\n unifiedCc?.transactionSetupId,\n updateUnifiedBilling,\n paymentMethod,\n setupId,\n ]);\n\n // Reset all payment state when editing CC\n useEffect(() => {\n if (editCc) {\n setIsOpen(true);\n setUnified(null);\n setUnifiedCc(null);\n setUnifiedPayment(null);\n setUnifiedBilling(false);\n setUnifiedResponse(false);\n setCapturedBin(null);\n hasVerifiedRef.current = null;\n if (persistPayment) {\n clearFromSession(PAYMENT_STORAGE_KEY);\n }\n }\n }, [editCc, persistPayment]);\n\n // Restore persisted payment tokens on mount\n const restorePayment = useCallback(async () => {\n if (!customerIdRef.current) return;\n\n const saved = loadFromSession<PersistedPayment>(PAYMENT_STORAGE_KEY);\n if (!isRestorable(saved)) return;\n\n const { transactionSetupId, uiEndpoint } = saved;\n try {\n const account = await callbacks.accountQuery({\n transactionSetupId,\n customerId: String(customerIdRef.current),\n });\n if (!account?.PaymentAccountID) {\n clearFromSession(PAYMENT_STORAGE_KEY);\n return;\n }\n // Restore already proved this setup valid (accountQuery succeeded);\n // mark it verified so the post-close effect does not re-validate it.\n hasVerifiedRef.current = transactionSetupId;\n setUnified({ transactionSetupId, uiEndpoint });\n setUnifiedPayment(account);\n setUnifiedResponse(true);\n setUnifiedBilling(true);\n const card = await callbacks.cardInfo({ transactionSetupId });\n if (card) setUnifiedCc(card);\n } catch {\n clearFromSession(PAYMENT_STORAGE_KEY);\n }\n }, [callbacks]);\n\n // Restore runs when persistPayment turns on (and on mount), not each time the consumer's\n // inline `callbacks` change identity: the effect reads the latest restorePayment through a ref.\n const restorePaymentRef = useRef(restorePayment);\n restorePaymentRef.current = restorePayment;\n useEffect(() => {\n if (persistPayment) {\n void restorePaymentRef.current();\n }\n }, [persistPayment]);\n\n return {\n isOpen,\n setIsOpen,\n editCc,\n setEditCc,\n unified,\n unifiedCc,\n unifiedResponse,\n unifiedBilling,\n unifiedPayment,\n capturedBin,\n handleBinCapture,\n };\n}\n","\"use client\";\n\nimport { useEffect, useState } from \"react\";\nimport { defaultReady, orderReadyOf, type ReadinessFlags } from \"../rules\";\nimport { useLatest } from \"./use-latest\";\n\n/** Parameters for order readiness validation. */\nexport interface OrderReadinessParams {\n cartHdrUid: string | number | undefined;\n shippingAddress: unknown;\n billingAddress: unknown;\n shippingMethodSaved: boolean;\n showBillingInfoSummary: boolean;\n processingOrder: boolean;\n paymentMethod: string;\n unifiedPaymentAccountId: string | undefined;\n unifiedBilling: boolean;\n isFreeShipping: boolean;\n carrierId: string;\n shippingFee: number | undefined;\n isEditShippingInfo: boolean;\n isEditShippingMethods: boolean;\n isEditBillingInfo: boolean;\n editCc: boolean;\n /**\n * Site-provided function to check if the order is ready.\n *\n * Return `true` or `false` to override the default gates. Return\n * `undefined` to defer to the default logic (useful when the override\n * only applies to specific order flows — e.g. sample-only or pickup).\n */\n customReadinessCheck?: (params: OrderReadinessParams) => boolean | undefined;\n}\n\n/**\n * Pure function that determines if an order is ready to submit.\n *\n * Checks all gates: cart exists, addresses present, shipping method saved,\n * billing shown, payment complete (for credit card), shipping fee present\n * (for non-free, non-pickup orders), and no sections being edited.\n */\nexport function determineOrderReadiness(params: OrderReadinessParams): boolean {\n return orderReadyOf(params.customReadinessCheck?.(params), defaultReady(readinessFlags(params)));\n}\n\n/** The params reduced to the flags `defaultReady` gates on. */\nfunction readinessFlags(params: OrderReadinessParams): ReadinessFlags {\n return {\n cartUidSet: !!params.cartHdrUid,\n editShippingInfo: params.isEditShippingInfo,\n editShippingMethods: params.isEditShippingMethods,\n editBillingInfo: params.isEditBillingInfo,\n editCc: params.editCc,\n hasShippingAddress: params.shippingAddress !== undefined,\n hasBillingAddress: params.billingAddress !== undefined,\n methodSaved: params.shippingMethodSaved,\n showBillingSummary: params.showBillingInfoSummary,\n processing: params.processingOrder,\n isCreditCard: params.paymentMethod === \"credit-card\",\n hasAccountId: !!params.unifiedPaymentAccountId,\n hasUnifiedBilling: params.unifiedBilling,\n isFreeShipping: params.isFreeShipping,\n hasShippingFee: params.shippingFee !== undefined,\n };\n}\n\n/**\n * Debounced order readiness hook.\n *\n * Recomputes readiness 300ms after any dependency changes to avoid\n * excessive re-renders during rapid state transitions (e.g., typing\n * in address fields).\n */\nexport function useOrderReadiness(params: OrderReadinessParams) {\n const [enableProcessOrderBtn, setEnableProcessOrderBtn] = useState(false);\n const [processingValidation, setProcessingValidation] = useState(false);\n\n // Re-checked when one of the listed inputs changes; the params (with the site's\n // customReadinessCheck, a new function each render) are read as of that render.\n const paramsRef = useLatest(params);\n useEffect(() => {\n setProcessingValidation(true);\n\n const current = paramsRef.current;\n const timeoutId = setTimeout(() => {\n const ready = determineOrderReadiness(current);\n setEnableProcessOrderBtn(ready);\n setProcessingValidation(false);\n }, 300);\n\n return () => clearTimeout(timeoutId);\n }, [\n paramsRef,\n params.billingAddress,\n params.shippingAddress,\n params.isEditShippingInfo,\n params.isEditShippingMethods,\n params.isEditBillingInfo,\n params.editCc,\n params.isFreeShipping,\n params.unifiedPaymentAccountId,\n params.unifiedBilling,\n params.paymentMethod,\n params.processingOrder,\n params.carrierId,\n params.shippingFee,\n params.shippingMethodSaved,\n params.showBillingInfoSummary,\n params.cartHdrUid,\n ]);\n\n return { enableProcessOrderBtn, processingValidation };\n}\n","import { useRef } from \"react\";\nimport type { RefObject } from \"react\";\n\n/**\n * A ref holding this render's `value`. An effect that MUST NOT re-run when the value changes\n * (a consumer's inline callback, data read only when another input changes) reads it through\n * the ref, so it sees the latest value without listing it as a dependency.\n */\nexport function useLatest<T>(value: T): RefObject<T> {\n const ref = useRef(value);\n ref.current = value;\n return ref;\n}\n"],"mappings":"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","names":["useEffect","useRef","useRef","useEffect","setupId","useEffect","useState","useRef","useState","useEffect"]}
@@ -0,0 +1,68 @@
1
+ import type { TCartLine } from "@simpleapps-com/augur-utils";
2
+ type CartLineInput = {
3
+ invMastUid: number;
4
+ quantity: number;
5
+ unitOfMeasure: string;
6
+ cartHdrUid?: number | string | undefined;
7
+ };
8
+ /** Site-specific callbacks injected into useCartActions. */
9
+ export interface CartActionCallbacks {
10
+ /** Add items to cart via API. Truthy = success, falsy = failure. */
11
+ addToCart: (cartHdrUid: number, items: Array<{
12
+ cartHdrUid: number;
13
+ invMastUid: number;
14
+ quantity: number;
15
+ unitOfMeasure: string;
16
+ }>) => Promise<boolean | undefined | void>;
17
+ /** Update cart lines via API. Truthy = success, falsy = failure. */
18
+ updateCartLines: (cartHdrUid: number, lines: TCartLine[]) => Promise<boolean | undefined | void>;
19
+ /** Delete all items from cart via API. Truthy = success, falsy = failure. */
20
+ deleteItemsFromCart: (cartHdrUid: number) => Promise<boolean | undefined | void>;
21
+ /** Optional toast notification callback. */
22
+ toast?: {
23
+ info?: (message: string) => void;
24
+ error?: (message: string) => void;
25
+ success?: (message: string) => void;
26
+ };
27
+ }
28
+ interface CartActionOptions {
29
+ showToast?: boolean;
30
+ itemId?: string;
31
+ onSuccess?: () => void;
32
+ onError?: (error: Error) => void;
33
+ }
34
+ /** Actions and state returned by useCartActions. */
35
+ interface CartActions {
36
+ addToCart: (item: CartLineInput, options?: CartActionOptions) => Promise<boolean>;
37
+ updateQuantity: (invMastUid: number, newQuantity: number, options?: CartActionOptions) => Promise<boolean>;
38
+ removeFromCart: (invMastUid: number, options?: CartActionOptions) => Promise<boolean>;
39
+ clearCart: (options?: Omit<CartActionOptions, "itemId">) => Promise<boolean>;
40
+ isInCart: (invMastUid: number) => boolean;
41
+ getItemQuantity: (invMastUid: number) => number;
42
+ cartHdrUid: number | string | undefined;
43
+ cartLines: TCartLine[];
44
+ invalidateCartCache: () => void;
45
+ }
46
+ /**
47
+ * Optimistic cart actions hook with automatic rollback on failure.
48
+ *
49
+ * Accepts site-specific server action callbacks so the hook itself
50
+ * has no dependency on any particular server action implementation.
51
+ *
52
+ * @example
53
+ * ```tsx
54
+ * import { useCartActions } from "@simpleapps-com/augur-hooks";
55
+ * import { addToCart, updateCartLines, deleteItemsFromCart } from "@/lib/actions/commerce";
56
+ * import { toast } from "react-toastify";
57
+ *
58
+ * const cart = useCartActions({
59
+ * addToCart, updateCartLines, deleteItemsFromCart,
60
+ * toast: { info: toast.info, error: toast.error },
61
+ * });
62
+ *
63
+ * await cart.addToCart({ invMastUid: 123, quantity: 1, unitOfMeasure: "EA" });
64
+ * ```
65
+ */
66
+ export declare function useCartActions(callbacks: CartActionCallbacks): CartActions;
67
+ export {};
68
+ //# sourceMappingURL=use-cart-actions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-cart-actions.d.ts","sourceRoot":"","sources":["../../src/hooks/use-cart-actions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAK7D,KAAK,aAAa,GAAG;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC1C,CAAC;AAEF,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,SAAS,EAAE,CACT,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,KAAK,CAAC;QACX,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC,KACC,OAAO,CAAC,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACzC,oEAAoE;IACpE,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,OAAO,CAAC,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACjG,6EAA6E;IAC7E,mBAAmB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACjF,4CAA4C;IAC5C,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;QACjC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;QAClC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;KACrC,CAAC;CACH;AAED,UAAU,iBAAiB;IACzB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,oDAAoD;AACpD,UAAU,WAAW;IACnB,SAAS,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClF,cAAc,EAAE,CACd,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,iBAAiB,KACxB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,cAAc,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF,SAAS,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7E,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAChD,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACxC,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,mBAAmB,EAAE,MAAM,IAAI,CAAC;CACjC;AAyKD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,mBAAmB,GAAG,WAAW,CAkK1E"}
@@ -0,0 +1,60 @@
1
+ import type { TCartLine } from "@simpleapps-com/augur-utils";
2
+ /** Session info passed from the consumer's auth system. */
3
+ export interface CartSessionInfo {
4
+ /** Auth status: "loading" | "authenticated" | "unauthenticated" */
5
+ status: "loading" | "authenticated" | "unauthenticated";
6
+ /** User's ID (e.g., Joomla user ID). Undefined if not authenticated. */
7
+ userId?: string | number;
8
+ /** Cart header UID from the auth session, if available. */
9
+ cartHdrUid?: number | string;
10
+ }
11
+ /** Site-specific callbacks injected into useCartInitialization. */
12
+ export interface CartInitCallbacks {
13
+ /** Look up or create a cart header. Returns { cartHdrUid, cartToken? }. */
14
+ cartHdrLookup: (userId: string | number, cartToken: string) => Promise<{
15
+ cartHdrUid: number;
16
+ cartToken?: string | null;
17
+ } | false | null | undefined>;
18
+ /** Fetch cart line items for a given cart header UID. */
19
+ getCartLines: (cartHdrUid: number) => Promise<TCartLine[] | undefined>;
20
+ /** Get the current cart token. Defaults to localStorage.getItem("cartToken"). */
21
+ getCartToken?: () => string | null;
22
+ /** Save cart token. Defaults to localStorage.setItem("cartToken", token). */
23
+ saveCartToken?: (token: string) => void;
24
+ /** Generate a new unique cart token. Defaults to crypto.randomUUID(). */
25
+ generateCartToken?: () => string;
26
+ }
27
+ /**
28
+ * Initialize cart state from session (authenticated) or cookie (guest).
29
+ * Call once in the root layout.
30
+ *
31
+ * @example
32
+ * ```tsx
33
+ * import { useCartInitialization } from "@simpleapps-com/augur-hooks";
34
+ * import { useSession } from "next-auth/react";
35
+ * import { cartHdrLookup, getCartLines } from "@/lib/actions/commerce";
36
+ *
37
+ * function CartInitializer() {
38
+ * const { data: session, status } = useSession();
39
+ *
40
+ * // Minimal setup — token storage defaults to localStorage,
41
+ * // token generation defaults to crypto.randomUUID().
42
+ * useCartInitialization(
43
+ * {
44
+ * status,
45
+ * userId: session?.user?.id,
46
+ * cartHdrUid: session?.user?.cartHdrUid,
47
+ * },
48
+ * { cartHdrLookup, getCartLines },
49
+ * );
50
+ *
51
+ * return null;
52
+ * }
53
+ * ```
54
+ */
55
+ export declare function useCartInitialization(session: CartSessionInfo, callbacks: CartInitCallbacks): {
56
+ cartHdrUid: string | number | undefined;
57
+ isInitializing: boolean;
58
+ retryCount: number;
59
+ };
60
+ //# sourceMappingURL=use-cart-initialization.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-cart-initialization.d.ts","sourceRoot":"","sources":["../../src/hooks/use-cart-initialization.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAmB7D,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,MAAM,EAAE,SAAS,GAAG,eAAe,GAAG,iBAAiB,CAAC;IACxD,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,aAAa,EAAE,CACb,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAC3F,yDAAyD;IACzD,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,EAAE,GAAG,SAAS,CAAC,CAAC;IACvE,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACnC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC;CAClC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,iBAAiB;;;;EAkH3F"}
@@ -0,0 +1,41 @@
1
+ import type { TPriceData } from "@simpleapps-com/augur-utils";
2
+ export interface CartPriceData {
3
+ unitPrice: number;
4
+ priceData: Record<string, unknown> | null;
5
+ }
6
+ export interface CartPricingResult {
7
+ /** Map of itemId -> price data (with quantity-specific pricing) */
8
+ prices: Record<string, CartPriceData>;
9
+ /** Get unit price for an item (returns 0 if not found) */
10
+ getUnitPrice: (itemId: string) => number;
11
+ /** Get total price for an item (unitPrice * quantity) */
12
+ getItemTotal: (itemId: string, quantity: number) => number;
13
+ /** Cart subtotal (sum of all item totals) */
14
+ subtotal: number;
15
+ /** True if any price is still loading */
16
+ isLoading: boolean;
17
+ /** True if all prices loaded successfully */
18
+ isSuccess: boolean;
19
+ /** True if any price failed to load */
20
+ isError: boolean;
21
+ }
22
+ interface UseCartPricingOptions {
23
+ customerId?: string | number;
24
+ /** Override per-item price fetching (e.g. with a custom server action). */
25
+ queryFn?: (itemId: string, customerId: string | number, quantity: number) => Promise<TPriceData>;
26
+ }
27
+ /**
28
+ * Centralized hook for cart/checkout pricing.
29
+ *
30
+ * Fetches prices for ALL cart items with their actual quantities
31
+ * to support quantity-based price breaks. React Query dedupes
32
+ * identical calls across components.
33
+ *
34
+ * Uses the proxy from AugurHooksProvider context. Works with:
35
+ * - Direct SDK (api prop on provider)
36
+ * - Server actions (auto-detected via queryAction registration)
37
+ * - Custom queryFn override
38
+ */
39
+ export declare function useCartPricing(options?: UseCartPricingOptions): CartPricingResult;
40
+ export {};
41
+ //# sourceMappingURL=use-cart-pricing.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-cart-pricing.d.ts","sourceRoot":"","sources":["../../src/hooks/use-cart-pricing.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAK9D,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,0DAA0D;IAC1D,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,yDAAyD;IACzD,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3D,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,UAAU,qBAAqB;IAC7B,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAClG;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,iBAAiB,CA2FrF"}
@@ -0,0 +1,40 @@
1
+ /** A single persisted field with its storage key and optional TTL. */
2
+ export interface CheckoutPersistField<T> {
3
+ key: string;
4
+ value: T;
5
+ set: (value: T) => void;
6
+ /** Valibot or custom validator. Return the parsed value or throw to reject. */
7
+ validate?: (raw: unknown) => T;
8
+ /** TTL in milliseconds. Default: 30 minutes. */
9
+ ttl?: number;
10
+ }
11
+ /**
12
+ * Saves a value to sessionStorage with a timestamp for TTL expiration.
13
+ *
14
+ * Fails silently on storage errors (private browsing, quota exceeded).
15
+ */
16
+ export declare function saveToSession(key: string, value: unknown): void;
17
+ /**
18
+ * Loads a value from sessionStorage, checking TTL and optionally validating.
19
+ *
20
+ * Returns null if missing, expired, invalid, or storage is unavailable.
21
+ * Cleans up expired entries automatically.
22
+ */
23
+ export declare function loadFromSession<T>(key: string, ttl?: number, validate?: (raw: unknown) => T): T | null;
24
+ /** Removes a checkout persistence key from sessionStorage. */
25
+ export declare function clearFromSession(key: string): void;
26
+ /**
27
+ * Hook that persists checkout state fields to sessionStorage and restores on mount.
28
+ *
29
+ * Each field is saved when its value changes and restored once on initial mount.
30
+ * Validates restored values against an optional schema to guard against
31
+ * corrupted or stale storage. Expired entries (past TTL) are discarded.
32
+ */
33
+ export declare function useCheckoutPersistence(fields: CheckoutPersistField<unknown>[]): void;
34
+ /**
35
+ * Clears all checkout persistence keys from sessionStorage.
36
+ *
37
+ * Call after successful order submission to prevent stale data on next checkout.
38
+ */
39
+ export declare function clearCheckoutPersistence(keys: string[]): void;
40
+ //# sourceMappingURL=use-checkout-persistence.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-checkout-persistence.d.ts","sourceRoot":"","sources":["../../src/hooks/use-checkout-persistence.ts"],"names":[],"mappings":"AAKA,sEAAsE;AACtE,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,CAAC,CAAC;IACT,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAC;IAC/B,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AASD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAO/D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,MAAoB,EACzB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,GAC7B,CAAC,GAAG,IAAI,CAmBV;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAMlD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAwBpF;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAI7D"}
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Debounces a rapidly-changing value.
3
+ * Returns the latest value only after `delay` ms of inactivity.
4
+ */
5
+ export declare function useDebounce<T>(value: T, delay?: number): T;
6
+ //# sourceMappingURL=use-debounce.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-debounce.d.ts","sourceRoot":"","sources":["../../src/hooks/use-debounce.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAE,MAAY,GAAG,CAAC,CAc/D"}
@@ -0,0 +1,29 @@
1
+ /** Options for configuring the useFormatPrice hook. */
2
+ export interface UseFormatPriceOptions {
3
+ /** BCP 47 locale tag. Overrides site.formatting.locale. */
4
+ locale?: string;
5
+ /** ISO 4217 currency code. Overrides site.formatting.currency. */
6
+ currency?: string;
7
+ /** Decimal digits. Overrides site.formatting.precision. */
8
+ precision?: number;
9
+ /** Label returned when the effective value is 0 (e.g. "Call for Price"). */
10
+ zeroLabel?: string;
11
+ }
12
+ /** Per-call options passed to the returned formatPrice function. */
13
+ export interface FormatPriceCallOptions {
14
+ /** Override decimal digits for this call only. */
15
+ precision?: number;
16
+ /** Multiply the value by this quantity before formatting. */
17
+ quantity?: number;
18
+ }
19
+ /**
20
+ * Hook that returns a price formatter.
21
+ * Reads defaults from site config when params are omitted.
22
+ *
23
+ * Supports both the new options-object signature and the legacy positional
24
+ * `(locale?, currency?)` signature for backwards compatibility.
25
+ */
26
+ export declare function useFormatPrice(optionsOrLocale?: UseFormatPriceOptions | string, legacyCurrency?: string): {
27
+ formatPrice: (price: number, callOptions?: FormatPriceCallOptions) => string;
28
+ };
29
+ //# sourceMappingURL=use-format-price.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-format-price.d.ts","sourceRoot":"","sources":["../../src/hooks/use-format-price.ts"],"names":[],"mappings":"AAIA,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAyBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,eAAe,CAAC,EAAE,qBAAqB,GAAG,MAAM,EAChD,cAAc,CAAC,EAAE,MAAM;yBAWK,MAAM,gBAAgB,sBAAsB,KAAG,MAAM;EAmBlF"}
@@ -0,0 +1,8 @@
1
+ import type { RefObject } from "react";
2
+ /**
3
+ * A ref holding this render's `value`. An effect that MUST NOT re-run when the value changes
4
+ * (a consumer's inline callback, data read only when another input changes) reads it through
5
+ * the ref, so it sees the latest value without listing it as a dependency.
6
+ */
7
+ export declare function useLatest<T>(value: T): RefObject<T>;
8
+ //# sourceMappingURL=use-latest.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-latest.d.ts","sourceRoot":"","sources":["../../src/hooks/use-latest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAInD"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Shared modal lifecycle hook -- scroll lock, Escape key, client-side hydration gate.
3
+ *
4
+ * Locks body scroll when the modal is open and restores it on close.
5
+ * Listens for Escape key to trigger onClose. Returns isClient for
6
+ * hydration-safe conditional rendering.
7
+ */
8
+ export declare function useModalLifecycle(isOpen: boolean, onClose: () => void): {
9
+ isClient: boolean;
10
+ };
11
+ //# sourceMappingURL=use-modal-lifecycle.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-modal-lifecycle.d.ts","sourceRoot":"","sources":["../../src/hooks/use-modal-lifecycle.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI;;EAyBrE"}
@@ -0,0 +1,47 @@
1
+ /** Parameters for order readiness validation. */
2
+ export interface OrderReadinessParams {
3
+ cartHdrUid: string | number | undefined;
4
+ shippingAddress: unknown;
5
+ billingAddress: unknown;
6
+ shippingMethodSaved: boolean;
7
+ showBillingInfoSummary: boolean;
8
+ processingOrder: boolean;
9
+ paymentMethod: string;
10
+ unifiedPaymentAccountId: string | undefined;
11
+ unifiedBilling: boolean;
12
+ isFreeShipping: boolean;
13
+ carrierId: string;
14
+ shippingFee: number | undefined;
15
+ isEditShippingInfo: boolean;
16
+ isEditShippingMethods: boolean;
17
+ isEditBillingInfo: boolean;
18
+ editCc: boolean;
19
+ /**
20
+ * Site-provided function to check if the order is ready.
21
+ *
22
+ * Return `true` or `false` to override the default gates. Return
23
+ * `undefined` to defer to the default logic (useful when the override
24
+ * only applies to specific order flows — e.g. sample-only or pickup).
25
+ */
26
+ customReadinessCheck?: (params: OrderReadinessParams) => boolean | undefined;
27
+ }
28
+ /**
29
+ * Pure function that determines if an order is ready to submit.
30
+ *
31
+ * Checks all gates: cart exists, addresses present, shipping method saved,
32
+ * billing shown, payment complete (for credit card), shipping fee present
33
+ * (for non-free, non-pickup orders), and no sections being edited.
34
+ */
35
+ export declare function determineOrderReadiness(params: OrderReadinessParams): boolean;
36
+ /**
37
+ * Debounced order readiness hook.
38
+ *
39
+ * Recomputes readiness 300ms after any dependency changes to avoid
40
+ * excessive re-renders during rapid state transitions (e.g., typing
41
+ * in address fields).
42
+ */
43
+ export declare function useOrderReadiness(params: OrderReadinessParams): {
44
+ enableProcessOrderBtn: boolean;
45
+ processingValidation: boolean;
46
+ };
47
+ //# sourceMappingURL=use-order-readiness.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-order-readiness.d.ts","sourceRoot":"","sources":["../../src/hooks/use-order-readiness.ts"],"names":[],"mappings":"AAMA,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACxC,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;IACxB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sBAAsB,EAAE,OAAO,CAAC;IAChC,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,OAAO,GAAG,SAAS,CAAC;CAC9E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAE7E;AAuBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB;;;EAuC7D"}
@@ -0,0 +1,26 @@
1
+ import type { QueryKey } from "@tanstack/react-query";
2
+ interface UsePaginationPrefetchOptions {
3
+ /** Query key for the paginated data */
4
+ queryKey: QueryKey;
5
+ /** Function to fetch a page of data */
6
+ queryFn: (offset: number) => Promise<unknown>;
7
+ /** Number of items per page */
8
+ pageSize: number;
9
+ /** Custom query key builder. Receives the base key and offset, returns the full key. Default: [...queryKey, offset]. */
10
+ queryKeyFn?: (baseKey: QueryKey, offset: number) => QueryKey;
11
+ /** Stale time in ms (defaults to 10 minutes) */
12
+ staleTime?: number;
13
+ /** GC time in ms (defaults to 30 minutes) */
14
+ gcTime?: number;
15
+ enabled?: boolean;
16
+ }
17
+ /**
18
+ * Prefetch adjacent pages on hover for instant pagination.
19
+ * Accepts a generic queryFn so it works with any paginated resource.
20
+ */
21
+ export declare const usePaginationPrefetch: ({ queryKey, queryFn, pageSize, queryKeyFn, staleTime, gcTime, enabled, }: UsePaginationPrefetchOptions) => {
22
+ prefetchPage: (page: number) => Promise<void>;
23
+ handlePaginationHover: (page: number) => () => void;
24
+ };
25
+ export {};
26
+ //# sourceMappingURL=use-pagination-prefetch.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-pagination-prefetch.d.ts","sourceRoot":"","sources":["../../src/hooks/use-pagination-prefetch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,UAAU,4BAA4B;IACpC,uCAAuC;IACvC,QAAQ,EAAE,QAAQ,CAAC;IACnB,uCAAuC;IACvC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,wHAAwH;IACxH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC;IAC7D,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,0EAQnC,4BAA4B;yBAId,MAAM;kCAkBZ,MAAM;CAWhB,CAAC"}