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

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

@@ -0,0 +1,300 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { formatOrderNumber, orderLineRefundCents, orderLineRefunded } from "./commerce-orders.js";
+import { fulfilledQuantities, lineRequiresShipping } from "./order-fulfillment.js";
+export const RETURN_STATUSES = [
+    'requested',
+    'approved',
+    'declined',
+    'received',
+    'refunded',
+    'closed'
+];
+export const RETURN_STATUS_LABELS = {
+    requested: 'Requested',
+    approved: 'Approved',
+    declined: 'Declined',
+    received: 'Received',
+    refunded: 'Refunded',
+    closed: 'Closed'
+};
+export const RETURN_STATUS_COLOR = {
+    requested: 'warning',
+    approved: 'info',
+    declined: 'default',
+    received: 'info',
+    refunded: 'success',
+    closed: 'default'
+};
+export const RETURN_REASON_LABELS = {
+    damaged: 'Arrived damaged',
+    wrong_item: 'Wrong item',
+    not_as_described: 'Not as described',
+    size_or_fit: 'Size or fit',
+    no_longer_needed: 'No longer needed',
+    other: 'Other'
+};
+export const RETURN_REASONS = Object.keys(RETURN_REASON_LABELS);
+export const DEFAULT_RETURN_SETTINGS = {
+    enabled: true,
+    windowDays: 30,
+    eligibleTypes: [
+        'physical'
+    ]
+};
+/** The most days a window may be set to, and the most a note may hold. */ export const RETURN_WINDOW_MAX_DAYS = 365;
+export const RETURN_NOTE_MAX = 1000;
+/** The stored settings, read defensively: the document is admin-writable. */ export function readReturnSettings(raw) {
+    const value = raw != null ? raw : {};
+    const days = Math.round(Number(value.windowDays));
+    const types = Array.isArray(value.eligibleTypes) ? value.eligibleTypes.filter((type)=>type === 'physical' || type === 'digital' || type === 'service') : DEFAULT_RETURN_SETTINGS.eligibleTypes;
+    return {
+        enabled: value.enabled !== false,
+        windowDays: Number.isFinite(days) && days >= 0 ? Math.min(days, RETURN_WINDOW_MAX_DAYS) : DEFAULT_RETURN_SETTINGS.windowDays,
+        eligibleTypes: types
+    };
+}
+const TRANSITIONS = {
+    requested: [
+        'approved',
+        'declined',
+        'closed'
+    ],
+    approved: [
+        'received',
+        'refunded',
+        'closed'
+    ],
+    declined: [
+        'closed'
+    ],
+    received: [
+        'refunded',
+        'closed'
+    ],
+    refunded: [
+        'closed'
+    ],
+    closed: []
+};
+/** The return state machine. */ export function canTransitionReturn(from, to) {
+    var _TRANSITIONS_from;
+    return ((_TRANSITIONS_from = TRANSITIONS[from]) != null ? _TRANSITIONS_from : []).includes(to);
+}
+/** Whether a return still holds units against the order. */ export function returnIsOpen(entry) {
+    return entry.status !== 'declined' && entry.status !== 'closed';
+}
+/** Whether a return is still holding units, or took them: anything not declined. */ export function returnHoldsUnits(entry) {
+    if (entry.status === 'declined') return false;
+    // A return closed without a refund gave its units back to the order.
+    if (entry.status === 'closed') return Boolean(entry.refundedAtMs);
+    return true;
+}
+/**
+ * What can come back on an order: each line's shipped units (every unit, for
+ * a line with nothing to ship), less units already in a return that has not
+ * been declined, less everything on a line already refunded by name.
+ */ export function returnableLines(order, existing, settings) {
+    var _order_lineItems;
+    const shipped = fulfilledQuantities(order);
+    const held = new Map();
+    for (const entry of existing){
+        var _entry_lines;
+        if (!returnHoldsUnits(entry)) continue;
+        for (const line of (_entry_lines = entry.lines) != null ? _entry_lines : []){
+            var _held_get;
+            held.set(line.lineItemId, ((_held_get = held.get(line.lineItemId)) != null ? _held_get : 0) + Math.max(0, Math.floor(Number(line.quantity) || 0)));
+        }
+    }
+    return ((_order_lineItems = order.lineItems) != null ? _order_lineItems : []).map((line, index)=>{
+        var _shipped_get, _line_productType, _held_get, _line_variantLabel;
+        const quantity = Math.max(0, Math.floor(Number(line.quantity) || 0));
+        const delivered = lineRequiresShipping(line) ? Math.min(quantity, (_shipped_get = shipped.get(index)) != null ? _shipped_get : 0) : quantity;
+        const type = (_line_productType = line.productType) != null ? _line_productType : null;
+        let blocked = null;
+        if (orderLineRefunded(order, index)) blocked = 'Already refunded';
+        else if (settings && !settings.eligibleTypes.includes(type != null ? type : 'physical')) blocked = 'Not returnable';
+        else if (delivered === 0) blocked = 'Not shipped yet';
+        const returnable = blocked ? 0 : Math.max(0, delivered - ((_held_get = held.get(index)) != null ? _held_get : 0));
+        return {
+            lineItemId: index,
+            name: line.name,
+            variantLabel: (_line_variantLabel = line.variantLabel) != null ? _line_variantLabel : null,
+            productType: type,
+            returnable,
+            blocked: blocked != null ? blocked : returnable === 0 ? 'Already being returned' : null
+        };
+    });
+}
+/**
+ * When the return window closes: `windowDays` after the latest shipment, or
+ * after the order was placed when nothing shipped (a digital order). `null`
+ * when the order carries no date at all, which reads as open.
+ */ export function returnWindowEndsAtMs(order, settings) {
+    var _order_fulfillments;
+    const shippedAt = Math.max(0, ...((_order_fulfillments = order.fulfillments) != null ? _order_fulfillments : []).filter((entry)=>entry.status !== 'cancelled').map((entry)=>Number(entry.atMs) || 0));
+    const from = shippedAt || Number(order.createdAtMs) || 0;
+    if (!from) return null;
+    return from + settings.windowDays * 86400000;
+}
+/** Order statuses a return may be opened against. */ export const RETURNABLE_ORDER_STATUSES = [
+    'paid',
+    'partially_fulfilled',
+    'fulfilled',
+    'delivered'
+];
+/**
+ * Checks a return request against the order and the returns already open on
+ * it, merging duplicate lines first. `merchant` skips the buyer-only rules —
+ * the switch and the window — since a merchant may take anything back.
+ */ export function validateReturnRequest(input) {
+    const { order, existing, settings, by, now } = input;
+    if (by === 'buyer' && !settings.enabled) return {
+        problem: 'disabled'
+    };
+    if (!RETURNABLE_ORDER_STATUSES.includes(order.status)) return {
+        problem: 'order_status',
+        status: order.status
+    };
+    if (by === 'buyer') {
+        const endsAt = returnWindowEndsAtMs(order, settings);
+        if (endsAt !== null && now > endsAt) return {
+            problem: 'window_closed',
+            endedAtMs: endsAt
+        };
+    }
+    const returnable = returnableLines(order, existing, by === 'buyer' ? settings : null);
+    const merged = new Map();
+    for (const entry of input.lines){
+        var _ref, _ref1, _ref2;
+        const lineItemId = Number(entry == null ? void 0 : entry.lineItemId);
+        const quantity = Number(entry == null ? void 0 : entry.quantity);
+        if (!Number.isInteger(lineItemId) || lineItemId < 0 || lineItemId >= returnable.length) {
+            return {
+                problem: 'bad_line',
+                lineItemId: Number.isFinite(lineItemId) ? lineItemId : -1
+            };
+        }
+        if (!Number.isInteger(quantity) || quantity <= 0) return {
+            problem: 'bad_line',
+            lineItemId
+        };
+        const reason = String((_ref = entry == null ? void 0 : entry.reason) != null ? _ref : '');
+        if (!RETURN_REASONS.includes(reason)) return {
+            problem: 'bad_reason',
+            lineItemId
+        };
+        const prior = merged.get(lineItemId);
+        merged.set(lineItemId, {
+            lineItemId,
+            quantity: ((_ref1 = prior == null ? void 0 : prior.quantity) != null ? _ref1 : 0) + quantity,
+            reason: (_ref2 = prior == null ? void 0 : prior.reason) != null ? _ref2 : reason
+        });
+    }
+    if (merged.size === 0) return {
+        problem: 'empty'
+    };
+    for (const line of merged.values()){
+        const allowed = returnable[line.lineItemId].returnable;
+        if (line.quantity > allowed) return {
+            problem: 'too_many',
+            lineItemId: line.lineItemId,
+            returnable: allowed
+        };
+    }
+    return {
+        lines: [
+            ...merged.values()
+        ].sort((a, b)=>a.lineItemId - b.lineItemId)
+    };
+}
+/** Words for a refused request, for the buyer and the merchant alike. */ export function describeReturnRequestProblem(problem) {
+    switch(problem.problem){
+        case 'disabled':
+            return 'This store does not take return requests online. Contact the store instead.';
+        case 'window_closed':
+            return `The return window for this order closed on ${new Date(problem.endedAtMs).toLocaleDateString('en-US')}.`;
+        case 'order_status':
+            return `An order that is ${problem.status.replace('_', ' ')} cannot be returned.`;
+        case 'empty':
+            return 'Choose at least one item to return.';
+        case 'bad_line':
+            return 'One of the items is not on this order.';
+        case 'bad_reason':
+            return 'Choose a reason for each item.';
+        case 'too_many':
+            return problem.returnable === 0 ? 'One of the items cannot be returned.' : `Only ${problem.returnable} of one item can be returned.`;
+    }
+}
+/**
+ * What refunding a return's units is worth: each line's paid share
+ * (`orderLineRefundCents`, discount apportioned) in proportion to the units
+ * coming back, never more than is left to refund on the order. Shipping and
+ * tax stay out, as they do for a line refund; the merchant may add them by
+ * amount.
+ */ export function returnRefundCents(order, lines) {
+    var _ref, _ref1, _order_refundedCents;
+    var _order_totals;
+    let cents = 0;
+    for (const line of lines){
+        var _order_lineItems;
+        const orderLine = (_order_lineItems = order.lineItems) == null ? void 0 : _order_lineItems[line.lineItemId];
+        if (!orderLine) continue;
+        const lineQuantity = Math.max(1, Math.floor(Number(orderLine.quantity) || 1));
+        const paid = orderLineRefundCents(order, [
+            line.lineItemId
+        ]);
+        cents += Math.round(paid * Math.min(lineQuantity, line.quantity) / lineQuantity);
+    }
+    const total = Number((_ref = (_ref1 = (_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents) != null ? _ref1 : order.amountCents) != null ? _ref : 0);
+    const left = Math.max(0, total - Math.max(0, Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0)));
+    return Math.max(0, Math.min(cents, left));
+}
+/**
+ * The lines a return can refund BY NAME: those it takes back in full, which
+ * the refund route then withdraws entitlements for. A partial-quantity line is
+ * refunded by amount alone.
+ */ export function returnWholeLineIds(order, lines) {
+    return lines.filter((line)=>{
+        var _order_lineItems_line_lineItemId, _order_lineItems;
+        return line.quantity >= Math.floor(Number((_order_lineItems = order.lineItems) == null ? void 0 : (_order_lineItems_line_lineItemId = _order_lineItems[line.lineItemId]) == null ? void 0 : _order_lineItems_line_lineItemId.quantity) || 0);
+    }).map((line)=>line.lineItemId);
+}
+/** A short "2× Mug, 1× Shirt" for a return's lines. */ export function describeReturnLines(order, lines) {
+    return lines.map((line)=>{
+        var _ref;
+        var _order_lineItems_line_lineItemId, _order_lineItems;
+        return `${line.quantity}× ${(_ref = (_order_lineItems = order.lineItems) == null ? void 0 : (_order_lineItems_line_lineItemId = _order_lineItems[line.lineItemId]) == null ? void 0 : _order_lineItems_line_lineItemId.name) != null ? _ref : `line ${line.lineItemId}`}`;
+    }).join(', ');
+}
+/** The order number a return lists by. */ export function returnOrderNumber(order, orderId) {
+    return formatOrderNumber(order, orderId);
+}
+/** Appends a return timeline event immutably. */ export function appendReturnEvent(entry, event, detail, atMs = Date.now()) {
+    var _entry_timeline;
+    return [
+        ...(_entry_timeline = entry.timeline) != null ? _entry_timeline : [],
+        _extends({
+            atMs,
+            event
+        }, detail ? {
+            detail
+        } : {})
+    ];
+}
+
+//# sourceMappingURL=commerce-returns.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-returns.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 type { ProductType } from './commerce'\nimport {\n  formatOrderNumber,\n  orderLineRefundCents,\n  orderLineRefunded,\n  type HostOrder,\n} from './commerce-orders'\nimport { fulfilledQuantities, lineRequiresShipping } from './order-fulfillment'\n\n/**\n * Returns (RMA, AGL-3611): `hosts/{hostId}/returns/{id}`.\n *\n * A buyer asks to send items back, from their account or the order-status\n * page; the merchant approves or declines, receives the parcel and decides\n * per line whether it goes back on the shelf, then refunds through the\n * order's own refund route. The return is the record of all of that, so the\n * order keeps meaning what it always meant and the money still moves through\n * the one door that guards it.\n *\n * Every rule here is pure and shared by the buyer's route, the merchant's\n * route and the console, so the three cannot disagree about what is\n * returnable.\n */\n\nexport type ReturnStatus = 'requested' | 'approved' | 'declined' | 'received' | 'refunded' | 'closed'\n\nexport const RETURN_STATUSES: readonly ReturnStatus[] = [\n  'requested',\n  'approved',\n  'declined',\n  'received',\n  'refunded',\n  'closed',\n]\n\nexport const RETURN_STATUS_LABELS: Record<ReturnStatus, string> = {\n  requested: 'Requested',\n  approved: 'Approved',\n  declined: 'Declined',\n  received: 'Received',\n  refunded: 'Refunded',\n  closed: 'Closed',\n}\n\nexport const RETURN_STATUS_COLOR: Record<ReturnStatus, 'default' | 'info' | 'warning' | 'success' | 'error'> = {\n  requested: 'warning',\n  approved: 'info',\n  declined: 'default',\n  received: 'info',\n  refunded: 'success',\n  closed: 'default',\n}\n\nexport type ReturnReason =\n  | 'damaged'\n  | 'wrong_item'\n  | 'not_as_described'\n  | 'size_or_fit'\n  | 'no_longer_needed'\n  | 'other'\n\nexport const RETURN_REASON_LABELS: Record<ReturnReason, string> = {\n  damaged: 'Arrived damaged',\n  wrong_item: 'Wrong item',\n  not_as_described: 'Not as described',\n  size_or_fit: 'Size or fit',\n  no_longer_needed: 'No longer needed',\n  other: 'Other',\n}\n\nexport const RETURN_REASONS = Object.keys(RETURN_REASON_LABELS) as ReturnReason[]\n\nexport interface ReturnLine {\n  lineItemId: number\n  quantity: number\n  reason: ReturnReason\n  /** The line's name when the return was opened, for lists that read no order. */\n  name?: string\n}\n\n/** A return label a shipping plugin bought for the buyer to send the parcel with. */\nexport interface ReturnLabel {\n  carrier: string\n  trackingNumber: string\n  labelUrl: string\n  trackingUrl?: string\n  attachedAtMs: number\n}\n\n/** What went back on the shelf when the parcel arrived. */\nexport interface ReturnRestock {\n  lines: Array<{ lineItemId: number; quantity: number }>\n  /** The stock location the units went to, for a multi-location store. */\n  locationId?: string\n  atMs: number\n}\n\nexport interface ReturnTimelineEvent {\n  atMs: number\n  event: string\n  detail?: string\n}\n\n/** `hosts/{hostId}/returns/{id}`, written only by the server. */\nexport interface HostReturn {\n  orderId: string\n  /** The order's number, for the list, e.g. `#1042`. */\n  orderNumber: string\n  customerEmail: string | null\n  customerName: string | null\n  lines: ReturnLine[]\n  status: ReturnStatus\n  /** Who opened it: the buyer, or the merchant on their behalf. */\n  requestedBy: 'buyer' | 'merchant'\n  /**\n   * `register` for a return taken and refunded at a POS register (AGL-3609):\n   * it is created already `refunded`, and the register's own record under\n   * `registers/{registerId}/returns` holds the tenders it went back to.\n   */\n  source?: 'register'\n  registerId?: string\n  customerNote?: string\n  merchantNote?: string\n  returnLabel?: ReturnLabel\n  restock?: ReturnRestock\n  /** When the refund went through the order's refund route, and for how much. */\n  refundedAtMs?: number\n  refundCents?: number\n  timeline: ReturnTimelineEvent[]\n  createdAtMs: number\n  updatedAtMs: number\n}\n\n/** The store's return policy, at `hosts/{hostId}/settings/store` `returns`. */\nexport interface StoreReturnSettings {\n  /** Whether buyers may ask for a return themselves. */\n  enabled: boolean\n  /** Days after the order shipped (or was placed, if it never shipped). */\n  windowDays: number\n  /** The product types a buyer may return. */\n  eligibleTypes: ProductType[]\n}\n\nexport const DEFAULT_RETURN_SETTINGS: StoreReturnSettings = {\n  enabled: true,\n  windowDays: 30,\n  eligibleTypes: ['physical'],\n}\n\n/** The most days a window may be set to, and the most a note may hold. */\nexport const RETURN_WINDOW_MAX_DAYS = 365\nexport const RETURN_NOTE_MAX = 1000\n\n/** The stored settings, read defensively: the document is admin-writable. */\nexport function readReturnSettings(raw: unknown): StoreReturnSettings {\n  const value = (raw ?? {}) as Partial<Record<keyof StoreReturnSettings, unknown>>\n  const days = Math.round(Number(value.windowDays))\n  const types = Array.isArray(value.eligibleTypes)\n    ? (value.eligibleTypes as unknown[]).filter(\n        (type): type is ProductType => type === 'physical' || type === 'digital' || type === 'service',\n      )\n    : DEFAULT_RETURN_SETTINGS.eligibleTypes\n  return {\n    enabled: value.enabled !== false,\n    windowDays:\n      Number.isFinite(days) && days >= 0 ? Math.min(days, RETURN_WINDOW_MAX_DAYS) : DEFAULT_RETURN_SETTINGS.windowDays,\n    eligibleTypes: types,\n  }\n}\n\nconst TRANSITIONS: Record<ReturnStatus, ReturnStatus[]> = {\n  requested: ['approved', 'declined', 'closed'],\n  approved: ['received', 'refunded', 'closed'],\n  declined: ['closed'],\n  received: ['refunded', 'closed'],\n  refunded: ['closed'],\n  closed: [],\n}\n\n/** The return state machine. */\nexport function canTransitionReturn(from: ReturnStatus, to: ReturnStatus): boolean {\n  return (TRANSITIONS[from] ?? []).includes(to)\n}\n\n/** Whether a return still holds units against the order. */\nexport function returnIsOpen(entry: Pick<HostReturn, 'status'>): boolean {\n  return entry.status !== 'declined' && entry.status !== 'closed'\n}\n\n/** Whether a return is still holding units, or took them: anything not declined. */\nexport function returnHoldsUnits(entry: Pick<HostReturn, 'status' | 'refundedAtMs'>): boolean {\n  if (entry.status === 'declined') return false\n  // A return closed without a refund gave its units back to the order.\n  if (entry.status === 'closed') return Boolean(entry.refundedAtMs)\n  return true\n}\n\n/** Units each line could be sent back, and why not where none can. */\nexport interface ReturnableLine {\n  lineItemId: number\n  name: string\n  variantLabel: string | null\n  productType: ProductType | null\n  /** Units the buyer has and may send back. */\n  returnable: number\n  /** Why `returnable` is 0, in the buyer's words; `null` when it is not. */\n  blocked: string | null\n}\n\n/**\n * What can come back on an order: each line's shipped units (every unit, for\n * a line with nothing to ship), less units already in a return that has not\n * been declined, less everything on a line already refunded by name.\n */\nexport function returnableLines(\n  order: Pick<HostOrder, 'lineItems' | 'fulfillments' | 'refundedLineItemIds'>,\n  existing: ReadonlyArray<Pick<HostReturn, 'status' | 'lines' | 'refundedAtMs'>>,\n  settings: Pick<StoreReturnSettings, 'eligibleTypes'> | null,\n): ReturnableLine[] {\n  const shipped = fulfilledQuantities(order)\n  const held = new Map<number, number>()\n  for (const entry of existing) {\n    if (!returnHoldsUnits(entry)) continue\n    for (const line of entry.lines ?? []) {\n      held.set(line.lineItemId, (held.get(line.lineItemId) ?? 0) + Math.max(0, Math.floor(Number(line.quantity) || 0)))\n    }\n  }\n  return (order.lineItems ?? []).map((line, index) => {\n    const quantity = Math.max(0, Math.floor(Number(line.quantity) || 0))\n    const delivered = lineRequiresShipping(line) ? Math.min(quantity, shipped.get(index) ?? 0) : quantity\n    const type = (line.productType ?? null) as ProductType | null\n    let blocked: string | null = null\n    if (orderLineRefunded(order, index)) blocked = 'Already refunded'\n    else if (settings && !settings.eligibleTypes.includes(type ?? 'physical')) blocked = 'Not returnable'\n    else if (delivered === 0) blocked = 'Not shipped yet'\n    const returnable = blocked ? 0 : Math.max(0, delivered - (held.get(index) ?? 0))\n    return {\n      lineItemId: index,\n      name: line.name,\n      variantLabel: line.variantLabel ?? null,\n      productType: type,\n      returnable,\n      blocked: blocked ?? (returnable === 0 ? 'Already being returned' : null),\n    }\n  })\n}\n\n/**\n * When the return window closes: `windowDays` after the latest shipment, or\n * after the order was placed when nothing shipped (a digital order). `null`\n * when the order carries no date at all, which reads as open.\n */\nexport function returnWindowEndsAtMs(\n  order: Pick<HostOrder, 'fulfillments' | 'createdAtMs'>,\n  settings: Pick<StoreReturnSettings, 'windowDays'>,\n): number | null {\n  const shippedAt = Math.max(0, ...(order.fulfillments ?? []).filter((entry) => entry.status !== 'cancelled').map((entry) => Number(entry.atMs) || 0))\n  const from = shippedAt || Number(order.createdAtMs) || 0\n  if (!from) return null\n  return from + settings.windowDays * 86_400_000\n}\n\n/** Why a requested return was refused. */\nexport type ReturnRequestProblem =\n  | { problem: 'disabled' }\n  | { problem: 'window_closed'; endedAtMs: number }\n  | { problem: 'order_status'; status: string }\n  | { problem: 'empty' }\n  | { problem: 'bad_line'; lineItemId: number }\n  | { problem: 'bad_reason'; lineItemId: number }\n  | { problem: 'too_many'; lineItemId: number; returnable: number }\n\n/** Order statuses a return may be opened against. */\nexport const RETURNABLE_ORDER_STATUSES: readonly string[] = ['paid', 'partially_fulfilled', 'fulfilled', 'delivered']\n\n/**\n * Checks a return request against the order and the returns already open on\n * it, merging duplicate lines first. `merchant` skips the buyer-only rules —\n * the switch and the window — since a merchant may take anything back.\n */\nexport function validateReturnRequest(input: {\n  order: Pick<HostOrder, 'status' | 'lineItems' | 'fulfillments' | 'refundedLineItemIds' | 'createdAtMs'>\n  existing: ReadonlyArray<Pick<HostReturn, 'status' | 'lines' | 'refundedAtMs'>>\n  settings: StoreReturnSettings\n  lines: ReadonlyArray<{ lineItemId: unknown; quantity: unknown; reason: unknown }>\n  by: 'buyer' | 'merchant'\n  now: number\n}): { lines: ReturnLine[] } | ReturnRequestProblem {\n  const { order, existing, settings, by, now } = input\n  if (by === 'buyer' && !settings.enabled) return { problem: 'disabled' }\n  if (!RETURNABLE_ORDER_STATUSES.includes(order.status)) return { problem: 'order_status', status: order.status }\n  if (by === 'buyer') {\n    const endsAt = returnWindowEndsAtMs(order, settings)\n    if (endsAt !== null && now > endsAt) return { problem: 'window_closed', endedAtMs: endsAt }\n  }\n  const returnable = returnableLines(order, existing, by === 'buyer' ? settings : null)\n  const merged = new Map<number, ReturnLine>()\n  for (const entry of input.lines) {\n    const lineItemId = Number(entry?.lineItemId)\n    const quantity = Number(entry?.quantity)\n    if (!Number.isInteger(lineItemId) || lineItemId < 0 || lineItemId >= returnable.length) {\n      return { problem: 'bad_line', lineItemId: Number.isFinite(lineItemId) ? lineItemId : -1 }\n    }\n    if (!Number.isInteger(quantity) || quantity <= 0) return { problem: 'bad_line', lineItemId }\n    const reason = String(entry?.reason ?? '') as ReturnReason\n    if (!RETURN_REASONS.includes(reason)) return { problem: 'bad_reason', lineItemId }\n    const prior = merged.get(lineItemId)\n    merged.set(lineItemId, { lineItemId, quantity: (prior?.quantity ?? 0) + quantity, reason: prior?.reason ?? reason })\n  }\n  if (merged.size === 0) return { problem: 'empty' }\n  for (const line of merged.values()) {\n    const allowed = returnable[line.lineItemId].returnable\n    if (line.quantity > allowed) return { problem: 'too_many', lineItemId: line.lineItemId, returnable: allowed }\n  }\n  return { lines: [...merged.values()].sort((a, b) => a.lineItemId - b.lineItemId) }\n}\n\n/** Words for a refused request, for the buyer and the merchant alike. */\nexport function describeReturnRequestProblem(problem: ReturnRequestProblem): string {\n  switch (problem.problem) {\n    case 'disabled':\n      return 'This store does not take return requests online. Contact the store instead.'\n    case 'window_closed':\n      return `The return window for this order closed on ${new Date(problem.endedAtMs).toLocaleDateString('en-US')}.`\n    case 'order_status':\n      return `An order that is ${problem.status.replace('_', ' ')} cannot be returned.`\n    case 'empty':\n      return 'Choose at least one item to return.'\n    case 'bad_line':\n      return 'One of the items is not on this order.'\n    case 'bad_reason':\n      return 'Choose a reason for each item.'\n    case 'too_many':\n      return problem.returnable === 0\n        ? 'One of the items cannot be returned.'\n        : `Only ${problem.returnable} of one item can be returned.`\n  }\n}\n\n/**\n * What refunding a return's units is worth: each line's paid share\n * (`orderLineRefundCents`, discount apportioned) in proportion to the units\n * coming back, never more than is left to refund on the order. Shipping and\n * tax stay out, as they do for a line refund; the merchant may add them by\n * amount.\n */\nexport function returnRefundCents(\n  order: Pick<HostOrder, 'lineItems' | 'totals' | 'refundedCents' | 'amountCents'>,\n  lines: ReadonlyArray<Pick<ReturnLine, 'lineItemId' | 'quantity'>>,\n): number {\n  let cents = 0\n  for (const line of lines) {\n    const orderLine = order.lineItems?.[line.lineItemId]\n    if (!orderLine) continue\n    const lineQuantity = Math.max(1, Math.floor(Number(orderLine.quantity) || 1))\n    const paid = orderLineRefundCents(order, [line.lineItemId])\n    cents += Math.round((paid * Math.min(lineQuantity, line.quantity)) / lineQuantity)\n  }\n  const total = Number(order.totals?.totalCents ?? order.amountCents ?? 0)\n  const left = Math.max(0, total - Math.max(0, Number(order.refundedCents ?? 0)))\n  return Math.max(0, Math.min(cents, left))\n}\n\n/**\n * The lines a return can refund BY NAME: those it takes back in full, which\n * the refund route then withdraws entitlements for. A partial-quantity line is\n * refunded by amount alone.\n */\nexport function returnWholeLineIds(\n  order: Pick<HostOrder, 'lineItems'>,\n  lines: ReadonlyArray<Pick<ReturnLine, 'lineItemId' | 'quantity'>>,\n): number[] {\n  return lines\n    .filter((line) => line.quantity >= Math.floor(Number(order.lineItems?.[line.lineItemId]?.quantity) || 0))\n    .map((line) => line.lineItemId)\n}\n\n/** A short \"2× Mug, 1× Shirt\" for a return's lines. */\nexport function describeReturnLines(\n  order: Pick<HostOrder, 'lineItems'>,\n  lines: ReadonlyArray<Pick<ReturnLine, 'lineItemId' | 'quantity'>>,\n): string {\n  return lines.map((line) => `${line.quantity}× ${order.lineItems?.[line.lineItemId]?.name ?? `line ${line.lineItemId}`}`).join(', ')\n}\n\n/** The order number a return lists by. */\nexport function returnOrderNumber(order: Pick<HostOrder, 'number'>, orderId: string): string {\n  return formatOrderNumber(order, orderId)\n}\n\n/** Appends a return timeline event immutably. */\nexport function appendReturnEvent(\n  entry: Pick<HostReturn, 'timeline'>,\n  event: string,\n  detail?: string,\n  atMs = Date.now(),\n): ReturnTimelineEvent[] {\n  return [...(entry.timeline ?? []), { atMs, event, ...(detail ? { detail } : {}) }]\n}\n"],"names":["formatOrderNumber","orderLineRefundCents","orderLineRefunded","fulfilledQuantities","lineRequiresShipping","RETURN_STATUSES","RETURN_STATUS_LABELS","requested","approved","declined","received","refunded","closed","RETURN_STATUS_COLOR","RETURN_REASON_LABELS","damaged","wrong_item","not_as_described","size_or_fit","no_longer_needed","other","RETURN_REASONS","Object","keys","DEFAULT_RETURN_SETTINGS","enabled","windowDays","eligibleTypes","RETURN_WINDOW_MAX_DAYS","RETURN_NOTE_MAX","readReturnSettings","raw","value","days","Math","round","Number","types","Array","isArray","filter","type","isFinite","min","TRANSITIONS","canTransitionReturn","from","to","includes","returnIsOpen","entry","status","returnHoldsUnits","Boolean","refundedAtMs","returnableLines","order","existing","settings","shipped","held","Map","line","lines","set","lineItemId","get","max","floor","quantity","lineItems","map","index","delivered","productType","blocked","returnable","name","variantLabel","returnWindowEndsAtMs","shippedAt","fulfillments","atMs","createdAtMs","RETURNABLE_ORDER_STATUSES","validateReturnRequest","input","by","now","problem","endsAt","endedAtMs","merged","isInteger","length","reason","String","prior","size","values","allowed","sort","a","b","describeReturnRequestProblem","Date","toLocaleDateString","replace","returnRefundCents","cents","orderLine","lineQuantity","paid","total","totals","totalCents","amountCents","left","refundedCents","returnWholeLineIds","describeReturnLines","join","returnOrderNumber","orderId","appendReturnEvent","event","detail","timeline"],"mappings":"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"}

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

