@aglyn/plugins-commerce 1.0.0-beta.229 → 1.0.0-beta.231

package/src/lib/server/cancel-order.js

@@ -16,6 +16,9 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * limitations under the License.
  */ import * as CommerceModel from "../model/index.js";
 import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { notifyOrderBuyer } from "./order-notifications.js";
+import { ORDER_CANCELLED_EVENT } from "../model/order-events.js";
+import { raiseOrderEvent } from "./order-events.js";
 import { capRestockLines, resolveTrackedRestockLines, saleReleaseCaps } from "./restock-flag.js";
 /**
  * Cancelling an order RELEASES its stock (AGL-1808) — the opposite of what the
@@ -170,6 +173,18 @@ import { capRestockLines, resolveTrackedRestockLines, saleReleaseCaps } from "./
                     }
                 };
             }
+            // An OPEN register sale that has taken money (AGL-3607) is voided at
+            // the register, which hands each payment back first. Cancelling it here
+            // would mark it cancelled with a card charge, a gift card debit or a
+            // room charge still standing.
+            if (order.status === 'pending' && CommerceModel.orderPayments(order).some((payment)=>payment.status === 'succeeded' || payment.status === 'pending') && Array.isArray(order.payments)) {
+                return {
+                    status: 409,
+                    body: {
+                        error: 'This register sale has payments on it. Void it at the register, ' + 'which hands each payment back first.'
+                    }
+                };
+            }
             // A POS CARD order's decrement happens in the webhook that pays it —
             // and before AGL-1825 it did not happen AT ALL: the paying branch's
             // decrement was gated on `productId` metadata the register's session
@@ -288,6 +303,8 @@ import { capRestockLines, resolveTrackedRestockLines, saleReleaseCaps } from "./
             const units = releasedLines.reduce((sum, line)=>sum + line.quantity, 0);
             const patch = {
                 status: 'cancelled',
+                // What a shipping tool's feed asks to learn of the cancel (AGL-3613).
+                updatedAtMs: atMs,
                 timeline: CommerceModel.appendOrderEvent(order, 'cancelled', units > 0 ? `${units} ${units === 1 ? 'unit' : 'units'} returned to stock` : undefined, atMs)
             };
             // An open restock question about THIS order's stock, raised by a partial
@@ -351,6 +368,18 @@ import { capRestockLines, resolveTrackedRestockLines, saleReleaseCaps } from "./
                 });
             }
         }
+        // The buyer is told (AGL-3610) — only by the request that cancelled it.
+        if (outcome.status === 200 && !outcome.body.alreadyCancelled) {
+            await notifyOrderBuyer({
+                hostId,
+                orderId
+            }, 'cancelled');
+            await raiseOrderEvent(ORDER_CANCELLED_EVENT, {
+                hostId,
+                orderId,
+                key: 'cancelled'
+            });
+        }
         return res.status(outcome.status).json(outcome.body);
     } catch (error) {
         // Nothing landed — the transaction is all-or-nothing — so the order is

package/src/lib/server/cancel-order.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/cancel-order.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\nimport * as CommerceModel from '../model'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { type PluginApiHandler } from '@aglyn/aglyn/server'\nimport {\n  capRestockLines,\n  resolveTrackedRestockLines,\n  saleReleaseCaps,\n} from './restock-flag'\n\n/**\n * Cancelling an order RELEASES its stock (AGL-1808) — the opposite of what the\n * reversal doors do, and for a structural reason rather than a preference.\n *\n * AGL-1797 refused to increment on a refund or a chargeback because the goods\n * may well be gone: a refund with no return, or a shopper who kept the item and\n * took the money, leaves stock that incrementing would INVENT. It flags and\n * lets the merchant answer. Cancellation carries no such question, and the\n * guarantee is `ORDER_TRANSITIONS`:\n *\n *     pending: ['paid', 'cancelled'],\n *     paid:    ['partially_fulfilled', 'fulfilled', 'cancelled', 'refunded'],\n *     partially_fulfilled | fulfilled | delivered: no 'cancelled'\n *\n * so a cancelled order was never fulfilled and nothing ever shipped. The units\n * are still on the shelf; the only wrong number is ours.\n *\n * THE GUARANTEE HAD TO BE ENFORCED BEFORE IT COULD BE RELIED ON, and that is\n * why this is a handler rather than a few lines in the console. The transition\n * table said the right thing but nothing consulted it on the way IN: the order\n * dialog cancelled with a client `updateDoc`, and `canTransitionOrder` only\n * decided whether to render the button. The Firestore rules impose no status\n * machine — an order update is allowed to any admin or editor — so a dialog\n * held open while the order shipped in another tab (or any other client) could\n * write `cancelled` straight onto a `fulfilled` order, and an automatic\n * increment behind that would restock goods already in the post. Re-asking the\n * transition INSIDE the transaction that writes the status is what turns the\n * comment into a guarantee, and it is what makes the release safe.\n *\n * `pending` RELEASES NOTHING, which is the other half the issue's premise\n * missed. Stock is decremented when the money lands, not when the order is\n * written: `draft-order.ts` and the POS card path both open a `pending` order\n * and decrement only in the webhook that pays it. Incrementing on a cancelled\n * `pending` order would invent inventory exactly the way AGL-1797 refused to —\n * so only a `paid` order, the one status reachable here whose sale provably\n * decremented, releases anything.\n *\n * ONE LEDGER, NOT A SECOND STOCK WRITER. The increment goes through\n * `adjustVariantInventory` and logs an `InventoryAdjustment` per line, the same\n * pair the sale paths and the products hub's \"Adjust stock\" write, with the new\n * `cancellation` reason and the `orderId`. An increment with no ledger row\n * would leave the hub's stock history unable to explain a count that moved on\n * its own — the mirror of AGL-1797's argument against writing a row for stock\n * that had NOT moved.\n *\n * ONLY WHAT THE SALE DECREMENTED comes back: `resolveTrackedRestockLines`, the\n * helper AGL-1797 already built, applies the sale path's own\n * `variant.inventory != null` test to the products as they stand now. A store\n * that tracks no stock gets a plain cancellation and no adjustment rows.\n *\n * IT FAILS THE CANCEL RATHER THAN LOSING THE RELEASE. `flagOrderRestock`\n * swallows its errors because the money had already moved and the flag was a\n * postscript; here the status flip and the stock write are one act, so they\n * share a transaction and a failure leaves the order uncancelled for the\n * merchant to retry. A cancelled order whose stock never came back is the\n * original bug.\n *\n * ONCE. The transaction's own read is the guard: a second cancel — a retried\n * request, two admins clicking together — finds `cancelled`, which\n * `canTransitionOrder` cannot leave, and returns without touching stock. Two\n * increments of the same units is the failure mode this shape exists to\n * prevent, and it is measured rather than asserted (`cancel-order.spec.ts`).\n *\n * REACHED FROM THE CONSOLE since AGL-1818: `order-detail-dialog`'s\n * `handleCancel` POSTs here with the console id token, and the client\n * `updateDoc` cancel it replaced is gone. (The wiring landed separately from\n * the route because the dialog belonged to a concurrent agent, AGL-1806,\n * when the route was written.)\n */\nexport const cancelOrderHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') {\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n  const authorization = String(req.headers.authorization ?? '')\n  const idToken = authorization.startsWith('Bearer ')\n    ? authorization.slice('Bearer '.length)\n    : undefined\n  if (!idToken) return res.status(401).json({ error: 'Unauthenticated' })\n  const body =\n    typeof req.body === 'string' ? JSON.parse(req.body) : (req.body ?? {})\n  const hostId = String(body.hostId ?? '')\n  const orderId = String(body.orderId ?? '')\n  if (!hostId || !orderId) {\n    return res.status(400).json({ error: 'Missing hostId or orderId' })\n  }\n  // Firestore reserves `__…__` ids and `.doc()` throws SYNCHRONOUSLY on one,\n  // which would surface as a 500 on a caller's typo rather than the 400 it is.\n  if (/^__.*__$/.test(hostId) || /^__.*__$/.test(orderId)) {\n    return res.status(400).json({ error: 'Missing hostId or orderId' })\n  }\n\n  try {\n    const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken)\n    const firestore = firebaseAdmin.app().firestore()\n    const hostRef = firestore.collection('hosts').doc(hostId)\n    const hostSnapshot = await hostRef.get()\n    if (!hostSnapshot.exists) {\n      return res.status(404).json({ error: 'Unknown site' })\n    }\n    // The role the CLIENT write already had, not a stricter one. Order updates\n    // fall through the rules' host catch-all, which admits `admin` and\n    // `editor` — narrowing to admin here would take the cancel button away\n    // from editors who have always had it, and widening it past what the rules\n    // allow would make this endpoint the way around them.\n    const memberRole = (hostSnapshot.get('memberRoles') ?? {})[decoded.uid]\n    if (memberRole !== 'admin' && memberRole !== 'editor') {\n      return res.status(403).json({ error: 'Not permitted' })\n    }\n    const orderRef = hostRef.collection('orders').doc(orderId)\n\n    const outcome = await firestore.runTransaction(async (transaction) => {\n      const snapshot = await transaction.get(orderRef)\n      if (!snapshot.exists) {\n        return { status: 404, body: { error: 'Unknown order' } }\n      }\n      const order = CommerceModel.liftLegacyOrder(\n        (snapshot.data() ?? {}) as never,\n      )\n      // A redelivered click, or the second of two admins. Answered as success\n      // because it IS the state the caller asked for — reporting 409 here\n      // teaches an admin that the cancel failed and invites a third attempt —\n      // but nothing is written, so the units are released exactly once.\n      if (order.status === 'cancelled') {\n        return {\n          status: 200,\n          body: { ok: true, alreadyCancelled: true, released: 0, units: 0 },\n        }\n      }\n      if (!CommerceModel.canTransitionOrder(order.status, 'cancelled')) {\n        return {\n          status: 409,\n          body: { error: `Orders in \"${order.status}\" cannot cancel` },\n        }\n      }\n\n      // A POS CARD order's decrement happens in the webhook that pays it —\n      // and before AGL-1825 it did not happen AT ALL: the paying branch's\n      // decrement was gated on `productId` metadata the register's session\n      // never carried. Releasing such an order restocks units that were never\n      // taken, turning the silent under-count into a silent over-count. The\n      // sale's own ledger is the discriminator: every decrement pairs with a\n      // `reason: 'sale'` row (AGL-1807 closed the last hole, and the AGL-1825\n      // decrement writes them from day one), so a paid card order with no\n      // sale row is one whose sale took nothing — and nothing is released.\n      //\n      // Scoped to card orders (the `pos-card-pending` timeline event) rather\n      // than applied to every order, because one historical path decremented\n      // WITHOUT rows — draft links paid before AGL-1807 — and asking the\n      // ledger to vouch for those would wrongly strand their stock. The\n      // residual is stated plainly: the sibling-shaped decrement/ledger pair\n      // is two swallowed sequential writes, so a card order whose ledger add\n      // alone failed will not release — a bounded under-count on that one\n      // order, visible as a sale missing from the hub's history, against the\n      // alternative of inflating stock on every pre-fix cancel.\n      //\n      // One equality filter, so the automatic single-field index answers it;\n      // the reason test runs here, over the handful of rows one order has.\n      //\n      // THE SAME READ NOW ALSO BOUNDS HOW MUCH COMES BACK (AGL-2149), so it is\n      // no longer scoped to card orders. `adjustVariantInventory` floors at\n      // zero, and that floor silently absorbs the overshoot on a BACKORDER\n      // product: stock 0, `canPurchase` admits the sale because the policy says\n      // to, three units sell, `Math.max(0, 0 + -3)` leaves the count at 0 —\n      // and a `+3` here would hand the merchant three units nobody has and a\n      // stock badge offering them. The sale rows carry `appliedDelta` for\n      // exactly this: `delta` stays the units sold (the merchant's history),\n      // `appliedDelta` says how many the count could actually give up.\n      //\n      // Only lines the ledger DESCRIBES are capped. A pair the ledger says\n      // nothing about restores as before, which is what keeps the pre-AGL-1807\n      // draft links — decremented with no row at all — from having their stock\n      // stranded, and what keeps a single swallowed ledger write from turning\n      // into a lost restock on an unrelated line of the same order.\n      let saleDecremented = true\n      // The cap rule itself lives beside the restock flag, which now bounds\n      // the question it ASKS by the same ledger this bounds the stock it\n      // RETURNS (AGL-2325). One implementation, so a prompt naming more units\n      // than a cancellation would put back is not expressible.\n      let releaseCap: ReadonlyMap<string, number> = new Map<string, number>()\n      if (order.status === 'paid') {\n        const orderAdjustments = await transaction.get(\n          hostRef\n            .collection('inventoryAdjustments')\n            .where('orderId', '==', orderId),\n        )\n        const saleRows = orderAdjustments.docs.filter(\n          (row) => row.get('reason') === 'sale',\n        )\n        if (\n          order.channel === 'pos' &&\n          (order.timeline ?? []).some(\n            (event) => event.event === 'pos-card-pending',\n          )\n        ) {\n          saleDecremented = saleRows.length > 0\n        }\n        releaseCap = saleReleaseCaps(saleRows)\n      }\n\n      // `paid` is the only status reachable here whose sale decremented; see\n      // the header. Reads happen before any write, as a transaction requires.\n      const { lines, products } =\n        order.status === 'paid' && saleDecremented\n          ? await resolveTrackedRestockLines(hostRef, order, (ref) =>\n              transaction.get(ref),\n            )\n          : {\n              lines: [],\n              products: new Map<string, CommerceModel.HostProduct>(),\n            }\n\n      const atMs = Date.now()\n      // Grouped by product, because two lines of one product (two variants, or\n      // the same variant twice) are two deltas against ONE document: writing\n      // them separately would compute both from the same read and land only\n      // the last, silently dropping units.\n      const byProduct = new Map<string, CommerceModel.OrderRestockLine[]>()\n      // Never more than the sale actually took off the shelf (AGL-2149).\n      for (const line of capRestockLines(lines, releaseCap)) {\n        byProduct.set(line.productId, [\n          ...(byProduct.get(line.productId) ?? []),\n          line,\n        ])\n      }\n      for (const [productId, productLines] of byProduct) {\n        const product = products.get(productId)\n        if (!product) continue\n        let variants = product.variants\n        for (const line of productLines) {\n          variants = CommerceModel.adjustVariantInventory(\n            { variants },\n            line.variantId,\n            line.quantity,\n            // The bucket the sale came out of, for a location-tracked store\n            // (AGL-286). Absent on every path that decremented the flat count,\n            // where `adjustVariantInventory` puts it back the same way.\n            order.locationId || undefined,\n          )\n        }\n        // `update()`, not `set(…, { merge: true })` as the sale paths use: the\n        // transaction has just read this product, so it exists, and a product\n        // deleted under us must not be conjured back as a stub holding nothing\n        // but a variants array.\n        transaction.update(hostRef.collection('products').doc(productId), {\n          variants,\n          // The total and the storefront's In stock verdict (AGL-3321).\n          ...CommerceModel.productStockFields({ ...product, variants }),\n          updatedAtMs: atMs,\n        })\n        for (const line of productLines) {\n          transaction.create(hostRef.collection('inventoryAdjustments').doc(), {\n            productId,\n            variantId: line.variantId,\n            delta: line.quantity,\n            reason: 'cancellation',\n            orderId,\n            ...(order.locationId ? { locationId: order.locationId } : {}),\n            atMs,\n          } satisfies CommerceModel.InventoryAdjustment)\n        }\n      }\n\n      // From the CAPPED lines, not the order's, so the timeline reports what\n      // was actually put back (AGL-2149).\n      const releasedLines = [...byProduct.values()].flat()\n      const units = releasedLines.reduce((sum, line) => sum + line.quantity, 0)\n      const patch: Record<string, unknown> = {\n        status: 'cancelled',\n        timeline: CommerceModel.appendOrderEvent(\n          order,\n          'cancelled',\n          units > 0\n            ? `${units} ${units === 1 ? 'unit' : 'units'} returned to stock`\n            : undefined,\n          atMs,\n        ),\n      }\n      // An open restock question about THIS order's stock, raised by a partial\n      // refund before the cancellation (AGL-1797). The units it asked about are\n      // the ones just put back, so leaving it open would invite the merchant to\n      // restock them a second time from the order dialog — the double-count\n      // that flag exists to avoid. Answered with what actually happened.\n      if (units > 0 && order.restockCheck && !order.restockCheck.resolution) {\n        patch.restockCheck = {\n          ...order.restockCheck,\n          resolution: 'restocked',\n          resolvedAtMs: atMs,\n          resolvedBy: decoded.uid,\n        } satisfies CommerceModel.OrderRestockCheck\n      }\n      transaction.update(orderRef, patch)\n      return {\n        status: 200,\n        body: { ok: true, released: releasedLines.length, units },\n        // The live Stripe page this cancellation orphans, if any (AGL-2244).\n        // Read inside the transaction that flips the status so the expiry\n        // below cannot act on an order some other writer paid meanwhile.\n        expireSessionId:\n          order.status === 'pending' ? (order.checkoutSessionId ?? '') : '',\n      }\n    })\n    // EXPIRE THE PAYMENT LINK (AGL-2244). Cancelling a `pending` draft order or\n    // POS card sale left its Checkout Session live: the URL is on the\n    // customer's phone or in the email the merchant sent, and Stripe keeps it\n    // payable for 24 hours. Paying it captured real money on the merchant's\n    // account and the completing webhook then discarded the event — its\n    // `status !== 'pending'` guard cannot tell a redelivery from a cancelled\n    // order — so the sale existed in Stripe and nowhere in the product: no\n    // order, no stock move, no contact, no notification, not even a timeline\n    // line. The webhook now says so when it happens; this is the half that\n    // stops it happening.\n    //\n    // OUTSIDE the transaction, because it is a network call, and best-effort\n    // by design: the cancellation itself already landed and is what the\n    // merchant asked for. A failure here leaves the pre-existing behaviour\n    // (a payable link) plus the webhook's new record of it, which is strictly\n    // better than failing a cancel that has already released stock. Stripe\n    // answers 400 for a session that is already expired or already paid, and\n    // both are states this has nothing to add to.\n    const expireSessionId = (outcome as { expireSessionId?: string })\n      .expireSessionId\n    if (expireSessionId && process.env.STRIPE_SECRET_KEY) {\n      const expiry = await fetch(\n        `https://api.stripe.com/v1/checkout/sessions/${expireSessionId}/expire`,\n        {\n          method: 'POST',\n          headers: {\n            Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,\n            'Content-Type': 'application/x-www-form-urlencoded',\n          },\n        },\n      ).catch(() => null)\n      if (!expiry?.ok) {\n        console.error(\n          'Cancelled order: Stripe session not expired, the payment link may still be payable',\n          { hostId, orderId, sessionId: expireSessionId },\n        )\n      }\n    }\n    return res.status(outcome.status).json(outcome.body)\n  } catch (error) {\n    // Nothing landed — the transaction is all-or-nothing — so the order is\n    // still open and the merchant can try again. Deliberately NOT the swallow\n    // `flagOrderRestock` uses: there the money had already moved and only a\n    // postscript was at risk; here a swallowed failure is a cancelled order\n    // whose stock never came back, which is the bug this closes.\n    console.error('cancelOrder failed', error)\n    return res.status(500).json({ error: 'Cancel failed' })\n  }\n}\n"],"names":["CommerceModel","firebaseAdmin","capRestockLines","resolveTrackedRestockLines","saleReleaseCaps","cancelOrderHandler","req","res","body","method","status","json","error","authorization","String","headers","idToken","startsWith","slice","length","undefined","JSON","parse","hostId","orderId","test","hostSnapshot","decoded","app","auth","verifyIdToken","firestore","hostRef","collection","doc","get","exists","memberRole","uid","orderRef","outcome","runTransaction","transaction","snapshot","order","liftLegacyOrder","data","ok","alreadyCancelled","released","units","canTransitionOrder","saleDecremented","releaseCap","Map","orderAdjustments","where","saleRows","docs","filter","row","channel","timeline","some","event","lines","products","ref","atMs","Date","now","byProduct","line","set","productId","productLines","product","variants","adjustVariantInventory","variantId","quantity","locationId","update","productStockFields","updatedAtMs","create","delta","reason","releasedLines","values","flat","reduce","sum","patch","appendOrderEvent","restockCheck","resolution","resolvedAtMs","resolvedBy","expireSessionId","checkoutSessionId","process","env","STRIPE_SECRET_KEY","expiry","fetch","Authorization","catch","console","sessionId"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/cancel-order.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\nimport * as CommerceModel from '../model'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { notifyOrderBuyer } from './order-notifications'\nimport { ORDER_CANCELLED_EVENT } from '../model/order-events'\nimport { raiseOrderEvent } from './order-events'\nimport { type PluginApiHandler } from '@aglyn/aglyn/server'\nimport {\n  capRestockLines,\n  resolveTrackedRestockLines,\n  saleReleaseCaps,\n} from './restock-flag'\n\n/**\n * Cancelling an order RELEASES its stock (AGL-1808) — the opposite of what the\n * reversal doors do, and for a structural reason rather than a preference.\n *\n * AGL-1797 refused to increment on a refund or a chargeback because the goods\n * may well be gone: a refund with no return, or a shopper who kept the item and\n * took the money, leaves stock that incrementing would INVENT. It flags and\n * lets the merchant answer. Cancellation carries no such question, and the\n * guarantee is `ORDER_TRANSITIONS`:\n *\n *     pending: ['paid', 'cancelled'],\n *     paid:    ['partially_fulfilled', 'fulfilled', 'cancelled', 'refunded'],\n *     partially_fulfilled | fulfilled | delivered: no 'cancelled'\n *\n * so a cancelled order was never fulfilled and nothing ever shipped. The units\n * are still on the shelf; the only wrong number is ours.\n *\n * THE GUARANTEE HAD TO BE ENFORCED BEFORE IT COULD BE RELIED ON, and that is\n * why this is a handler rather than a few lines in the console. The transition\n * table said the right thing but nothing consulted it on the way IN: the order\n * dialog cancelled with a client `updateDoc`, and `canTransitionOrder` only\n * decided whether to render the button. The Firestore rules impose no status\n * machine — an order update is allowed to any admin or editor — so a dialog\n * held open while the order shipped in another tab (or any other client) could\n * write `cancelled` straight onto a `fulfilled` order, and an automatic\n * increment behind that would restock goods already in the post. Re-asking the\n * transition INSIDE the transaction that writes the status is what turns the\n * comment into a guarantee, and it is what makes the release safe.\n *\n * `pending` RELEASES NOTHING, which is the other half the issue's premise\n * missed. Stock is decremented when the money lands, not when the order is\n * written: `draft-order.ts` and the POS card path both open a `pending` order\n * and decrement only in the webhook that pays it. Incrementing on a cancelled\n * `pending` order would invent inventory exactly the way AGL-1797 refused to —\n * so only a `paid` order, the one status reachable here whose sale provably\n * decremented, releases anything.\n *\n * ONE LEDGER, NOT A SECOND STOCK WRITER. The increment goes through\n * `adjustVariantInventory` and logs an `InventoryAdjustment` per line, the same\n * pair the sale paths and the products hub's \"Adjust stock\" write, with the new\n * `cancellation` reason and the `orderId`. An increment with no ledger row\n * would leave the hub's stock history unable to explain a count that moved on\n * its own — the mirror of AGL-1797's argument against writing a row for stock\n * that had NOT moved.\n *\n * ONLY WHAT THE SALE DECREMENTED comes back: `resolveTrackedRestockLines`, the\n * helper AGL-1797 already built, applies the sale path's own\n * `variant.inventory != null` test to the products as they stand now. A store\n * that tracks no stock gets a plain cancellation and no adjustment rows.\n *\n * IT FAILS THE CANCEL RATHER THAN LOSING THE RELEASE. `flagOrderRestock`\n * swallows its errors because the money had already moved and the flag was a\n * postscript; here the status flip and the stock write are one act, so they\n * share a transaction and a failure leaves the order uncancelled for the\n * merchant to retry. A cancelled order whose stock never came back is the\n * original bug.\n *\n * ONCE. The transaction's own read is the guard: a second cancel — a retried\n * request, two admins clicking together — finds `cancelled`, which\n * `canTransitionOrder` cannot leave, and returns without touching stock. Two\n * increments of the same units is the failure mode this shape exists to\n * prevent, and it is measured rather than asserted (`cancel-order.spec.ts`).\n *\n * REACHED FROM THE CONSOLE since AGL-1818: `order-detail-dialog`'s\n * `handleCancel` POSTs here with the console id token, and the client\n * `updateDoc` cancel it replaced is gone. (The wiring landed separately from\n * the route because the dialog belonged to a concurrent agent, AGL-1806,\n * when the route was written.)\n */\nexport const cancelOrderHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') {\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n  const authorization = String(req.headers.authorization ?? '')\n  const idToken = authorization.startsWith('Bearer ')\n    ? authorization.slice('Bearer '.length)\n    : undefined\n  if (!idToken) return res.status(401).json({ error: 'Unauthenticated' })\n  const body =\n    typeof req.body === 'string' ? JSON.parse(req.body) : (req.body ?? {})\n  const hostId = String(body.hostId ?? '')\n  const orderId = String(body.orderId ?? '')\n  if (!hostId || !orderId) {\n    return res.status(400).json({ error: 'Missing hostId or orderId' })\n  }\n  // Firestore reserves `__…__` ids and `.doc()` throws SYNCHRONOUSLY on one,\n  // which would surface as a 500 on a caller's typo rather than the 400 it is.\n  if (/^__.*__$/.test(hostId) || /^__.*__$/.test(orderId)) {\n    return res.status(400).json({ error: 'Missing hostId or orderId' })\n  }\n\n  try {\n    const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken)\n    const firestore = firebaseAdmin.app().firestore()\n    const hostRef = firestore.collection('hosts').doc(hostId)\n    const hostSnapshot = await hostRef.get()\n    if (!hostSnapshot.exists) {\n      return res.status(404).json({ error: 'Unknown site' })\n    }\n    // The role the CLIENT write already had, not a stricter one. Order updates\n    // fall through the rules' host catch-all, which admits `admin` and\n    // `editor` — narrowing to admin here would take the cancel button away\n    // from editors who have always had it, and widening it past what the rules\n    // allow would make this endpoint the way around them.\n    const memberRole = (hostSnapshot.get('memberRoles') ?? {})[decoded.uid]\n    if (memberRole !== 'admin' && memberRole !== 'editor') {\n      return res.status(403).json({ error: 'Not permitted' })\n    }\n    const orderRef = hostRef.collection('orders').doc(orderId)\n\n    const outcome = await firestore.runTransaction(async (transaction) => {\n      const snapshot = await transaction.get(orderRef)\n      if (!snapshot.exists) {\n        return { status: 404, body: { error: 'Unknown order' } }\n      }\n      const order = CommerceModel.liftLegacyOrder(\n        (snapshot.data() ?? {}) as never,\n      )\n      // A redelivered click, or the second of two admins. Answered as success\n      // because it IS the state the caller asked for — reporting 409 here\n      // teaches an admin that the cancel failed and invites a third attempt —\n      // but nothing is written, so the units are released exactly once.\n      if (order.status === 'cancelled') {\n        return {\n          status: 200,\n          body: { ok: true, alreadyCancelled: true, released: 0, units: 0 },\n        }\n      }\n      if (!CommerceModel.canTransitionOrder(order.status, 'cancelled')) {\n        return {\n          status: 409,\n          body: { error: `Orders in \"${order.status}\" cannot cancel` },\n        }\n      }\n      // An OPEN register sale that has taken money (AGL-3607) is voided at\n      // the register, which hands each payment back first. Cancelling it here\n      // would mark it cancelled with a card charge, a gift card debit or a\n      // room charge still standing.\n      if (\n        order.status === 'pending' &&\n        CommerceModel.orderPayments(order).some(\n          (payment) => payment.status === 'succeeded' || payment.status === 'pending',\n        ) &&\n        Array.isArray(order.payments)\n      ) {\n        return {\n          status: 409,\n          body: {\n            error:\n              'This register sale has payments on it. Void it at the register, ' +\n              'which hands each payment back first.',\n          },\n        }\n      }\n\n      // A POS CARD order's decrement happens in the webhook that pays it —\n      // and before AGL-1825 it did not happen AT ALL: the paying branch's\n      // decrement was gated on `productId` metadata the register's session\n      // never carried. Releasing such an order restocks units that were never\n      // taken, turning the silent under-count into a silent over-count. The\n      // sale's own ledger is the discriminator: every decrement pairs with a\n      // `reason: 'sale'` row (AGL-1807 closed the last hole, and the AGL-1825\n      // decrement writes them from day one), so a paid card order with no\n      // sale row is one whose sale took nothing — and nothing is released.\n      //\n      // Scoped to card orders (the `pos-card-pending` timeline event) rather\n      // than applied to every order, because one historical path decremented\n      // WITHOUT rows — draft links paid before AGL-1807 — and asking the\n      // ledger to vouch for those would wrongly strand their stock. The\n      // residual is stated plainly: the sibling-shaped decrement/ledger pair\n      // is two swallowed sequential writes, so a card order whose ledger add\n      // alone failed will not release — a bounded under-count on that one\n      // order, visible as a sale missing from the hub's history, against the\n      // alternative of inflating stock on every pre-fix cancel.\n      //\n      // One equality filter, so the automatic single-field index answers it;\n      // the reason test runs here, over the handful of rows one order has.\n      //\n      // THE SAME READ NOW ALSO BOUNDS HOW MUCH COMES BACK (AGL-2149), so it is\n      // no longer scoped to card orders. `adjustVariantInventory` floors at\n      // zero, and that floor silently absorbs the overshoot on a BACKORDER\n      // product: stock 0, `canPurchase` admits the sale because the policy says\n      // to, three units sell, `Math.max(0, 0 + -3)` leaves the count at 0 —\n      // and a `+3` here would hand the merchant three units nobody has and a\n      // stock badge offering them. The sale rows carry `appliedDelta` for\n      // exactly this: `delta` stays the units sold (the merchant's history),\n      // `appliedDelta` says how many the count could actually give up.\n      //\n      // Only lines the ledger DESCRIBES are capped. A pair the ledger says\n      // nothing about restores as before, which is what keeps the pre-AGL-1807\n      // draft links — decremented with no row at all — from having their stock\n      // stranded, and what keeps a single swallowed ledger write from turning\n      // into a lost restock on an unrelated line of the same order.\n      let saleDecremented = true\n      // The cap rule itself lives beside the restock flag, which now bounds\n      // the question it ASKS by the same ledger this bounds the stock it\n      // RETURNS (AGL-2325). One implementation, so a prompt naming more units\n      // than a cancellation would put back is not expressible.\n      let releaseCap: ReadonlyMap<string, number> = new Map<string, number>()\n      if (order.status === 'paid') {\n        const orderAdjustments = await transaction.get(\n          hostRef\n            .collection('inventoryAdjustments')\n            .where('orderId', '==', orderId),\n        )\n        const saleRows = orderAdjustments.docs.filter(\n          (row) => row.get('reason') === 'sale',\n        )\n        if (\n          order.channel === 'pos' &&\n          (order.timeline ?? []).some(\n            (event) => event.event === 'pos-card-pending',\n          )\n        ) {\n          saleDecremented = saleRows.length > 0\n        }\n        releaseCap = saleReleaseCaps(saleRows)\n      }\n\n      // `paid` is the only status reachable here whose sale decremented; see\n      // the header. Reads happen before any write, as a transaction requires.\n      const { lines, products } =\n        order.status === 'paid' && saleDecremented\n          ? await resolveTrackedRestockLines(hostRef, order, (ref) =>\n              transaction.get(ref),\n            )\n          : {\n              lines: [],\n              products: new Map<string, CommerceModel.HostProduct>(),\n            }\n\n      const atMs = Date.now()\n      // Grouped by product, because two lines of one product (two variants, or\n      // the same variant twice) are two deltas against ONE document: writing\n      // them separately would compute both from the same read and land only\n      // the last, silently dropping units.\n      const byProduct = new Map<string, CommerceModel.OrderRestockLine[]>()\n      // Never more than the sale actually took off the shelf (AGL-2149).\n      for (const line of capRestockLines(lines, releaseCap)) {\n        byProduct.set(line.productId, [\n          ...(byProduct.get(line.productId) ?? []),\n          line,\n        ])\n      }\n      for (const [productId, productLines] of byProduct) {\n        const product = products.get(productId)\n        if (!product) continue\n        let variants = product.variants\n        for (const line of productLines) {\n          variants = CommerceModel.adjustVariantInventory(\n            { variants },\n            line.variantId,\n            line.quantity,\n            // The bucket the sale came out of, for a location-tracked store\n            // (AGL-286). Absent on every path that decremented the flat count,\n            // where `adjustVariantInventory` puts it back the same way.\n            order.locationId || undefined,\n          )\n        }\n        // `update()`, not `set(…, { merge: true })` as the sale paths use: the\n        // transaction has just read this product, so it exists, and a product\n        // deleted under us must not be conjured back as a stub holding nothing\n        // but a variants array.\n        transaction.update(hostRef.collection('products').doc(productId), {\n          variants,\n          // The total and the storefront's In stock verdict (AGL-3321).\n          ...CommerceModel.productStockFields({ ...product, variants }),\n          updatedAtMs: atMs,\n        })\n        for (const line of productLines) {\n          transaction.create(hostRef.collection('inventoryAdjustments').doc(), {\n            productId,\n            variantId: line.variantId,\n            delta: line.quantity,\n            reason: 'cancellation',\n            orderId,\n            ...(order.locationId ? { locationId: order.locationId } : {}),\n            atMs,\n          } satisfies CommerceModel.InventoryAdjustment)\n        }\n      }\n\n      // From the CAPPED lines, not the order's, so the timeline reports what\n      // was actually put back (AGL-2149).\n      const releasedLines = [...byProduct.values()].flat()\n      const units = releasedLines.reduce((sum, line) => sum + line.quantity, 0)\n      const patch: Record<string, unknown> = {\n        status: 'cancelled',\n        // What a shipping tool's feed asks to learn of the cancel (AGL-3613).\n        updatedAtMs: atMs,\n        timeline: CommerceModel.appendOrderEvent(\n          order,\n          'cancelled',\n          units > 0\n            ? `${units} ${units === 1 ? 'unit' : 'units'} returned to stock`\n            : undefined,\n          atMs,\n        ),\n      }\n      // An open restock question about THIS order's stock, raised by a partial\n      // refund before the cancellation (AGL-1797). The units it asked about are\n      // the ones just put back, so leaving it open would invite the merchant to\n      // restock them a second time from the order dialog — the double-count\n      // that flag exists to avoid. Answered with what actually happened.\n      if (units > 0 && order.restockCheck && !order.restockCheck.resolution) {\n        patch.restockCheck = {\n          ...order.restockCheck,\n          resolution: 'restocked',\n          resolvedAtMs: atMs,\n          resolvedBy: decoded.uid,\n        } satisfies CommerceModel.OrderRestockCheck\n      }\n      transaction.update(orderRef, patch)\n      return {\n        status: 200,\n        body: { ok: true, released: releasedLines.length, units },\n        // The live Stripe page this cancellation orphans, if any (AGL-2244).\n        // Read inside the transaction that flips the status so the expiry\n        // below cannot act on an order some other writer paid meanwhile.\n        expireSessionId:\n          order.status === 'pending' ? (order.checkoutSessionId ?? '') : '',\n      }\n    })\n    // EXPIRE THE PAYMENT LINK (AGL-2244). Cancelling a `pending` draft order or\n    // POS card sale left its Checkout Session live: the URL is on the\n    // customer's phone or in the email the merchant sent, and Stripe keeps it\n    // payable for 24 hours. Paying it captured real money on the merchant's\n    // account and the completing webhook then discarded the event — its\n    // `status !== 'pending'` guard cannot tell a redelivery from a cancelled\n    // order — so the sale existed in Stripe and nowhere in the product: no\n    // order, no stock move, no contact, no notification, not even a timeline\n    // line. The webhook now says so when it happens; this is the half that\n    // stops it happening.\n    //\n    // OUTSIDE the transaction, because it is a network call, and best-effort\n    // by design: the cancellation itself already landed and is what the\n    // merchant asked for. A failure here leaves the pre-existing behaviour\n    // (a payable link) plus the webhook's new record of it, which is strictly\n    // better than failing a cancel that has already released stock. Stripe\n    // answers 400 for a session that is already expired or already paid, and\n    // both are states this has nothing to add to.\n    const expireSessionId = (outcome as { expireSessionId?: string })\n      .expireSessionId\n    if (expireSessionId && process.env.STRIPE_SECRET_KEY) {\n      const expiry = await fetch(\n        `https://api.stripe.com/v1/checkout/sessions/${expireSessionId}/expire`,\n        {\n          method: 'POST',\n          headers: {\n            Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,\n            'Content-Type': 'application/x-www-form-urlencoded',\n          },\n        },\n      ).catch(() => null)\n      if (!expiry?.ok) {\n        console.error(\n          'Cancelled order: Stripe session not expired, the payment link may still be payable',\n          { hostId, orderId, sessionId: expireSessionId },\n        )\n      }\n    }\n    // The buyer is told (AGL-3610) — only by the request that cancelled it.\n    if (outcome.status === 200 && !(outcome.body as { alreadyCancelled?: boolean }).alreadyCancelled) {\n      await notifyOrderBuyer({ hostId, orderId }, 'cancelled')\n      await raiseOrderEvent(ORDER_CANCELLED_EVENT, { hostId, orderId, key: 'cancelled' })\n    }\n    return res.status(outcome.status).json(outcome.body)\n  } catch (error) {\n    // Nothing landed — the transaction is all-or-nothing — so the order is\n    // still open and the merchant can try again. Deliberately NOT the swallow\n    // `flagOrderRestock` uses: there the money had already moved and only a\n    // postscript was at risk; here a swallowed failure is a cancelled order\n    // whose stock never came back, which is the bug this closes.\n    console.error('cancelOrder failed', error)\n    return res.status(500).json({ error: 'Cancel failed' })\n  }\n}\n"],"names":["CommerceModel","firebaseAdmin","notifyOrderBuyer","ORDER_CANCELLED_EVENT","raiseOrderEvent","capRestockLines","resolveTrackedRestockLines","saleReleaseCaps","cancelOrderHandler","req","res","body","method","status","json","error","authorization","String","headers","idToken","startsWith","slice","length","undefined","JSON","parse","hostId","orderId","test","hostSnapshot","decoded","app","auth","verifyIdToken","firestore","hostRef","collection","doc","get","exists","memberRole","uid","orderRef","outcome","runTransaction","transaction","snapshot","order","liftLegacyOrder","data","ok","alreadyCancelled","released","units","canTransitionOrder","orderPayments","some","payment","Array","isArray","payments","saleDecremented","releaseCap","Map","orderAdjustments","where","saleRows","docs","filter","row","channel","timeline","event","lines","products","ref","atMs","Date","now","byProduct","line","set","productId","productLines","product","variants","adjustVariantInventory","variantId","quantity","locationId","update","productStockFields","updatedAtMs","create","delta","reason","releasedLines","values","flat","reduce","sum","patch","appendOrderEvent","restockCheck","resolution","resolvedAtMs","resolvedBy","expireSessionId","checkoutSessionId","process","env","STRIPE_SECRET_KEY","expiry","fetch","Authorization","catch","console","sessionId","key"],"mappings":"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"}

