@aglyn/plugins-commerce 1.0.0-beta.230 → 1.0.0-beta.232

package/src/lib/model/order-fulfillment.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/order-fulfillment.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Quantity-level fulfillment (AGL-3611).\n *\n * A fulfillment used to name whole lines (`lineItemIds`), so \"ship 2 of the 5\n * mugs now, the rest next week\" could not be said. A fulfillment now carries\n * `lines: [{ lineItemId, quantity }]`; one written before that reads as every\n * unit of each line it named, which is what it meant when it was written.\n *\n * Every figure here is computed from the order's own fulfillments, so the\n * server's transaction and the console's panel ask the same question of the\n * same record and cannot disagree about what is left to ship.\n */\n\nimport type {\n  HostOrder,\n  OrderFulfillment,\n  OrderLineItem,\n  OrderStatus,\n} from './commerce-orders'\n\n/** One line of a fulfillment: which order line, and how many of its units. */\nexport interface OrderFulfillmentLine {\n  /** The line's index in `order.lineItems`. */\n  lineItemId: number\n  quantity: number\n}\n\n/** A fulfillment's lifecycle; absent reads as `active`. */\nexport type OrderFulfillmentStatus = 'active' | 'cancelled'\n\n/**\n * Whether a line has to be shipped at all. Digital goods and services are\n * delivered by other means, so they never hold an order in\n * `partially_fulfilled`. A line with no recorded type predates types and is\n * treated as physical, the only reading that cannot close an order early.\n */\nexport function lineRequiresShipping(line: Pick<OrderLineItem, 'productType'>): boolean {\n  return line.productType !== 'digital' && line.productType !== 'service'\n}\n\nconst wholeUnits = (value: unknown): number => {\n  const units = Math.floor(Number(value ?? 0))\n  return Number.isFinite(units) && units > 0 ? units : 0\n}\n\n/** Whether a fulfillment still counts: a cancelled one ships nothing. */\nexport function fulfillmentIsActive(fulfillment: Partial<OrderFulfillment> | null | undefined): boolean {\n  return Boolean(fulfillment) && fulfillment?.status !== 'cancelled'\n}\n\n/**\n * The units one fulfillment covers, per line. A legacy fulfillment (no\n * `lines`) covers every unit of each line it names.\n */\nexport function fulfillmentLineQuantities(\n  order: Pick<HostOrder, 'lineItems'>,\n  fulfillment: Partial<OrderFulfillment>,\n): OrderFulfillmentLine[] {\n  const lines = order.lineItems ?? []\n  if (Array.isArray(fulfillment.lines) && fulfillment.lines.length > 0) {\n    return fulfillment.lines\n      .map((entry) => ({\n        lineItemId: Math.round(Number(entry?.lineItemId)),\n        quantity: wholeUnits(entry?.quantity),\n      }))\n      .filter(\n        (entry) =>\n          Number.isInteger(entry.lineItemId) &&\n          entry.lineItemId >= 0 &&\n          entry.lineItemId < lines.length &&\n          entry.quantity > 0,\n      )\n  }\n  return (fulfillment.lineItemIds ?? [])\n    .map((index) => Math.round(Number(index)))\n    .filter((index) => Number.isInteger(index) && index >= 0 && index < lines.length)\n    .map((index) => ({ lineItemId: index, quantity: wholeUnits(lines[index]?.quantity) }))\n    .filter((entry) => entry.quantity > 0)\n}\n\n/** Units already fulfilled per line index, over every active fulfillment. */\nexport function fulfilledQuantities(order: Pick<HostOrder, 'lineItems' | 'fulfillments'>): Map<number, number> {\n  const totals = new Map<number, number>()\n  for (const fulfillment of order.fulfillments ?? []) {\n    if (!fulfillmentIsActive(fulfillment)) continue\n    for (const entry of fulfillmentLineQuantities(order, fulfillment)) {\n      totals.set(entry.lineItemId, (totals.get(entry.lineItemId) ?? 0) + entry.quantity)\n    }\n  }\n  return totals\n}\n\n/** A line as the fulfillment panel and the server both reason about it. */\nexport interface OrderLineFulfillmentState {\n  lineItemId: number\n  quantity: number\n  fulfilledQuantity: number\n  remainingQuantity: number\n  requiresShipping: boolean\n}\n\n/** Every line's fulfilled and remaining units. */\nexport function orderLineFulfillmentStates(\n  order: Pick<HostOrder, 'lineItems' | 'fulfillments'>,\n): OrderLineFulfillmentState[] {\n  const fulfilled = fulfilledQuantities(order)\n  return (order.lineItems ?? []).map((line, index) => {\n    const quantity = wholeUnits(line.quantity)\n    const done = Math.min(quantity, fulfilled.get(index) ?? 0)\n    return {\n      lineItemId: index,\n      quantity,\n      fulfilledQuantity: done,\n      remainingQuantity: quantity - done,\n      requiresShipping: lineRequiresShipping(line),\n    }\n  })\n}\n\n/**\n * What is left to ship: every shippable line's remaining units. This is what\n * a \"fulfill everything\" request covers.\n */\nexport function remainingFulfillmentLines(\n  order: Pick<HostOrder, 'lineItems' | 'fulfillments'>,\n): OrderFulfillmentLine[] {\n  return orderLineFulfillmentStates(order)\n    .filter((state) => state.requiresShipping && state.remainingQuantity > 0)\n    .map((state) => ({ lineItemId: state.lineItemId, quantity: state.remainingQuantity }))\n}\n\n/** Why a requested set of fulfillment lines was refused. */\nexport type FulfillmentLinesProblem =\n  | { problem: 'empty' }\n  | { problem: 'unknown_line'; lineItemId: number }\n  | { problem: 'bad_quantity'; lineItemId: number }\n  | { problem: 'over_fulfilled'; lineItemId: number; remaining: number; requested: number }\n\n/**\n * Validates and merges a requested set of lines against what is left.\n *\n * Duplicate entries for one line are summed before the check, so a request\n * cannot slip past the remaining count by naming the line twice. A digital\n * or service line may be fulfilled (a merchant marking a service done), but\n * never beyond its quantity.\n */\nexport function resolveFulfillmentLines(\n  order: Pick<HostOrder, 'lineItems' | 'fulfillments'>,\n  requested: ReadonlyArray<{ lineItemId: unknown; quantity: unknown }>,\n): { lines: OrderFulfillmentLine[] } | FulfillmentLinesProblem {\n  const states = orderLineFulfillmentStates(order)\n  const merged = new Map<number, number>()\n  for (const entry of requested) {\n    const lineItemId = Number(entry?.lineItemId)\n    if (!Number.isInteger(lineItemId) || lineItemId < 0 || lineItemId >= states.length) {\n      return { problem: 'unknown_line', lineItemId: Number.isFinite(lineItemId) ? lineItemId : -1 }\n    }\n    const quantity = Number(entry?.quantity)\n    if (!Number.isInteger(quantity) || quantity <= 0) {\n      return { problem: 'bad_quantity', lineItemId }\n    }\n    merged.set(lineItemId, (merged.get(lineItemId) ?? 0) + quantity)\n  }\n  if (merged.size === 0) return { problem: 'empty' }\n  const lines: OrderFulfillmentLine[] = []\n  for (const [lineItemId, quantity] of [...merged.entries()].sort((a, b) => a[0] - b[0])) {\n    const remaining = states[lineItemId].remainingQuantity\n    if (quantity > remaining) {\n      return { problem: 'over_fulfilled', lineItemId, remaining, requested: quantity }\n    }\n    lines.push({ lineItemId, quantity })\n  }\n  return { lines }\n}\n\n/** Words for a refused request, for the console and the API. */\nexport function describeFulfillmentLinesProblem(problem: FulfillmentLinesProblem): string {\n  switch (problem.problem) {\n    case 'empty':\n      return 'Choose at least one item to fulfill'\n    case 'unknown_line':\n      return `Line ${problem.lineItemId} is not on this order`\n    case 'bad_quantity':\n      return `The quantity for line ${problem.lineItemId} must be a whole number above zero`\n    case 'over_fulfilled':\n      return problem.remaining === 0\n        ? `Line ${problem.lineItemId} is already fully fulfilled`\n        : `Line ${problem.lineItemId} has only ${problem.remaining} left to fulfill, not ${problem.requested}`\n  }\n}\n\n/**\n * The status an order's fulfillments put it in: `fulfilled` once every\n * shippable unit is covered, `partially_fulfilled` while some are, and\n * `paid` when none are. An order with nothing to ship reads as `fulfilled`\n * once anything at all was recorded against it, and as `paid` before.\n */\nexport function statusFromFulfillments(\n  order: Pick<HostOrder, 'lineItems' | 'fulfillments'>,\n): Extract<OrderStatus, 'paid' | 'partially_fulfilled' | 'fulfilled'> {\n  const states = orderLineFulfillmentStates(order)\n  const shippable = states.filter((state) => state.requiresShipping)\n  const anything = states.some((state) => state.fulfilledQuantity > 0)\n  if (shippable.length === 0) return anything ? 'fulfilled' : 'paid'\n  if (shippable.every((state) => state.remainingQuantity === 0)) return 'fulfilled'\n  return shippable.some((state) => state.fulfilledQuantity > 0) || anything\n    ? 'partially_fulfilled'\n    : 'paid'\n}\n\n/** Statuses whose fulfillments may still be added to, edited or cancelled. */\nconst FULFILLMENT_OPEN_STATUSES: readonly OrderStatus[] = ['paid', 'partially_fulfilled', 'fulfilled']\n\n/**\n * Whether a fulfillment on this order may be edited or cancelled. A delivered,\n * refunded or cancelled order is history: its fulfillments are what happened.\n */\nexport function orderFulfillmentsEditable(order: Pick<HostOrder, 'status'>): boolean {\n  return FULFILLMENT_OPEN_STATUSES.includes(order.status)\n}\n\n/** A short \"2× Mug, 1× Shirt\" for a fulfillment, for timelines and emails. */\nexport function describeFulfillmentLines(\n  order: Pick<HostOrder, 'lineItems'>,\n  lines: readonly OrderFulfillmentLine[],\n): string {\n  return lines\n    .map((entry) => `${entry.quantity}× ${order.lineItems?.[entry.lineItemId]?.name ?? `line ${entry.lineItemId}`}`)\n    .join(', ')\n}\n\n/** The carriers the console offers by name; anything else is typed under Other. */\nexport const FULFILLMENT_CARRIER_CHOICES: readonly string[] = [\n  'USPS',\n  'UPS',\n  'FedEx',\n  'DHL',\n  'Canada Post',\n  'Royal Mail',\n  'Australia Post',\n]\n\n/** What a merchant reads for a carrier's tracking status (AGL-3612). */\nconst TRACKING_STATUS_LABELS: Readonly<Record<string, string>> = {\n  pre_transit: 'Label created',\n  in_transit: 'In transit',\n  out_for_delivery: 'Out for delivery',\n  delivered: 'Delivered',\n  exception: 'Delivery problem',\n  returned: 'Returned to sender',\n}\n\n/** The words for a fulfillment's `trackingStatus`, or the status itself. */\nexport function trackingStatusLabel(status: string | undefined | null): string {\n  return status ? TRACKING_STATUS_LABELS[status] ?? status : ''\n}\n"],"names":["lineRequiresShipping","line","productType","wholeUnits","value","units","Math","floor","Number","isFinite","fulfillmentIsActive","fulfillment","Boolean","status","fulfillmentLineQuantities","order","lines","lineItems","Array","isArray","length","map","entry","lineItemId","round","quantity","filter","isInteger","lineItemIds","index","fulfilledQuantities","totals","Map","fulfillments","set","get","orderLineFulfillmentStates","fulfilled","done","min","fulfilledQuantity","remainingQuantity","requiresShipping","remainingFulfillmentLines","state","resolveFulfillmentLines","requested","states","merged","problem","size","entries","sort","a","b","remaining","push","describeFulfillmentLinesProblem","statusFromFulfillments","shippable","anything","some","every","FULFILLMENT_OPEN_STATUSES","orderFulfillmentsEditable","includes","describeFulfillmentLines","name","join","FULFILLMENT_CARRIER_CHOICES","TRACKING_STATUS_LABELS","pre_transit","in_transit","out_for_delivery","delivered","exception","returned","trackingStatusLabel"],"mappings":"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"}

