@aglyn/plugins-commerce 1.0.0-beta.230 → 1.0.0-beta.232

package/src/lib/model/commerce-shipping.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-shipping.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Shipping v1 (AGL-288): zones own countries; rates belong to a zone and\n * price as flat, free-over-threshold, or subtotal/weight tiers. Settings\n * live on `hosts/{hostId}/settings/store` under `shipping`. Pure.\n *\n * `resolveShippingRates` is the per-destination resolver;\n * `resolveCheckoutShippingOptions` is the Stripe Checkout adapter,\n * `planCheckoutShipping` decides which destinations one session may serve,\n * `appendCheckoutShippingParams` emits it onto a session, and\n * `summarizeShippingCoverage` answers the same question for the console, so a\n * merchant can see which destinations their zones refuse. AGL-288 shipped this\n * model with no production call site at all — the doc comment here claimed the\n * cart estimator, checkout and POS pickup used it, and none of them did, so\n * nothing ever read the settings a merchant saved and no shipping was ever\n * charged. Cart checkout calls it (AGL-1707), buy-now calls it for physical\n * one-time products (AGL-1720), and a draft order's payment link calls it for\n * physical products (AGL-1792).\n *\n * POS DOES NOT, AND SHOULD NOT (AGL-1792). A register has no destination\n * anywhere in it — no address field, no delivery choice — and all three\n * tenders settle at the counter: cash, a card QR the customer scans while\n * standing there, and a room folio collected at check-out. There is nothing to\n * price a parcel against, so the only rate POS could resolve is the free\n * `Local pickup` one this module appends, which is 0¢ and would add a step to\n * a register flow in exchange for nothing. A POS sale that must be shipped is\n * a draft order.\n */\n\nexport interface ShippingZone {\n  id: string\n  name: string\n  /** ISO-3166 alpha-2 codes; '*' = rest of world. */\n  countries: string[]\n}\n\nexport interface ShippingTier {\n  /** Tier applies while subtotal (cents) or weight (grams) ≤ this. */\n  upTo: number\n  amountCents: number\n}\n\nexport interface ShippingRate {\n  id: string\n  zoneId: string\n  name: string\n  kind: 'flat' | 'free_over' | 'price_tiers' | 'weight_tiers'\n  /** flat + free_over base amount. */\n  amountCents?: number\n  /** free_over: order subtotal (cents) at/above which shipping is free. */\n  freeOverCents?: number\n  /** price_tiers (upTo = subtotal cents) / weight_tiers (upTo = grams). */\n  tiers?: ShippingTier[]\n}\n\nexport interface ShippingSettings {\n  zones?: ShippingZone[]\n  rates?: ShippingRate[]\n  /**\n   * Offer free local pickup as a delivery choice. Does NOT widen where the\n   * store ships: a destination no rate reaches is still refused (AGL-2325).\n   */\n  localPickup?: boolean\n}\n\nexport interface ResolvedShippingRate {\n  rateId: string\n  name: string\n  amountCents: number\n}\n\n/**\n * The rate id appended for local pickup (AGL-2325).\n *\n * Exported because pickup is the one entry in a resolved list that is NOT a\n * shipping promise: it is appended AFTER and INDEPENDENT of zone matching, so\n * it resolves for every destination on earth. Anything asking \"does this store\n * ship there\" — the checkout refusal, the console coverage card — has to be\n * able to tell it apart from a rate, or it reads a merchant who offers\n * collection as a merchant who delivers worldwide.\n */\nexport const LOCAL_PICKUP_RATE_ID = 'pickup'\n\n/**\n * One stored country code, normalised (AGL-2298).\n *\n * TRIMMED as well as upper-cased. The console trims on save, so this only\n * matters for a document written any other way — an import, the REST API, a\n * hand edit — but the failure it produces is silent and expensive: `' US'`\n * upper-cases to `' US'`, matches nothing, and the store refuses every US\n * shopper with \"This store does not ship to the United States\" while its\n * settings card shows `US` right there.\n */\nconst zoneCode = (code: unknown): string => String(code ?? '').trim().toUpperCase()\n\n/** Whether a stored code is the rest-of-world wildcard. */\nconst isWildcard = (code: unknown): boolean => zoneCode(code) === '*'\n\nfunction zoneMatches(zone: ShippingZone, country: string): boolean {\n  return (zone.countries ?? []).some(\n    (code) => isWildcard(code) || zoneCode(code) === country,\n  )\n}\n\nfunction tierAmount(\n  tiers: ShippingTier[] | undefined,\n  value: number,\n): number | null {\n  const sorted = [...(tiers ?? [])].sort((a, b) => a.upTo - b.upTo)\n  for (const tier of sorted) {\n    if (value <= tier.upTo) return tier.amountCents\n  }\n  // Beyond the last tier the rate does not apply (merchant should add a\n  // catch-all tier with a large upTo).\n  return null\n}\n\n/**\n * Rates available for a destination + cart, cheapest first. Specific\n * country zones beat '*' zones: when any specific zone matches, '*'\n * zones are ignored (rest-of-world semantics).\n *\n * Local pickup is appended AFTER and INDEPENDENT of zone matching, so this\n * list is never empty for a merchant who offers it, at any destination. That\n * is correct for a resolver — a shopper anywhere may choose to come and\n * collect — but it means A NON-EMPTY RESULT IS NOT A PROMISE TO SHIP THERE.\n * Callers deciding whether a destination is served must filter pickup out\n * first; `planCheckoutShipping` and `summarizeShippingCoverage` do (AGL-2325).\n */\nexport function resolveShippingRates(\n  settings: ShippingSettings | undefined,\n  destinationCountry: string | undefined,\n  cart: { subtotalCents: number; totalGrams?: number },\n): ResolvedShippingRate[] {\n  if (!settings || !destinationCountry) return []\n  const country = destinationCountry.toUpperCase()\n  const zones = settings.zones ?? []\n  // A zone is SPECIFIC when it names this country outright — not merely when\n  // it is \"not wildcard-only\" (AGL-2298). The old test was `!every(code ===\n  // '*')`, so a zone spelled `['*','US']` counted as specific for all six\n  // destinations (it matches every country through the `*`) and suppressed\n  // every genuine rest-of-world zone globally. Asking the narrower question\n  // makes such a zone specific for `US` and wildcard for the rest, which is\n  // what its two entries actually say.\n  const specific = zones.filter((zone) =>\n    (zone.countries ?? []).some((code) => zoneCode(code) === country),\n  )\n  const matched = specific.length\n    ? specific\n    : zones.filter((zone) => zoneMatches(zone, country))\n  const zoneIds = new Set(matched.map((zone) => zone.id))\n  const resolved: ResolvedShippingRate[] = []\n  for (const rate of settings.rates ?? []) {\n    if (!zoneIds.has(rate.zoneId)) continue\n    let amountCents: number | null = null\n    switch (rate.kind) {\n      case 'flat':\n        amountCents = Math.max(0, Math.round(rate.amountCents ?? 0))\n        break\n      case 'free_over':\n        amountCents =\n          rate.freeOverCents != null &&\n          cart.subtotalCents >= rate.freeOverCents\n            ? 0\n            : Math.max(0, Math.round(rate.amountCents ?? 0))\n        break\n      case 'price_tiers':\n        amountCents = tierAmount(rate.tiers, cart.subtotalCents)\n        break\n      case 'weight_tiers':\n        amountCents = tierAmount(rate.tiers, cart.totalGrams ?? 0)\n        break\n    }\n    if (amountCents == null) continue\n    resolved.push({ rateId: rate.id, name: rate.name, amountCents })\n  }\n  if (settings.localPickup) {\n    resolved.push({\n      rateId: LOCAL_PICKUP_RATE_ID,\n      name: 'Local pickup',\n      amountCents: 0,\n    })\n  }\n  return resolved.sort((a, b) => a.amountCents - b.amountCents)\n}\n\n/**\n * The resolved options that actually carry a parcel (AGL-2325).\n *\n * Safe to apply AFTER `MAX_CHECKOUT_SHIPPING_OPTIONS` truncation: pickup is\n * 0¢ and sorts first, so it occupies at most one of the five slots and a\n * merchant with any shippable rate at all keeps at least one of them.\n */\nfunction shippableOnly(\n  options: readonly ResolvedShippingRate[],\n): ResolvedShippingRate[] {\n  return options.filter((option) => option.rateId !== LOCAL_PICKUP_RATE_ID)\n}\n\n/** Stripe Checkout accepts at most 5 `shipping_options` on one session. */\nexport const MAX_CHECKOUT_SHIPPING_OPTIONS = 5\n\n/**\n * Destinations a storefront Checkout Session collects an address for, and\n * therefore the destinations shipping rates are resolved against (AGL-1707).\n *\n * NOT narrowed to the zones the merchant configured: narrowing would block\n * checkouts that complete today, turning a money fix into lost sales. The\n * wider list only means a shopper outside the merchant's zones is offered some\n * rate rather than none. Shared by cart checkout and buy-now (AGL-1720) so the\n * two paths cannot drift into offering different destinations.\n */\nexport const CHECKOUT_SHIPPING_COUNTRIES = [\n  'US',\n  'CA',\n  'GB',\n  'AU',\n  'DE',\n  'FR',\n] as const\n\n/**\n * The rates to declare as `shipping_options` on a Stripe Checkout Session\n * (AGL-1707), unioned over `destinationCountries`. Stripe charges shipping\n * ONLY when the session declares them.\n *\n * A UNION IS ONLY HONEST OVER DESTINATIONS THE SESSION IS ALSO RESTRICTED TO.\n * Called with every collectable country while the session accepted an address\n * in any of them — which is what AGL-1707 shipped — it offers a shopper in one\n * zone a rate belonging to another, and Stripe applies whichever the shopper\n * picks (a `shipping_rate_data` carries no country of its own, so nothing\n * downstream re-checks it against the address). That is AGL-1721. Callers now\n * reach this through `planCheckoutShipping`, which pairs the country list it\n * unions over with the country list the session allows, so the two cannot\n * disagree. Do not call it directly from a handler.\n *\n * Returns `[]` for a merchant who has configured nothing, and the caller must\n * then declare no `shipping_options` at all rather than an empty array — a\n * merchant who never set shipping up keeps a session identical to today's.\n */\nexport function resolveCheckoutShippingOptions(\n  settings: ShippingSettings | undefined,\n  destinationCountries: readonly string[],\n  cart: { subtotalCents: number; totalGrams?: number },\n): ResolvedShippingRate[] {\n  if (!settings) return []\n  const byRateId = new Map<string, ResolvedShippingRate>()\n  for (const country of destinationCountries) {\n    for (const rate of resolveShippingRates(settings, country, cart)) {\n      // Stripe requires a display name, and a rate id is the dedupe key —\n      // the console lets a merchant add a blank row, so neither is assured.\n      if (!rate.rateId || !rate.name) continue\n      const amountCents = Math.max(0, Math.round(Number(rate.amountCents) || 0))\n      const existing = byRateId.get(rate.rateId)\n      // One rate resolving differently for two countries should not be\n      // possible (a zone selects a rate, it does not reprice one), but if it\n      // ever is, keep the dearer. Under-charging is the defect being fixed.\n      if (!existing || amountCents > existing.amountCents) {\n        byRateId.set(rate.rateId, { ...rate, amountCents })\n      }\n    }\n  }\n  return (\n    [...byRateId.values()]\n      // Cheapest first, id as a tie-break so the emitted params are stable.\n      .sort(\n        (a, b) =>\n          a.amountCents - b.amountCents || a.rateId.localeCompare(b.rateId),\n      )\n      // Past Stripe's cap the dearest are dropped, which is the harmless end\n      // to lose: a shopper offered the cheap options would have taken one.\n      .slice(0, MAX_CHECKOUT_SHIPPING_OPTIONS)\n  )\n}\n\n/** Shopper-facing names for the collectable destinations (AGL-1721). */\nexport const CHECKOUT_SHIPPING_COUNTRY_NAMES: Readonly<Record<string, string>> =\n  {\n    US: 'United States',\n    CA: 'Canada',\n    GB: 'United Kingdom',\n    AU: 'Australia',\n    DE: 'Germany',\n    FR: 'France',\n  }\n\n/**\n * A destination a shopper declared, or `undefined` for anything this session\n * could not collect an address for anyway. Never throws: an unknown code is\n * an undeclared destination, not an error, so a stale storefront that posts\n * one is answered by the plan below rather than by a 400 nobody can act on.\n */\nexport function normalizeCheckoutShippingCountry(\n  value: unknown,\n): string | undefined {\n  // `typeof` rather than `String(value)`: a JSON body is caller-shaped, and\n  // `String(['US'])` is 'US'. Coercing would let an array declare a\n  // destination, which is not a spelling any storefront sends.\n  if (typeof value !== 'string') return undefined\n  const code = value.trim().toUpperCase()\n  return (CHECKOUT_SHIPPING_COUNTRIES as readonly string[]).includes(code)\n    ? code\n    : undefined\n}\n\nexport interface CheckoutShippingPlan {\n  /** `shipping_address_collection[allowed_countries]` for this session. */\n  countries: readonly string[]\n  /** `shipping_options` for this session — valid for EVERY `countries` entry. */\n  options: ResolvedShippingRate[]\n  /**\n   * Set when no session may be created at all:\n   *\n   * - `destination-required` — the merchant's rates differ by destination, so\n   *   there is no set of options honest for every address Stripe would accept.\n   *   Ask the shopper where they are shipping and plan again.\n   * - `destination-unserved` — the merchant ships somewhere, but not there.\n   * - `cart-unpriceable` — the merchant priced shipping, but no rate of theirs\n   *   resolves for THIS cart at ANY destination (AGL-2232). A tier table that\n   *   stops at 2 kg says nothing about a 3 kg parcel, and the honest answer is\n   *   to refuse rather than to ship it for nothing.\n   */\n  refusal?: 'destination-required' | 'destination-unserved' | 'cart-unpriceable'\n}\n\n/**\n * Whether this merchant prices shipping AT ALL (AGL-2232).\n *\n * A pure question about the SETTINGS, deliberately taking no cart, and that is\n * the whole point of it existing. `planCheckoutShipping` used to ask \"does any\n * rate resolve for any destination?\" and pass the live cart into the probe, so\n * a cart that exhausted every tier made the probe empty too — and an empty\n * probe reads as \"this merchant never set shipping up\", the one case that must\n * complete with no `shipping_options` and nothing charged. A 3 kg order at a\n * store whose weight tiers stop at 2 kg therefore shipped free, silently, on\n * every one of the three doors.\n *\n * Answered from the stored zones and rates instead: a rate bound to a zone\n * that exists, or local pickup, means the merchant made a shipping decision\n * and a cart their table cannot price is a REFUSAL. A merchant with no zones,\n * no rates and no pickup has made no such decision, and their session stays\n * byte-identical to the one AGL-1707 shipped.\n */\nexport function merchantPricesShipping(\n  settings: ShippingSettings | undefined,\n): boolean {\n  if (!settings) return false\n  if (settings.localPickup) return true\n  const zoneIds = new Set((settings.zones ?? []).map((zone) => zone.id))\n  // A rate whose `zoneId` names no zone is unreachable by every resolver here,\n  // so it is not evidence of a decision — counting it would refuse carts at a\n  // store with nothing but orphaned rows.\n  return (settings.rates ?? []).some((rate) => zoneIds.has(rate.zoneId))\n}\n\n/**\n * What a shopper is told when `cart-unpriceable` refuses (AGL-2232).\n *\n * One string, shared by all three doors, because the three used to phrase the\n * two existing refusals identically and drifting here would make the same\n * store say different things depending on which button was pressed. It names\n * the cart rather than the destination on purpose — a `Ship to` select cannot\n * fix a parcel no tier covers, so the refusal deliberately does NOT set\n * `needsShippingCountry`.\n */\nexport const CART_UNPRICEABLE_SHIPPING_MESSAGE =\n  'This store cannot price shipping for this order — it falls outside every ' +\n  'shipping rate the store has set up. Try removing an item, or contact the ' +\n  'store.'\n\n/** Identity of a resolved list, for comparing two destinations' offers. */\nfunction optionsKey(options: readonly ResolvedShippingRate[]): string {\n  return options\n    .map((option) => `${option.rateId}:${option.amountCents}`)\n    .join('|')\n}\n\n/**\n * The whole shipping half of a Checkout Session: which destinations it may\n * accept an address for, and which rates it may charge (AGL-1721).\n *\n * THE INVARIANT IS THAT EVERY RETURNED OPTION IS VALID FOR EVERY RETURNED\n * COUNTRY. Stripe offers a session's `shipping_options` to whoever reaches the\n * page and charges whichever the shopper picks — it does not filter them by\n * the address entered, and there is no field on a `shipping_rate_data` that\n * would let it. So the ONLY place a zone can be enforced is here, by choosing\n * the two lists together: narrowing the allowed countries to the declared\n * destination is what makes the rates offered for it unpickable by anyone\n * else. Filtering the rate list alone would leave a session that still accepts\n * a French address against a US rate.\n *\n * Three shapes come out of it:\n *\n *   1. A merchant whose rates resolve the SAME for every collectable country —\n *      one zone, a single '*' zone, or none at all — needs no destination and\n *      keeps the session AGL-1707 shipped, byte for byte. The issue notes this\n *      is the common configuration, and it is the one that must not regress.\n *   2. A declared destination resolves exactly, and the session is restricted\n *      to it. A caller may not skip the restriction: the country arrives in a\n *      request body a shopper can craft, so a session that took the country's\n *      cheap rate while still accepting any address would hand that shopper\n *      the defect on purpose.\n *   3. Otherwise the caller must refuse — see `refusal`. Refusing is not lost\n *      revenue in either case: with rates that differ by zone there is no\n *      correct amount to charge without knowing where the parcel is going, and\n *      the union AGL-1707 shipped chose the wrong one silently.\n *\n * `cart.subtotalCents` is the PRE-discount items total, matching what the cart\n * displays, so a free-over threshold means what the shopper saw it mean.\n */\nexport function planCheckoutShipping(\n  settings: ShippingSettings | undefined,\n  cart: { subtotalCents: number; totalGrams?: number },\n  destinationCountry?: unknown,\n): CheckoutShippingPlan {\n  const countries = CHECKOUT_SHIPPING_COUNTRIES as readonly string[]\n  const destination = normalizeCheckoutShippingCountry(destinationCountry)\n  if (destination) {\n    const options = resolveCheckoutShippingOptions(\n      settings,\n      [destination],\n      cart,\n    )\n    // REFUSAL IS DECIDED ON SHIPPABLE RATES, PICKUP IS OFFERED AFTERWARDS\n    // (AGL-2325). `resolveShippingRates` appends pickup independent of zone\n    // matching, so a merchant who turned it on had a non-empty list for every\n    // destination on earth and this branch returned before it could refuse\n    // anyone: a shopper in France picked `Local pickup — Free` on a physical\n    // order from a US-only store, Stripe collected their French address\n    // because the session still allowed it, and the merchant was paid nothing\n    // to carry the parcel there. Pickup is collection, not delivery, so it\n    // cannot answer \"do you ship to France\".\n    //\n    // `shipsElsewhere` is the same question the old probe asked, narrowed to\n    // shippable rates, and it keeps the same two-way fork: a merchant who\n    // configured NO shipping is not refusing anyone, so that store keeps\n    // completing exactly as it does today, while a merchant who ships\n    // elsewhere but not here is refusing and saying so is the honest answer.\n    // A merchant who ships NOWHERE is untouched by this: pickup-only is a\n    // real configuration — they deliver to no one and refuse no one — and it\n    // falls through to the offer below exactly as it did.\n    const shipsElsewhere = countries.some(\n      (country) =>\n        shippableOnly(resolveCheckoutShippingOptions(settings, [country], cart))\n          .length > 0,\n    )\n    if (shippableOnly(options).length === 0 && shipsElsewhere) {\n      return { countries, options: [], refusal: 'destination-unserved' }\n    }\n    if (options.length > 0) return { countries: [destination], options }\n    // NOTHING resolves anywhere for this cart, and the two reasons that can be\n    // true of are opposite (AGL-2232). Asked of the SETTINGS rather than of\n    // this cart, because the probe above cannot tell them apart: a merchant\n    // who priced shipping and whose table simply does not reach this order is\n    // refusing, and used to be handed the \"never set shipping up\" branch.\n    return merchantPricesShipping(settings)\n      ? { countries, options: [], refusal: 'cart-unpriceable' }\n      : { countries, options: [] }\n  }\n  const offers = new Set(\n    countries.map((country) =>\n      optionsKey(resolveCheckoutShippingOptions(settings, [country], cart)),\n    ),\n  )\n  // Compared as EMITTED — capped and sanitized — because that is the list a\n  // shopper can pick from. Two destinations whose rates differ only past\n  // Stripe's cap still offer the same five, and offering them is honest.\n  if (offers.size > 1) {\n    return { countries, options: [], refusal: 'destination-required' }\n  }\n  const union = resolveCheckoutShippingOptions(settings, countries, cart)\n  // Every destination agrees, and what they agree on is NOTHING. The same\n  // fork as the declared-destination branch above (AGL-2232): a store with no\n  // shipping settings completes untouched, a store whose rates cannot reach\n  // this cart refuses instead of carrying the parcel for free.\n  if (union.length === 0 && merchantPricesShipping(settings)) {\n    return { countries, options: [], refusal: 'cart-unpriceable' }\n  }\n  return { countries, options: union }\n}\n\n/**\n * A cart chosen so that every rate a merchant could have written resolves if\n * it can resolve at all (AGL-1791). The settings page has no cart, and two of\n * the four rate kinds price against one: `tierAmount` takes the first tier\n * whose `upTo` is at least the value, so a zero subtotal and zero weight clear\n * every tier a merchant would write, and a `free_over` rate resolves at any\n * subtotal.\n *\n * That makes a coverage answer a LOWER BOUND on the gaps. A destination\n * reported unserved is unserved for every cart; a destination reported served\n * may still be refused for a cart dearer or heavier than the merchant's last\n * tier. Erring in this direction is the deliberate half: the console must not\n * warn a merchant whose settings are fine.\n */\nconst COVERAGE_PROBE_CART = { subtotalCents: 0, totalGrams: 0 }\n\n/** What a merchant's saved zones and rates cost their shoppers (AGL-1791). */\nexport interface ShippingCoverage {\n  /** Collectable destinations at least one rate reaches. */\n  served: string[]\n  /**\n   * Collectable destinations CHECKOUT REFUSES — `destination-unserved`.\n   *\n   * EMPTY FOR A MERCHANT WHOSE RATES REACH NOWHERE, who is not misconfigured:\n   * `planCheckoutShipping` refuses nobody when no rate resolves anywhere, so\n   * that store charges no shipping and completes exactly as it always has.\n   * The rule lives here rather than in the caller because reading `served`\n   * against a bare partition is how a surface comes to warn every store that\n   * does not ship.\n   */\n  unserved: string[]\n  /** No rate reaches anywhere: no shipping is charged, and nobody refused. */\n  shipsNowhere: boolean\n  /**\n   * Rates differ by destination, so the storefront asks the shopper where the\n   * parcel is going before it can price one — a checkout step the merchant\n   * added by saving these zones, and never chose.\n   */\n  asksDestination: boolean\n  /** Some zone already claims rest of world, so `*` is not the missing piece. */\n  hasRestOfWorldZone: boolean\n  /**\n   * The merchant offers local pickup, so checkout presents a free collection\n   * choice at every destination it does not refuse (AGL-2325).\n   *\n   * Deliberately NOT folded into `served`: pickup resolves for every country\n   * because it is appended independent of zone matching, so counting it as\n   * coverage told a US-only merchant who had switched it on that checkout\n   * \"can price shipping to every destination\", which is the sentence that\n   * hid the defect. It is reported alongside instead, so the card can say\n   * both true things: these destinations are refused, and pickup is offered\n   * to the ones that are not.\n   */\n  offersLocalPickup: boolean\n}\n\n/**\n * Which of the collectable destinations a merchant's settings actually cover\n * (AGL-1791), for a console surface to show them.\n *\n * Measured against `CHECKOUT_SHIPPING_COUNTRIES` and nothing wider: those six\n * are the only destinations a storefront session collects an address for, so\n * they are the only ones a merchant can lose an order to. Counting coverage\n * against every country on earth would report a gap for destinations no\n * shopper can reach checkout from.\n *\n * Answered through `resolveCheckoutShippingOptions` — the same function the\n * session is built from — so a row the console allows but Stripe would reject\n * (blank id, blank name) counts as the nothing it resolves to, and a specific\n * zone with no rates still hides a `*` zone here exactly as it does at\n * checkout.\n */\nexport function summarizeShippingCoverage(\n  settings: ShippingSettings | undefined,\n): ShippingCoverage {\n  const served: string[] = []\n  const unserved: string[] = []\n  const offers = new Set<string>()\n  for (const country of CHECKOUT_SHIPPING_COUNTRIES) {\n    const options = resolveCheckoutShippingOptions(\n      settings,\n      [country],\n      COVERAGE_PROBE_CART,\n    )\n    // `asksDestination` is asked of the FULL list — pickup is a real option a\n    // shopper picks, so a merchant whose US destination offers a rate plus\n    // pickup while France offers only pickup genuinely does make checkout ask.\n    offers.add(optionsKey(options))\n    // `served` is asked of the SHIPPABLE list, so that it answers the same\n    // question `planCheckoutShipping` refuses on (AGL-2325).\n    ;(shippableOnly(options).length > 0 ? served : unserved).push(country)\n  }\n  return {\n    served,\n    unserved: served.length > 0 ? unserved : [],\n    shipsNowhere: served.length === 0,\n    asksDestination: offers.size > 1,\n    offersLocalPickup: Boolean(settings?.localPickup),\n    hasRestOfWorldZone: (settings?.zones ?? []).some((zone) =>\n      zone.countries.some((code) => code === '*'),\n    ),\n  }\n}\n\n/**\n * Emit `shipping_address_collection[allowed_countries][n]` onto a session's\n * form body. Stripe will not apply a `shipping_options` rate without an\n * address to ship to, so the two always travel together — and the countries\n * are the OTHER half of what makes a rate honest (AGL-1721), so pass the list\n * `planCheckoutShipping` returned rather than defaulting it beside a rate list\n * resolved for something narrower.\n */\nexport function appendShippingAddressCollectionParams(\n  params: URLSearchParams,\n  countries: readonly string[] = CHECKOUT_SHIPPING_COUNTRIES,\n): void {\n  countries.forEach((code, index) => {\n    params.set(`shipping_address_collection[allowed_countries][${index}]`, code)\n  })\n}\n\n/**\n * Emit resolved rates as `shipping_options` on a Checkout Session's form body.\n *\n * THIS IS THE ONLY THING THAT MAKES STRIPE CHARGE SHIPPING. Without these keys\n * Stripe presents no shipping choice and `total_details.amount_shipping` is 0\n * however many zones and rates the merchant saved (AGL-1707).\n *\n * An empty list emits NOTHING — not an empty array — so a merchant who\n * configured no shipping keeps a session byte-identical to the one built\n * before shipping was wired at all. That guarantee lives here rather than in\n * each caller, so neither checkout path can lose it independently (AGL-1720).\n */\nexport function appendCheckoutShippingParams(\n  params: URLSearchParams,\n  options: readonly ResolvedShippingRate[],\n): void {\n  options.forEach((option, index) => {\n    const field = `shipping_options[${index}][shipping_rate_data]`\n    params.set(`${field}[type]`, 'fixed_amount')\n    params.set(`${field}[display_name]`, option.name.slice(0, 100))\n    params.set(`${field}[fixed_amount][amount]`, String(option.amountCents))\n    params.set(`${field}[fixed_amount][currency]`, 'usd')\n  })\n}\n"],"names":["LOCAL_PICKUP_RATE_ID","zoneCode","code","String","trim","toUpperCase","isWildcard","zoneMatches","zone","country","countries","some","tierAmount","tiers","value","sorted","sort","a","b","upTo","tier","amountCents","resolveShippingRates","settings","destinationCountry","cart","zones","specific","filter","matched","length","zoneIds","Set","map","id","resolved","rate","rates","has","zoneId","kind","Math","max","round","freeOverCents","subtotalCents","totalGrams","push","rateId","name","localPickup","shippableOnly","options","option","MAX_CHECKOUT_SHIPPING_OPTIONS","CHECKOUT_SHIPPING_COUNTRIES","resolveCheckoutShippingOptions","destinationCountries","byRateId","Map","Number","existing","get","set","values","localeCompare","slice","CHECKOUT_SHIPPING_COUNTRY_NAMES","US","CA","GB","AU","DE","FR","normalizeCheckoutShippingCountry","undefined","includes","merchantPricesShipping","CART_UNPRICEABLE_SHIPPING_MESSAGE","optionsKey","join","planCheckoutShipping","destination","shipsElsewhere","refusal","offers","size","union","COVERAGE_PROBE_CART","summarizeShippingCoverage","served","unserved","add","shipsNowhere","asksDestination","offersLocalPickup","Boolean","hasRestOfWorldZone","appendShippingAddressCollectionParams","params","forEach","index","appendCheckoutShippingParams","field"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-shipping.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Shipping v1 (AGL-288): zones own countries; rates belong to a zone and\n * price as flat, free-over-threshold, or subtotal/weight tiers. Settings\n * live on `hosts/{hostId}/settings/store` under `shipping`. Pure.\n *\n * `resolveShippingRates` is the per-destination resolver;\n * `resolveCheckoutShippingOptions` is the Stripe Checkout adapter,\n * `planCheckoutShipping` decides which destinations one session may serve,\n * `appendCheckoutShippingParams` emits it onto a session, and\n * `summarizeShippingCoverage` answers the same question for the console, so a\n * merchant can see which destinations their zones refuse. AGL-288 shipped this\n * model with no production call site at all — the doc comment here claimed the\n * cart estimator, checkout and POS pickup used it, and none of them did, so\n * nothing ever read the settings a merchant saved and no shipping was ever\n * charged. Cart checkout calls it (AGL-1707), buy-now calls it for physical\n * one-time products (AGL-1720), and a draft order's payment link calls it for\n * physical products (AGL-1792).\n *\n * POS DOES NOT, AND SHOULD NOT (AGL-1792). A register has no destination\n * anywhere in it — no address field, no delivery choice — and all three\n * tenders settle at the counter: cash, a card QR the customer scans while\n * standing there, and a room folio collected at check-out. There is nothing to\n * price a parcel against, so the only rate POS could resolve is the free\n * `Local pickup` one this module appends, which is 0¢ and would add a step to\n * a register flow in exchange for nothing. A POS sale that must be shipped is\n * a draft order.\n */\n\nexport interface ShippingZone {\n  id: string\n  name: string\n  /** ISO-3166 alpha-2 codes; '*' = rest of world. */\n  countries: string[]\n}\n\nexport interface ShippingTier {\n  /** Tier applies while subtotal (cents) or weight (grams) ≤ this. */\n  upTo: number\n  amountCents: number\n}\n\n/**\n * A live carrier rate (AGL-3612): the zone's price is what a carrier quotes\n * for the parcel to the shopper's address, asked through core's\n * `core.shipping-rate-quoter` seam of whichever plugin quotes carriers. With\n * no quoter, a quoter that is not available for the site, no postal code to\n * quote against, or a quote slower than {@link CARRIER_QUOTE_TIMEOUT_MS}, it\n * offers nothing and its fallback rate is offered instead.\n */\nexport interface CarrierRateSettings {\n  /** Service keys (`carrier:service`) to offer; empty offers every quoted service. */\n  services?: string[]\n  /** Added to each quote, in percent. */\n  markupPct?: number\n  /** Added to each quote after the markup, in cents. */\n  handlingCents?: number\n  /**\n   * A rate of this zone offered when no live quote is: it is HIDDEN while\n   * quotes are offered, so the shopper picks between carriers, not between a\n   * carrier and the merchant's guess.\n   */\n  fallbackRateId?: string\n}\n\n/** How long checkout waits for live carrier quotes before it falls back. */\nexport const CARRIER_QUOTE_TIMEOUT_MS = 3_000\n\nexport interface ShippingRate {\n  id: string\n  zoneId: string\n  name: string\n  kind: 'flat' | 'free_over' | 'price_tiers' | 'weight_tiers' | 'carrier'\n  /** flat + free_over base amount. */\n  amountCents?: number\n  /** free_over: order subtotal (cents) at/above which shipping is free. */\n  freeOverCents?: number\n  /** price_tiers (upTo = subtotal cents) / weight_tiers (upTo = grams). */\n  tiers?: ShippingTier[]\n  /** carrier: the live rate's options (AGL-3612). */\n  carrier?: CarrierRateSettings\n}\n\nexport interface ShippingSettings {\n  zones?: ShippingZone[]\n  rates?: ShippingRate[]\n  /**\n   * Offer free local pickup as a delivery choice. Does NOT widen where the\n   * store ships: a destination no rate reaches is still refused (AGL-2325).\n   */\n  localPickup?: boolean\n}\n\nexport interface ResolvedShippingRate {\n  rateId: string\n  name: string\n  amountCents: number\n}\n\n/**\n * The rate id appended for local pickup (AGL-2325).\n *\n * Exported because pickup is the one entry in a resolved list that is NOT a\n * shipping promise: it is appended AFTER and INDEPENDENT of zone matching, so\n * it resolves for every destination on earth. Anything asking \"does this store\n * ship there\" — the checkout refusal, the console coverage card — has to be\n * able to tell it apart from a rate, or it reads a merchant who offers\n * collection as a merchant who delivers worldwide.\n */\nexport const LOCAL_PICKUP_RATE_ID = 'pickup'\n\n/**\n * One stored country code, normalised (AGL-2298).\n *\n * TRIMMED as well as upper-cased. The console trims on save, so this only\n * matters for a document written any other way — an import, the REST API, a\n * hand edit — but the failure it produces is silent and expensive: `' US'`\n * upper-cases to `' US'`, matches nothing, and the store refuses every US\n * shopper with \"This store does not ship to the United States\" while its\n * settings card shows `US` right there.\n */\nconst zoneCode = (code: unknown): string => String(code ?? '').trim().toUpperCase()\n\n/** Whether a stored code is the rest-of-world wildcard. */\nconst isWildcard = (code: unknown): boolean => zoneCode(code) === '*'\n\nfunction zoneMatches(zone: ShippingZone, country: string): boolean {\n  return (zone.countries ?? []).some(\n    (code) => isWildcard(code) || zoneCode(code) === country,\n  )\n}\n\nfunction tierAmount(\n  tiers: ShippingTier[] | undefined,\n  value: number,\n): number | null {\n  const sorted = [...(tiers ?? [])].sort((a, b) => a.upTo - b.upTo)\n  for (const tier of sorted) {\n    if (value <= tier.upTo) return tier.amountCents\n  }\n  // Beyond the last tier the rate does not apply (merchant should add a\n  // catch-all tier with a large upTo).\n  return null\n}\n\n/**\n * The zones a destination falls in (AGL-1707, factored out for AGL-3612).\n * Specific country zones beat '*' zones: when any zone names the country\n * outright, rest-of-world zones are ignored.\n */\nexport function matchedZoneIds(\n  settings: ShippingSettings | undefined,\n  destinationCountry: string,\n): Set<string> {\n  const country = destinationCountry.toUpperCase()\n  const zones = settings?.zones ?? []\n  // A zone is SPECIFIC when it names this country outright — not merely when\n  // it is \"not wildcard-only\" (AGL-2298). The old test was `!every(code ===\n  // '*')`, so a zone spelled `['*','US']` counted as specific for all six\n  // destinations (it matches every country through the `*`) and suppressed\n  // every genuine rest-of-world zone globally. Asking the narrower question\n  // makes such a zone specific for `US` and wildcard for the rest, which is\n  // what its two entries actually say.\n  const specific = zones.filter((zone) =>\n    (zone.countries ?? []).some((code) => zoneCode(code) === country),\n  )\n  const matched = specific.length\n    ? specific\n    : zones.filter((zone) => zoneMatches(zone, country))\n  return new Set(matched.map((zone) => zone.id))\n}\n\n/** The live carrier rates a destination's zones carry (AGL-3612). */\nexport function carrierRatesFor(\n  settings: ShippingSettings | undefined,\n  destinationCountry: string,\n): ShippingRate[] {\n  if (!settings) return []\n  const zoneIds = matchedZoneIds(settings, destinationCountry)\n  return (settings.rates ?? []).filter(\n    (rate) => rate.kind === 'carrier' && zoneIds.has(rate.zoneId),\n  )\n}\n\n/** Whether any zone carries a live carrier rate (AGL-3612). */\nexport function hasCarrierRates(settings: ShippingSettings | undefined): boolean {\n  return (settings?.rates ?? []).some((rate) => rate.kind === 'carrier')\n}\n\n/** The rate id a quoted service is offered under: stable per rate and service. */\nexport function carrierOptionRateId(rateId: string, serviceKey: string): string {\n  return `carrier:${rateId}:${serviceKey}`\n}\n\n/**\n * What a shopper pays for a carrier's quote under one carrier rate: the\n * quote, plus the markup, plus the handling fee, in whole cents.\n */\nexport function carrierOptionAmountCents(\n  quotedCents: number,\n  settings: CarrierRateSettings | undefined,\n): number {\n  const quote = Math.max(0, Math.round(Number(quotedCents) || 0))\n  const pct = Number(settings?.markupPct)\n  const handling = Number(settings?.handlingCents)\n  return (\n    quote +\n    (Number.isFinite(pct) && pct > 0 ? Math.round((quote * Math.min(pct, 500)) / 100) : 0) +\n    (Number.isFinite(handling) && handling > 0 ? Math.round(handling) : 0)\n  )\n}\n\n/**\n * Rates available for a destination + cart, cheapest first. Specific\n * country zones beat '*' zones: when any specific zone matches, '*'\n * zones are ignored (rest-of-world semantics).\n *\n * Local pickup is appended AFTER and INDEPENDENT of zone matching, so this\n * list is never empty for a merchant who offers it, at any destination. That\n * is correct for a resolver — a shopper anywhere may choose to come and\n * collect — but it means A NON-EMPTY RESULT IS NOT A PROMISE TO SHIP THERE.\n * Callers deciding whether a destination is served must filter pickup out\n * first; `planCheckoutShipping` and `summarizeShippingCoverage` do (AGL-2325).\n */\nexport function resolveShippingRates(\n  settings: ShippingSettings | undefined,\n  destinationCountry: string | undefined,\n  cart: { subtotalCents: number; totalGrams?: number },\n): ResolvedShippingRate[] {\n  if (!settings || !destinationCountry) return []\n  const zoneIds = matchedZoneIds(settings, destinationCountry)\n  // A zone is SPECIFIC when it names this country outright — not merely when\n  // it is \"not wildcard-only\" (AGL-2298). The old test was `!every(code ===\n  // '*')`, so a zone spelled `['*','US']` counted as specific for all six\n  // destinations (it matches every country through the `*`) and suppressed\n  // every genuine rest-of-world zone globally. Asking the narrower question\n  // makes such a zone specific for `US` and wildcard for the rest, which is\n  // what its two entries actually say.\n  const resolved: ResolvedShippingRate[] = []\n  for (const rate of settings.rates ?? []) {\n    if (!zoneIds.has(rate.zoneId)) continue\n    let amountCents: number | null = null\n    switch (rate.kind) {\n      case 'flat':\n        amountCents = Math.max(0, Math.round(rate.amountCents ?? 0))\n        break\n      case 'free_over':\n        amountCents =\n          rate.freeOverCents != null &&\n          cart.subtotalCents >= rate.freeOverCents\n            ? 0\n            : Math.max(0, Math.round(rate.amountCents ?? 0))\n        break\n      case 'price_tiers':\n        amountCents = tierAmount(rate.tiers, cart.subtotalCents)\n        break\n      case 'weight_tiers':\n        amountCents = tierAmount(rate.tiers, cart.totalGrams ?? 0)\n        break\n      // A carrier's price exists only once a carrier quoted it for an\n      // address (AGL-3612), so a table read offers nothing for it and its\n      // fallback rate is what resolves here. `carrier-shipping.ts` adds the\n      // quotes where one can be had.\n      case 'carrier':\n        break\n    }\n    if (amountCents == null) continue\n    resolved.push({ rateId: rate.id, name: rate.name, amountCents })\n  }\n  if (settings.localPickup) {\n    resolved.push({\n      rateId: LOCAL_PICKUP_RATE_ID,\n      name: 'Local pickup',\n      amountCents: 0,\n    })\n  }\n  return resolved.sort((a, b) => a.amountCents - b.amountCents)\n}\n\n/**\n * The resolved options that actually carry a parcel (AGL-2325).\n *\n * Safe to apply AFTER `MAX_CHECKOUT_SHIPPING_OPTIONS` truncation: pickup is\n * 0¢ and sorts first, so it occupies at most one of the five slots and a\n * merchant with any shippable rate at all keeps at least one of them.\n */\nfunction shippableOnly(\n  options: readonly ResolvedShippingRate[],\n): ResolvedShippingRate[] {\n  return options.filter((option) => option.rateId !== LOCAL_PICKUP_RATE_ID)\n}\n\n/** Stripe Checkout accepts at most 5 `shipping_options` on one session. */\nexport const MAX_CHECKOUT_SHIPPING_OPTIONS = 5\n\n/**\n * Destinations a storefront Checkout Session collects an address for, and\n * therefore the destinations shipping rates are resolved against (AGL-1707).\n *\n * NOT narrowed to the zones the merchant configured: narrowing would block\n * checkouts that complete today, turning a money fix into lost sales. The\n * wider list only means a shopper outside the merchant's zones is offered some\n * rate rather than none. Shared by cart checkout and buy-now (AGL-1720) so the\n * two paths cannot drift into offering different destinations.\n */\nexport const CHECKOUT_SHIPPING_COUNTRIES = [\n  'US',\n  'CA',\n  'GB',\n  'AU',\n  'DE',\n  'FR',\n] as const\n\n/**\n * The rates to declare as `shipping_options` on a Stripe Checkout Session\n * (AGL-1707), unioned over `destinationCountries`. Stripe charges shipping\n * ONLY when the session declares them.\n *\n * A UNION IS ONLY HONEST OVER DESTINATIONS THE SESSION IS ALSO RESTRICTED TO.\n * Called with every collectable country while the session accepted an address\n * in any of them — which is what AGL-1707 shipped — it offers a shopper in one\n * zone a rate belonging to another, and Stripe applies whichever the shopper\n * picks (a `shipping_rate_data` carries no country of its own, so nothing\n * downstream re-checks it against the address). That is AGL-1721. Callers now\n * reach this through `planCheckoutShipping`, which pairs the country list it\n * unions over with the country list the session allows, so the two cannot\n * disagree. Do not call it directly from a handler.\n *\n * Returns `[]` for a merchant who has configured nothing, and the caller must\n * then declare no `shipping_options` at all rather than an empty array — a\n * merchant who never set shipping up keeps a session identical to today's.\n */\nexport function resolveCheckoutShippingOptions(\n  settings: ShippingSettings | undefined,\n  destinationCountries: readonly string[],\n  cart: { subtotalCents: number; totalGrams?: number },\n): ResolvedShippingRate[] {\n  if (!settings) return []\n  const byRateId = new Map<string, ResolvedShippingRate>()\n  for (const country of destinationCountries) {\n    for (const rate of resolveShippingRates(settings, country, cart)) {\n      // Stripe requires a display name, and a rate id is the dedupe key —\n      // the console lets a merchant add a blank row, so neither is assured.\n      if (!rate.rateId || !rate.name) continue\n      const amountCents = Math.max(0, Math.round(Number(rate.amountCents) || 0))\n      const existing = byRateId.get(rate.rateId)\n      // One rate resolving differently for two countries should not be\n      // possible (a zone selects a rate, it does not reprice one), but if it\n      // ever is, keep the dearer. Under-charging is the defect being fixed.\n      if (!existing || amountCents > existing.amountCents) {\n        byRateId.set(rate.rateId, { ...rate, amountCents })\n      }\n    }\n  }\n  return (\n    [...byRateId.values()]\n      // Cheapest first, id as a tie-break so the emitted params are stable.\n      .sort(\n        (a, b) =>\n          a.amountCents - b.amountCents || a.rateId.localeCompare(b.rateId),\n      )\n      // Past Stripe's cap the dearest are dropped, which is the harmless end\n      // to lose: a shopper offered the cheap options would have taken one.\n      .slice(0, MAX_CHECKOUT_SHIPPING_OPTIONS)\n  )\n}\n\n/** Shopper-facing names for the collectable destinations (AGL-1721). */\nexport const CHECKOUT_SHIPPING_COUNTRY_NAMES: Readonly<Record<string, string>> =\n  {\n    US: 'United States',\n    CA: 'Canada',\n    GB: 'United Kingdom',\n    AU: 'Australia',\n    DE: 'Germany',\n    FR: 'France',\n  }\n\n/**\n * A destination a shopper declared, or `undefined` for anything this session\n * could not collect an address for anyway. Never throws: an unknown code is\n * an undeclared destination, not an error, so a stale storefront that posts\n * one is answered by the plan below rather than by a 400 nobody can act on.\n */\nexport function normalizeCheckoutShippingCountry(\n  value: unknown,\n): string | undefined {\n  // `typeof` rather than `String(value)`: a JSON body is caller-shaped, and\n  // `String(['US'])` is 'US'. Coercing would let an array declare a\n  // destination, which is not a spelling any storefront sends.\n  if (typeof value !== 'string') return undefined\n  const code = value.trim().toUpperCase()\n  return (CHECKOUT_SHIPPING_COUNTRIES as readonly string[]).includes(code)\n    ? code\n    : undefined\n}\n\nexport interface CheckoutShippingPlan {\n  /** `shipping_address_collection[allowed_countries]` for this session. */\n  countries: readonly string[]\n  /** `shipping_options` for this session — valid for EVERY `countries` entry. */\n  options: ResolvedShippingRate[]\n  /**\n   * Set when no session may be created at all:\n   *\n   * - `destination-required` — the merchant's rates differ by destination, so\n   *   there is no set of options honest for every address Stripe would accept.\n   *   Ask the shopper where they are shipping and plan again.\n   * - `destination-unserved` — the merchant ships somewhere, but not there.\n   * - `cart-unpriceable` — the merchant priced shipping, but no rate of theirs\n   *   resolves for THIS cart at ANY destination (AGL-2232). A tier table that\n   *   stops at 2 kg says nothing about a 3 kg parcel, and the honest answer is\n   *   to refuse rather than to ship it for nothing.\n   */\n  refusal?: 'destination-required' | 'destination-unserved' | 'cart-unpriceable'\n}\n\n/**\n * Whether this merchant prices shipping AT ALL (AGL-2232).\n *\n * A pure question about the SETTINGS, deliberately taking no cart, and that is\n * the whole point of it existing. `planCheckoutShipping` used to ask \"does any\n * rate resolve for any destination?\" and pass the live cart into the probe, so\n * a cart that exhausted every tier made the probe empty too — and an empty\n * probe reads as \"this merchant never set shipping up\", the one case that must\n * complete with no `shipping_options` and nothing charged. A 3 kg order at a\n * store whose weight tiers stop at 2 kg therefore shipped free, silently, on\n * every one of the three doors.\n *\n * Answered from the stored zones and rates instead: a rate bound to a zone\n * that exists, or local pickup, means the merchant made a shipping decision\n * and a cart their table cannot price is a REFUSAL. A merchant with no zones,\n * no rates and no pickup has made no such decision, and their session stays\n * byte-identical to the one AGL-1707 shipped.\n */\nexport function merchantPricesShipping(\n  settings: ShippingSettings | undefined,\n): boolean {\n  if (!settings) return false\n  if (settings.localPickup) return true\n  const zoneIds = new Set((settings.zones ?? []).map((zone) => zone.id))\n  // A rate whose `zoneId` names no zone is unreachable by every resolver here,\n  // so it is not evidence of a decision — counting it would refuse carts at a\n  // store with nothing but orphaned rows.\n  return (settings.rates ?? []).some((rate) => zoneIds.has(rate.zoneId))\n}\n\n/**\n * What a shopper is told when `cart-unpriceable` refuses (AGL-2232).\n *\n * One string, shared by all three doors, because the three used to phrase the\n * two existing refusals identically and drifting here would make the same\n * store say different things depending on which button was pressed. It names\n * the cart rather than the destination on purpose — a `Ship to` select cannot\n * fix a parcel no tier covers, so the refusal deliberately does NOT set\n * `needsShippingCountry`.\n */\nexport const CART_UNPRICEABLE_SHIPPING_MESSAGE =\n  'This store cannot price shipping for this order — it falls outside every ' +\n  'shipping rate the store has set up. Try removing an item, or contact the ' +\n  'store.'\n\n/** Identity of a resolved list, for comparing two destinations' offers. */\nfunction optionsKey(options: readonly ResolvedShippingRate[]): string {\n  return options\n    .map((option) => `${option.rateId}:${option.amountCents}`)\n    .join('|')\n}\n\n/**\n * The whole shipping half of a Checkout Session: which destinations it may\n * accept an address for, and which rates it may charge (AGL-1721).\n *\n * THE INVARIANT IS THAT EVERY RETURNED OPTION IS VALID FOR EVERY RETURNED\n * COUNTRY. Stripe offers a session's `shipping_options` to whoever reaches the\n * page and charges whichever the shopper picks — it does not filter them by\n * the address entered, and there is no field on a `shipping_rate_data` that\n * would let it. So the ONLY place a zone can be enforced is here, by choosing\n * the two lists together: narrowing the allowed countries to the declared\n * destination is what makes the rates offered for it unpickable by anyone\n * else. Filtering the rate list alone would leave a session that still accepts\n * a French address against a US rate.\n *\n * Three shapes come out of it:\n *\n *   1. A merchant whose rates resolve the SAME for every collectable country —\n *      one zone, a single '*' zone, or none at all — needs no destination and\n *      keeps the session AGL-1707 shipped, byte for byte. The issue notes this\n *      is the common configuration, and it is the one that must not regress.\n *   2. A declared destination resolves exactly, and the session is restricted\n *      to it. A caller may not skip the restriction: the country arrives in a\n *      request body a shopper can craft, so a session that took the country's\n *      cheap rate while still accepting any address would hand that shopper\n *      the defect on purpose.\n *   3. Otherwise the caller must refuse — see `refusal`. Refusing is not lost\n *      revenue in either case: with rates that differ by zone there is no\n *      correct amount to charge without knowing where the parcel is going, and\n *      the union AGL-1707 shipped chose the wrong one silently.\n *\n * `cart.subtotalCents` is the PRE-discount items total, matching what the cart\n * displays, so a free-over threshold means what the shopper saw it mean.\n */\nexport function planCheckoutShipping(\n  settings: ShippingSettings | undefined,\n  cart: { subtotalCents: number; totalGrams?: number },\n  destinationCountry?: unknown,\n): CheckoutShippingPlan {\n  const countries = CHECKOUT_SHIPPING_COUNTRIES as readonly string[]\n  const destination = normalizeCheckoutShippingCountry(destinationCountry)\n  if (destination) {\n    const options = resolveCheckoutShippingOptions(\n      settings,\n      [destination],\n      cart,\n    )\n    // REFUSAL IS DECIDED ON SHIPPABLE RATES, PICKUP IS OFFERED AFTERWARDS\n    // (AGL-2325). `resolveShippingRates` appends pickup independent of zone\n    // matching, so a merchant who turned it on had a non-empty list for every\n    // destination on earth and this branch returned before it could refuse\n    // anyone: a shopper in France picked `Local pickup — Free` on a physical\n    // order from a US-only store, Stripe collected their French address\n    // because the session still allowed it, and the merchant was paid nothing\n    // to carry the parcel there. Pickup is collection, not delivery, so it\n    // cannot answer \"do you ship to France\".\n    //\n    // `shipsElsewhere` is the same question the old probe asked, narrowed to\n    // shippable rates, and it keeps the same two-way fork: a merchant who\n    // configured NO shipping is not refusing anyone, so that store keeps\n    // completing exactly as it does today, while a merchant who ships\n    // elsewhere but not here is refusing and saying so is the honest answer.\n    // A merchant who ships NOWHERE is untouched by this: pickup-only is a\n    // real configuration — they deliver to no one and refuse no one — and it\n    // falls through to the offer below exactly as it did.\n    const shipsElsewhere = countries.some(\n      (country) =>\n        shippableOnly(resolveCheckoutShippingOptions(settings, [country], cart))\n          .length > 0,\n    )\n    if (shippableOnly(options).length === 0 && shipsElsewhere) {\n      return { countries, options: [], refusal: 'destination-unserved' }\n    }\n    if (options.length > 0) return { countries: [destination], options }\n    // NOTHING resolves anywhere for this cart, and the two reasons that can be\n    // true of are opposite (AGL-2232). Asked of the SETTINGS rather than of\n    // this cart, because the probe above cannot tell them apart: a merchant\n    // who priced shipping and whose table simply does not reach this order is\n    // refusing, and used to be handed the \"never set shipping up\" branch.\n    return merchantPricesShipping(settings)\n      ? { countries, options: [], refusal: 'cart-unpriceable' }\n      : { countries, options: [] }\n  }\n  const offers = new Set(\n    countries.map((country) =>\n      optionsKey(resolveCheckoutShippingOptions(settings, [country], cart)),\n    ),\n  )\n  // Compared as EMITTED — capped and sanitized — because that is the list a\n  // shopper can pick from. Two destinations whose rates differ only past\n  // Stripe's cap still offer the same five, and offering them is honest.\n  if (offers.size > 1) {\n    return { countries, options: [], refusal: 'destination-required' }\n  }\n  const union = resolveCheckoutShippingOptions(settings, countries, cart)\n  // Every destination agrees, and what they agree on is NOTHING. The same\n  // fork as the declared-destination branch above (AGL-2232): a store with no\n  // shipping settings completes untouched, a store whose rates cannot reach\n  // this cart refuses instead of carrying the parcel for free.\n  if (union.length === 0 && merchantPricesShipping(settings)) {\n    return { countries, options: [], refusal: 'cart-unpriceable' }\n  }\n  return { countries, options: union }\n}\n\n/**\n * A cart chosen so that every rate a merchant could have written resolves if\n * it can resolve at all (AGL-1791). The settings page has no cart, and two of\n * the four rate kinds price against one: `tierAmount` takes the first tier\n * whose `upTo` is at least the value, so a zero subtotal and zero weight clear\n * every tier a merchant would write, and a `free_over` rate resolves at any\n * subtotal.\n *\n * That makes a coverage answer a LOWER BOUND on the gaps. A destination\n * reported unserved is unserved for every cart; a destination reported served\n * may still be refused for a cart dearer or heavier than the merchant's last\n * tier. Erring in this direction is the deliberate half: the console must not\n * warn a merchant whose settings are fine.\n */\nconst COVERAGE_PROBE_CART = { subtotalCents: 0, totalGrams: 0 }\n\n/** What a merchant's saved zones and rates cost their shoppers (AGL-1791). */\nexport interface ShippingCoverage {\n  /** Collectable destinations at least one rate reaches. */\n  served: string[]\n  /**\n   * Collectable destinations CHECKOUT REFUSES — `destination-unserved`.\n   *\n   * EMPTY FOR A MERCHANT WHOSE RATES REACH NOWHERE, who is not misconfigured:\n   * `planCheckoutShipping` refuses nobody when no rate resolves anywhere, so\n   * that store charges no shipping and completes exactly as it always has.\n   * The rule lives here rather than in the caller because reading `served`\n   * against a bare partition is how a surface comes to warn every store that\n   * does not ship.\n   */\n  unserved: string[]\n  /** No rate reaches anywhere: no shipping is charged, and nobody refused. */\n  shipsNowhere: boolean\n  /**\n   * Rates differ by destination, so the storefront asks the shopper where the\n   * parcel is going before it can price one — a checkout step the merchant\n   * added by saving these zones, and never chose.\n   */\n  asksDestination: boolean\n  /** Some zone already claims rest of world, so `*` is not the missing piece. */\n  hasRestOfWorldZone: boolean\n  /**\n   * The merchant offers local pickup, so checkout presents a free collection\n   * choice at every destination it does not refuse (AGL-2325).\n   *\n   * Deliberately NOT folded into `served`: pickup resolves for every country\n   * because it is appended independent of zone matching, so counting it as\n   * coverage told a US-only merchant who had switched it on that checkout\n   * \"can price shipping to every destination\", which is the sentence that\n   * hid the defect. It is reported alongside instead, so the card can say\n   * both true things: these destinations are refused, and pickup is offered\n   * to the ones that are not.\n   */\n  offersLocalPickup: boolean\n}\n\n/**\n * Which of the collectable destinations a merchant's settings actually cover\n * (AGL-1791), for a console surface to show them.\n *\n * Measured against `CHECKOUT_SHIPPING_COUNTRIES` and nothing wider: those six\n * are the only destinations a storefront session collects an address for, so\n * they are the only ones a merchant can lose an order to. Counting coverage\n * against every country on earth would report a gap for destinations no\n * shopper can reach checkout from.\n *\n * Answered through `resolveCheckoutShippingOptions` — the same function the\n * session is built from — so a row the console allows but Stripe would reject\n * (blank id, blank name) counts as the nothing it resolves to, and a specific\n * zone with no rates still hides a `*` zone here exactly as it does at\n * checkout.\n */\nexport function summarizeShippingCoverage(\n  settings: ShippingSettings | undefined,\n): ShippingCoverage {\n  const served: string[] = []\n  const unserved: string[] = []\n  const offers = new Set<string>()\n  for (const country of CHECKOUT_SHIPPING_COUNTRIES) {\n    const options = resolveCheckoutShippingOptions(\n      settings,\n      [country],\n      COVERAGE_PROBE_CART,\n    )\n    // `asksDestination` is asked of the FULL list — pickup is a real option a\n    // shopper picks, so a merchant whose US destination offers a rate plus\n    // pickup while France offers only pickup genuinely does make checkout ask.\n    offers.add(optionsKey(options))\n    // `served` is asked of the SHIPPABLE list, so that it answers the same\n    // question `planCheckoutShipping` refuses on (AGL-2325).\n    ;(shippableOnly(options).length > 0 ? served : unserved).push(country)\n  }\n  return {\n    served,\n    unserved: served.length > 0 ? unserved : [],\n    shipsNowhere: served.length === 0,\n    asksDestination: offers.size > 1,\n    offersLocalPickup: Boolean(settings?.localPickup),\n    hasRestOfWorldZone: (settings?.zones ?? []).some((zone) =>\n      zone.countries.some((code) => code === '*'),\n    ),\n  }\n}\n\n/**\n * Emit `shipping_address_collection[allowed_countries][n]` onto a session's\n * form body. Stripe will not apply a `shipping_options` rate without an\n * address to ship to, so the two always travel together — and the countries\n * are the OTHER half of what makes a rate honest (AGL-1721), so pass the list\n * `planCheckoutShipping` returned rather than defaulting it beside a rate list\n * resolved for something narrower.\n */\nexport function appendShippingAddressCollectionParams(\n  params: URLSearchParams,\n  countries: readonly string[] = CHECKOUT_SHIPPING_COUNTRIES,\n): void {\n  countries.forEach((code, index) => {\n    params.set(`shipping_address_collection[allowed_countries][${index}]`, code)\n  })\n}\n\n/**\n * Emit resolved rates as `shipping_options` on a Checkout Session's form body.\n *\n * THIS IS THE ONLY THING THAT MAKES STRIPE CHARGE SHIPPING. Without these keys\n * Stripe presents no shipping choice and `total_details.amount_shipping` is 0\n * however many zones and rates the merchant saved (AGL-1707).\n *\n * An empty list emits NOTHING — not an empty array — so a merchant who\n * configured no shipping keeps a session byte-identical to the one built\n * before shipping was wired at all. That guarantee lives here rather than in\n * each caller, so neither checkout path can lose it independently (AGL-1720).\n */\nexport function appendCheckoutShippingParams(\n  params: URLSearchParams,\n  options: readonly ResolvedShippingRate[],\n): void {\n  options.forEach((option, index) => {\n    const field = `shipping_options[${index}][shipping_rate_data]`\n    params.set(`${field}[type]`, 'fixed_amount')\n    params.set(`${field}[display_name]`, option.name.slice(0, 100))\n    params.set(`${field}[fixed_amount][amount]`, String(option.amountCents))\n    params.set(`${field}[fixed_amount][currency]`, 'usd')\n  })\n}\n"],"names":["CARRIER_QUOTE_TIMEOUT_MS","LOCAL_PICKUP_RATE_ID","zoneCode","code","String","trim","toUpperCase","isWildcard","zoneMatches","zone","country","countries","some","tierAmount","tiers","value","sorted","sort","a","b","upTo","tier","amountCents","matchedZoneIds","settings","destinationCountry","zones","specific","filter","matched","length","Set","map","id","carrierRatesFor","zoneIds","rates","rate","kind","has","zoneId","hasCarrierRates","carrierOptionRateId","rateId","serviceKey","carrierOptionAmountCents","quotedCents","quote","Math","max","round","Number","pct","markupPct","handling","handlingCents","isFinite","min","resolveShippingRates","cart","resolved","freeOverCents","subtotalCents","totalGrams","push","name","localPickup","shippableOnly","options","option","MAX_CHECKOUT_SHIPPING_OPTIONS","CHECKOUT_SHIPPING_COUNTRIES","resolveCheckoutShippingOptions","destinationCountries","byRateId","Map","existing","get","set","values","localeCompare","slice","CHECKOUT_SHIPPING_COUNTRY_NAMES","US","CA","GB","AU","DE","FR","normalizeCheckoutShippingCountry","undefined","includes","merchantPricesShipping","CART_UNPRICEABLE_SHIPPING_MESSAGE","optionsKey","join","planCheckoutShipping","destination","shipsElsewhere","refusal","offers","size","union","COVERAGE_PROBE_CART","summarizeShippingCoverage","served","unserved","add","shipsNowhere","asksDestination","offersLocalPickup","Boolean","hasRestOfWorldZone","appendShippingAddressCollectionParams","params","forEach","index","appendCheckoutShippingParams","field"],"mappings":"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"}

package/src/lib/model/commerce-tax-engine.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * WHEN AN OUTSIDE TAX SERVICE PRICED A SALE (AGL-3631).
+ *
+ * A merchant may connect their own Avalara AvaTax or TaxJar account through
+ * another plugin, which answers core's `core.tax-engine` contract. Commerce
+ * asks it only where the store collects tax at its OWN rates (`mode:
+ * 'manual'`, prices exclusive of tax): that is the regime where the merchant
+ * is the one liable for the tax, so an engine of theirs answering for it
+ * changes the arithmetic and not whose money it is. A Stripe Tax store is
+ * never sent to an engine — that tax is computed against Aglyn's
+ * registrations and is Aglyn's to remit (AGL-1904).
+ *
+ * The order's `taxMode` therefore stays what `storefrontTaxModeOf` says,
+ * `manual` (or `none` at zero), and accounting posts it as tax the merchant
+ * owes. What this module adds beside it is the `taxEngine` stamp: which
+ * service answered, or that it was asked and did not, so the order says the
+ * sale fell back to the store's own rates.
+ *
+ * Pure: no Firestore, no fetch. Imported by path, not through the model
+ * barrel, so it costs the console bundle nothing.
+ */
+/** Which outside service priced a sale, or that it was asked and the sale fell back. */
+export interface OrderTaxEngineStamp {
+    /** The service's id, e.g. `avalara`. */
+    provider: string;
+    /** Its name in the merchant's words, e.g. `Avalara AvaTax`. */
+    providerLabel: string;
+    /** `quoted`: the service's tax was charged. `fallback`: the store's own rates were. */
+    status: 'quoted' | 'fallback';
+    /** Why it fell back: `timeout` or `error`; `null` when quoted. */
+    reason: string | null;
+    /** Whether the service's test environment answered. */
+    sandbox: boolean;
+}
+/** Whether a store's tax settings let an outside service price its sales. */
+export declare function storeTaxAllowsEngine(settings: {
+    mode?: string;
+    pricesIncludeTax?: boolean;
+} | null | undefined): boolean;
+/**
+ * The stamp as Checkout Session metadata, for the webhook that writes the
+ * order to restate. Stripe caps a metadata value at 500 characters; these
+ * are a few dozen.
+ */
+export declare function taxEngineSessionMetadata(stamp: OrderTaxEngineStamp | null | undefined): Record<string, string>;
+/** The stamp read back off a session's metadata, spread onto the order. */
+export declare function taxEngineStampFromMetadata(metadata: Record<string, unknown> | null | undefined): {
+    taxEngine?: OrderTaxEngineStamp;
+};
+/** The stamp as the public order view carries it: `null` when no service was asked. */
+export declare function orderTaxEngineView(value: unknown): OrderTaxEngineStamp | null;
+/**
+ * Splits `totalCents` across `weights` so the parts sum exactly to the
+ * total: each part floored, the leftover cents handed out by the largest
+ * remainders. Stripe spreads a session coupon across lines in proportion to
+ * their amounts; this is the same proportion, so a rate derived from it is
+ * applied by Stripe to (within a cent) the amount it was derived from.
+ */
+export declare function allocateCentsByWeight(totalCents: number, weights: readonly number[]): number[];
+/**
+ * A quoted tax as one PERCENTAGE per line, for the cart's hosted checkout.
+ *
+ * The cart charges tax through real Stripe Tax Rates on each line (AGL-1953)
+ * because its discounts are session coupons Stripe spreads across every line,
+ * and a rate is applied after them. An engine answers in cents per line, so
+ * each line's cents become the rate that yields them on that line's
+ * discounted amount, to Stripe's four decimal places — exact to the cent for
+ * any line under $10,000. A line the engine taxed at zero, or one with
+ * nothing left to tax, carries no rate (`null`).
+ */
+export declare function engineLineTaxPercentages(lines: ReadonlyArray<{
+    amountCents: number;
+    taxCents: number;
+}>, discountCents: number): Array<number | null>;

package/src/lib/model/commerce-tax-engine.js

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * WHEN AN OUTSIDE TAX SERVICE PRICED A SALE (AGL-3631).
+ *
+ * A merchant may connect their own Avalara AvaTax or TaxJar account through
+ * another plugin, which answers core's `core.tax-engine` contract. Commerce
+ * asks it only where the store collects tax at its OWN rates (`mode:
+ * 'manual'`, prices exclusive of tax): that is the regime where the merchant
+ * is the one liable for the tax, so an engine of theirs answering for it
+ * changes the arithmetic and not whose money it is. A Stripe Tax store is
+ * never sent to an engine — that tax is computed against Aglyn's
+ * registrations and is Aglyn's to remit (AGL-1904).
+ *
+ * The order's `taxMode` therefore stays what `storefrontTaxModeOf` says,
+ * `manual` (or `none` at zero), and accounting posts it as tax the merchant
+ * owes. What this module adds beside it is the `taxEngine` stamp: which
+ * service answered, or that it was asked and did not, so the order says the
+ * sale fell back to the store's own rates.
+ *
+ * Pure: no Firestore, no fetch. Imported by path, not through the model
+ * barrel, so it costs the console bundle nothing.
+ */ /** Which outside service priced a sale, or that it was asked and the sale fell back. */ import { _ as _extends } from "@swc/helpers/_/_extends";
+/** Whether a store's tax settings let an outside service price its sales. */ export function storeTaxAllowsEngine(settings) {
+    return (settings == null ? void 0 : settings.mode) === 'manual' && !settings.pricesIncludeTax;
+}
+/**
+ * The stamp as Checkout Session metadata, for the webhook that writes the
+ * order to restate. Stripe caps a metadata value at 500 characters; these
+ * are a few dozen.
+ */ export function taxEngineSessionMetadata(stamp) {
+    if (!stamp) return {};
+    return _extends({
+        'metadata[taxEngine]': stamp.provider.slice(0, 40),
+        'metadata[taxEngineLabel]': stamp.providerLabel.slice(0, 80),
+        'metadata[taxEngineStatus]': stamp.status
+    }, stamp.reason ? {
+        'metadata[taxEngineReason]': stamp.reason.slice(0, 40)
+    } : {}, stamp.sandbox ? {
+        'metadata[taxEngineSandbox]': 'true'
+    } : {});
+}
+/** The stamp read back off a session's metadata, spread onto the order. */ export function taxEngineStampFromMetadata(metadata) {
+    var _ref, _ref1, _ref2;
+    const provider = String((_ref = metadata == null ? void 0 : metadata['taxEngine']) != null ? _ref : '').trim();
+    if (!provider) return {};
+    const status = (metadata == null ? void 0 : metadata['taxEngineStatus']) === 'quoted' ? 'quoted' : 'fallback';
+    return {
+        taxEngine: {
+            provider,
+            providerLabel: String((_ref1 = metadata == null ? void 0 : metadata['taxEngineLabel']) != null ? _ref1 : '') || provider,
+            status,
+            reason: status === 'fallback' ? String((_ref2 = metadata == null ? void 0 : metadata['taxEngineReason']) != null ? _ref2 : '') || 'error' : null,
+            sandbox: (metadata == null ? void 0 : metadata['taxEngineSandbox']) === 'true'
+        }
+    };
+}
+/** The stamp as the public order view carries it: `null` when no service was asked. */ export function orderTaxEngineView(value) {
+    var _stamp_providerLabel, _stamp_reason;
+    const stamp = value != null ? value : null;
+    if (!stamp || typeof stamp['provider'] !== 'string' || !stamp['provider']) return null;
+    const status = stamp['status'] === 'quoted' ? 'quoted' : 'fallback';
+    return {
+        provider: stamp['provider'],
+        providerLabel: String((_stamp_providerLabel = stamp['providerLabel']) != null ? _stamp_providerLabel : '') || stamp['provider'],
+        status,
+        reason: status === 'fallback' ? String((_stamp_reason = stamp['reason']) != null ? _stamp_reason : '') || 'error' : null,
+        sandbox: stamp['sandbox'] === true
+    };
+}
+/**
+ * Splits `totalCents` across `weights` so the parts sum exactly to the
+ * total: each part floored, the leftover cents handed out by the largest
+ * remainders. Stripe spreads a session coupon across lines in proportion to
+ * their amounts; this is the same proportion, so a rate derived from it is
+ * applied by Stripe to (within a cent) the amount it was derived from.
+ */ export function allocateCentsByWeight(totalCents, weights) {
+    const total = Math.max(0, Math.round(Number(totalCents) || 0));
+    const clean = weights.map((weight)=>Number.isFinite(weight) && weight > 0 ? weight : 0);
+    const sum = clean.reduce((a, b)=>a + b, 0);
+    if (sum <= 0 || total === 0) return clean.map(()=>0);
+    const raw = clean.map((weight)=>total * weight / sum);
+    const parts = raw.map(Math.floor);
+    let left = total - parts.reduce((a, b)=>a + b, 0);
+    const order = raw.map((value, index)=>({
+            index,
+            remainder: value - Math.floor(value)
+        })).filter(({ index })=>clean[index] > 0).sort((a, b)=>b.remainder - a.remainder || a.index - b.index);
+    for(let i = 0; left > 0 && order.length > 0; i = (i + 1) % order.length){
+        parts[order[i].index] += 1;
+        left -= 1;
+    }
+    return parts;
+}
+/**
+ * A quoted tax as one PERCENTAGE per line, for the cart's hosted checkout.
+ *
+ * The cart charges tax through real Stripe Tax Rates on each line (AGL-1953)
+ * because its discounts are session coupons Stripe spreads across every line,
+ * and a rate is applied after them. An engine answers in cents per line, so
+ * each line's cents become the rate that yields them on that line's
+ * discounted amount, to Stripe's four decimal places — exact to the cent for
+ * any line under $10,000. A line the engine taxed at zero, or one with
+ * nothing left to tax, carries no rate (`null`).
+ */ export function engineLineTaxPercentages(lines, discountCents) {
+    const amounts = lines.map((line)=>Math.max(0, Math.round(Number(line.amountCents) || 0)));
+    const discounts = allocateCentsByWeight(Math.min(Math.max(0, discountCents), amounts.reduce((a, b)=>a + b, 0)), amounts);
+    return lines.map((line, index)=>{
+        const net = amounts[index] - discounts[index];
+        const tax = Math.max(0, Math.round(Number(line.taxCents) || 0));
+        if (net <= 0 || tax <= 0) return null;
+        return Math.round(tax / net * 100 * 10000) / 10000;
+    });
+}
+
+//# sourceMappingURL=commerce-tax-engine.js.map

package/src/lib/model/commerce-tax-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-tax-engine.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * WHEN AN OUTSIDE TAX SERVICE PRICED A SALE (AGL-3631).\n *\n * A merchant may connect their own Avalara AvaTax or TaxJar account through\n * another plugin, which answers core's `core.tax-engine` contract. Commerce\n * asks it only where the store collects tax at its OWN rates (`mode:\n * 'manual'`, prices exclusive of tax): that is the regime where the merchant\n * is the one liable for the tax, so an engine of theirs answering for it\n * changes the arithmetic and not whose money it is. A Stripe Tax store is\n * never sent to an engine — that tax is computed against Aglyn's\n * registrations and is Aglyn's to remit (AGL-1904).\n *\n * The order's `taxMode` therefore stays what `storefrontTaxModeOf` says,\n * `manual` (or `none` at zero), and accounting posts it as tax the merchant\n * owes. What this module adds beside it is the `taxEngine` stamp: which\n * service answered, or that it was asked and did not, so the order says the\n * sale fell back to the store's own rates.\n *\n * Pure: no Firestore, no fetch. Imported by path, not through the model\n * barrel, so it costs the console bundle nothing.\n */\n\n/** Which outside service priced a sale, or that it was asked and the sale fell back. */\nexport interface OrderTaxEngineStamp {\n  /** The service's id, e.g. `avalara`. */\n  provider: string\n  /** Its name in the merchant's words, e.g. `Avalara AvaTax`. */\n  providerLabel: string\n  /** `quoted`: the service's tax was charged. `fallback`: the store's own rates were. */\n  status: 'quoted' | 'fallback'\n  /** Why it fell back: `timeout` or `error`; `null` when quoted. */\n  reason: string | null\n  /** Whether the service's test environment answered. */\n  sandbox: boolean\n}\n\n/** Whether a store's tax settings let an outside service price its sales. */\nexport function storeTaxAllowsEngine(settings: {\n  mode?: string\n  pricesIncludeTax?: boolean\n} | null | undefined): boolean {\n  return settings?.mode === 'manual' && !settings.pricesIncludeTax\n}\n\n/**\n * The stamp as Checkout Session metadata, for the webhook that writes the\n * order to restate. Stripe caps a metadata value at 500 characters; these\n * are a few dozen.\n */\nexport function taxEngineSessionMetadata(\n  stamp: OrderTaxEngineStamp | null | undefined,\n): Record<string, string> {\n  if (!stamp) return {}\n  return {\n    'metadata[taxEngine]': stamp.provider.slice(0, 40),\n    'metadata[taxEngineLabel]': stamp.providerLabel.slice(0, 80),\n    'metadata[taxEngineStatus]': stamp.status,\n    ...(stamp.reason ? { 'metadata[taxEngineReason]': stamp.reason.slice(0, 40) } : {}),\n    ...(stamp.sandbox ? { 'metadata[taxEngineSandbox]': 'true' } : {}),\n  }\n}\n\n/** The stamp read back off a session's metadata, spread onto the order. */\nexport function taxEngineStampFromMetadata(\n  metadata: Record<string, unknown> | null | undefined,\n): { taxEngine?: OrderTaxEngineStamp } {\n  const provider = String(metadata?.['taxEngine'] ?? '').trim()\n  if (!provider) return {}\n  const status = metadata?.['taxEngineStatus'] === 'quoted' ? 'quoted' : 'fallback'\n  return {\n    taxEngine: {\n      provider,\n      providerLabel: String(metadata?.['taxEngineLabel'] ?? '') || provider,\n      status,\n      reason: status === 'fallback' ? String(metadata?.['taxEngineReason'] ?? '') || 'error' : null,\n      sandbox: metadata?.['taxEngineSandbox'] === 'true',\n    },\n  }\n}\n\n/** The stamp as the public order view carries it: `null` when no service was asked. */\nexport function orderTaxEngineView(value: unknown): OrderTaxEngineStamp | null {\n  const stamp = (value ?? null) as Record<string, unknown> | null\n  if (!stamp || typeof stamp['provider'] !== 'string' || !stamp['provider']) return null\n  const status = stamp['status'] === 'quoted' ? 'quoted' : 'fallback'\n  return {\n    provider: stamp['provider'],\n    providerLabel: String(stamp['providerLabel'] ?? '') || stamp['provider'],\n    status,\n    reason: status === 'fallback' ? String(stamp['reason'] ?? '') || 'error' : null,\n    sandbox: stamp['sandbox'] === true,\n  }\n}\n\n/**\n * Splits `totalCents` across `weights` so the parts sum exactly to the\n * total: each part floored, the leftover cents handed out by the largest\n * remainders. Stripe spreads a session coupon across lines in proportion to\n * their amounts; this is the same proportion, so a rate derived from it is\n * applied by Stripe to (within a cent) the amount it was derived from.\n */\nexport function allocateCentsByWeight(totalCents: number, weights: readonly number[]): number[] {\n  const total = Math.max(0, Math.round(Number(totalCents) || 0))\n  const clean = weights.map((weight) => (Number.isFinite(weight) && weight > 0 ? weight : 0))\n  const sum = clean.reduce((a, b) => a + b, 0)\n  if (sum <= 0 || total === 0) return clean.map(() => 0)\n  const raw = clean.map((weight) => (total * weight) / sum)\n  const parts = raw.map(Math.floor)\n  let left = total - parts.reduce((a, b) => a + b, 0)\n  const order = raw\n    .map((value, index) => ({ index, remainder: value - Math.floor(value) }))\n    .filter(({ index }) => clean[index] > 0)\n    .sort((a, b) => b.remainder - a.remainder || a.index - b.index)\n  for (let i = 0; left > 0 && order.length > 0; i = (i + 1) % order.length) {\n    parts[order[i].index] += 1\n    left -= 1\n  }\n  return parts\n}\n\n/**\n * A quoted tax as one PERCENTAGE per line, for the cart's hosted checkout.\n *\n * The cart charges tax through real Stripe Tax Rates on each line (AGL-1953)\n * because its discounts are session coupons Stripe spreads across every line,\n * and a rate is applied after them. An engine answers in cents per line, so\n * each line's cents become the rate that yields them on that line's\n * discounted amount, to Stripe's four decimal places — exact to the cent for\n * any line under $10,000. A line the engine taxed at zero, or one with\n * nothing left to tax, carries no rate (`null`).\n */\nexport function engineLineTaxPercentages(\n  lines: ReadonlyArray<{ amountCents: number; taxCents: number }>,\n  discountCents: number,\n): Array<number | null> {\n  const amounts = lines.map((line) => Math.max(0, Math.round(Number(line.amountCents) || 0)))\n  const discounts = allocateCentsByWeight(\n    Math.min(Math.max(0, discountCents), amounts.reduce((a, b) => a + b, 0)),\n    amounts,\n  )\n  return lines.map((line, index) => {\n    const net = amounts[index] - discounts[index]\n    const tax = Math.max(0, Math.round(Number(line.taxCents) || 0))\n    if (net <= 0 || tax <= 0) return null\n    return Math.round((tax / net) * 100 * 10_000) / 10_000\n  })\n}\n"],"names":["storeTaxAllowsEngine","settings","mode","pricesIncludeTax","taxEngineSessionMetadata","stamp","provider","slice","providerLabel","status","reason","sandbox","taxEngineStampFromMetadata","metadata","String","trim","taxEngine","orderTaxEngineView","value","allocateCentsByWeight","totalCents","weights","total","Math","max","round","Number","clean","map","weight","isFinite","sum","reduce","a","b","raw","parts","floor","left","order","index","remainder","filter","sort","i","length","engineLineTaxPercentages","lines","discountCents","amounts","line","amountCents","discounts","min","net","tax","taxCents"],"mappings":"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"}

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

@@ -14,6 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { type ProductModifierGroup } from './product-modifiers';
+import { type ProductChannelFacts } from './product-channel';
 /**
  * Commerce catalog v1 (AGL-276): products with options/variants,
  * hierarchical categories, tags, and manual/smart collections. Pure
@@ -54,12 +56,56 @@ export interface ProductVariant {
     /** Media-library image URL shown when this variant is selected. */
     imageUrl?: string;
 }
+/** A product's packed size and customs facts (AGL-3612). */
+export interface ProductShippingFacts {
+    lengthCm?: number | null;
+    widthCm?: number | null;
+    heightCm?: number | null;
+    /** Harmonized System tariff code. */
+    hsCode?: string;
+    /** ISO-3166 alpha-2 country the product was made in. */
+    originCountry?: string;
+}
+/** A place's postal address, in parts (AGL-3612). Country is ISO-3166 alpha-2. */
+export interface PostalAddress {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+    phone?: string;
+}
 /** `hosts/{hostId}/locations/{id}` doc (AGL-286). */
 export interface InventoryLocation {
     name: string;
     isDefault?: boolean;
+    /** Free text, as the location was first described. */
     address?: string;
+    /**
+     * The same place as a postal address (AGL-3612), so parcels can ship from
+     * it. Optional: a location written before this has only `address`.
+     */
+    postalAddress?: PostalAddress;
 }
+/** A product's packed size for one unit, when all three sides are known. */
+export declare function productParcelDimensions(product: Pick<HostProduct, 'shipping'> | null | undefined): {
+    lengthCm: number;
+    widthCm: number;
+    heightCm: number;
+} | undefined;
+/**
+ * Shipping facts as the product editor stages them, keystroke by keystroke
+ * (AGL-3647): {@link normalizeProductShippingFacts}, except that a country
+ * of origin being typed keeps its first letter. The editor runs this on
+ * every keystroke, and the strict form drops anything short of two letters,
+ * so the field could never be typed into. Readers normalize what is stored.
+ */
+export declare function draftProductShippingFacts(value: unknown): ProductShippingFacts | undefined;
+/** A stored product's shipping facts made safe (AGL-3612); never throws. */
+export declare function normalizeProductShippingFacts(value: unknown): ProductShippingFacts | undefined;
+/** A stored location's postal address made safe (AGL-3612); never throws. */
+export declare function normalizePostalAddress(value: unknown): PostalAddress | undefined;
 /**
  * `hosts/{hostId}/registers/{id}` doc (AGL-472): a named point-of-sale
  * register. Creation is capped by the plan's `posRegisters` quota (Pro 1,
@@ -120,6 +166,12 @@ export interface HostProduct {
         description?: string;
         imageUrl?: string;
     };
+    /**
+     * What shopping channels ask of the product (AGL-3637): brand, GTIN, MPN,
+     * condition and Google category. Absent means nothing was entered; the
+     * channel feeds fall back to the store's defaults.
+     */
+    channel?: ProductChannelFacts;
     /** Supplier for dropship routing (AGL-289). */
     supplierId?: string;
     /** Out-of-stock behavior (AGL-281): deny (default) or allow backorder. */
@@ -160,10 +212,25 @@ export interface HostProduct {
     }>;
     /** Manual related products for the upsell block (AGL-325). */
     relatedProductIds?: string[];
+    /**
+     * What one unit ships as (AGL-3612): its packed size, for a carrier to
+     * price, and its customs facts, for a parcel that crosses a border. Weight
+     * stays per variant. Absent means unknown, and a label is priced in the
+     * merchant's default box.
+     */
+    shipping?: ProductShippingFacts;
     /** Buying this issues a gift-card code for its price (AGL-322). */
     giftCard?: boolean;
     /** Tracked-total at/below this alerts host managers (AGL-281). */
     lowStockThreshold?: number;
+    /**
+     * Choices added to the item at the register (AGL-3607) — "Oat milk",
+     * "Extra shot" — priced by the server from this list. See
+     * `product-modifiers.ts`.
+     */
+    modifierGroups?: ProductModifierGroup[];
+    /** Shown under Quick keys on the register's first screen (AGL-3607). */
+    posQuickKey?: boolean;
     createdAtMs?: number;
     updatedAtMs?: number;
     deletedAt?: number | null;
@@ -359,6 +426,18 @@ export interface ProductCopyValues {
     optionNames?: string[];
     seoTitle?: string;
     seoDescription?: string;
+    /**
+     * Packed size and customs facts (AGL-3612), merged over what the product
+     * has; a side set to `null` is cleared.
+     */
+    shipping?: Partial<ProductShippingFacts>;
+    /**
+     * Shopping-channel facts (AGL-3637), merged over what the product has; a
+     * field set to `''` is cleared.
+     */
+    channel?: {
+        [Field in keyof ProductChannelFacts]?: string;
+    };
 }
 /**
  * The fields proposed copy changes on a product (AGL-2916), in the shape the
@@ -367,7 +446,7 @@ export interface ProductCopyValues {
  * rename the product's options through `renameProductOptions`, keeping every
  * variant, only when they name each option once with a name of its own.
  */
-export declare function productCopyPatch(product: Pick<HostProduct, 'options' | 'variants' | 'seo'>, values: ProductCopyValues): Partial<Pick<HostProduct, 'description' | 'tags' | 'categoryIds' | 'seo' | 'options' | 'variants'>>;
+export declare function productCopyPatch(product: Pick<HostProduct, 'options' | 'variants' | 'seo' | 'shipping'> & Pick<Partial<HostProduct>, 'channel'>, values: ProductCopyValues): Partial<Pick<HostProduct, 'description' | 'tags' | 'categoryIds' | 'seo' | 'options' | 'variants' | 'shipping' | 'channel'>>;
 /** A product proposed for a store, before anyone has priced it (AGL-2916). */
 export interface ProposedProduct {
     name: string;
@@ -408,8 +487,13 @@ export declare function productInventory(product: Pick<HostProduct, 'variants'>)
  * picks when the count disagreed with the shelf for a reason nobody recorded.
  * Kept out of the "Adjust stock" dialog's menu on purpose: a merchant reaching
  * for it by hand means something else happened.
+ *
+ * `sync` is a count another warehouse reported (AGL-3634): a fulfillment
+ * network holding the goods said how many it can ship, and the count was set
+ * to that. Written only through core's `core.stock-levels`, with `source`
+ * naming who counted, and kept out of the dialog's menu for the same reason.
  */
-export type InventoryAdjustmentReason = 'sale' | 'refund' | 'restock' | 'correction' | 'damage' | 'cancellation';
+export type InventoryAdjustmentReason = 'sale' | 'refund' | 'restock' | 'correction' | 'damage' | 'cancellation' | 'sync';
 /** `hosts/{hostId}/inventoryAdjustments/{id}` doc. */
 export interface InventoryAdjustment {
     productId: string;
@@ -436,6 +520,11 @@ export interface InventoryAdjustment {
     orderId?: string;
     /** Location for multi-location stock (AGL-286); absent = default. */
     locationId?: string;
+    /**
+     * Who counted, for a `sync` row: the warehouse that reported it (AGL-3634);
+     * for a `sale` another channel made, that channel (AGL-3638).
+     */
+    source?: string;
     atMs: number;
 }
 /**