package/src/lib/server/carrier-rates-availability.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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.
+ */
+import type { PluginApiHandler } from '@aglyn/aglyn/server';
+/**
+ * `GET commerce/shipping/carrier-rates?hostId` (AGL-3612): whether this site
+ * can price shipping by carrier, and the services it may offer — what the
+ * Shipping card asks before it shows the Carrier rates kind. Answered from
+ * core's quoter seam, so it is `available: false` wherever no plugin quotes
+ * carriers or the deployment names no carrier provider, and the kind is not
+ * offered. A site collaborator may ask; nothing here is a secret.
+ */
+export declare const carrierRatesAvailabilityHandler: PluginApiHandler;

package/src/lib/server/carrier-rates-availability.js

@@ -0,0 +1,76 @@
+/**
+ * @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.
+ */ import { pluginShippingRateQuoter } from "@aglyn/aglyn/plugin-manager/plugin-shipping-rates";
+import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { isRefusedIdToken } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+/**
+ * `GET commerce/shipping/carrier-rates?hostId` (AGL-3612): whether this site
+ * can price shipping by carrier, and the services it may offer — what the
+ * Shipping card asks before it shows the Carrier rates kind. Answered from
+ * core's quoter seam, so it is `available: false` wherever no plugin quotes
+ * carriers or the deployment names no carrier provider, and the kind is not
+ * offered. A site collaborator may ask; nothing here is a secret.
+ */ export const carrierRatesAvailabilityHandler = async (req, res)=>{
+    var _req_headers_authorization, _ref;
+    var _req_query;
+    if (req.method !== 'GET') return res.status(405).json({
+        error: 'Method not allowed'
+    });
+    const authorization = String((_req_headers_authorization = req.headers.authorization) != null ? _req_headers_authorization : '');
+    if (!authorization.startsWith('Bearer ')) return res.status(401).json({
+        error: 'Unauthenticated'
+    });
+    const hostId = String((_ref = (_req_query = req.query) == null ? void 0 : _req_query['hostId']) != null ? _ref : '');
+    if (!hostId || hostId.includes('/') || /^__.*__$/.test(hostId)) {
+        return res.status(400).json({
+            error: 'Missing hostId'
+        });
+    }
+    let decoded;
+    try {
+        decoded = await firebaseAdmin.app().auth().verifyIdToken(authorization.slice('Bearer '.length));
+    } catch (error) {
+        if (!isRefusedIdToken(error)) throw error;
+        return res.status(401).json({
+            error: 'Unauthenticated'
+        });
+    }
+    try {
+        var _host_get;
+        const host = await firebaseAdmin.app().firestore().collection('hosts').doc(hostId).get();
+        if (!host.exists) return res.status(404).json({
+            error: 'Unknown site'
+        });
+        const role = ((_host_get = host.get('memberRoles')) != null ? _host_get : {})[decoded.uid];
+        if (!role && decoded['staff'] !== true) return res.status(403).json({
+            error: 'Not permitted'
+        });
+        const quoter = pluginShippingRateQuoter();
+        const available = quoter ? await quoter.available(hostId).catch(()=>false) : false;
+        const services = available && quoter ? await quoter.listServices(hostId).catch(()=>[]) : [];
+        return res.status(200).json({
+            available,
+            services
+        });
+    } catch (unused) {
+        return res.status(200).json({
+            available: false,
+            services: []
+        });
+    }
+};
+
+//# sourceMappingURL=carrier-rates-availability.js.map