package/src/lib/model/order-history.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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 { OrderEventOrder } from './order-events';
+/**
+ * A site's order HISTORY, for another plugin (AGL-3614).
+ *
+ * The order events (`order-events.ts`) bring every order from the moment a
+ * subscriber listens. A plugin that must also read the orders BEFORE that —
+ * accounting, posting a merchant's earlier sales from a start date — reads
+ * them through this service, in the same public shape the events carry, and
+ * never through commerce's storage. Commerce registers the one
+ * implementation from its console server declarations; a reader in another
+ * plugin restates this contract under the same id, as an event subscriber
+ * restates an event.
+ */
+/** One stored order, as the history hands it out. */
+export interface OrderHistoryEntry {
+    id: string;
+    createdAtMs: number;
+    /** When it was paid; `null` for one never paid. */
+    paidAtMs: number | null;
+    /** The newest refund on its timeline, or `null`. */
+    lastRefundAtMs: number | null;
+    /** Whether its prices include the tax. */
+    taxInclusive: boolean;
+    /** The tax rate it was charged under, when one was named. */
+    taxRateId: string | null;
+    /** The order in the public API's shape. */
+    order: OrderEventOrder;
+}
+export interface OrderHistoryPageRequest {
+    hostId: string;
+    /** Orders created at or after this… */
+    fromMs: number;
+    /** …and before this. */
+    untilMs: number;
+    /** At most this many, oldest first; capped at 200. */
+    limit: number;
+}
+export interface OrderHistoryReader {
+    listOrders(request: OrderHistoryPageRequest): Promise<OrderHistoryEntry[]>;
+}
+export declare const ORDER_HISTORY_CONTRACT_ID = "commerce.orderHistory";
+export declare const ORDER_HISTORY_CONTRACT: import("@aglyn/aglyn/src").PluginServiceContract<OrderHistoryReader>;

package/src/lib/model/order-history.js

@@ -0,0 +1,22 @@
+/**
+ * @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 { definePluginServiceContract } from "@aglyn/aglyn/plugin-manager/plugin-services";
+export const ORDER_HISTORY_CONTRACT_ID = 'commerce.orderHistory';
+export const ORDER_HISTORY_CONTRACT = definePluginServiceContract(ORDER_HISTORY_CONTRACT_ID, {
+    multiple: false
+});
+
+//# sourceMappingURL=order-history.js.map

package/src/lib/model/order-history.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/order-history.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 { definePluginServiceContract } from '@aglyn/aglyn/plugin-manager/plugin-services'\nimport type { OrderEventOrder } from './order-events'\n\n/**\n * A site's order HISTORY, for another plugin (AGL-3614).\n *\n * The order events (`order-events.ts`) bring every order from the moment a\n * subscriber listens. A plugin that must also read the orders BEFORE that —\n * accounting, posting a merchant's earlier sales from a start date — reads\n * them through this service, in the same public shape the events carry, and\n * never through commerce's storage. Commerce registers the one\n * implementation from its console server declarations; a reader in another\n * plugin restates this contract under the same id, as an event subscriber\n * restates an event.\n */\n\n/** One stored order, as the history hands it out. */\nexport interface OrderHistoryEntry {\n  id: string\n  createdAtMs: number\n  /** When it was paid; `null` for one never paid. */\n  paidAtMs: number | null\n  /** The newest refund on its timeline, or `null`. */\n  lastRefundAtMs: number | null\n  /** Whether its prices include the tax. */\n  taxInclusive: boolean\n  /** The tax rate it was charged under, when one was named. */\n  taxRateId: string | null\n  /** The order in the public API's shape. */\n  order: OrderEventOrder\n}\n\nexport interface OrderHistoryPageRequest {\n  hostId: string\n  /** Orders created at or after this… */\n  fromMs: number\n  /** …and before this. */\n  untilMs: number\n  /** At most this many, oldest first; capped at 200. */\n  limit: number\n}\n\nexport interface OrderHistoryReader {\n  listOrders(request: OrderHistoryPageRequest): Promise<OrderHistoryEntry[]>\n}\n\nexport const ORDER_HISTORY_CONTRACT_ID = 'commerce.orderHistory'\n\nexport const ORDER_HISTORY_CONTRACT = definePluginServiceContract<OrderHistoryReader>(ORDER_HISTORY_CONTRACT_ID, {\n  multiple: false,\n})\n"],"names":["definePluginServiceContract","ORDER_HISTORY_CONTRACT_ID","ORDER_HISTORY_CONTRACT","multiple"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,2BAA2B,QAAQ,8CAA6C;AA8CzF,OAAO,MAAMC,4BAA4B,wBAAuB;AAEhE,OAAO,MAAMC,yBAAyBF,4BAAgDC,2BAA2B;IAC/GE,UAAU;AACZ,GAAE"}

package/src/lib/model/order-list-fields.d.ts

