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

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

@@ -0,0 +1,180 @@
+/**
+ * @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";
+/** A money amount for print: `$12.50`, `-€3.00`. Locale is fixed so receipts read the same everywhere. */ export function formatReceiptMoney(cents, currency) {
+    const code = String(currency || 'usd').toUpperCase();
+    const safe = Number.isFinite(cents) ? Math.round(cents) : 0;
+    try {
+        var _resolvedOptions_maximumFractionDigits;
+        const digits = (_resolvedOptions_maximumFractionDigits = new Intl.NumberFormat('en-US', {
+            style: 'currency',
+            currency: code
+        }).resolvedOptions().maximumFractionDigits) != null ? _resolvedOptions_maximumFractionDigits : 2;
+        return new Intl.NumberFormat('en-US', {
+            style: 'currency',
+            currency: code,
+            minimumFractionDigits: digits,
+            maximumFractionDigits: digits
+        }).format(safe / 10 ** digits);
+    } catch (unused) {
+        return `${(safe / 100).toFixed(2)} ${code}`;
+    }
+}
+/** The receipt timestamp, e.g. `Oct 6, 2026, 3:04 PM`. */ export function formatReceiptTime(atMs, timeZone) {
+    const options = {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit'
+    };
+    try {
+        return new Intl.DateTimeFormat('en-US', _extends({}, options, {
+            timeZone: timeZone || 'UTC'
+        })).format(new Date(atMs));
+    } catch (unused) {
+        return new Intl.DateTimeFormat('en-US', _extends({}, options, {
+            timeZone: 'UTC'
+        })).format(new Date(atMs));
+    }
+}
+const PAYMENT_METHOD_LABELS = {
+    cash: 'Cash',
+    card_present: 'Card',
+    card_keyed: 'Card',
+    card_link: 'Card',
+    gift_card: 'Gift card',
+    folio: 'Charged to room'
+};
+const whole = (value)=>{
+    const number = Math.round(Number(value));
+    return Number.isFinite(number) && number > 0 ? number : 0;
+};
+/**
+ * The tenders an order was paid with: the register's payment ledger
+ * (`payments[]`, AGL-3607) when the order has one, otherwise a single tender
+ * read from the order itself (a cash sale's `changeCents`, a QR card sale).
+ */ export function receiptTendersFromOrder(order) {
+    var _order_totals;
+    const payments = Array.isArray(order['payments']) ? order['payments'] : [];
+    if (payments.length) {
+        let changeCents = 0;
+        let tipCents = 0;
+        const tenders = payments.filter((payment)=>payment && payment.status === 'succeeded').map((payment)=>{
+            changeCents += whole(payment.changeCents);
+            tipCents += whole(payment.tipCents);
+            const card = [
+                payment.cardBrand,
+                payment.last4 ? `**** ${payment.last4}` : ''
+            ].filter(Boolean).join(' ');
+            const label = card || PAYMENT_METHOD_LABELS[String(payment.method)] || 'Payment';
+            const tendered = whole(payment.cashTenderedCents);
+            return {
+                label,
+                amountCents: tendered || whole(payment.amountCents) + whole(payment.tipCents)
+            };
+        });
+        return {
+            tenders,
+            changeCents,
+            tipCents
+        };
+    }
+    const totalCents = whole((_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents);
+    const changeCents = whole(order['changeCents']);
+    if (!totalCents) return {
+        tenders: [],
+        changeCents: 0,
+        tipCents: 0
+    };
+    const isCash = order.channel === 'pos' && !order.checkoutSessionId && !order.paymentIntentId;
+    return {
+        tenders: [
+            {
+                label: order['reservationId'] ? 'Charged to room' : isCash ? 'Cash' : 'Card',
+                amountCents: totalCents + (isCash ? changeCents : 0)
+            }
+        ],
+        changeCents: isCash ? changeCents : 0,
+        tipCents: 0
+    };
+}
+/** The receipt an order prints, from the order as stored. */ export function receiptDataFromOrder(orderId, order, context) {
+    var _order_lineItems, _ref, _ref1, _order_currency, _ref2;
+    var _context_storeLines;
+    const lines = ((_order_lineItems = order.lineItems) != null ? _order_lineItems : []).map((line)=>{
+        var _line_name;
+        const quantity = Math.max(1, Math.round(Number(line.quantity) || 1));
+        const unitCents = Math.round(Number(line.unitAmountCents) || 0);
+        return _extends({
+            name: String((_line_name = line.name) != null ? _line_name : 'Item')
+        }, line.variantLabel ? {
+            detail: String(line.variantLabel)
+        } : {}, {
+            quantity,
+            unitCents,
+            totalCents: unitCents * quantity
+        });
+    });
+    const totals = order.totals;
+    const subtotalCents = (_ref = totals == null ? void 0 : totals.itemsCents) != null ? _ref : lines.reduce((sum, line)=>sum + line.totalCents, 0);
+    const { tenders, changeCents, tipCents } = receiptTendersFromOrder(order);
+    const tip = whole(totals == null ? void 0 : totals.tipCents) || tipCents;
+    const orderNumber = order.number ? String(order.number) : orderId.slice(0, 8).toUpperCase();
+    return _extends({
+        storeName: context.storeName
+    }, ((_context_storeLines = context.storeLines) == null ? void 0 : _context_storeLines.length) ? {
+        storeLines: context.storeLines
+    } : {}, {
+        orderNumber,
+        orderId,
+        createdAtMs: Number(order['createdAtMs']) || Date.now()
+    }, context.timeZone ? {
+        timeZone: context.timeZone
+    } : {}, context.registerName ? {
+        registerName: context.registerName
+    } : {}, context.cashierName ? {
+        cashierName: context.cashierName
+    } : {}, {
+        currency: String((_ref1 = (_order_currency = order['currency']) != null ? _order_currency : context.currency) != null ? _ref1 : 'usd'),
+        lines,
+        subtotalCents
+    }, (totals == null ? void 0 : totals.discountCents) ? {
+        discountCents: totals.discountCents
+    } : {}, (totals == null ? void 0 : totals.shippingCents) ? {
+        shippingCents: totals.shippingCents
+    } : {}, (totals == null ? void 0 : totals.taxCents) ? {
+        taxCents: totals.taxCents
+    } : {}, tip ? {
+        tipCents: tip
+    } : {}, {
+        totalCents: (_ref2 = totals == null ? void 0 : totals.totalCents) != null ? _ref2 : subtotalCents
+    }, tenders.length ? {
+        tenders
+    } : {}, changeCents ? {
+        changeCents
+    } : {}, whole(order.refundedCents) ? {
+        refundedCents: whole(order.refundedCents)
+    } : {}, context.footer ? {
+        footer: context.footer
+    } : {}, {
+        barcode: orderNumber
+    }, context.banner ? {
+        banner: context.banner
+    } : {});
+}
+
+//# sourceMappingURL=commerce-receipt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-receipt.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 { HostOrder } from './commerce-orders'\n\n/**\n * A receipt as DATA (AGL-3619), shared by every surface that prints one: the\n * cloud printer renderers (Star bytes, Epson ePOS-Print XML, plain text) and\n * the 80mm thermal receipt the register shows and prints from the browser\n * (AGL-3609). One model, so a reprint from the console, an auto-print on a\n * sale and the on-screen receipt cannot disagree about what was sold.\n *\n * Amounts are integer minor units in `currency`, and every label is already\n * the words to print: the renderers lay text out, they do not decide it.\n */\nexport interface ReceiptLine {\n  name: string\n  /** A variant label or SKU, printed under the name. */\n  detail?: string\n  quantity: number\n  unitCents: number\n  totalCents: number\n}\n\nexport interface ReceiptTender {\n  /** e.g. `Cash`, `Visa •••• 4242`, `Gift card`. */\n  label: string\n  amountCents: number\n}\n\nexport interface ReceiptData {\n  storeName: string\n  /** Address, phone or website lines under the store name. */\n  storeLines?: string[]\n  /** The printable order number, e.g. `1042`. */\n  orderNumber: string\n  orderId?: string\n  createdAtMs: number\n  /** IANA zone the timestamp is printed in; UTC when absent. */\n  timeZone?: string\n  registerName?: string\n  cashierName?: string\n  /** ISO 4217, any case. */\n  currency: string\n  lines: ReceiptLine[]\n  subtotalCents: number\n  discountCents?: number\n  shippingCents?: number\n  taxCents?: number\n  tipCents?: number\n  totalCents: number\n  tenders?: ReceiptTender[]\n  changeCents?: number\n  refundedCents?: number\n  /** Printed small at the bottom: a returns policy, a thank-you. */\n  footer?: string\n  /** Code128 under the totals so a return can scan the order back up. Defaults to the order number. */\n  barcode?: string\n  /** `REPRINT` / `COPY` banner. */\n  banner?: string\n}\n\n/** A money amount for print: `$12.50`, `-€3.00`. Locale is fixed so receipts read the same everywhere. */\nexport function formatReceiptMoney(cents: number, currency: string): string {\n  const code = String(currency || 'usd').toUpperCase()\n  const safe = Number.isFinite(cents) ? Math.round(cents) : 0\n  try {\n    const digits = new Intl.NumberFormat('en-US', { style: 'currency', currency: code })\n      .resolvedOptions().maximumFractionDigits ?? 2\n    return new Intl.NumberFormat('en-US', {\n      style: 'currency',\n      currency: code,\n      minimumFractionDigits: digits,\n      maximumFractionDigits: digits,\n    }).format(safe / 10 ** digits)\n  } catch {\n    return `${(safe / 100).toFixed(2)} ${code}`\n  }\n}\n\n/** The receipt timestamp, e.g. `Oct 6, 2026, 3:04 PM`. */\nexport function formatReceiptTime(atMs: number, timeZone?: string): string {\n  const options: Intl.DateTimeFormatOptions = {\n    year: 'numeric',\n    month: 'short',\n    day: 'numeric',\n    hour: 'numeric',\n    minute: '2-digit',\n  }\n  try {\n    return new Intl.DateTimeFormat('en-US', { ...options, timeZone: timeZone || 'UTC' }).format(\n      new Date(atMs),\n    )\n  } catch {\n    return new Intl.DateTimeFormat('en-US', { ...options, timeZone: 'UTC' }).format(new Date(atMs))\n  }\n}\n\nconst PAYMENT_METHOD_LABELS: Record<string, string> = {\n  cash: 'Cash',\n  card_present: 'Card',\n  card_keyed: 'Card',\n  card_link: 'Card',\n  gift_card: 'Gift card',\n  folio: 'Charged to room',\n}\n\nconst whole = (value: unknown): number => {\n  const number = Math.round(Number(value))\n  return Number.isFinite(number) && number > 0 ? number : 0\n}\n\n/**\n * The tenders an order was paid with: the register's payment ledger\n * (`payments[]`, AGL-3607) when the order has one, otherwise a single tender\n * read from the order itself (a cash sale's `changeCents`, a QR card sale).\n */\nexport function receiptTendersFromOrder(order: HostOrder & Record<string, any>): {\n  tenders: ReceiptTender[]\n  changeCents: number\n  tipCents: number\n} {\n  const payments: any[] = Array.isArray(order['payments']) ? order['payments'] : []\n  if (payments.length) {\n    let changeCents = 0\n    let tipCents = 0\n    const tenders = payments\n      .filter((payment) => payment && payment.status === 'succeeded')\n      .map((payment) => {\n        changeCents += whole(payment.changeCents)\n        tipCents += whole(payment.tipCents)\n        const card = [payment.cardBrand, payment.last4 ? `**** ${payment.last4}` : '']\n          .filter(Boolean)\n          .join(' ')\n        const label = card || PAYMENT_METHOD_LABELS[String(payment.method)] || 'Payment'\n        const tendered = whole(payment.cashTenderedCents)\n        return {\n          label,\n          amountCents: tendered || whole(payment.amountCents) + whole(payment.tipCents),\n        }\n      })\n    return { tenders, changeCents, tipCents }\n  }\n  const totalCents = whole(order.totals?.totalCents)\n  const changeCents = whole(order['changeCents'])\n  if (!totalCents) return { tenders: [], changeCents: 0, tipCents: 0 }\n  const isCash = order.channel === 'pos' && !order.checkoutSessionId && !order.paymentIntentId\n  return {\n    tenders: [\n      {\n        label: order['reservationId'] ? 'Charged to room' : isCash ? 'Cash' : 'Card',\n        amountCents: totalCents + (isCash ? changeCents : 0),\n      },\n    ],\n    changeCents: isCash ? changeCents : 0,\n    tipCents: 0,\n  }\n}\n\nexport interface ReceiptContext {\n  storeName: string\n  storeLines?: string[]\n  registerName?: string\n  cashierName?: string\n  timeZone?: string\n  currency?: string\n  footer?: string\n  banner?: string\n}\n\n/** The receipt an order prints, from the order as stored. */\nexport function receiptDataFromOrder(\n  orderId: string,\n  order: HostOrder & Record<string, any>,\n  context: ReceiptContext,\n): ReceiptData {\n  const lines: ReceiptLine[] = (order.lineItems ?? []).map((line) => {\n    const quantity = Math.max(1, Math.round(Number(line.quantity) || 1))\n    const unitCents = Math.round(Number(line.unitAmountCents) || 0)\n    return {\n      name: String(line.name ?? 'Item'),\n      ...(line.variantLabel ? { detail: String(line.variantLabel) } : {}),\n      quantity,\n      unitCents,\n      totalCents: unitCents * quantity,\n    }\n  })\n  const totals = order.totals\n  const subtotalCents = totals?.itemsCents ?? lines.reduce((sum, line) => sum + line.totalCents, 0)\n  const { tenders, changeCents, tipCents } = receiptTendersFromOrder(order)\n  const tip = whole((totals as any)?.tipCents) || tipCents\n  const orderNumber = order.number ? String(order.number) : orderId.slice(0, 8).toUpperCase()\n  return {\n    storeName: context.storeName,\n    ...(context.storeLines?.length ? { storeLines: context.storeLines } : {}),\n    orderNumber,\n    orderId,\n    createdAtMs: Number(order['createdAtMs']) || Date.now(),\n    ...(context.timeZone ? { timeZone: context.timeZone } : {}),\n    ...(context.registerName ? { registerName: context.registerName } : {}),\n    ...(context.cashierName ? { cashierName: context.cashierName } : {}),\n    currency: String(order['currency'] ?? context.currency ?? 'usd'),\n    lines,\n    subtotalCents,\n    ...(totals?.discountCents ? { discountCents: totals.discountCents } : {}),\n    ...(totals?.shippingCents ? { shippingCents: totals.shippingCents } : {}),\n    ...(totals?.taxCents ? { taxCents: totals.taxCents } : {}),\n    ...(tip ? { tipCents: tip } : {}),\n    totalCents: totals?.totalCents ?? subtotalCents,\n    ...(tenders.length ? { tenders } : {}),\n    ...(changeCents ? { changeCents } : {}),\n    ...(whole(order.refundedCents) ? { refundedCents: whole(order.refundedCents) } : {}),\n    ...(context.footer ? { footer: context.footer } : {}),\n    barcode: orderNumber,\n    ...(context.banner ? { banner: context.banner } : {}),\n  }\n}\n"],"names":["formatReceiptMoney","cents","currency","code","String","toUpperCase","safe","Number","isFinite","Math","round","digits","Intl","NumberFormat","style","resolvedOptions","maximumFractionDigits","minimumFractionDigits","format","toFixed","formatReceiptTime","atMs","timeZone","options","year","month","day","hour","minute","DateTimeFormat","Date","PAYMENT_METHOD_LABELS","cash","card_present","card_keyed","card_link","gift_card","folio","whole","value","number","receiptTendersFromOrder","order","payments","Array","isArray","length","changeCents","tipCents","tenders","filter","payment","status","map","card","cardBrand","last4","Boolean","join","label","method","tendered","cashTenderedCents","amountCents","totalCents","totals","isCash","channel","checkoutSessionId","paymentIntentId","receiptDataFromOrder","orderId","context","lines","lineItems","line","quantity","max","unitCents","unitAmountCents","name","variantLabel","detail","subtotalCents","itemsCents","reduce","sum","tip","orderNumber","slice","storeName","storeLines","createdAtMs","now","registerName","cashierName","discountCents","shippingCents","taxCents","refundedCents","footer","barcode","banner"],"mappings":"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"}

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

@@ -0,0 +1,207 @@
+/**
+ * @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 { ProductType } from './commerce';
+import { type HostOrder } from './commerce-orders';
+/**
+ * Returns (RMA, AGL-3611): `hosts/{hostId}/returns/{id}`.
+ *
+ * A buyer asks to send items back, from their account or the order-status
+ * page; the merchant approves or declines, receives the parcel and decides
+ * per line whether it goes back on the shelf, then refunds through the
+ * order's own refund route. The return is the record of all of that, so the
+ * order keeps meaning what it always meant and the money still moves through
+ * the one door that guards it.
+ *
+ * Every rule here is pure and shared by the buyer's route, the merchant's
+ * route and the console, so the three cannot disagree about what is
+ * returnable.
+ */
+export type ReturnStatus = 'requested' | 'approved' | 'declined' | 'received' | 'refunded' | 'closed';
+export declare const RETURN_STATUSES: readonly ReturnStatus[];
+export declare const RETURN_STATUS_LABELS: Record<ReturnStatus, string>;
+export declare const RETURN_STATUS_COLOR: Record<ReturnStatus, 'default' | 'info' | 'warning' | 'success' | 'error'>;
+export type ReturnReason = 'damaged' | 'wrong_item' | 'not_as_described' | 'size_or_fit' | 'no_longer_needed' | 'other';
+export declare const RETURN_REASON_LABELS: Record<ReturnReason, string>;
+export declare const RETURN_REASONS: ReturnReason[];
+export interface ReturnLine {
+    lineItemId: number;
+    quantity: number;
+    reason: ReturnReason;
+    /** The line's name when the return was opened, for lists that read no order. */
+    name?: string;
+}
+/** A return label a shipping plugin bought for the buyer to send the parcel with. */
+export interface ReturnLabel {
+    carrier: string;
+    trackingNumber: string;
+    labelUrl: string;
+    trackingUrl?: string;
+    attachedAtMs: number;
+}
+/** What went back on the shelf when the parcel arrived. */
+export interface ReturnRestock {
+    lines: Array<{
+        lineItemId: number;
+        quantity: number;
+    }>;
+    /** The stock location the units went to, for a multi-location store. */
+    locationId?: string;
+    atMs: number;
+}
+export interface ReturnTimelineEvent {
+    atMs: number;
+    event: string;
+    detail?: string;
+}
+/** `hosts/{hostId}/returns/{id}`, written only by the server. */
+export interface HostReturn {
+    orderId: string;
+    /** The order's number, for the list, e.g. `#1042`. */
+    orderNumber: string;
+    customerEmail: string | null;
+    customerName: string | null;
+    lines: ReturnLine[];
+    status: ReturnStatus;
+    /** Who opened it: the buyer, or the merchant on their behalf. */
+    requestedBy: 'buyer' | 'merchant';
+    /**
+     * `register` for a return taken and refunded at a POS register (AGL-3609):
+     * it is created already `refunded`, and the register's own record under
+     * `registers/{registerId}/returns` holds the tenders it went back to.
+     */
+    source?: 'register';
+    registerId?: string;
+    customerNote?: string;
+    merchantNote?: string;
+    returnLabel?: ReturnLabel;
+    restock?: ReturnRestock;
+    /** When the refund went through the order's refund route, and for how much. */
+    refundedAtMs?: number;
+    refundCents?: number;
+    timeline: ReturnTimelineEvent[];
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+/** The store's return policy, at `hosts/{hostId}/settings/store` `returns`. */
+export interface StoreReturnSettings {
+    /** Whether buyers may ask for a return themselves. */
+    enabled: boolean;
+    /** Days after the order shipped (or was placed, if it never shipped). */
+    windowDays: number;
+    /** The product types a buyer may return. */
+    eligibleTypes: ProductType[];
+}
+export declare const DEFAULT_RETURN_SETTINGS: StoreReturnSettings;
+/** The most days a window may be set to, and the most a note may hold. */
+export declare const RETURN_WINDOW_MAX_DAYS = 365;
+export declare const RETURN_NOTE_MAX = 1000;
+/** The stored settings, read defensively: the document is admin-writable. */
+export declare function readReturnSettings(raw: unknown): StoreReturnSettings;
+/** The return state machine. */
+export declare function canTransitionReturn(from: ReturnStatus, to: ReturnStatus): boolean;
+/** Whether a return still holds units against the order. */
+export declare function returnIsOpen(entry: Pick<HostReturn, 'status'>): boolean;
+/** Whether a return is still holding units, or took them: anything not declined. */
+export declare function returnHoldsUnits(entry: Pick<HostReturn, 'status' | 'refundedAtMs'>): boolean;
+/** Units each line could be sent back, and why not where none can. */
+export interface ReturnableLine {
+    lineItemId: number;
+    name: string;
+    variantLabel: string | null;
+    productType: ProductType | null;
+    /** Units the buyer has and may send back. */
+    returnable: number;
+    /** Why `returnable` is 0, in the buyer's words; `null` when it is not. */
+    blocked: string | null;
+}
+/**
+ * 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 declare function returnableLines(order: Pick<HostOrder, 'lineItems' | 'fulfillments' | 'refundedLineItemIds'>, existing: ReadonlyArray<Pick<HostReturn, 'status' | 'lines' | 'refundedAtMs'>>, settings: Pick<StoreReturnSettings, 'eligibleTypes'> | null): ReturnableLine[];
+/**
+ * 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 declare function returnWindowEndsAtMs(order: Pick<HostOrder, 'fulfillments' | 'createdAtMs'>, settings: Pick<StoreReturnSettings, 'windowDays'>): number | null;
+/** Why a requested return was refused. */
+export type ReturnRequestProblem = {
+    problem: 'disabled';
+} | {
+    problem: 'window_closed';
+    endedAtMs: number;
+} | {
+    problem: 'order_status';
+    status: string;
+} | {
+    problem: 'empty';
+} | {
+    problem: 'bad_line';
+    lineItemId: number;
+} | {
+    problem: 'bad_reason';
+    lineItemId: number;
+} | {
+    problem: 'too_many';
+    lineItemId: number;
+    returnable: number;
+};
+/** Order statuses a return may be opened against. */
+export declare const RETURNABLE_ORDER_STATUSES: readonly string[];
+/**
+ * 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 declare function validateReturnRequest(input: {
+    order: Pick<HostOrder, 'status' | 'lineItems' | 'fulfillments' | 'refundedLineItemIds' | 'createdAtMs'>;
+    existing: ReadonlyArray<Pick<HostReturn, 'status' | 'lines' | 'refundedAtMs'>>;
+    settings: StoreReturnSettings;
+    lines: ReadonlyArray<{
+        lineItemId: unknown;
+        quantity: unknown;
+        reason: unknown;
+    }>;
+    by: 'buyer' | 'merchant';
+    now: number;
+}): {
+    lines: ReturnLine[];
+} | ReturnRequestProblem;
+/** Words for a refused request, for the buyer and the merchant alike. */
+export declare function describeReturnRequestProblem(problem: ReturnRequestProblem): string;
+/**
+ * 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 declare function returnRefundCents(order: Pick<HostOrder, 'lineItems' | 'totals' | 'refundedCents' | 'amountCents'>, lines: ReadonlyArray<Pick<ReturnLine, 'lineItemId' | 'quantity'>>): number;
+/**
+ * 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 declare function returnWholeLineIds(order: Pick<HostOrder, 'lineItems'>, lines: ReadonlyArray<Pick<ReturnLine, 'lineItemId' | 'quantity'>>): number[];
+/** A short "2× Mug, 1× Shirt" for a return's lines. */
+export declare function describeReturnLines(order: Pick<HostOrder, 'lineItems'>, lines: ReadonlyArray<Pick<ReturnLine, 'lineItemId' | 'quantity'>>): string;
+/** The order number a return lists by. */
+export declare function returnOrderNumber(order: Pick<HostOrder, 'number'>, orderId: string): string;
+/** Appends a return timeline event immutably. */
+export declare function appendReturnEvent(entry: Pick<HostReturn, 'timeline'>, event: string, detail?: string, atMs?: number): ReturnTimelineEvent[];