package/src/lib/server/carrier-rates-availability.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/carrier-rates-availability.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\nimport { pluginShippingRateQuoter } from '@aglyn/aglyn/plugin-manager/plugin-shipping-rates'\nimport type { PluginApiHandler } from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { isRefusedIdToken } from '@aglyn/tenant-data-admin/server/id-token-refusal'\n\n/**\n * `GET commerce/shipping/carrier-rates?hostId` (AGL-3612): whether this site\n * can price shipping by carrier, and the services it may offer — what the\n * Shipping card asks before it shows the Carrier rates kind. Answered from\n * core's quoter seam, so it is `available: false` wherever no plugin quotes\n * carriers or the deployment names no carrier provider, and the kind is not\n * offered. A site collaborator may ask; nothing here is a secret.\n */\nexport const carrierRatesAvailabilityHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'GET') return res.status(405).json({ error: 'Method not allowed' })\n  const authorization = String(req.headers.authorization ?? '')\n  if (!authorization.startsWith('Bearer ')) return res.status(401).json({ error: 'Unauthenticated' })\n  const hostId = String((req.query as Record<string, unknown> | undefined)?.['hostId'] ?? '')\n  if (!hostId || hostId.includes('/') || /^__.*__$/.test(hostId)) {\n    return res.status(400).json({ error: 'Missing hostId' })\n  }\n  let decoded\n  try {\n    decoded = await firebaseAdmin.app().auth().verifyIdToken(authorization.slice('Bearer '.length))\n  } catch (error) {\n    if (!isRefusedIdToken(error)) throw error\n    return res.status(401).json({ error: 'Unauthenticated' })\n  }\n  try {\n    const host = await firebaseAdmin.app().firestore().collection('hosts').doc(hostId).get()\n    if (!host.exists) return res.status(404).json({ error: 'Unknown site' })\n    const role = (host.get('memberRoles') ?? {})[decoded.uid]\n    if (!role && decoded['staff'] !== true) return res.status(403).json({ error: 'Not permitted' })\n    const quoter = pluginShippingRateQuoter()\n    const available = quoter ? await quoter.available(hostId).catch(() => false) : false\n    const services = available && quoter ? await quoter.listServices(hostId).catch(() => []) : []\n    return res.status(200).json({ available, services })\n  } catch {\n    return res.status(200).json({ available: false, services: [] })\n  }\n}\n"],"names":["pluginShippingRateQuoter","firebaseAdmin","isRefusedIdToken","carrierRatesAvailabilityHandler","req","res","method","status","json","error","authorization","String","headers","startsWith","hostId","query","includes","test","decoded","app","auth","verifyIdToken","slice","length","host","firestore","collection","doc","get","exists","role","uid","quoter","available","catch","services","listServices"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,wBAAwB,QAAQ,oDAAmD;AAE5F,SAASC,aAAa,QAAQ,2BAA0B;AACxD,SAASC,gBAAgB,QAAQ,mDAAkD;AAEnF;;;;;;;CAOC,GACD,OAAO,MAAMC,kCAAoD,OAAOC,KAAKC;QAE9CD;QAENA;IAHvB,IAAIA,IAAIE,MAAM,KAAK,OAAO,OAAOD,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;QAAEC,OAAO;IAAqB;IACpF,MAAMC,gBAAgBC,QAAOP,6BAAAA,IAAIQ,OAAO,CAACF,aAAa,YAAzBN,6BAA6B;IAC1D,IAAI,CAACM,cAAcG,UAAU,CAAC,YAAY,OAAOR,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;QAAEC,OAAO;IAAkB;IACjG,MAAMK,SAASH,gBAAQP,aAAAA,IAAIW,KAAK,qBAAV,AAACX,UAAmD,CAAC,SAAS,mBAAI;IACxF,IAAI,CAACU,UAAUA,OAAOE,QAAQ,CAAC,QAAQ,WAAWC,IAAI,CAACH,SAAS;QAC9D,OAAOT,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAiB;IACxD;IACA,IAAIS;IACJ,IAAI;QACFA,UAAU,MAAMjB,cAAckB,GAAG,GAAGC,IAAI,GAAGC,aAAa,CAACX,cAAcY,KAAK,CAAC,UAAUC,MAAM;IAC/F,EAAE,OAAOd,OAAO;QACd,IAAI,CAACP,iBAAiBO,QAAQ,MAAMA;QACpC,OAAOJ,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAkB;IACzD;IACA,IAAI;YAGYe;QAFd,MAAMA,OAAO,MAAMvB,cAAckB,GAAG,GAAGM,SAAS,GAAGC,UAAU,CAAC,SAASC,GAAG,CAACb,QAAQc,GAAG;QACtF,IAAI,CAACJ,KAAKK,MAAM,EAAE,OAAOxB,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAe;QACtE,MAAMqB,OAAO,EAACN,YAAAA,KAAKI,GAAG,CAAC,0BAATJ,YAA2B,CAAC,EAAE,CAACN,QAAQa,GAAG,CAAC;QACzD,IAAI,CAACD,QAAQZ,OAAO,CAAC,QAAQ,KAAK,MAAM,OAAOb,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAgB;QAC7F,MAAMuB,SAAShC;QACf,MAAMiC,YAAYD,SAAS,MAAMA,OAAOC,SAAS,CAACnB,QAAQoB,KAAK,CAAC,IAAM,SAAS;QAC/E,MAAMC,WAAWF,aAAaD,SAAS,MAAMA,OAAOI,YAAY,CAACtB,QAAQoB,KAAK,CAAC,IAAM,EAAE,IAAI,EAAE;QAC7F,OAAO7B,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEyB;YAAWE;QAAS;IACpD,EAAE,eAAM;QACN,OAAO9B,IAAIE,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEyB,WAAW;YAAOE,UAAU,EAAE;QAAC;IAC/D;AACF,EAAC"}