@@ -76,5 +76,13 @@ export declare function orderListFields(order: object, docId: string, options?:
  * An order document with its list fields spread over it — what a creator
  * writes. The document's own `status` and `channel` win where it names them,
  * which every creator does; the rest is derived from it.
+ *
+ * A creator also stamps whether the order ships and when it last changed
+ * (`orderSyncFields`, AGL-3613): the query the shipping export and the
+ * ShipStation feed ask. Those stay OFF `orderListFields`, which the orders
+ * backfill restates field for field — they are not list columns.
  */
-export declare function withOrderListFields<T extends object>(docId: string, doc: T): T & OrderListFields;
+export declare function withOrderListFields<T extends object>(docId: string, doc: T): T & OrderListFields & {
+    requiresShipping: boolean;
+    updatedAtMs?: number;
+};

package/src/lib/model/order-list-fields.js

@@ -17,6 +17,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  */ import { emailSearchTokens } from "@aglyn/aglyn/app-utils/email-search";
 import { nameSearchKey, nameSearchTokens } from "@aglyn/aglyn/app-utils/name-search";
 import { describeOrderDispute } from "./commerce-dispute.js";
+import { orderSyncFields } from "./order-shipping-export.js";
 import { formatOrderNumber } from "./commerce-orders.js";
 /*
  * WHAT THE ORDERS LIST ASKS ITS QUERY, WRITTEN ON THE ORDER (AGL-3321).
@@ -105,8 +106,13 @@ const text = (value)=>typeof value === 'string' ? value : '';
  * An order document with its list fields spread over it — what a creator
  * writes. The document's own `status` and `channel` win where it names them,
  * which every creator does; the rest is derived from it.
+ *
+ * A creator also stamps whether the order ships and when it last changed
+ * (`orderSyncFields`, AGL-3613): the query the shipping export and the
+ * ShipStation feed ask. Those stay OFF `orderListFields`, which the orders
+ * backfill restates field for field — they are not list columns.
  */ export function withOrderListFields(docId, doc) {
-    return _extends({}, doc, orderListFields(doc, docId));
+    return _extends({}, doc, orderListFields(doc, docId), orderSyncFields(doc));
 }
 
 //# sourceMappingURL=order-list-fields.js.map

package/src/lib/model/order-list-fields.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/order-list-fields.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 { emailSearchTokens } from '@aglyn/aglyn/app-utils/email-search'\nimport {\n  nameSearchKey,\n  nameSearchTokens,\n} from '@aglyn/aglyn/app-utils/name-search'\nimport { describeOrderDispute, type OrderDisputeTone } from './commerce-dispute'\nimport {\n  formatOrderNumber,\n  type HostOrder,\n  type OrderChannel,\n  type OrderDispute,\n  type OrderStatus,\n} from './commerce-orders'\n\n/*\n * WHAT THE ORDERS LIST ASKS ITS QUERY, WRITTEN ON THE ORDER (AGL-3321).\n *\n * The orders list puts every filter and its search on the Firestore query,\n * and a query can only ask about a field a document stores. The list used to\n * derive five of its columns in the browser — a legacy order's status and\n * channel, the products in a cart, the dispute badge, the order number — and\n * match them over the two hundred rows it had read, which answered \"none\"\n * for an order on the next page.\n *\n * So every writer of `hosts/{hostId}/orders` spreads `orderListFields` over\n * the document it writes, computed from the whole document as it will stand:\n * the creators (cart, buy-now, subscription renewal, POS, draft) and every\n * write that moves an input — the dispute record, the address a paid draft\n * learns. A write that moves none of them (a status flip, a fulfillment, a\n * refund, a timeline note) moves none of these either: `status` is its own\n * field and is what the Status filter reads.\n *\n * `tools/scripts/backfill-orders-list-fields.mjs` restates this for the\n * orders written before it; the two answer the same worked examples,\n * `tools/scripts/lib/order-list-fields.fixtures.json`.\n */\n\n/** Tokens past this many are dropped from the quick search's array. */\nexport const ORDER_SEARCH_TOKEN_LIMIT = 200\n\n/** The fields the orders list's query reads, as every writer stamps them. */\nexport interface OrderListFields {\n  /**\n   * Always present. A Commerce Starter order (AGL-90) carried none and was\n   * read as `paid` (`liftLegacyOrder`); the lift is written down so the\n   * Status filter finds it.\n   */\n  status: OrderStatus\n  /** Always present; absent was always read as `online`. */\n  channel: OrderChannel\n  /**\n   * Every product the order holds, line items first and the legacy flat\n   * `productId` after — the Product filter's `array-contains-any`.\n   */\n  productIds: string[]\n  /**\n   * The dispute badge's tone (`describeOrderDispute`), or null with no\n   * dispute. `open` is a case with a deadline; `lost` a chargeback; `won` and\n   * `settled` closed with no money reversed. What the Disputes filter and the\n   * open-dispute banner ask.\n   */\n  disputeKey: OrderDisputeTone | null\n  /** The buyer's address, lower-cased — the Customer filter's `equals`. */\n  customerEmailLower: string | null\n  /** The address's search prefixes (`emailSearchTokens`) — its `contains`. */\n  customerEmailTokens: string[]\n  /** The order number's prefixes, with and without its `#` — Order `contains`. */\n  orderLabelTokens: string[]\n  /**\n   * The quick search: the order number's, the buyer's address's and every\n   * line item name's word prefixes, capped at {@link ORDER_SEARCH_TOKEN_LIMIT}\n   * with the item names cut first.\n   */\n  searchTokens: string[]\n}\n\n/** The dispute badge's tone, stored — see {@link OrderListFields.disputeKey}. */\nexport function orderDisputeKey(\n  dispute: OrderDispute | null | undefined,\n): OrderDisputeTone | null {\n  if (!dispute || typeof dispute !== 'object') return null\n  return describeOrderDispute({ dispute })?.tone ?? null\n}\n\n/**\n * The order number's prefixes, as `#1042` and as `1042`, so a reader who\n * types either finds it. An order with no number is labelled by its document\n * id (`formatOrderNumber`), and is found by that label the same way.\n */\nexport function orderLabelTokens(\n  order: Pick<Partial<HostOrder>, 'number'>,\n  docId: string,\n): string[] {\n  const label = nameSearchKey(formatOrderNumber({ number: order.number }, docId))\n  const bare = label.replace(/^#+/, '')\n  return nameSearchTokens(bare && bare !== label ? `${label} ${bare}` : label)\n}\n\nconst text = (value: unknown): string =>\n  typeof value === 'string' ? value : ''\n\n/**\n * The fields the orders list's query reads, from an order as it will be\n * stored — see {@link OrderListFields}. Pure: the same answer on the server,\n * in a spec and (restated) in the backfill.\n *\n * `legacyProductName` names the product of a Commerce Starter order, which\n * stored an id and no line items; only the backfill has it to give.\n */\nexport function orderListFields(\n  order: object,\n  docId: string,\n  options: { legacyProductName?: string } = {},\n): OrderListFields {\n  const source = order as Partial<HostOrder> & Record<string, unknown>\n  const lineItems = Array.isArray(source.lineItems) ? source.lineItems : []\n  const productIds = [\n    ...new Set(\n      [...lineItems.map((line) => line?.productId), source.productId].filter(\n        (id): id is string => typeof id === 'string' && id !== '',\n      ),\n    ),\n  ]\n  const email = text(source.customerEmail)\n  const emailTokens = emailSearchTokens(email)\n  const labelTokens = orderLabelTokens(source, docId)\n  const names = lineItems.map((line) => text(line?.name)).filter(Boolean)\n  if (!names.length && options.legacyProductName) {\n    names.push(options.legacyProductName)\n  }\n  const searchTokens = [\n    ...new Set([\n      ...labelTokens,\n      ...emailTokens,\n      ...names.flatMap((name) => nameSearchTokens(name)),\n    ]),\n  ].slice(0, ORDER_SEARCH_TOKEN_LIMIT)\n  return {\n    status: (text(source.status) || 'paid') as OrderStatus,\n    channel: (text(source.channel) || 'online') as OrderChannel,\n    productIds,\n    disputeKey: orderDisputeKey(source.dispute),\n    customerEmailLower: nameSearchKey(email) || null,\n    customerEmailTokens: emailTokens,\n    orderLabelTokens: labelTokens,\n    searchTokens,\n  }\n}\n\n/**\n * An order document with its list fields spread over it — what a creator\n * writes. The document's own `status` and `channel` win where it names them,\n * which every creator does; the rest is derived from it.\n */\nexport function withOrderListFields<T extends object>(\n  docId: string,\n  doc: T,\n): T & OrderListFields {\n  return { ...doc, ...orderListFields(doc, docId) }\n}\n"],"names":["emailSearchTokens","nameSearchKey","nameSearchTokens","describeOrderDispute","formatOrderNumber","ORDER_SEARCH_TOKEN_LIMIT","orderDisputeKey","dispute","tone","orderLabelTokens","order","docId","label","number","bare","replace","text","value","orderListFields","options","source","lineItems","Array","isArray","productIds","Set","map","line","productId","filter","id","email","customerEmail","emailTokens","labelTokens","names","name","Boolean","length","legacyProductName","push","searchTokens","flatMap","slice","status","channel","disputeKey","customerEmailLower","customerEmailTokens","withOrderListFields","doc"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,iBAAiB,QAAQ,sCAAqC;AACvE,SACEC,aAAa,EACbC,gBAAgB,QACX,qCAAoC;AAC3C,SAASC,oBAAoB,QAA+B,wBAAoB;AAChF,SACEC,iBAAiB,QAKZ,uBAAmB;AAE1B;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED,qEAAqE,GACrE,OAAO,MAAMC,2BAA2B,IAAG;AAsC3C,+EAA+E,GAC/E,OAAO,SAASC,gBACdC,OAAwC;;QAGjCJ;IADP,IAAI,CAACI,WAAW,OAAOA,YAAY,UAAU,OAAO;IACpD,gBAAOJ,wBAAAA,qBAAqB;QAAEI;IAAQ,uBAA/BJ,sBAAmCK,IAAI,mBAAI;AACpD;AAEA;;;;CAIC,GACD,OAAO,SAASC,iBACdC,KAAyC,EACzCC,KAAa;IAEb,MAAMC,QAAQX,cAAcG,kBAAkB;QAAES,QAAQH,MAAMG,MAAM;IAAC,GAAGF;IACxE,MAAMG,OAAOF,MAAMG,OAAO,CAAC,OAAO;IAClC,OAAOb,iBAAiBY,QAAQA,SAASF,QAAQ,GAAGA,MAAM,CAAC,EAAEE,MAAM,GAAGF;AACxE;AAEA,MAAMI,OAAO,CAACC,QACZ,OAAOA,UAAU,WAAWA,QAAQ;AAEtC;;;;;;;CAOC,GACD,OAAO,SAASC,gBACdR,KAAa,EACbC,KAAa,EACbQ,UAA0C,CAAC,CAAC;IAE5C,MAAMC,SAASV;IACf,MAAMW,YAAYC,MAAMC,OAAO,CAACH,OAAOC,SAAS,IAAID,OAAOC,SAAS,GAAG,EAAE;IACzE,MAAMG,aAAa;WACd,IAAIC,IACL;eAAIJ,UAAUK,GAAG,CAAC,CAACC,OAASA,wBAAAA,KAAMC,SAAS;YAAGR,OAAOQ,SAAS;SAAC,CAACC,MAAM,CACpE,CAACC,KAAqB,OAAOA,OAAO,YAAYA,OAAO;KAG5D;IACD,MAAMC,QAAQf,KAAKI,OAAOY,aAAa;IACvC,MAAMC,cAAcjC,kBAAkB+B;IACtC,MAAMG,cAAczB,iBAAiBW,QAAQT;IAC7C,MAAMwB,QAAQd,UAAUK,GAAG,CAAC,CAACC,OAASX,KAAKW,wBAAAA,KAAMS,IAAI,GAAGP,MAAM,CAACQ;IAC/D,IAAI,CAACF,MAAMG,MAAM,IAAInB,QAAQoB,iBAAiB,EAAE;QAC9CJ,MAAMK,IAAI,CAACrB,QAAQoB,iBAAiB;IACtC;IACA,MAAME,eAAe;WAChB,IAAIhB,IAAI;eACNS;eACAD;eACAE,MAAMO,OAAO,CAAC,CAACN,OAASlC,iBAAiBkC;SAC7C;KACF,CAACO,KAAK,CAAC,GAAGtC;IACX,OAAO;QACLuC,QAAS5B,KAAKI,OAAOwB,MAAM,KAAK;QAChCC,SAAU7B,KAAKI,OAAOyB,OAAO,KAAK;QAClCrB;QACAsB,YAAYxC,gBAAgBc,OAAOb,OAAO;QAC1CwC,oBAAoB9C,cAAc8B,UAAU;QAC5CiB,qBAAqBf;QACrBxB,kBAAkByB;QAClBO;IACF;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASQ,oBACdtC,KAAa,EACbuC,GAAM;IAEN,OAAO,aAAKA,KAAQhC,gBAAgBgC,KAAKvC;AAC3C"}
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/order-list-fields.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 { emailSearchTokens } from '@aglyn/aglyn/app-utils/email-search'\nimport {\n  nameSearchKey,\n  nameSearchTokens,\n} from '@aglyn/aglyn/app-utils/name-search'\nimport { describeOrderDispute, type OrderDisputeTone } from './commerce-dispute'\nimport { orderSyncFields } from './order-shipping-export'\nimport {\n  formatOrderNumber,\n  type HostOrder,\n  type OrderChannel,\n  type OrderDispute,\n  type OrderStatus,\n} from './commerce-orders'\n\n/*\n * WHAT THE ORDERS LIST ASKS ITS QUERY, WRITTEN ON THE ORDER (AGL-3321).\n *\n * The orders list puts every filter and its search on the Firestore query,\n * and a query can only ask about a field a document stores. The list used to\n * derive five of its columns in the browser — a legacy order's status and\n * channel, the products in a cart, the dispute badge, the order number — and\n * match them over the two hundred rows it had read, which answered \"none\"\n * for an order on the next page.\n *\n * So every writer of `hosts/{hostId}/orders` spreads `orderListFields` over\n * the document it writes, computed from the whole document as it will stand:\n * the creators (cart, buy-now, subscription renewal, POS, draft) and every\n * write that moves an input — the dispute record, the address a paid draft\n * learns. A write that moves none of them (a status flip, a fulfillment, a\n * refund, a timeline note) moves none of these either: `status` is its own\n * field and is what the Status filter reads.\n *\n * `tools/scripts/backfill-orders-list-fields.mjs` restates this for the\n * orders written before it; the two answer the same worked examples,\n * `tools/scripts/lib/order-list-fields.fixtures.json`.\n */\n\n/** Tokens past this many are dropped from the quick search's array. */\nexport const ORDER_SEARCH_TOKEN_LIMIT = 200\n\n/** The fields the orders list's query reads, as every writer stamps them. */\nexport interface OrderListFields {\n  /**\n   * Always present. A Commerce Starter order (AGL-90) carried none and was\n   * read as `paid` (`liftLegacyOrder`); the lift is written down so the\n   * Status filter finds it.\n   */\n  status: OrderStatus\n  /** Always present; absent was always read as `online`. */\n  channel: OrderChannel\n  /**\n   * Every product the order holds, line items first and the legacy flat\n   * `productId` after — the Product filter's `array-contains-any`.\n   */\n  productIds: string[]\n  /**\n   * The dispute badge's tone (`describeOrderDispute`), or null with no\n   * dispute. `open` is a case with a deadline; `lost` a chargeback; `won` and\n   * `settled` closed with no money reversed. What the Disputes filter and the\n   * open-dispute banner ask.\n   */\n  disputeKey: OrderDisputeTone | null\n  /** The buyer's address, lower-cased — the Customer filter's `equals`. */\n  customerEmailLower: string | null\n  /** The address's search prefixes (`emailSearchTokens`) — its `contains`. */\n  customerEmailTokens: string[]\n  /** The order number's prefixes, with and without its `#` — Order `contains`. */\n  orderLabelTokens: string[]\n  /**\n   * The quick search: the order number's, the buyer's address's and every\n   * line item name's word prefixes, capped at {@link ORDER_SEARCH_TOKEN_LIMIT}\n   * with the item names cut first.\n   */\n  searchTokens: string[]\n}\n\n/** The dispute badge's tone, stored — see {@link OrderListFields.disputeKey}. */\nexport function orderDisputeKey(\n  dispute: OrderDispute | null | undefined,\n): OrderDisputeTone | null {\n  if (!dispute || typeof dispute !== 'object') return null\n  return describeOrderDispute({ dispute })?.tone ?? null\n}\n\n/**\n * The order number's prefixes, as `#1042` and as `1042`, so a reader who\n * types either finds it. An order with no number is labelled by its document\n * id (`formatOrderNumber`), and is found by that label the same way.\n */\nexport function orderLabelTokens(\n  order: Pick<Partial<HostOrder>, 'number'>,\n  docId: string,\n): string[] {\n  const label = nameSearchKey(formatOrderNumber({ number: order.number }, docId))\n  const bare = label.replace(/^#+/, '')\n  return nameSearchTokens(bare && bare !== label ? `${label} ${bare}` : label)\n}\n\nconst text = (value: unknown): string =>\n  typeof value === 'string' ? value : ''\n\n/**\n * The fields the orders list's query reads, from an order as it will be\n * stored — see {@link OrderListFields}. Pure: the same answer on the server,\n * in a spec and (restated) in the backfill.\n *\n * `legacyProductName` names the product of a Commerce Starter order, which\n * stored an id and no line items; only the backfill has it to give.\n */\nexport function orderListFields(\n  order: object,\n  docId: string,\n  options: { legacyProductName?: string } = {},\n): OrderListFields {\n  const source = order as Partial<HostOrder> & Record<string, unknown>\n  const lineItems = Array.isArray(source.lineItems) ? source.lineItems : []\n  const productIds = [\n    ...new Set(\n      [...lineItems.map((line) => line?.productId), source.productId].filter(\n        (id): id is string => typeof id === 'string' && id !== '',\n      ),\n    ),\n  ]\n  const email = text(source.customerEmail)\n  const emailTokens = emailSearchTokens(email)\n  const labelTokens = orderLabelTokens(source, docId)\n  const names = lineItems.map((line) => text(line?.name)).filter(Boolean)\n  if (!names.length && options.legacyProductName) {\n    names.push(options.legacyProductName)\n  }\n  const searchTokens = [\n    ...new Set([\n      ...labelTokens,\n      ...emailTokens,\n      ...names.flatMap((name) => nameSearchTokens(name)),\n    ]),\n  ].slice(0, ORDER_SEARCH_TOKEN_LIMIT)\n  return {\n    status: (text(source.status) || 'paid') as OrderStatus,\n    channel: (text(source.channel) || 'online') as OrderChannel,\n    productIds,\n    disputeKey: orderDisputeKey(source.dispute),\n    customerEmailLower: nameSearchKey(email) || null,\n    customerEmailTokens: emailTokens,\n    orderLabelTokens: labelTokens,\n    searchTokens,\n  }\n}\n\n/**\n * An order document with its list fields spread over it — what a creator\n * writes. The document's own `status` and `channel` win where it names them,\n * which every creator does; the rest is derived from it.\n *\n * A creator also stamps whether the order ships and when it last changed\n * (`orderSyncFields`, AGL-3613): the query the shipping export and the\n * ShipStation feed ask. Those stay OFF `orderListFields`, which the orders\n * backfill restates field for field — they are not list columns.\n */\nexport function withOrderListFields<T extends object>(\n  docId: string,\n  doc: T,\n): T & OrderListFields & { requiresShipping: boolean; updatedAtMs?: number } {\n  return { ...doc, ...orderListFields(doc, docId), ...orderSyncFields(doc) }\n}\n"],"names":["emailSearchTokens","nameSearchKey","nameSearchTokens","describeOrderDispute","orderSyncFields","formatOrderNumber","ORDER_SEARCH_TOKEN_LIMIT","orderDisputeKey","dispute","tone","orderLabelTokens","order","docId","label","number","bare","replace","text","value","orderListFields","options","source","lineItems","Array","isArray","productIds","Set","map","line","productId","filter","id","email","customerEmail","emailTokens","labelTokens","names","name","Boolean","length","legacyProductName","push","searchTokens","flatMap","slice","status","channel","disputeKey","customerEmailLower","customerEmailTokens","withOrderListFields","doc"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,iBAAiB,QAAQ,sCAAqC;AACvE,SACEC,aAAa,EACbC,gBAAgB,QACX,qCAAoC;AAC3C,SAASC,oBAAoB,QAA+B,wBAAoB;AAChF,SAASC,eAAe,QAAQ,6BAAyB;AACzD,SACEC,iBAAiB,QAKZ,uBAAmB;AAE1B;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED,qEAAqE,GACrE,OAAO,MAAMC,2BAA2B,IAAG;AAsC3C,+EAA+E,GAC/E,OAAO,SAASC,gBACdC,OAAwC;;QAGjCL;IADP,IAAI,CAACK,WAAW,OAAOA,YAAY,UAAU,OAAO;IACpD,gBAAOL,wBAAAA,qBAAqB;QAAEK;IAAQ,uBAA/BL,sBAAmCM,IAAI,mBAAI;AACpD;AAEA;;;;CAIC,GACD,OAAO,SAASC,iBACdC,KAAyC,EACzCC,KAAa;IAEb,MAAMC,QAAQZ,cAAcI,kBAAkB;QAAES,QAAQH,MAAMG,MAAM;IAAC,GAAGF;IACxE,MAAMG,OAAOF,MAAMG,OAAO,CAAC,OAAO;IAClC,OAAOd,iBAAiBa,QAAQA,SAASF,QAAQ,GAAGA,MAAM,CAAC,EAAEE,MAAM,GAAGF;AACxE;AAEA,MAAMI,OAAO,CAACC,QACZ,OAAOA,UAAU,WAAWA,QAAQ;AAEtC;;;;;;;CAOC,GACD,OAAO,SAASC,gBACdR,KAAa,EACbC,KAAa,EACbQ,UAA0C,CAAC,CAAC;IAE5C,MAAMC,SAASV;IACf,MAAMW,YAAYC,MAAMC,OAAO,CAACH,OAAOC,SAAS,IAAID,OAAOC,SAAS,GAAG,EAAE;IACzE,MAAMG,aAAa;WACd,IAAIC,IACL;eAAIJ,UAAUK,GAAG,CAAC,CAACC,OAASA,wBAAAA,KAAMC,SAAS;YAAGR,OAAOQ,SAAS;SAAC,CAACC,MAAM,CACpE,CAACC,KAAqB,OAAOA,OAAO,YAAYA,OAAO;KAG5D;IACD,MAAMC,QAAQf,KAAKI,OAAOY,aAAa;IACvC,MAAMC,cAAclC,kBAAkBgC;IACtC,MAAMG,cAAczB,iBAAiBW,QAAQT;IAC7C,MAAMwB,QAAQd,UAAUK,GAAG,CAAC,CAACC,OAASX,KAAKW,wBAAAA,KAAMS,IAAI,GAAGP,MAAM,CAACQ;IAC/D,IAAI,CAACF,MAAMG,MAAM,IAAInB,QAAQoB,iBAAiB,EAAE;QAC9CJ,MAAMK,IAAI,CAACrB,QAAQoB,iBAAiB;IACtC;IACA,MAAME,eAAe;WAChB,IAAIhB,IAAI;eACNS;eACAD;eACAE,MAAMO,OAAO,CAAC,CAACN,OAASnC,iBAAiBmC;SAC7C;KACF,CAACO,KAAK,CAAC,GAAGtC;IACX,OAAO;QACLuC,QAAS5B,KAAKI,OAAOwB,MAAM,KAAK;QAChCC,SAAU7B,KAAKI,OAAOyB,OAAO,KAAK;QAClCrB;QACAsB,YAAYxC,gBAAgBc,OAAOb,OAAO;QAC1CwC,oBAAoB/C,cAAc+B,UAAU;QAC5CiB,qBAAqBf;QACrBxB,kBAAkByB;QAClBO;IACF;AACF;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASQ,oBACdtC,KAAa,EACbuC,GAAM;IAEN,OAAO,aAAKA,KAAQhC,gBAAgBgC,KAAKvC,QAAWR,gBAAgB+C;AACtE"}

package/src/lib/model/order-shipping-export.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @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 { HostOrder, OrderFulfillment, OrderLineItem } from './commerce-orders';
+/** Grams in one avoirdupois ounce. */
+export declare const GRAMS_PER_OUNCE = 28.349523125;
+/** Ounces in one pound. */
+export declare const OUNCES_PER_POUND = 16;
+/** A weight in grams as ounces, to two places. */
+export declare function gramsToOunces(grams: number): number;
+/** A weight in ounces as pounds, to two places. */
+export declare function ouncesToPounds(ounces: number): number;
+/**
+ * Whether an order has anything to put in a box.
+ *
+ * A line with no recorded type predates types and counts as physical, the
+ * reading that never hides an order a merchant has to ship. A register sale
+ * left the shop in the buyer's hands, so a POS order ships only when it was
+ * given a shipping address. A legacy Commerce Starter order with no lines
+ * ships when it carries an address.
+ */
+export declare function orderRequiresShipping(order: Partial<HostOrder>): boolean;
+/**
+ * The fields a CREATOR of an order stamps beside its list fields: whether it
+ * ships, and when it last changed — its creation, for a new order. Writers
+ * that change an order afterwards stamp `updatedAtMs` themselves; nothing
+ * else here moves after creation, because an order's lines never do.
+ */
+export declare function orderSyncFields(order: object): {
+    requiresShipping: boolean;
+    updatedAtMs?: number;
+};
+/** The number a shipping tool shows and sends back: `1042`, or the document id for an unnumbered order. */
+export declare function shippingOrderNumber(order: Pick<HostOrder, 'number'>, docId: string): string;
+/**
+ * Every spelling of an order a file or a ShipNotice may name it by: `1042`,
+ * `#1042` and the document id. What `parseShippingOrderRef` reads back.
+ */
+export declare function shippingOrderRefs(order: Pick<HostOrder, 'number'>, docId: string): string[];
+/** What a reference a tool sent back names: an order number, or a document id. */
+export declare function parseShippingOrderRef(value: unknown): {
+    number?: number;
+    id?: string;
+} | null;
+/** A product's weights, keyed by variant id (`''` for a product with no variant named). */
+export type ProductWeights = Readonly<Record<string, Readonly<Record<string, number>>>>;
+/** One unit of a line's weight in grams, or `null` when the product records none. */
+export declare function lineUnitGrams(line: Pick<OrderLineItem, 'productId' | 'variantId'>, weights: ProductWeights): number | null;
+/** One line still to ship: which line, how many units, and what one weighs. */
+export interface ShippingLine {
+    lineItemId: number;
+    line: OrderLineItem;
+    quantity: number;
+    unitGrams: number | null;
+}
+/** The lines still to ship, with their remaining units. */
+export declare function shippingLines(order: Pick<HostOrder, 'lineItems' | 'fulfillments'>, weights?: ProductWeights): ShippingLine[];
+/**
+ * The parcel's weight in ounces: every remaining unit's recorded weight.
+ * `null` when no line records one, so a tool falls back to the default
+ * package the merchant set there rather than a weight of zero.
+ */
+export declare function shippingWeightOunces(lines: readonly ShippingLine[]): number | null;
+/** A line as a packing list names it: `2 × Mug (Blue), SKU MUG-B`. */
+export declare function describeShippingLine(entry: Pick<ShippingLine, 'line' | 'quantity'>): string;
+/**
+ * The shipping columns of one order, as the orders export writes them
+ * (`ORDER_SHIPPING_FIELDS`). Every value is what the order holds; nothing is
+ * invented — an order with no phone exports no phone.
+ */
+export declare function orderShippingRecord(docId: string, order: Partial<HostOrder>, weights?: ProductWeights): Record<string, unknown>;
+/**
+ * A tracking number as a parcel's identity: spaces and dashes dropped,
+ * upper-cased. `9400 1000 0000` and `94001000000` are one parcel.
+ */
+export declare function normalizeTrackingNumber(value: unknown): string;
+/** The active fulfillment already carrying this tracking number, if any. */
+export declare function fulfillmentWithTracking(order: Pick<HostOrder, 'fulfillments'>, trackingNumber: unknown): OrderFulfillment | undefined;

package/src/lib/model/order-shipping-export.js

@@ -0,0 +1,192 @@
+/**
+ * @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 { fulfillmentIsActive, lineRequiresShipping, remainingFulfillmentLines } from "./order-fulfillment.js";
+/*
+ * AN ORDER AS A SHIPPING TOOL READS IT (AGL-3613).
+ *
+ * ShipStation's Custom Store feed, Pirate Ship's spreadsheet upload and the
+ * Shippo and EasyPost CSVs all want the same facts about an order: who it
+ * goes to, what is still to be packed, and what that weighs. This module is
+ * that one reading, pure, so the XML feed and the CSV export cannot disagree
+ * about an order's weight or which units are still owed.
+ *
+ * WHAT IS STILL TO SHIP, NOT WHAT WAS BOUGHT. A partially fulfilled order
+ * exports its remaining units (`remainingFulfillmentLines`), so a label tool
+ * that imports it again after the first parcel left asks for the rest and
+ * not the whole order a second time. Digital and service lines never ship.
+ *
+ * WHICH ORDERS SHIP AT ALL is stamped on the order as `requiresShipping`
+ * when it is written (`withOrderListFields`), so the export and the
+ * ShipStation feed ask it of their Firestore query instead of reading every
+ * order and dropping the downloads afterwards.
+ */ /** Grams in one avoirdupois ounce. */ export const GRAMS_PER_OUNCE = 28.349523125;
+/** Ounces in one pound. */ export const OUNCES_PER_POUND = 16;
+/** A weight in grams as ounces, to two places. */ export function gramsToOunces(grams) {
+    return Math.round(grams / GRAMS_PER_OUNCE * 100) / 100;
+}
+/** A weight in ounces as pounds, to two places. */ export function ouncesToPounds(ounces) {
+    return Math.round(ounces / OUNCES_PER_POUND * 100) / 100;
+}
+/**
+ * Whether an order has anything to put in a box.
+ *
+ * A line with no recorded type predates types and counts as physical, the
+ * reading that never hides an order a merchant has to ship. A register sale
+ * left the shop in the buyer's hands, so a POS order ships only when it was
+ * given a shipping address. A legacy Commerce Starter order with no lines
+ * ships when it carries an address.
+ */ export function orderRequiresShipping(order) {
+    const lines = Array.isArray(order.lineItems) ? order.lineItems : [];
+    const address = hasShippingAddress(order.shippingAddress);
+    if (!lines.length) return address;
+    if (!lines.some((line)=>line && lineRequiresShipping(line))) return false;
+    return order.channel === 'pos' ? address : true;
+}
+function hasShippingAddress(address) {
+    var _address_line1;
+    return Boolean(address && String((_address_line1 = address.line1) != null ? _address_line1 : '').trim());
+}
+/**
+ * The fields a CREATOR of an order stamps beside its list fields: whether it
+ * ships, and when it last changed — its creation, for a new order. Writers
+ * that change an order afterwards stamp `updatedAtMs` themselves; nothing
+ * else here moves after creation, because an order's lines never do.
+ */ export function orderSyncFields(order) {
+    var _source_updatedAtMs;
+    const source = order;
+    const at = Number((_source_updatedAtMs = source.updatedAtMs) != null ? _source_updatedAtMs : source.createdAtMs);
+    return _extends({
+        requiresShipping: orderRequiresShipping(source)
+    }, Number.isFinite(at) && at > 0 ? {
+        updatedAtMs: at
+    } : {});
+}
+/** The number a shipping tool shows and sends back: `1042`, or the document id for an unnumbered order. */ export function shippingOrderNumber(order, docId) {
+    return typeof order.number === 'number' && Number.isFinite(order.number) ? String(order.number) : docId;
+}
+/**
+ * Every spelling of an order a file or a ShipNotice may name it by: `1042`,
+ * `#1042` and the document id. What `parseShippingOrderRef` reads back.
+ */ export function shippingOrderRefs(order, docId) {
+    const refs = [
+        docId
+    ];
+    if (typeof order.number === 'number' && Number.isFinite(order.number)) {
+        refs.unshift(String(order.number), `#${order.number}`);
+    }
+    return refs;
+}
+/** What a reference a tool sent back names: an order number, or a document id. */ export function parseShippingOrderRef(value) {
+    const text = String(value != null ? value : '').trim();
+    if (!text) return null;
+    const numbered = /^#?\s*(\d{1,12})$/.exec(text);
+    if (numbered) return {
+        number: Number(numbered[1]),
+        id: text.replace(/^#\s*/, '')
+    };
+    // Document ids are what Firestore accepts: no slash, not reserved.
+    if (/[/]/.test(text) || /^__.*__$/.test(text) || text.length > 200) return null;
+    return {
+        id: text
+    };
+}
+/** One unit of a line's weight in grams, or `null` when the product records none. */ export function lineUnitGrams(line, weights) {
+    const byVariant = weights[line.productId];
+    if (!byVariant) return null;
+    const grams = line.variantId ? byVariant[line.variantId] : undefined;
+    const value = grams != null ? grams : byVariant[''];
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
+}
+/** The lines still to ship, with their remaining units. */ export function shippingLines(order, weights = {}) {
+    var _order_lineItems;
+    const lines = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
+    return remainingFulfillmentLines(order).map((entry)=>({
+            entry,
+            line: lines[entry.lineItemId]
+        })).filter((pair)=>Boolean(pair.line)).map(({ entry, line })=>({
+            lineItemId: entry.lineItemId,
+            line,
+            quantity: entry.quantity,
+            unitGrams: lineUnitGrams(line, weights)
+        }));
+}
+/**
+ * The parcel's weight in ounces: every remaining unit's recorded weight.
+ * `null` when no line records one, so a tool falls back to the default
+ * package the merchant set there rather than a weight of zero.
+ */ export function shippingWeightOunces(lines) {
+    let grams = 0;
+    let known = false;
+    for (const entry of lines){
+        if (entry.unitGrams === null) continue;
+        known = true;
+        grams += entry.unitGrams * entry.quantity;
+    }
+    return known ? gramsToOunces(grams) : null;
+}
+/** A line as a packing list names it: `2 × Mug (Blue), SKU MUG-B`. */ export function describeShippingLine(entry) {
+    const { line } = entry;
+    return `${entry.quantity} × ${line.name}${line.variantLabel ? ` (${line.variantLabel})` : ''}${line.sku ? `, SKU ${line.sku}` : ''}`;
+}
+const text = (value)=>{
+    const trimmed = value === null || value === undefined ? '' : String(value).trim();
+    return trimmed || null;
+};
+/**
+ * The shipping columns of one order, as the orders export writes them
+ * (`ORDER_SHIPPING_FIELDS`). Every value is what the order holds; nothing is
+ * invented — an order with no phone exports no phone.
+ */ export function orderShippingRecord(docId, order, weights = {}) {
+    var _order_shippingAddress, _order_lineItems, _order_fulfillments, _text, _text1;
+    const address = (_order_shippingAddress = order.shippingAddress) != null ? _order_shippingAddress : {};
+    const lines = shippingLines({
+        lineItems: (_order_lineItems = order.lineItems) != null ? _order_lineItems : [],
+        fulfillments: (_order_fulfillments = order.fulfillments) != null ? _order_fulfillments : []
+    }, weights);
+    const ounces = shippingWeightOunces(lines);
+    return {
+        orderRef: shippingOrderNumber(order, docId),
+        shipName: (_text = text(address.name)) != null ? _text : text(order.customerName),
+        shipLine1: text(address.line1),
+        shipLine2: text(address.line2),
+        shipCity: text(address.city),
+        shipState: text(address.state),
+        shipPostalCode: text(address.postalCode),
+        shipCountry: text(address.country),
+        shipPhone: (_text1 = text(address.phone)) != null ? _text1 : text(order.customerPhone),
+        shipEmail: text(order.customerEmail),
+        itemsToShip: lines.length ? lines.map(describeShippingLine).join('; ') : null,
+        unitsToShip: lines.reduce((sum, entry)=>sum + entry.quantity, 0),
+        weightOz: ounces,
+        weightLb: ounces === null ? null : ouncesToPounds(ounces),
+        weightUnit: ounces === null ? null : 'oz'
+    };
+}
+/**
+ * A tracking number as a parcel's identity: spaces and dashes dropped,
+ * upper-cased. `9400 1000 0000` and `94001000000` are one parcel.
+ */ export function normalizeTrackingNumber(value) {
+    return String(value != null ? value : '').replace(/[\s-]+/g, '').toUpperCase();
+}
+/** The active fulfillment already carrying this tracking number, if any. */ export function fulfillmentWithTracking(order, trackingNumber) {
+    var _order_fulfillments;
+    const wanted = normalizeTrackingNumber(trackingNumber);
+    if (!wanted) return undefined;
+    return ((_order_fulfillments = order.fulfillments) != null ? _order_fulfillments : []).find((entry)=>fulfillmentIsActive(entry) && normalizeTrackingNumber(entry.trackingNumber) === wanted);
+}
+
+//# sourceMappingURL=order-shipping-export.js.map

package/src/lib/model/order-shipping-export.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/order-shipping-export.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, OrderAddress, OrderFulfillment, OrderLineItem } from './commerce-orders'\nimport { fulfillmentIsActive, lineRequiresShipping, remainingFulfillmentLines } from './order-fulfillment'\n\n/*\n * AN ORDER AS A SHIPPING TOOL READS IT (AGL-3613).\n *\n * ShipStation's Custom Store feed, Pirate Ship's spreadsheet upload and the\n * Shippo and EasyPost CSVs all want the same facts about an order: who it\n * goes to, what is still to be packed, and what that weighs. This module is\n * that one reading, pure, so the XML feed and the CSV export cannot disagree\n * about an order's weight or which units are still owed.\n *\n * WHAT IS STILL TO SHIP, NOT WHAT WAS BOUGHT. A partially fulfilled order\n * exports its remaining units (`remainingFulfillmentLines`), so a label tool\n * that imports it again after the first parcel left asks for the rest and\n * not the whole order a second time. Digital and service lines never ship.\n *\n * WHICH ORDERS SHIP AT ALL is stamped on the order as `requiresShipping`\n * when it is written (`withOrderListFields`), so the export and the\n * ShipStation feed ask it of their Firestore query instead of reading every\n * order and dropping the downloads afterwards.\n */\n\n/** Grams in one avoirdupois ounce. */\nexport const GRAMS_PER_OUNCE = 28.349523125\n\n/** Ounces in one pound. */\nexport const OUNCES_PER_POUND = 16\n\n/** A weight in grams as ounces, to two places. */\nexport function gramsToOunces(grams: number): number {\n  return Math.round((grams / GRAMS_PER_OUNCE) * 100) / 100\n}\n\n/** A weight in ounces as pounds, to two places. */\nexport function ouncesToPounds(ounces: number): number {\n  return Math.round((ounces / OUNCES_PER_POUND) * 100) / 100\n}\n\n/**\n * Whether an order has anything to put in a box.\n *\n * A line with no recorded type predates types and counts as physical, the\n * reading that never hides an order a merchant has to ship. A register sale\n * left the shop in the buyer's hands, so a POS order ships only when it was\n * given a shipping address. A legacy Commerce Starter order with no lines\n * ships when it carries an address.\n */\nexport function orderRequiresShipping(order: Partial<HostOrder>): boolean {\n  const lines = Array.isArray(order.lineItems) ? order.lineItems : []\n  const address = hasShippingAddress(order.shippingAddress)\n  if (!lines.length) return address\n  if (!lines.some((line) => line && lineRequiresShipping(line))) return false\n  return order.channel === 'pos' ? address : true\n}\n\nfunction hasShippingAddress(address: OrderAddress | undefined | null): boolean {\n  return Boolean(address && String(address.line1 ?? '').trim())\n}\n\n/**\n * The fields a CREATOR of an order stamps beside its list fields: whether it\n * ships, and when it last changed — its creation, for a new order. Writers\n * that change an order afterwards stamp `updatedAtMs` themselves; nothing\n * else here moves after creation, because an order's lines never do.\n */\nexport function orderSyncFields(order: object): { requiresShipping: boolean; updatedAtMs?: number } {\n  const source = order as Partial<HostOrder> & { updatedAtMs?: unknown; createdAtMs?: unknown }\n  const at = Number(source.updatedAtMs ?? source.createdAtMs)\n  return {\n    requiresShipping: orderRequiresShipping(source),\n    ...(Number.isFinite(at) && at > 0 ? { updatedAtMs: at } : {}),\n  }\n}\n\n/** The number a shipping tool shows and sends back: `1042`, or the document id for an unnumbered order. */\nexport function shippingOrderNumber(order: Pick<HostOrder, 'number'>, docId: string): string {\n  return typeof order.number === 'number' && Number.isFinite(order.number) ? String(order.number) : docId\n}\n\n/**\n * Every spelling of an order a file or a ShipNotice may name it by: `1042`,\n * `#1042` and the document id. What `parseShippingOrderRef` reads back.\n */\nexport function shippingOrderRefs(order: Pick<HostOrder, 'number'>, docId: string): string[] {\n  const refs = [docId]\n  if (typeof order.number === 'number' && Number.isFinite(order.number)) {\n    refs.unshift(String(order.number), `#${order.number}`)\n  }\n  return refs\n}\n\n/** What a reference a tool sent back names: an order number, or a document id. */\nexport function parseShippingOrderRef(value: unknown): { number?: number; id?: string } | null {\n  const text = String(value ?? '').trim()\n  if (!text) return null\n  const numbered = /^#?\\s*(\\d{1,12})$/.exec(text)\n  if (numbered) return { number: Number(numbered[1]), id: text.replace(/^#\\s*/, '') }\n  // Document ids are what Firestore accepts: no slash, not reserved.\n  if (/[/]/.test(text) || /^__.*__$/.test(text) || text.length > 200) return null\n  return { id: text }\n}\n\n/** A product's weights, keyed by variant id (`''` for a product with no variant named). */\nexport type ProductWeights = Readonly<Record<string, Readonly<Record<string, number>>>>\n\n/** One unit of a line's weight in grams, or `null` when the product records none. */\nexport function lineUnitGrams(line: Pick<OrderLineItem, 'productId' | 'variantId'>, weights: ProductWeights): number | null {\n  const byVariant = weights[line.productId]\n  if (!byVariant) return null\n  const grams = line.variantId ? byVariant[line.variantId] : undefined\n  const value = grams ?? byVariant['']\n  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null\n}\n\n/** One line still to ship: which line, how many units, and what one weighs. */\nexport interface ShippingLine {\n  lineItemId: number\n  line: OrderLineItem\n  quantity: number\n  unitGrams: number | null\n}\n\n/** The lines still to ship, with their remaining units. */\nexport function shippingLines(order: Pick<HostOrder, 'lineItems' | 'fulfillments'>, weights: ProductWeights = {}): ShippingLine[] {\n  const lines = order.lineItems ?? []\n  return remainingFulfillmentLines(order)\n    .map((entry) => ({ entry, line: lines[entry.lineItemId] }))\n    .filter((pair): pair is { entry: { lineItemId: number; quantity: number }; line: OrderLineItem } => Boolean(pair.line))\n    .map(({ entry, line }) => ({\n      lineItemId: entry.lineItemId,\n      line,\n      quantity: entry.quantity,\n      unitGrams: lineUnitGrams(line, weights),\n    }))\n}\n\n/**\n * The parcel's weight in ounces: every remaining unit's recorded weight.\n * `null` when no line records one, so a tool falls back to the default\n * package the merchant set there rather than a weight of zero.\n */\nexport function shippingWeightOunces(lines: readonly ShippingLine[]): number | null {\n  let grams = 0\n  let known = false\n  for (const entry of lines) {\n    if (entry.unitGrams === null) continue\n    known = true\n    grams += entry.unitGrams * entry.quantity\n  }\n  return known ? gramsToOunces(grams) : null\n}\n\n/** A line as a packing list names it: `2 × Mug (Blue), SKU MUG-B`. */\nexport function describeShippingLine(entry: Pick<ShippingLine, 'line' | 'quantity'>): string {\n  const { line } = entry\n  return `${entry.quantity} × ${line.name}${line.variantLabel ? ` (${line.variantLabel})` : ''}${line.sku ? `, SKU ${line.sku}` : ''}`\n}\n\nconst text = (value: unknown): string | null => {\n  const trimmed = value === null || value === undefined ? '' : String(value).trim()\n  return trimmed || null\n}\n\n/**\n * The shipping columns of one order, as the orders export writes them\n * (`ORDER_SHIPPING_FIELDS`). Every value is what the order holds; nothing is\n * invented — an order with no phone exports no phone.\n */\nexport function orderShippingRecord(\n  docId: string,\n  order: Partial<HostOrder>,\n  weights: ProductWeights = {},\n): Record<string, unknown> {\n  const address = order.shippingAddress ?? {}\n  const lines = shippingLines({ lineItems: order.lineItems ?? [], fulfillments: order.fulfillments ?? [] }, weights)\n  const ounces = shippingWeightOunces(lines)\n  return {\n    orderRef: shippingOrderNumber(order, docId),\n    shipName: text(address.name) ?? text(order.customerName),\n    shipLine1: text(address.line1),\n    shipLine2: text(address.line2),\n    shipCity: text(address.city),\n    shipState: text(address.state),\n    shipPostalCode: text(address.postalCode),\n    shipCountry: text(address.country),\n    shipPhone: text(address.phone) ?? text(order.customerPhone),\n    shipEmail: text(order.customerEmail),\n    itemsToShip: lines.length ? lines.map(describeShippingLine).join('; ') : null,\n    unitsToShip: lines.reduce((sum, entry) => sum + entry.quantity, 0),\n    weightOz: ounces,\n    weightLb: ounces === null ? null : ouncesToPounds(ounces),\n    weightUnit: ounces === null ? null : 'oz',\n  }\n}\n\n/**\n * A tracking number as a parcel's identity: spaces and dashes dropped,\n * upper-cased. `9400 1000 0000` and `94001000000` are one parcel.\n */\nexport function normalizeTrackingNumber(value: unknown): string {\n  return String(value ?? '')\n    .replace(/[\\s-]+/g, '')\n    .toUpperCase()\n}\n\n/** The active fulfillment already carrying this tracking number, if any. */\nexport function fulfillmentWithTracking(\n  order: Pick<HostOrder, 'fulfillments'>,\n  trackingNumber: unknown,\n): OrderFulfillment | undefined {\n  const wanted = normalizeTrackingNumber(trackingNumber)\n  if (!wanted) return undefined\n  return (order.fulfillments ?? []).find(\n    (entry) => fulfillmentIsActive(entry) && normalizeTrackingNumber(entry.trackingNumber) === wanted,\n  )\n}\n"],"names":["fulfillmentIsActive","lineRequiresShipping","remainingFulfillmentLines","GRAMS_PER_OUNCE","OUNCES_PER_POUND","gramsToOunces","grams","Math","round","ouncesToPounds","ounces","orderRequiresShipping","order","lines","Array","isArray","lineItems","address","hasShippingAddress","shippingAddress","length","some","line","channel","Boolean","String","line1","trim","orderSyncFields","source","at","Number","updatedAtMs","createdAtMs","requiresShipping","isFinite","shippingOrderNumber","docId","number","shippingOrderRefs","refs","unshift","parseShippingOrderRef","value","text","numbered","exec","id","replace","test","lineUnitGrams","weights","byVariant","productId","variantId","undefined","shippingLines","map","entry","lineItemId","filter","pair","quantity","unitGrams","shippingWeightOunces","known","describeShippingLine","name","variantLabel","sku","trimmed","orderShippingRecord","fulfillments","orderRef","shipName","customerName","shipLine1","shipLine2","line2","shipCity","city","shipState","state","shipPostalCode","postalCode","shipCountry","country","shipPhone","phone","customerPhone","shipEmail","customerEmail","itemsToShip","join","unitsToShip","reduce","sum","weightOz","weightLb","weightUnit","normalizeTrackingNumber","toUpperCase","fulfillmentWithTracking","trackingNumber","wanted","find"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SAASA,mBAAmB,EAAEC,oBAAoB,EAAEC,yBAAyB,QAAQ,yBAAqB;AAE1G;;;;;;;;;;;;;;;;;;CAkBC,GAED,oCAAoC,GACpC,OAAO,MAAMC,kBAAkB,aAAY;AAE3C,yBAAyB,GACzB,OAAO,MAAMC,mBAAmB,GAAE;AAElC,gDAAgD,GAChD,OAAO,SAASC,cAAcC,KAAa;IACzC,OAAOC,KAAKC,KAAK,CAAC,AAACF,QAAQH,kBAAmB,OAAO;AACvD;AAEA,iDAAiD,GACjD,OAAO,SAASM,eAAeC,MAAc;IAC3C,OAAOH,KAAKC,KAAK,CAAC,AAACE,SAASN,mBAAoB,OAAO;AACzD;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASO,sBAAsBC,KAAyB;IAC7D,MAAMC,QAAQC,MAAMC,OAAO,CAACH,MAAMI,SAAS,IAAIJ,MAAMI,SAAS,GAAG,EAAE;IACnE,MAAMC,UAAUC,mBAAmBN,MAAMO,eAAe;IACxD,IAAI,CAACN,MAAMO,MAAM,EAAE,OAAOH;IAC1B,IAAI,CAACJ,MAAMQ,IAAI,CAAC,CAACC,OAASA,QAAQrB,qBAAqBqB,QAAQ,OAAO;IACtE,OAAOV,MAAMW,OAAO,KAAK,QAAQN,UAAU;AAC7C;AAEA,SAASC,mBAAmBD,OAAwC;QACjCA;IAAjC,OAAOO,QAAQP,WAAWQ,QAAOR,iBAAAA,QAAQS,KAAK,YAAbT,iBAAiB,IAAIU,IAAI;AAC5D;AAEA;;;;;CAKC,GACD,OAAO,SAASC,gBAAgBhB,KAAa;QAEzBiB;IADlB,MAAMA,SAASjB;IACf,MAAMkB,KAAKC,QAAOF,sBAAAA,OAAOG,WAAW,YAAlBH,sBAAsBA,OAAOI,WAAW;IAC1D,OAAO;QACLC,kBAAkBvB,sBAAsBkB;OACpCE,OAAOI,QAAQ,CAACL,OAAOA,KAAK,IAAI;QAAEE,aAAaF;IAAG,IAAI,CAAC;AAE/D;AAEA,yGAAyG,GACzG,OAAO,SAASM,oBAAoBxB,KAAgC,EAAEyB,KAAa;IACjF,OAAO,OAAOzB,MAAM0B,MAAM,KAAK,YAAYP,OAAOI,QAAQ,CAACvB,MAAM0B,MAAM,IAAIb,OAAOb,MAAM0B,MAAM,IAAID;AACpG;AAEA;;;CAGC,GACD,OAAO,SAASE,kBAAkB3B,KAAgC,EAAEyB,KAAa;IAC/E,MAAMG,OAAO;QAACH;KAAM;IACpB,IAAI,OAAOzB,MAAM0B,MAAM,KAAK,YAAYP,OAAOI,QAAQ,CAACvB,MAAM0B,MAAM,GAAG;QACrEE,KAAKC,OAAO,CAAChB,OAAOb,MAAM0B,MAAM,GAAG,CAAC,CAAC,EAAE1B,MAAM0B,MAAM,EAAE;IACvD;IACA,OAAOE;AACT;AAEA,gFAAgF,GAChF,OAAO,SAASE,sBAAsBC,KAAc;IAClD,MAAMC,OAAOnB,OAAOkB,gBAAAA,QAAS,IAAIhB,IAAI;IACrC,IAAI,CAACiB,MAAM,OAAO;IAClB,MAAMC,WAAW,oBAAoBC,IAAI,CAACF;IAC1C,IAAIC,UAAU,OAAO;QAAEP,QAAQP,OAAOc,QAAQ,CAAC,EAAE;QAAGE,IAAIH,KAAKI,OAAO,CAAC,SAAS;IAAI;IAClF,mEAAmE;IACnE,IAAI,MAAMC,IAAI,CAACL,SAAS,WAAWK,IAAI,CAACL,SAASA,KAAKxB,MAAM,GAAG,KAAK,OAAO;IAC3E,OAAO;QAAE2B,IAAIH;IAAK;AACpB;AAKA,mFAAmF,GACnF,OAAO,SAASM,cAAc5B,IAAoD,EAAE6B,OAAuB;IACzG,MAAMC,YAAYD,OAAO,CAAC7B,KAAK+B,SAAS,CAAC;IACzC,IAAI,CAACD,WAAW,OAAO;IACvB,MAAM9C,QAAQgB,KAAKgC,SAAS,GAAGF,SAAS,CAAC9B,KAAKgC,SAAS,CAAC,GAAGC;IAC3D,MAAMZ,QAAQrC,gBAAAA,QAAS8C,SAAS,CAAC,GAAG;IACpC,OAAO,OAAOT,UAAU,YAAYZ,OAAOI,QAAQ,CAACQ,UAAUA,QAAQ,IAAIA,QAAQ;AACpF;AAUA,yDAAyD,GACzD,OAAO,SAASa,cAAc5C,KAAoD,EAAEuC,UAA0B,CAAC,CAAC;QAChGvC;IAAd,MAAMC,SAAQD,mBAAAA,MAAMI,SAAS,YAAfJ,mBAAmB,EAAE;IACnC,OAAOV,0BAA0BU,OAC9B6C,GAAG,CAAC,CAACC,QAAW,CAAA;YAAEA;YAAOpC,MAAMT,KAAK,CAAC6C,MAAMC,UAAU,CAAC;QAAC,CAAA,GACvDC,MAAM,CAAC,CAACC,OAA2FrC,QAAQqC,KAAKvC,IAAI,GACpHmC,GAAG,CAAC,CAAC,EAAEC,KAAK,EAAEpC,IAAI,EAAE,GAAM,CAAA;YACzBqC,YAAYD,MAAMC,UAAU;YAC5BrC;YACAwC,UAAUJ,MAAMI,QAAQ;YACxBC,WAAWb,cAAc5B,MAAM6B;QACjC,CAAA;AACJ;AAEA;;;;CAIC,GACD,OAAO,SAASa,qBAAqBnD,KAA8B;IACjE,IAAIP,QAAQ;IACZ,IAAI2D,QAAQ;IACZ,KAAK,MAAMP,SAAS7C,MAAO;QACzB,IAAI6C,MAAMK,SAAS,KAAK,MAAM;QAC9BE,QAAQ;QACR3D,SAASoD,MAAMK,SAAS,GAAGL,MAAMI,QAAQ;IAC3C;IACA,OAAOG,QAAQ5D,cAAcC,SAAS;AACxC;AAEA,oEAAoE,GACpE,OAAO,SAAS4D,qBAAqBR,KAA8C;IACjF,MAAM,EAAEpC,IAAI,EAAE,GAAGoC;IACjB,OAAO,GAAGA,MAAMI,QAAQ,CAAC,GAAG,EAAExC,KAAK6C,IAAI,GAAG7C,KAAK8C,YAAY,GAAG,CAAC,EAAE,EAAE9C,KAAK8C,YAAY,CAAC,CAAC,CAAC,GAAG,KAAK9C,KAAK+C,GAAG,GAAG,CAAC,MAAM,EAAE/C,KAAK+C,GAAG,EAAE,GAAG,IAAI;AACtI;AAEA,MAAMzB,OAAO,CAACD;IACZ,MAAM2B,UAAU3B,UAAU,QAAQA,UAAUY,YAAY,KAAK9B,OAAOkB,OAAOhB,IAAI;IAC/E,OAAO2C,WAAW;AACpB;AAEA;;;;CAIC,GACD,OAAO,SAASC,oBACdlC,KAAa,EACbzB,KAAyB,EACzBuC,UAA0B,CAAC,CAAC;QAEZvC,wBACyBA,kBAAqCA,qBAIlEgC,OAOCA;IAZb,MAAM3B,WAAUL,yBAAAA,MAAMO,eAAe,YAArBP,yBAAyB,CAAC;IAC1C,MAAMC,QAAQ2C,cAAc;QAAExC,SAAS,GAAEJ,mBAAAA,MAAMI,SAAS,YAAfJ,mBAAmB,EAAE;QAAE4D,YAAY,GAAE5D,sBAAAA,MAAM4D,YAAY,YAAlB5D,sBAAsB,EAAE;IAAC,GAAGuC;IAC1G,MAAMzC,SAASsD,qBAAqBnD;IACpC,OAAO;QACL4D,UAAUrC,oBAAoBxB,OAAOyB;QACrCqC,QAAQ,GAAE9B,QAAAA,KAAK3B,QAAQkD,IAAI,aAAjBvB,QAAsBA,KAAKhC,MAAM+D,YAAY;QACvDC,WAAWhC,KAAK3B,QAAQS,KAAK;QAC7BmD,WAAWjC,KAAK3B,QAAQ6D,KAAK;QAC7BC,UAAUnC,KAAK3B,QAAQ+D,IAAI;QAC3BC,WAAWrC,KAAK3B,QAAQiE,KAAK;QAC7BC,gBAAgBvC,KAAK3B,QAAQmE,UAAU;QACvCC,aAAazC,KAAK3B,QAAQqE,OAAO;QACjCC,SAAS,GAAE3C,SAAAA,KAAK3B,QAAQuE,KAAK,aAAlB5C,SAAuBA,KAAKhC,MAAM6E,aAAa;QAC1DC,WAAW9C,KAAKhC,MAAM+E,aAAa;QACnCC,aAAa/E,MAAMO,MAAM,GAAGP,MAAM4C,GAAG,CAACS,sBAAsB2B,IAAI,CAAC,QAAQ;QACzEC,aAAajF,MAAMkF,MAAM,CAAC,CAACC,KAAKtC,QAAUsC,MAAMtC,MAAMI,QAAQ,EAAE;QAChEmC,UAAUvF;QACVwF,UAAUxF,WAAW,OAAO,OAAOD,eAAeC;QAClDyF,YAAYzF,WAAW,OAAO,OAAO;IACvC;AACF;AAEA;;;CAGC,GACD,OAAO,SAAS0F,wBAAwBzD,KAAc;IACpD,OAAOlB,OAAOkB,gBAAAA,QAAS,IACpBK,OAAO,CAAC,WAAW,IACnBqD,WAAW;AAChB;AAEA,0EAA0E,GAC1E,OAAO,SAASC,wBACd1F,KAAsC,EACtC2F,cAAuB;QAIf3F;IAFR,MAAM4F,SAASJ,wBAAwBG;IACvC,IAAI,CAACC,QAAQ,OAAOjD;IACpB,OAAO,EAAC3C,sBAAAA,MAAM4D,YAAY,YAAlB5D,sBAAsB,EAAE,EAAE6F,IAAI,CACpC,CAAC/C,QAAU1D,oBAAoB0D,UAAU0C,wBAAwB1C,MAAM6C,cAAc,MAAMC;AAE/F"}