@aglyn/plugins-commerce 1.0.0-beta.143

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

@@ -0,0 +1,316 @@
+/**
+ * @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.
+ */
+export interface ShippingZone {
+    id: string;
+    name: string;
+    /** ISO-3166 alpha-2 codes; '*' = rest of world. */
+    countries: string[];
+}
+export interface ShippingTier {
+    /** Tier applies while subtotal (cents) or weight (grams) ≤ this. */
+    upTo: number;
+    amountCents: number;
+}
+export interface ShippingRate {
+    id: string;
+    zoneId: string;
+    name: string;
+    kind: 'flat' | 'free_over' | 'price_tiers' | 'weight_tiers';
+    /** flat + free_over base amount. */
+    amountCents?: number;
+    /** free_over: order subtotal (cents) at/above which shipping is free. */
+    freeOverCents?: number;
+    /** price_tiers (upTo = subtotal cents) / weight_tiers (upTo = grams). */
+    tiers?: ShippingTier[];
+}
+export interface ShippingSettings {
+    zones?: ShippingZone[];
+    rates?: ShippingRate[];
+    /**
+     * Offer free local pickup as a delivery choice. Does NOT widen where the
+     * store ships: a destination no rate reaches is still refused (AGL-2325).
+     */
+    localPickup?: boolean;
+}
+export interface ResolvedShippingRate {
+    rateId: string;
+    name: string;
+    amountCents: number;
+}
+/**
+ * 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 declare const LOCAL_PICKUP_RATE_ID = "pickup";
+/**
+ * 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 declare function resolveShippingRates(settings: ShippingSettings | undefined, destinationCountry: string | undefined, cart: {
+    subtotalCents: number;
+    totalGrams?: number;
+}): ResolvedShippingRate[];
+/** Stripe Checkout accepts at most 5 `shipping_options` on one session. */
+export declare 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 declare const CHECKOUT_SHIPPING_COUNTRIES: readonly ["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 declare function resolveCheckoutShippingOptions(settings: ShippingSettings | undefined, destinationCountries: readonly string[], cart: {
+    subtotalCents: number;
+    totalGrams?: number;
+}): ResolvedShippingRate[];
+/** Shopper-facing names for the collectable destinations (AGL-1721). */
+export declare const CHECKOUT_SHIPPING_COUNTRY_NAMES: Readonly<Record<string, string>>;
+/**
+ * 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 declare function normalizeCheckoutShippingCountry(value: unknown): string | undefined;
+export interface CheckoutShippingPlan {
+    /** `shipping_address_collection[allowed_countries]` for this session. */
+    countries: readonly string[];
+    /** `shipping_options` for this session — valid for EVERY `countries` entry. */
+    options: ResolvedShippingRate[];
+    /**
+     * Set when no session may be created at all:
+     *
+     * - `destination-required` — the merchant's rates differ by destination, so
+     *   there is no set of options honest for every address Stripe would accept.
+     *   Ask the shopper where they are shipping and plan again.
+     * - `destination-unserved` — the merchant ships somewhere, but not there.
+     * - `cart-unpriceable` — the merchant priced shipping, but no rate of theirs
+     *   resolves for THIS cart at ANY destination (AGL-2232). A tier table that
+     *   stops at 2 kg says nothing about a 3 kg parcel, and the honest answer is
+     *   to refuse rather than to ship it for nothing.
+     */
+    refusal?: 'destination-required' | 'destination-unserved' | 'cart-unpriceable';
+}
+/**
+ * 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 declare function merchantPricesShipping(settings: ShippingSettings | undefined): boolean;
+/**
+ * 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 declare const CART_UNPRICEABLE_SHIPPING_MESSAGE: string;
+/**
+ * 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 declare function planCheckoutShipping(settings: ShippingSettings | undefined, cart: {
+    subtotalCents: number;
+    totalGrams?: number;
+}, destinationCountry?: unknown): CheckoutShippingPlan;
+/** What a merchant's saved zones and rates cost their shoppers (AGL-1791). */
+export interface ShippingCoverage {
+    /** Collectable destinations at least one rate reaches. */
+    served: string[];
+    /**
+     * Collectable destinations CHECKOUT REFUSES — `destination-unserved`.
+     *
+     * EMPTY FOR A MERCHANT WHOSE RATES REACH NOWHERE, who is not misconfigured:
+     * `planCheckoutShipping` refuses nobody when no rate resolves anywhere, so
+     * that store charges no shipping and completes exactly as it always has.
+     * The rule lives here rather than in the caller because reading `served`
+     * against a bare partition is how a surface comes to warn every store that
+     * does not ship.
+     */
+    unserved: string[];
+    /** No rate reaches anywhere: no shipping is charged, and nobody refused. */
+    shipsNowhere: boolean;
+    /**
+     * Rates differ by destination, so the storefront asks the shopper where the
+     * parcel is going before it can price one — a checkout step the merchant
+     * added by saving these zones, and never chose.
+     */
+    asksDestination: boolean;
+    /** Some zone already claims rest of world, so `*` is not the missing piece. */
+    hasRestOfWorldZone: boolean;
+    /**
+     * The merchant offers local pickup, so checkout presents a free collection
+     * choice at every destination it does not refuse (AGL-2325).
+     *
+     * Deliberately NOT folded into `served`: pickup resolves for every country
+     * because it is appended independent of zone matching, so counting it as
+     * coverage told a US-only merchant who had switched it on that checkout
+     * "can price shipping to every destination", which is the sentence that
+     * hid the defect. It is reported alongside instead, so the card can say
+     * both true things: these destinations are refused, and pickup is offered
+     * to the ones that are not.
+     */
+    offersLocalPickup: boolean;
+}
+/**
+ * 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 declare function summarizeShippingCoverage(settings: ShippingSettings | undefined): ShippingCoverage;
+/**
+ * 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 declare function appendShippingAddressCollectionParams(params: URLSearchParams, countries?: readonly string[]): void;
+/**
+ * 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 declare function appendCheckoutShippingParams(params: URLSearchParams, options: readonly ResolvedShippingRate[]): void;