package/src/lib/server/carrier-shipping.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @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.
+ */
+import { type PluginShippingParcel } from '@aglyn/aglyn/plugin-manager/plugin-shipping-rates';
+import * as CommerceModel from '../model';
+/**
+ * LIVE CARRIER RATES AT CHECKOUT (AGL-3612): the `carrier` rate kind, priced
+ * by asking core's `core.shipping-rate-quoter` — whichever plugin quotes
+ * carriers — and never by importing it.
+ *
+ * ## Quoted before the session exists, on every door
+ *
+ * Stripe's hosted Checkout cannot change a session's shipping options once
+ * the shopper types an address ("The hosted page integration doesn't support
+ * dynamically customizing shipping options"), and the in-page form can only
+ * by a server update after the fact — while this module's callers fix the
+ * platform fee and the Connect transfer from the session's options at
+ * creation. So the quote is taken BEFORE the session, against the
+ * destination the shopper declares (country and postal code), and the
+ * session is then restricted to that country exactly as a zone rate is
+ * (AGL-1721). The same code serves cart checkout, buy-now and a draft
+ * order's link, hosted and in-page, and the fee arithmetic downstream sees
+ * ordinary options.
+ *
+ * ## The fallback is the merchant's own
+ *
+ * No quoter, a quoter not available for this site, or a quote that fails or
+ * takes longer than {@link CommerceModel.CARRIER_QUOTE_TIMEOUT_MS}: the plan
+ * is exactly the one {@link CommerceModel.planCheckoutShipping} makes from
+ * the table, where a carrier rate offers nothing and its fallback rate is
+ * offered. A store with no carrier rate never reaches the quoter at all, so
+ * its sessions are byte-identical to the ones before this existed.
+ */
+export interface CarrierShippingCart {
+    subtotalCents: number;
+    totalGrams: number;
+    /** One parcel's dimensions, when the cart is one product that has them. */
+    parcel?: Omit<PluginShippingParcel, 'weightGrams'>;
+}
+export interface CarrierShippingDestination {
+    country?: unknown;
+    postalCode?: unknown;
+    state?: unknown;
+    city?: unknown;
+}
+/** A postal code a shopper declared, trimmed and bounded, or `undefined`. */
+export declare function normalizeCheckoutPostalCode(value: unknown): string | undefined;
+export type CarrierShippingPlan = CommerceModel.CheckoutShippingPlan & {
+    /** Set when the plan offers live quotes: the postal code they were priced for. */
+    quotedPostalCode?: string;
+    /**
+     * The destination's zone prices by carrier and the store can quote, but the
+     * shopper has not said where in the country: ask for a postal code.
+     */
+    needsPostalCode?: boolean;
+};
+/** What a shopper is told when a postal code is needed. */
+export declare const CARRIER_POSTAL_CODE_MESSAGE = "Enter the postal code you\u2019re shipping to.";
+/**
+ * The shipping half of a session for a store that may price by carrier.
+ * See the module comment; `planCheckoutShipping` is the whole answer for any
+ * store without a carrier rate.
+ */
+export declare function planCheckoutShippingWithCarriers(input: {
+    hostId: string;
+    settings: CommerceModel.ShippingSettings | undefined;
+    cart: CarrierShippingCart;
+    destination: CarrierShippingDestination;
+    currency?: string;
+    timeoutMs?: number;
+}): Promise<CarrierShippingPlan>;