@@ -52,17 +52,43 @@ export interface ShippingTier {
     upTo: number;
     amountCents: number;
 }
+/**
+ * A live carrier rate (AGL-3612): the zone's price is what a carrier quotes
+ * for the parcel to the shopper's address, asked through core's
+ * `core.shipping-rate-quoter` seam of whichever plugin quotes carriers. With
+ * no quoter, a quoter that is not available for the site, no postal code to
+ * quote against, or a quote slower than {@link CARRIER_QUOTE_TIMEOUT_MS}, it
+ * offers nothing and its fallback rate is offered instead.
+ */
+export interface CarrierRateSettings {
+    /** Service keys (`carrier:service`) to offer; empty offers every quoted service. */
+    services?: string[];
+    /** Added to each quote, in percent. */
+    markupPct?: number;
+    /** Added to each quote after the markup, in cents. */
+    handlingCents?: number;
+    /**
+     * A rate of this zone offered when no live quote is: it is HIDDEN while
+     * quotes are offered, so the shopper picks between carriers, not between a
+     * carrier and the merchant's guess.
+     */
+    fallbackRateId?: string;
+}
+/** How long checkout waits for live carrier quotes before it falls back. */
+export declare const CARRIER_QUOTE_TIMEOUT_MS = 3000;
 export interface ShippingRate {
     id: string;
     zoneId: string;
     name: string;
-    kind: 'flat' | 'free_over' | 'price_tiers' | 'weight_tiers';
+    kind: 'flat' | 'free_over' | 'price_tiers' | 'weight_tiers' | 'carrier';
     /** 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[];
+    /** carrier: the live rate's options (AGL-3612). */
+    carrier?: CarrierRateSettings;
 }
 export interface ShippingSettings {
     zones?: ShippingZone[];
@@ -89,6 +115,23 @@ export interface ResolvedShippingRate {
  * collection as a merchant who delivers worldwide.
  */
 export declare const LOCAL_PICKUP_RATE_ID = "pickup";
+/**
+ * The zones a destination falls in (AGL-1707, factored out for AGL-3612).
+ * Specific country zones beat '*' zones: when any zone names the country
+ * outright, rest-of-world zones are ignored.
+ */
+export declare function matchedZoneIds(settings: ShippingSettings | undefined, destinationCountry: string): Set<string>;
+/** The live carrier rates a destination's zones carry (AGL-3612). */
+export declare function carrierRatesFor(settings: ShippingSettings | undefined, destinationCountry: string): ShippingRate[];
+/** Whether any zone carries a live carrier rate (AGL-3612). */
+export declare function hasCarrierRates(settings: ShippingSettings | undefined): boolean;
+/** The rate id a quoted service is offered under: stable per rate and service. */
+export declare function carrierOptionRateId(rateId: string, serviceKey: string): string;
+/**
+ * What a shopper pays for a carrier's quote under one carrier rate: the
+ * quote, plus the markup, plus the handling fee, in whole cents.
+ */
+export declare function carrierOptionAmountCents(quotedCents: number, settings: CarrierRateSettings | undefined): number;
 /**
  * Rates available for a destination + cart, cheapest first. Specific
  * country zones beat '*' zones: when any specific zone matches, '*'

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

@@ -40,6 +40,7 @@
  * a register flow in exchange for nothing. A POS sale that must be shipped is
  * a draft order.
  */ import { _ as _extends } from "@swc/helpers/_/_extends";
+/** How long checkout waits for live carrier quotes before it falls back. */ export const CARRIER_QUOTE_TIMEOUT_MS = 3000;
 /**
  * The rate id appended for local pickup (AGL-2325).
  *
@@ -76,6 +77,50 @@ function tierAmount(tiers, value) {
     // catch-all tier with a large upTo).
     return null;
 }
+/**
+ * The zones a destination falls in (AGL-1707, factored out for AGL-3612).
+ * Specific country zones beat '*' zones: when any zone names the country
+ * outright, rest-of-world zones are ignored.
+ */ export function matchedZoneIds(settings, destinationCountry) {
+    var _ref;
+    const country = destinationCountry.toUpperCase();
+    const zones = (_ref = settings == null ? void 0 : settings.zones) != null ? _ref : [];
+    // A zone is SPECIFIC when it names this country outright — not merely when
+    // it is "not wildcard-only" (AGL-2298). The old test was `!every(code ===
+    // '*')`, so a zone spelled `['*','US']` counted as specific for all six
+    // destinations (it matches every country through the `*`) and suppressed
+    // every genuine rest-of-world zone globally. Asking the narrower question
+    // makes such a zone specific for `US` and wildcard for the rest, which is
+    // what its two entries actually say.
+    const specific = zones.filter((zone)=>{
+        var _zone_countries;
+        return ((_zone_countries = zone.countries) != null ? _zone_countries : []).some((code)=>zoneCode(code) === country);
+    });
+    const matched = specific.length ? specific : zones.filter((zone)=>zoneMatches(zone, country));
+    return new Set(matched.map((zone)=>zone.id));
+}
+/** The live carrier rates a destination's zones carry (AGL-3612). */ export function carrierRatesFor(settings, destinationCountry) {
+    var _settings_rates;
+    if (!settings) return [];
+    const zoneIds = matchedZoneIds(settings, destinationCountry);
+    return ((_settings_rates = settings.rates) != null ? _settings_rates : []).filter((rate)=>rate.kind === 'carrier' && zoneIds.has(rate.zoneId));
+}
+/** Whether any zone carries a live carrier rate (AGL-3612). */ export function hasCarrierRates(settings) {
+    var _ref;
+    return ((_ref = settings == null ? void 0 : settings.rates) != null ? _ref : []).some((rate)=>rate.kind === 'carrier');
+}
+/** The rate id a quoted service is offered under: stable per rate and service. */ export function carrierOptionRateId(rateId, serviceKey) {
+    return `carrier:${rateId}:${serviceKey}`;
+}
+/**
+ * What a shopper pays for a carrier's quote under one carrier rate: the
+ * quote, plus the markup, plus the handling fee, in whole cents.
+ */ export function carrierOptionAmountCents(quotedCents, settings) {
+    const quote = Math.max(0, Math.round(Number(quotedCents) || 0));
+    const pct = Number(settings == null ? void 0 : settings.markupPct);
+    const handling = Number(settings == null ? void 0 : settings.handlingCents);
+    return quote + (Number.isFinite(pct) && pct > 0 ? Math.round(quote * Math.min(pct, 500) / 100) : 0) + (Number.isFinite(handling) && handling > 0 ? Math.round(handling) : 0);
+}
 /**
  * Rates available for a destination + cart, cheapest first. Specific
  * country zones beat '*' zones: when any specific zone matches, '*'
@@ -88,10 +133,9 @@ function tierAmount(tiers, value) {
  * Callers deciding whether a destination is served must filter pickup out
  * first; `planCheckoutShipping` and `summarizeShippingCoverage` do (AGL-2325).
  */ export function resolveShippingRates(settings, destinationCountry, cart) {
-    var _settings_zones, _settings_rates;
+    var _settings_rates;
     if (!settings || !destinationCountry) return [];
-    const country = destinationCountry.toUpperCase();
-    const zones = (_settings_zones = settings.zones) != null ? _settings_zones : [];
+    const zoneIds = matchedZoneIds(settings, destinationCountry);
     // A zone is SPECIFIC when it names this country outright — not merely when
     // it is "not wildcard-only" (AGL-2298). The old test was `!every(code ===
     // '*')`, so a zone spelled `['*','US']` counted as specific for all six
@@ -99,12 +143,6 @@ function tierAmount(tiers, value) {
     // every genuine rest-of-world zone globally. Asking the narrower question
     // makes such a zone specific for `US` and wildcard for the rest, which is
     // what its two entries actually say.
-    const specific = zones.filter((zone)=>{
-        var _zone_countries;
-        return ((_zone_countries = zone.countries) != null ? _zone_countries : []).some((code)=>zoneCode(code) === country);
-    });
-    const matched = specific.length ? specific : zones.filter((zone)=>zoneMatches(zone, country));
-    const zoneIds = new Set(matched.map((zone)=>zone.id));
     const resolved = [];
     for (const rate of (_settings_rates = settings.rates) != null ? _settings_rates : []){
         if (!zoneIds.has(rate.zoneId)) continue;
@@ -125,6 +163,12 @@ function tierAmount(tiers, value) {
                 var _cart_totalGrams;
                 amountCents = tierAmount(rate.tiers, (_cart_totalGrams = cart.totalGrams) != null ? _cart_totalGrams : 0);
                 break;
+            // A carrier's price exists only once a carrier quoted it for an
+            // address (AGL-3612), so a table read offers nothing for it and its
+            // fallback rate is what resolves here. `carrier-shipping.ts` adds the
+            // quotes where one can be had.
+            case 'carrier':
+                break;
         }
         if (amountCents == null) continue;
         resolved.push({