@aglyn/plugins-commerce 1.0.0-beta.143

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

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

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

@@ -0,0 +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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"}