package/src/lib/server/carrier-shipping.js

@@ -0,0 +1,135 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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.
+ */ import { pluginShippingRateQuoter, quotePluginShippingRates } from "@aglyn/aglyn/plugin-manager/plugin-shipping-rates";
+import * as CommerceModel from "../model/index.js";
+/** A postal code a shopper declared, trimmed and bounded, or `undefined`. */ export function normalizeCheckoutPostalCode(value) {
+    if (typeof value !== 'string') return undefined;
+    const code = value.trim().toUpperCase().slice(0, 12);
+    return /^[A-Z0-9][A-Z0-9 -]{1,11}$/.test(code) ? code : undefined;
+}
+/** What a shopper is told when a postal code is needed. */ export const CARRIER_POSTAL_CODE_MESSAGE = 'Enter the postal code you’re shipping to.';
+/**
+ * The shipping half of a session for a store that may price by carrier.
+ * See the module comment; `planCheckoutShipping` is the whole answer for any
+ * store without a carrier rate.
+ */ export async function planCheckoutShippingWithCarriers(input) {
+    var _input_currency, _cart_parcel, _input_timeoutMs;
+    const { settings, cart } = input;
+    const tablePlan = ()=>CommerceModel.planCheckoutShipping(settings, {
+            subtotalCents: cart.subtotalCents,
+            totalGrams: cart.totalGrams
+        }, input.destination.country);
+    if (!CommerceModel.hasCarrierRates(settings)) return tablePlan();
+    const quoter = pluginShippingRateQuoter();
+    if (!quoter) return tablePlan();
+    const available = await quoter.available(input.hostId).catch(()=>false);
+    if (!available) return tablePlan();
+    const country = CommerceModel.normalizeCheckoutShippingCountry(input.destination.country);
+    if (!country) {
+        // Carrier prices differ by address by construction, so a session that
+        // does not know the destination cannot be honest about any of them.
+        return {
+            countries: CommerceModel.CHECKOUT_SHIPPING_COUNTRIES,
+            options: [],
+            refusal: 'destination-required'
+        };
+    }
+    const carrierRates = CommerceModel.carrierRatesFor(settings, country);
+    if (!carrierRates.length) return tablePlan();
+    const postalCode = normalizeCheckoutPostalCode(input.destination.postalCode);
+    if (!postalCode) {
+        return {
+            countries: [
+                country
+            ],
+            options: [],
+            refusal: 'destination-required',
+            needsPostalCode: true
+        };
+    }
+    const currency = String((_input_currency = input.currency) != null ? _input_currency : 'usd').toLowerCase();
+    const quotes = await quotePluginShippingRates({
+        hostId: input.hostId,
+        to: _extends({
+            country,
+            postalCode
+        }, typeof input.destination.state === 'string' && input.destination.state.trim() ? {
+            state: input.destination.state.trim().slice(0, 40)
+        } : {}, typeof input.destination.city === 'string' && input.destination.city.trim() ? {
+            city: input.destination.city.trim().slice(0, 80)
+        } : {}),
+        parcels: [
+            _extends({
+                weightGrams: Math.max(0, Math.round(cart.totalGrams))
+            }, (_cart_parcel = cart.parcel) != null ? _cart_parcel : {})
+        ],
+        currency,
+        valueCents: Math.max(0, Math.round(cart.subtotalCents))
+    }, {
+        timeoutMs: (_input_timeoutMs = input.timeoutMs) != null ? _input_timeoutMs : CommerceModel.CARRIER_QUOTE_TIMEOUT_MS
+    });
+    if (!quotes || !quotes.length) return tablePlan();
+    const quoted = [];
+    const hidden = new Set();
+    for (const rate of carrierRates){
+        var _ref;
+        var _rate_carrier, _rate_carrier1;
+        const services = ((_ref = (_rate_carrier = rate.carrier) == null ? void 0 : _rate_carrier.services) != null ? _ref : []).map((key)=>key.toLowerCase());
+        const offered = quotes.filter((quote)=>quote.currency === currency && (!services.length || services.includes(quote.serviceKey.toLowerCase())));
+        if (!offered.length) continue;
+        if ((_rate_carrier1 = rate.carrier) == null ? void 0 : _rate_carrier1.fallbackRateId) hidden.add(rate.carrier.fallbackRateId);
+        for (const quote of offered){
+            quoted.push({
+                rateId: CommerceModel.carrierOptionRateId(rate.id, quote.serviceKey),
+                name: (quote.estimatedDays ? `${quote.label} (${quote.estimatedDays} business day${quote.estimatedDays === 1 ? '' : 's'})` : quote.label).slice(0, 100),
+                amountCents: CommerceModel.carrierOptionAmountCents(quote.amountCents, rate.carrier)
+            });
+        }
+    }
+    if (!quoted.length) return tablePlan();
+    // The table's own options for this destination stay — a flat rate the
+    // merchant offers beside carriers, local pickup — less any fallback a
+    // carrier rate replaced now that it has quotes.
+    const table = CommerceModel.resolveCheckoutShippingOptions(settings, [
+        country
+    ], {
+        subtotalCents: cart.subtotalCents,
+        totalGrams: cart.totalGrams
+    }).filter((option)=>!hidden.has(option.rateId));
+    // One option per name: two carrier rates quoting the same service keep the
+    // cheaper, so a shopper never sees the same service twice.
+    const byName = new Map();
+    for (const option of [
+        ...table,
+        ...quoted
+    ]){
+        const existing = byName.get(option.name);
+        if (!existing || option.amountCents < existing.amountCents) byName.set(option.name, option);
+    }
+    const options = [
+        ...byName.values()
+    ].sort((a, b)=>a.amountCents - b.amountCents || a.rateId.localeCompare(b.rateId)).slice(0, CommerceModel.MAX_CHECKOUT_SHIPPING_OPTIONS);
+    return {
+        countries: [
+            country
+        ],
+        options,
+        quotedPostalCode: postalCode
+    };
+}
+
+//# sourceMappingURL=carrier-shipping.js.map

package/src/lib/server/carrier-shipping.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/carrier-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\nimport {\n  pluginShippingRateQuoter,\n  quotePluginShippingRates,\n  type PluginShippingParcel,\n} from '@aglyn/aglyn/plugin-manager/plugin-shipping-rates'\nimport * as CommerceModel from '../model'\n\n/**\n * LIVE CARRIER RATES AT CHECKOUT (AGL-3612): the `carrier` rate kind, priced\n * by asking core's `core.shipping-rate-quoter` — whichever plugin quotes\n * carriers — and never by importing it.\n *\n * ## Quoted before the session exists, on every door\n *\n * Stripe's hosted Checkout cannot change a session's shipping options once\n * the shopper types an address (\"The hosted page integration doesn't support\n * dynamically customizing shipping options\"), and the in-page form can only\n * by a server update after the fact — while this module's callers fix the\n * platform fee and the Connect transfer from the session's options at\n * creation. So the quote is taken BEFORE the session, against the\n * destination the shopper declares (country and postal code), and the\n * session is then restricted to that country exactly as a zone rate is\n * (AGL-1721). The same code serves cart checkout, buy-now and a draft\n * order's link, hosted and in-page, and the fee arithmetic downstream sees\n * ordinary options.\n *\n * ## The fallback is the merchant's own\n *\n * No quoter, a quoter not available for this site, or a quote that fails or\n * takes longer than {@link CommerceModel.CARRIER_QUOTE_TIMEOUT_MS}: the plan\n * is exactly the one {@link CommerceModel.planCheckoutShipping} makes from\n * the table, where a carrier rate offers nothing and its fallback rate is\n * offered. A store with no carrier rate never reaches the quoter at all, so\n * its sessions are byte-identical to the ones before this existed.\n */\n\nexport interface CarrierShippingCart {\n  subtotalCents: number\n  totalGrams: number\n  /** One parcel's dimensions, when the cart is one product that has them. */\n  parcel?: Omit<PluginShippingParcel, 'weightGrams'>\n}\n\nexport interface CarrierShippingDestination {\n  country?: unknown\n  postalCode?: unknown\n  state?: unknown\n  city?: unknown\n}\n\n/** A postal code a shopper declared, trimmed and bounded, or `undefined`. */\nexport function normalizeCheckoutPostalCode(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const code = value.trim().toUpperCase().slice(0, 12)\n  return /^[A-Z0-9][A-Z0-9 -]{1,11}$/.test(code) ? code : undefined\n}\n\nexport type CarrierShippingPlan = CommerceModel.CheckoutShippingPlan & {\n  /** Set when the plan offers live quotes: the postal code they were priced for. */\n  quotedPostalCode?: string\n  /**\n   * The destination's zone prices by carrier and the store can quote, but the\n   * shopper has not said where in the country: ask for a postal code.\n   */\n  needsPostalCode?: boolean\n}\n\n/** What a shopper is told when a postal code is needed. */\nexport const CARRIER_POSTAL_CODE_MESSAGE = 'Enter the postal code you’re shipping to.'\n\n/**\n * The shipping half of a session for a store that may price by carrier.\n * See the module comment; `planCheckoutShipping` is the whole answer for any\n * store without a carrier rate.\n */\nexport async function planCheckoutShippingWithCarriers(input: {\n  hostId: string\n  settings: CommerceModel.ShippingSettings | undefined\n  cart: CarrierShippingCart\n  destination: CarrierShippingDestination\n  currency?: string\n  timeoutMs?: number\n}): Promise<CarrierShippingPlan> {\n  const { settings, cart } = input\n  const tablePlan = () =>\n    CommerceModel.planCheckoutShipping(\n      settings,\n      { subtotalCents: cart.subtotalCents, totalGrams: cart.totalGrams },\n      input.destination.country,\n    )\n  if (!CommerceModel.hasCarrierRates(settings)) return tablePlan()\n  const quoter = pluginShippingRateQuoter()\n  if (!quoter) return tablePlan()\n  const available = await quoter.available(input.hostId).catch(() => false)\n  if (!available) return tablePlan()\n\n  const country = CommerceModel.normalizeCheckoutShippingCountry(input.destination.country)\n  if (!country) {\n    // Carrier prices differ by address by construction, so a session that\n    // does not know the destination cannot be honest about any of them.\n    return { countries: CommerceModel.CHECKOUT_SHIPPING_COUNTRIES, options: [], refusal: 'destination-required' }\n  }\n  const carrierRates = CommerceModel.carrierRatesFor(settings, country)\n  if (!carrierRates.length) return tablePlan()\n  const postalCode = normalizeCheckoutPostalCode(input.destination.postalCode)\n  if (!postalCode) {\n    return {\n      countries: [country],\n      options: [],\n      refusal: 'destination-required',\n      needsPostalCode: true,\n    }\n  }\n\n  const currency = String(input.currency ?? 'usd').toLowerCase()\n  const quotes = await quotePluginShippingRates(\n    {\n      hostId: input.hostId,\n      to: {\n        country,\n        postalCode,\n        ...(typeof input.destination.state === 'string' && input.destination.state.trim()\n          ? { state: input.destination.state.trim().slice(0, 40) }\n          : {}),\n        ...(typeof input.destination.city === 'string' && input.destination.city.trim()\n          ? { city: input.destination.city.trim().slice(0, 80) }\n          : {}),\n      },\n      parcels: [{ weightGrams: Math.max(0, Math.round(cart.totalGrams)), ...(cart.parcel ?? {}) }],\n      currency,\n      valueCents: Math.max(0, Math.round(cart.subtotalCents)),\n    },\n    { timeoutMs: input.timeoutMs ?? CommerceModel.CARRIER_QUOTE_TIMEOUT_MS },\n  )\n  if (!quotes || !quotes.length) return tablePlan()\n\n  const quoted: CommerceModel.ResolvedShippingRate[] = []\n  const hidden = new Set<string>()\n  for (const rate of carrierRates) {\n    const services = (rate.carrier?.services ?? []).map((key) => key.toLowerCase())\n    const offered = quotes.filter(\n      (quote) => quote.currency === currency && (!services.length || services.includes(quote.serviceKey.toLowerCase())),\n    )\n    if (!offered.length) continue\n    if (rate.carrier?.fallbackRateId) hidden.add(rate.carrier.fallbackRateId)\n    for (const quote of offered) {\n      quoted.push({\n        rateId: CommerceModel.carrierOptionRateId(rate.id, quote.serviceKey),\n        name: (quote.estimatedDays\n          ? `${quote.label} (${quote.estimatedDays} business day${quote.estimatedDays === 1 ? '' : 's'})`\n          : quote.label\n        ).slice(0, 100),\n        amountCents: CommerceModel.carrierOptionAmountCents(quote.amountCents, rate.carrier),\n      })\n    }\n  }\n  if (!quoted.length) return tablePlan()\n\n  // The table's own options for this destination stay — a flat rate the\n  // merchant offers beside carriers, local pickup — less any fallback a\n  // carrier rate replaced now that it has quotes.\n  const table = CommerceModel.resolveCheckoutShippingOptions(\n    settings,\n    [country],\n    { subtotalCents: cart.subtotalCents, totalGrams: cart.totalGrams },\n  ).filter((option) => !hidden.has(option.rateId))\n  // One option per name: two carrier rates quoting the same service keep the\n  // cheaper, so a shopper never sees the same service twice.\n  const byName = new Map<string, CommerceModel.ResolvedShippingRate>()\n  for (const option of [...table, ...quoted]) {\n    const existing = byName.get(option.name)\n    if (!existing || option.amountCents < existing.amountCents) byName.set(option.name, option)\n  }\n  const options = [...byName.values()]\n    .sort((a, b) => a.amountCents - b.amountCents || a.rateId.localeCompare(b.rateId))\n    .slice(0, CommerceModel.MAX_CHECKOUT_SHIPPING_OPTIONS)\n  return { countries: [country], options, quotedPostalCode: postalCode }\n}\n"],"names":["pluginShippingRateQuoter","quotePluginShippingRates","CommerceModel","normalizeCheckoutPostalCode","value","undefined","code","trim","toUpperCase","slice","test","CARRIER_POSTAL_CODE_MESSAGE","planCheckoutShippingWithCarriers","input","cart","settings","tablePlan","planCheckoutShipping","subtotalCents","totalGrams","destination","country","hasCarrierRates","quoter","available","hostId","catch","normalizeCheckoutShippingCountry","countries","CHECKOUT_SHIPPING_COUNTRIES","options","refusal","carrierRates","carrierRatesFor","length","postalCode","needsPostalCode","currency","String","toLowerCase","quotes","to","state","city","parcels","weightGrams","Math","max","round","parcel","valueCents","timeoutMs","CARRIER_QUOTE_TIMEOUT_MS","quoted","hidden","Set","rate","services","carrier","map","key","offered","filter","quote","includes","serviceKey","fallbackRateId","add","push","rateId","carrierOptionRateId","id","name","estimatedDays","label","amountCents","carrierOptionAmountCents","table","resolveCheckoutShippingOptions","option","has","byName","Map","existing","get","set","values","sort","a","b","localeCompare","MAX_CHECKOUT_SHIPPING_OPTIONS","quotedPostalCode"],"mappings":"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"}

package/src/lib/server/cart-checkout.d.ts

@@ -15,6 +15,8 @@
  * limitations under the License.
  */
 import type { PluginApiHandler } from '@aglyn/aglyn/server';
+/** An option the buyer ticked is no longer offered (AGL-3635). */
+export declare const CHECKOUT_EXTRA_UNAVAILABLE_MESSAGE = "An option you picked is no longer available. Review your cart and try again.";
 /**
  * Cart checkout (AGL-293): the whole cart in one Stripe Checkout
  * session on the merchant's account. Every line re-prices from its