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

package/src/lib/model/order-status-view.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @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, OrderStatus } from './commerce-orders';
+/**
+ * What the guest order-status page shows (AGL-3610): the ONE projection of an
+ * order that leaves the server for a visitor holding a signed link.
+ *
+ * Allow-listed, never spread: an order document carries the buyer's email,
+ * phone and addresses, Stripe ids, risk signals and the merchant's notes, and
+ * a forwarded link must disclose no more than the email it arrived in. Every
+ * field below is one the buyer's own receipt or shipping email already
+ * states. New fields are added here deliberately, or not at all.
+ */
+export interface OrderStatusLine {
+    name: string;
+    variantLabel: string | null;
+    quantity: number;
+    amountCents: number;
+    /** Units of this line in an active shipment. */
+    shippedQuantity: number;
+    refunded: boolean;
+}
+export interface OrderStatusShipment {
+    id: string;
+    atMs: number;
+    carrier: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    lines: Array<{
+        name: string;
+        quantity: number;
+    }>;
+}
+export interface OrderStatusStep {
+    key: 'placed' | 'paid' | 'shipped' | 'delivered' | 'cancelled' | 'refunded';
+    label: string;
+    atMs: number | null;
+    done: boolean;
+}
+/**
+ * Something the buyer can do from the page — "Request a return" is the case
+ * the order-processing lane (AGL-3611) adds through
+ * `registerOrderStatusActions` on the server. The page renders each as a
+ * button to `url`; it knows nothing of what the action is.
+ */
+export interface OrderStatusAction {
+    id: string;
+    label: string;
+    url: string;
+}
+export interface OrderStatusView {
+    storeName: string;
+    number: string;
+    status: OrderStatus;
+    /** The status as a buyer reads it. */
+    statusLabel: string;
+    createdAtMs: number | null;
+    currency: string;
+    lines: OrderStatusLine[];
+    totals: {
+        itemsCents: number;
+        shippingCents: number;
+        taxCents: number;
+        discountCents: number;
+        totalCents: number;
+        refundedCents: number;
+    };
+    /**
+     * Optional lines the buyer took at checkout (AGL-3635) — "Package
+     * protection" — by the name and price their receipt states. Optional so
+     * an answer from before this field reads as none.
+     */
+    extras?: Array<{
+        label: string;
+        amountCents: number;
+    }>;
+    shipments: OrderStatusShipment[];
+    steps: OrderStatusStep[];
+    actions: OrderStatusAction[];
+}
+/** Builds the public projection. Pure; the caller has verified the link. */
+export declare function buildOrderStatusView(input: {
+    order: HostOrder;
+    orderId: string;
+    storeName: string;
+    currency?: string;
+    number: string;
+    actions?: OrderStatusAction[];
+}): OrderStatusView;

package/src/lib/model/order-status-view.js

@@ -0,0 +1,156 @@
+/**
+ * @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 { fulfillmentIsActive, fulfillmentLineQuantities } from "./order-fulfillment.js";
+import { carrierLabelFor, fulfillmentTrackingUrl } from "./tracking-url.js";
+const STATUS_LABELS = {
+    pending: 'Awaiting payment',
+    paid: 'Confirmed',
+    partially_fulfilled: 'Partly shipped',
+    fulfilled: 'Shipped',
+    delivered: 'Delivered',
+    cancelled: 'Canceled',
+    refunded: 'Refunded'
+};
+function eventAt(order, ...events) {
+    var _order_timeline;
+    const found = ((_order_timeline = order.timeline) != null ? _order_timeline : []).find((entry)=>{
+        var _ref;
+        return events.includes(String((_ref = entry == null ? void 0 : entry.event) != null ? _ref : ''));
+    });
+    return found ? Number(found.atMs) || null : null;
+}
+/** Builds the public projection. Pure; the caller has verified the link. */ export function buildOrderStatusView(input) {
+    var _order_lineItems, _order_fulfillments, _order_refundedLineItemIds, _ref, _order_amountCents, _eventAt, _ref1, _STATUS_LABELS_status, _ref2, _ref3, _ref4, _ref5, _order_refundedCents, _order_extras, _input_actions;
+    var _shipments_;
+    const { order } = input;
+    const lineItems = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
+    const active = ((_order_fulfillments = order.fulfillments) != null ? _order_fulfillments : []).filter(fulfillmentIsActive);
+    const shippedByLine = new Map();
+    const shipments = active.map((fulfillment)=>{
+        var _fulfillment_id, _fulfillment_trackingNumber;
+        const quantities = fulfillmentLineQuantities(order, fulfillment);
+        for (const entry of quantities){
+            var _shippedByLine_get;
+            shippedByLine.set(entry.lineItemId, ((_shippedByLine_get = shippedByLine.get(entry.lineItemId)) != null ? _shippedByLine_get : 0) + entry.quantity);
+        }
+        return {
+            id: String((_fulfillment_id = fulfillment.id) != null ? _fulfillment_id : ''),
+            atMs: Number(fulfillment.atMs) || 0,
+            carrier: fulfillment.carrier ? carrierLabelFor(fulfillment.carrier) : null,
+            trackingNumber: (_fulfillment_trackingNumber = fulfillment.trackingNumber) != null ? _fulfillment_trackingNumber : null,
+            trackingUrl: fulfillmentTrackingUrl(fulfillment),
+            lines: quantities.map((entry)=>{
+                var _ref;
+                var _lineItems_entry_lineItemId;
+                return {
+                    name: String((_ref = (_lineItems_entry_lineItemId = lineItems[entry.lineItemId]) == null ? void 0 : _lineItems_entry_lineItemId.name) != null ? _ref : 'Item'),
+                    quantity: entry.quantity
+                };
+            })
+        };
+    }).sort((a, b)=>a.atMs - b.atMs);
+    const refundedLines = new Set((_order_refundedLineItemIds = order.refundedLineItemIds) != null ? _order_refundedLineItemIds : []);
+    const lines = lineItems.map((line, index)=>{
+        var _line_name, _line_variantLabel, _shippedByLine_get;
+        return {
+            name: String((_line_name = line.name) != null ? _line_name : 'Item'),
+            variantLabel: (_line_variantLabel = line.variantLabel) != null ? _line_variantLabel : null,
+            quantity: Number(line.quantity) || 0,
+            amountCents: (Number(line.unitAmountCents) || 0) * (Number(line.quantity) || 0),
+            shippedQuantity: Math.min(Number(line.quantity) || 0, (_shippedByLine_get = shippedByLine.get(index)) != null ? _shippedByLine_get : 0),
+            refunded: refundedLines.has(index)
+        };
+    });
+    const totals = order.totals;
+    const totalCents = (_ref = totals == null ? void 0 : totals.totalCents) != null ? _ref : Number((_order_amountCents = order.amountCents) != null ? _order_amountCents : 0);
+    const status = order.status;
+    const createdAtMs = Number(order.createdAtMs) || null;
+    const paidAtMs = (_eventAt = eventAt(order, 'paid')) != null ? _eventAt : status !== 'pending' ? createdAtMs : null;
+    const firstShipAt = (_ref1 = (_shipments_ = shipments[0]) == null ? void 0 : _shipments_.atMs) != null ? _ref1 : eventAt(order, 'fulfilled', 'partially_fulfilled');
+    const deliveredAt = eventAt(order, 'delivered');
+    const steps = [
+        {
+            key: 'placed',
+            label: 'Order placed',
+            atMs: createdAtMs,
+            done: true
+        },
+        {
+            key: 'paid',
+            label: 'Payment confirmed',
+            atMs: paidAtMs,
+            done: status !== 'pending' && paidAtMs !== null
+        }
+    ];
+    if (status === 'cancelled') {
+        steps.push({
+            key: 'cancelled',
+            label: 'Canceled',
+            atMs: eventAt(order, 'cancelled'),
+            done: true
+        });
+    } else {
+        steps.push({
+            key: 'shipped',
+            label: status === 'partially_fulfilled' ? 'Partly shipped' : 'Shipped',
+            atMs: firstShipAt,
+            done: [
+                'partially_fulfilled',
+                'fulfilled',
+                'delivered'
+            ].includes(status) || shipments.length > 0
+        }, {
+            key: 'delivered',
+            label: 'Delivered',
+            atMs: deliveredAt,
+            done: status === 'delivered' || deliveredAt !== null
+        });
+    }
+    if (status === 'refunded') {
+        steps.push({
+            key: 'refunded',
+            label: 'Refunded',
+            atMs: eventAt(order, 'refund'),
+            done: true
+        });
+    }
+    return {
+        storeName: input.storeName,
+        number: input.number,
+        status,
+        statusLabel: (_STATUS_LABELS_status = STATUS_LABELS[status]) != null ? _STATUS_LABELS_status : 'Confirmed',
+        createdAtMs,
+        currency: input.currency || 'USD',
+        lines,
+        totals: {
+            itemsCents: (_ref2 = totals == null ? void 0 : totals.itemsCents) != null ? _ref2 : lines.reduce((sum, line)=>sum + line.amountCents, 0),
+            shippingCents: (_ref3 = totals == null ? void 0 : totals.shippingCents) != null ? _ref3 : 0,
+            taxCents: (_ref4 = totals == null ? void 0 : totals.taxCents) != null ? _ref4 : 0,
+            discountCents: (_ref5 = totals == null ? void 0 : totals.discountCents) != null ? _ref5 : 0,
+            totalCents,
+            refundedCents: Number((_order_refundedCents = order.refundedCents) != null ? _order_refundedCents : 0) || 0
+        },
+        extras: ((_order_extras = order.extras) != null ? _order_extras : []).filter((extra)=>extra && Number(extra.amountCents) > 0).map((extra)=>({
+                label: String(extra.label || 'Extra'),
+                amountCents: Number(extra.amountCents)
+            })),
+        shipments,
+        steps,
+        actions: (_input_actions = input.actions) != null ? _input_actions : []
+    };
+}
+
+//# sourceMappingURL=order-status-view.js.map

package/src/lib/model/order-status-view.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/order-status-view.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, OrderStatus } from './commerce-orders'\nimport { fulfillmentIsActive, fulfillmentLineQuantities } from './order-fulfillment'\nimport { carrierLabelFor, fulfillmentTrackingUrl } from './tracking-url'\n\n/**\n * What the guest order-status page shows (AGL-3610): the ONE projection of an\n * order that leaves the server for a visitor holding a signed link.\n *\n * Allow-listed, never spread: an order document carries the buyer's email,\n * phone and addresses, Stripe ids, risk signals and the merchant's notes, and\n * a forwarded link must disclose no more than the email it arrived in. Every\n * field below is one the buyer's own receipt or shipping email already\n * states. New fields are added here deliberately, or not at all.\n */\nexport interface OrderStatusLine {\n  name: string\n  variantLabel: string | null\n  quantity: number\n  amountCents: number\n  /** Units of this line in an active shipment. */\n  shippedQuantity: number\n  refunded: boolean\n}\n\nexport interface OrderStatusShipment {\n  id: string\n  atMs: number\n  carrier: string | null\n  trackingNumber: string | null\n  trackingUrl: string | null\n  lines: Array<{ name: string; quantity: number }>\n}\n\nexport interface OrderStatusStep {\n  key: 'placed' | 'paid' | 'shipped' | 'delivered' | 'cancelled' | 'refunded'\n  label: string\n  atMs: number | null\n  done: boolean\n}\n\n/**\n * Something the buyer can do from the page — \"Request a return\" is the case\n * the order-processing lane (AGL-3611) adds through\n * `registerOrderStatusActions` on the server. The page renders each as a\n * button to `url`; it knows nothing of what the action is.\n */\nexport interface OrderStatusAction {\n  id: string\n  label: string\n  url: string\n}\n\nexport interface OrderStatusView {\n  storeName: string\n  number: string\n  status: OrderStatus\n  /** The status as a buyer reads it. */\n  statusLabel: string\n  createdAtMs: number | null\n  currency: string\n  lines: OrderStatusLine[]\n  totals: {\n    itemsCents: number\n    shippingCents: number\n    taxCents: number\n    discountCents: number\n    totalCents: number\n    refundedCents: number\n  }\n  /**\n   * Optional lines the buyer took at checkout (AGL-3635) — \"Package\n   * protection\" — by the name and price their receipt states. Optional so\n   * an answer from before this field reads as none.\n   */\n  extras?: Array<{ label: string; amountCents: number }>\n  shipments: OrderStatusShipment[]\n  steps: OrderStatusStep[]\n  actions: OrderStatusAction[]\n}\n\nconst STATUS_LABELS: Record<OrderStatus, string> = {\n  pending: 'Awaiting payment',\n  paid: 'Confirmed',\n  partially_fulfilled: 'Partly shipped',\n  fulfilled: 'Shipped',\n  delivered: 'Delivered',\n  cancelled: 'Canceled',\n  refunded: 'Refunded',\n}\n\nfunction eventAt(order: HostOrder, ...events: string[]): number | null {\n  const found = (order.timeline ?? []).find((entry) =>\n    events.includes(String(entry?.event ?? '')),\n  )\n  return found ? Number(found.atMs) || null : null\n}\n\n/** Builds the public projection. Pure; the caller has verified the link. */\nexport function buildOrderStatusView(input: {\n  order: HostOrder\n  orderId: string\n  storeName: string\n  currency?: string\n  number: string\n  actions?: OrderStatusAction[]\n}): OrderStatusView {\n  const { order } = input\n  const lineItems = order.lineItems ?? []\n  const active = (order.fulfillments ?? []).filter(fulfillmentIsActive)\n  const shippedByLine = new Map<number, number>()\n  const shipments: OrderStatusShipment[] = active\n    .map((fulfillment) => {\n      const quantities = fulfillmentLineQuantities(order, fulfillment)\n      for (const entry of quantities) {\n        shippedByLine.set(\n          entry.lineItemId,\n          (shippedByLine.get(entry.lineItemId) ?? 0) + entry.quantity,\n        )\n      }\n      return {\n        id: String(fulfillment.id ?? ''),\n        atMs: Number(fulfillment.atMs) || 0,\n        carrier: fulfillment.carrier ? carrierLabelFor(fulfillment.carrier) : null,\n        trackingNumber: fulfillment.trackingNumber ?? null,\n        trackingUrl: fulfillmentTrackingUrl(fulfillment),\n        lines: quantities.map((entry) => ({\n          name: String(lineItems[entry.lineItemId]?.name ?? 'Item'),\n          quantity: entry.quantity,\n        })),\n      }\n    })\n    .sort((a, b) => a.atMs - b.atMs)\n  const refundedLines = new Set(order.refundedLineItemIds ?? [])\n  const lines: OrderStatusLine[] = lineItems.map((line, index) => ({\n    name: String(line.name ?? 'Item'),\n    variantLabel: line.variantLabel ?? null,\n    quantity: Number(line.quantity) || 0,\n    amountCents: (Number(line.unitAmountCents) || 0) * (Number(line.quantity) || 0),\n    shippedQuantity: Math.min(Number(line.quantity) || 0, shippedByLine.get(index) ?? 0),\n    refunded: refundedLines.has(index),\n  }))\n  const totals = order.totals\n  const totalCents = totals?.totalCents ?? Number(order.amountCents ?? 0)\n  const status = order.status\n  const createdAtMs = Number(order.createdAtMs) || null\n  const paidAtMs = eventAt(order, 'paid') ?? (status !== 'pending' ? createdAtMs : null)\n  const firstShipAt = shipments[0]?.atMs ?? eventAt(order, 'fulfilled', 'partially_fulfilled')\n  const deliveredAt = eventAt(order, 'delivered')\n  const steps: OrderStatusStep[] = [\n    { key: 'placed', label: 'Order placed', atMs: createdAtMs, done: true },\n    {\n      key: 'paid',\n      label: 'Payment confirmed',\n      atMs: paidAtMs,\n      done: status !== 'pending' && paidAtMs !== null,\n    },\n  ]\n  if (status === 'cancelled') {\n    steps.push({ key: 'cancelled', label: 'Canceled', atMs: eventAt(order, 'cancelled'), done: true })\n  } else {\n    steps.push(\n      {\n        key: 'shipped',\n        label: status === 'partially_fulfilled' ? 'Partly shipped' : 'Shipped',\n        atMs: firstShipAt,\n        done: ['partially_fulfilled', 'fulfilled', 'delivered'].includes(status) ||\n          shipments.length > 0,\n      },\n      {\n        key: 'delivered',\n        label: 'Delivered',\n        atMs: deliveredAt,\n        done: status === 'delivered' || deliveredAt !== null,\n      },\n    )\n  }\n  if (status === 'refunded') {\n    steps.push({ key: 'refunded', label: 'Refunded', atMs: eventAt(order, 'refund'), done: true })\n  }\n  return {\n    storeName: input.storeName,\n    number: input.number,\n    status,\n    statusLabel: STATUS_LABELS[status] ?? 'Confirmed',\n    createdAtMs,\n    currency: input.currency || 'USD',\n    lines,\n    totals: {\n      itemsCents: totals?.itemsCents ?? lines.reduce((sum, line) => sum + line.amountCents, 0),\n      shippingCents: totals?.shippingCents ?? 0,\n      taxCents: totals?.taxCents ?? 0,\n      discountCents: totals?.discountCents ?? 0,\n      totalCents,\n      refundedCents: Number(order.refundedCents ?? 0) || 0,\n    },\n    extras: (order.extras ?? [])\n      .filter((extra) => extra && Number(extra.amountCents) > 0)\n      .map((extra) => ({ label: String(extra.label || 'Extra'), amountCents: Number(extra.amountCents) })),\n    shipments,\n    steps,\n    actions: input.actions ?? [],\n  }\n}\n"],"names":["fulfillmentIsActive","fulfillmentLineQuantities","carrierLabelFor","fulfillmentTrackingUrl","STATUS_LABELS","pending","paid","partially_fulfilled","fulfilled","delivered","cancelled","refunded","eventAt","order","events","found","timeline","find","entry","includes","String","event","Number","atMs","buildOrderStatusView","input","shipments","lineItems","active","fulfillments","filter","shippedByLine","Map","map","fulfillment","quantities","set","lineItemId","get","quantity","id","carrier","trackingNumber","trackingUrl","lines","name","sort","a","b","refundedLines","Set","refundedLineItemIds","line","index","variantLabel","amountCents","unitAmountCents","shippedQuantity","Math","min","has","totals","totalCents","status","createdAtMs","paidAtMs","firstShipAt","deliveredAt","steps","key","label","done","push","length","storeName","number","statusLabel","currency","itemsCents","reduce","sum","shippingCents","taxCents","discountCents","refundedCents","extras","extra","actions"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,mBAAmB,EAAEC,yBAAyB,QAAQ,yBAAqB;AACpF,SAASC,eAAe,EAAEC,sBAAsB,QAAQ,oBAAgB;AA8ExE,MAAMC,gBAA6C;IACjDC,SAAS;IACTC,MAAM;IACNC,qBAAqB;IACrBC,WAAW;IACXC,WAAW;IACXC,WAAW;IACXC,UAAU;AACZ;AAEA,SAASC,QAAQC,KAAgB,EAAE,GAAGC,MAAgB;QACrCD;IAAf,MAAME,QAAQ,EAACF,kBAAAA,MAAMG,QAAQ,YAAdH,kBAAkB,EAAE,EAAEI,IAAI,CAAC,CAACC;;eACzCJ,OAAOK,QAAQ,CAACC,eAAOF,yBAAAA,MAAOG,KAAK,mBAAI;;IAEzC,OAAON,QAAQO,OAAOP,MAAMQ,IAAI,KAAK,OAAO;AAC9C;AAEA,0EAA0E,GAC1E,OAAO,SAASC,qBAAqBC,KAOpC;QAEmBZ,kBACFA,qBAwBcA,kCAUkBA,oBAG/BD,iBAsCFR,mDAUWS,sBAEfA,eAKAY;QAtDSC;IAxCpB,MAAM,EAAEb,KAAK,EAAE,GAAGY;IAClB,MAAME,aAAYd,mBAAAA,MAAMc,SAAS,YAAfd,mBAAmB,EAAE;IACvC,MAAMe,SAAS,EAACf,sBAAAA,MAAMgB,YAAY,YAAlBhB,sBAAsB,EAAE,EAAEiB,MAAM,CAAC9B;IACjD,MAAM+B,gBAAgB,IAAIC;IAC1B,MAAMN,YAAmCE,OACtCK,GAAG,CAAC,CAACC;YASSA,iBAGKA;QAXlB,MAAMC,aAAalC,0BAA0BY,OAAOqB;QACpD,KAAK,MAAMhB,SAASiB,WAAY;gBAG3BJ;YAFHA,cAAcK,GAAG,CACflB,MAAMmB,UAAU,EAChB,EAACN,qBAAAA,cAAcO,GAAG,CAACpB,MAAMmB,UAAU,aAAlCN,qBAAuC,KAAKb,MAAMqB,QAAQ;QAE/D;QACA,OAAO;YACLC,IAAIpB,QAAOc,kBAAAA,YAAYM,EAAE,YAAdN,kBAAkB;YAC7BX,MAAMD,OAAOY,YAAYX,IAAI,KAAK;YAClCkB,SAASP,YAAYO,OAAO,GAAGvC,gBAAgBgC,YAAYO,OAAO,IAAI;YACtEC,cAAc,GAAER,8BAAAA,YAAYQ,cAAc,YAA1BR,8BAA8B;YAC9CS,aAAaxC,uBAAuB+B;YACpCU,OAAOT,WAAWF,GAAG,CAAC,CAACf;;oBACRS;uBADmB;oBAChCkB,MAAMzB,gBAAOO,8BAAAA,SAAS,CAACT,MAAMmB,UAAU,CAAC,qBAA3BV,4BAA6BkB,IAAI,mBAAI;oBAClDN,UAAUrB,MAAMqB,QAAQ;gBAC1B;;QACF;IACF,GACCO,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAExB,IAAI,GAAGyB,EAAEzB,IAAI;IACjC,MAAM0B,gBAAgB,IAAIC,KAAIrC,6BAAAA,MAAMsC,mBAAmB,YAAzBtC,6BAA6B,EAAE;IAC7D,MAAM+B,QAA2BjB,UAAUM,GAAG,CAAC,CAACmB,MAAMC;YACvCD,YACCA,oBAGwCrB;eALS;YAC/Dc,MAAMzB,QAAOgC,aAAAA,KAAKP,IAAI,YAATO,aAAa;YAC1BE,YAAY,GAAEF,qBAAAA,KAAKE,YAAY,YAAjBF,qBAAqB;YACnCb,UAAUjB,OAAO8B,KAAKb,QAAQ,KAAK;YACnCgB,aAAa,AAACjC,CAAAA,OAAO8B,KAAKI,eAAe,KAAK,CAAA,IAAMlC,CAAAA,OAAO8B,KAAKb,QAAQ,KAAK,CAAA;YAC7EkB,iBAAiBC,KAAKC,GAAG,CAACrC,OAAO8B,KAAKb,QAAQ,KAAK,IAAGR,qBAAAA,cAAcO,GAAG,CAACe,kBAAlBtB,qBAA4B;YAClFpB,UAAUsC,cAAcW,GAAG,CAACP;QAC9B;;IACA,MAAMQ,SAAShD,MAAMgD,MAAM;IAC3B,MAAMC,qBAAaD,0BAAAA,OAAQC,UAAU,mBAAIxC,QAAOT,qBAAAA,MAAM0C,WAAW,YAAjB1C,qBAAqB;IACrE,MAAMkD,SAASlD,MAAMkD,MAAM;IAC3B,MAAMC,cAAc1C,OAAOT,MAAMmD,WAAW,KAAK;IACjD,MAAMC,YAAWrD,WAAAA,QAAQC,OAAO,mBAAfD,WAA2BmD,WAAW,YAAYC,cAAc;IACjF,MAAME,wBAAcxC,cAAAA,SAAS,CAAC,EAAE,qBAAZA,YAAcH,IAAI,oBAAIX,QAAQC,OAAO,aAAa;IACtE,MAAMsD,cAAcvD,QAAQC,OAAO;IACnC,MAAMuD,QAA2B;QAC/B;YAAEC,KAAK;YAAUC,OAAO;YAAgB/C,MAAMyC;YAAaO,MAAM;QAAK;QACtE;YACEF,KAAK;YACLC,OAAO;YACP/C,MAAM0C;YACNM,MAAMR,WAAW,aAAaE,aAAa;QAC7C;KACD;IACD,IAAIF,WAAW,aAAa;QAC1BK,MAAMI,IAAI,CAAC;YAAEH,KAAK;YAAaC,OAAO;YAAY/C,MAAMX,QAAQC,OAAO;YAAc0D,MAAM;QAAK;IAClG,OAAO;QACLH,MAAMI,IAAI,CACR;YACEH,KAAK;YACLC,OAAOP,WAAW,wBAAwB,mBAAmB;YAC7DxC,MAAM2C;YACNK,MAAM;gBAAC;gBAAuB;gBAAa;aAAY,CAACpD,QAAQ,CAAC4C,WAC/DrC,UAAU+C,MAAM,GAAG;QACvB,GACA;YACEJ,KAAK;YACLC,OAAO;YACP/C,MAAM4C;YACNI,MAAMR,WAAW,eAAeI,gBAAgB;QAClD;IAEJ;IACA,IAAIJ,WAAW,YAAY;QACzBK,MAAMI,IAAI,CAAC;YAAEH,KAAK;YAAYC,OAAO;YAAY/C,MAAMX,QAAQC,OAAO;YAAW0D,MAAM;QAAK;IAC9F;IACA,OAAO;QACLG,WAAWjD,MAAMiD,SAAS;QAC1BC,QAAQlD,MAAMkD,MAAM;QACpBZ;QACAa,WAAW,GAAExE,wBAAAA,aAAa,CAAC2D,OAAO,YAArB3D,wBAAyB;QACtC4D;QACAa,UAAUpD,MAAMoD,QAAQ,IAAI;QAC5BjC;QACAiB,QAAQ;YACNiB,UAAU,WAAEjB,0BAAAA,OAAQiB,UAAU,oBAAIlC,MAAMmC,MAAM,CAAC,CAACC,KAAK5B,OAAS4B,MAAM5B,KAAKG,WAAW,EAAE;YACtF0B,aAAa,WAAEpB,0BAAAA,OAAQoB,aAAa,oBAAI;YACxCC,QAAQ,WAAErB,0BAAAA,OAAQqB,QAAQ,oBAAI;YAC9BC,aAAa,WAAEtB,0BAAAA,OAAQsB,aAAa,oBAAI;YACxCrB;YACAsB,eAAe9D,QAAOT,uBAAAA,MAAMuE,aAAa,YAAnBvE,uBAAuB,MAAM;QACrD;QACAwE,QAAQ,EAACxE,gBAAAA,MAAMwE,MAAM,YAAZxE,gBAAgB,EAAE,EACxBiB,MAAM,CAAC,CAACwD,QAAUA,SAAShE,OAAOgE,MAAM/B,WAAW,IAAI,GACvDtB,GAAG,CAAC,CAACqD,QAAW,CAAA;gBAAEhB,OAAOlD,OAAOkE,MAAMhB,KAAK,IAAI;gBAAUf,aAAajC,OAAOgE,MAAM/B,WAAW;YAAE,CAAA;QACnG7B;QACA0C;QACAmB,OAAO,GAAE9D,iBAAAA,MAAM8D,OAAO,YAAb9D,iBAAiB,EAAE;IAC9B;AACF"}

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

@@ -0,0 +1,142 @@
+/**
+ * @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 CommerceEventName } from './order-events';
+/**
+ * Merchant order webhooks (AGL-3611): endpoints a store adds so its own
+ * systems hear about orders — an ERP, a warehouse, a spreadsheet script.
+ *
+ * Three collections under the site, every one written only by
+ * `/api/commerce/order-webhooks` and by the event subscriber:
+ *
+ *  - `orderWebhooks/{id}`: the endpoint — its URL, the events it takes,
+ *    whether it is on, and the last few characters of its secret so a person
+ *    can tell two apart. Read by the order book's readers.
+ *  - `orderWebhookSecrets/{id}`: the signing secret, sealed with the shared
+ *    secret box. No client reads it; the merchant sees the secret once, when
+ *    it is made or rolled.
+ *  - `orderWebhookDeliveries/{id}`: the delivery log, one row per event per
+ *    endpoint, with each attempt's status. Read by the order book's readers.
+ *
+ * Each event commerce raises reaches each endpoint that takes it AT LEAST
+ * ONCE, through the plugin event outbox, which retries with backoff. A
+ * receiver dedupes on the `Aglyn-Event-Id` header, which is the same on every
+ * attempt.
+ */
+/** `hosts/{hostId}/orderWebhooks/{id}`. */
+export interface OrderWebhookEndpoint {
+    url: string;
+    /** The event names this endpoint takes. */
+    events: CommerceEventName[];
+    enabled: boolean;
+    /** An optional label, e.g. "Warehouse". */
+    description?: string;
+    /** The secret's last four characters, to tell secrets apart. */
+    secretHint: string;
+    /** Deliveries that failed in a row; any success resets it. */
+    consecutiveFailures: number;
+    lastDeliveryAtMs?: number;
+    lastDeliveryStatus?: OrderWebhookDeliveryStatus;
+    createdAtMs: number;
+    updatedAtMs: number;
+    createdBy: string;
+}
+/** `hosts/{hostId}/orderWebhookSecrets/{id}`, Admin SDK only. */
+export interface OrderWebhookSecretRecord {
+    /** The signing secret, sealed (`sealSecret`), bound to this endpoint. */
+    sealedSecret: string;
+    /** The id of the key that sealed it, for rotation. */
+    secretKeyId: string;
+    updatedAtMs: number;
+}
+export type OrderWebhookDeliveryStatus = 'delivered' | 'retrying' | 'failed';
+/** One attempt at a delivery. */
+export interface OrderWebhookAttempt {
+    atMs: number;
+    /** The receiver's HTTP status; `null` when no answer came back. */
+    httpStatus: number | null;
+    /** Why it failed, in words; absent on a success. */
+    error?: string;
+    durationMs: number;
+}
+/** `hosts/{hostId}/orderWebhookDeliveries/{eventId}__{endpointId}`. */
+export interface OrderWebhookDelivery {
+    endpointId: string;
+    /** The event's id, the same on every attempt: `Aglyn-Event-Id`. */
+    eventId: string;
+    event: string;
+    /** The order the event is about. */
+    orderId: string | null;
+    status: OrderWebhookDeliveryStatus;
+    attempts: OrderWebhookAttempt[];
+    /** The JSON body as sent, so a resend sends the same bytes' meaning. */
+    body: string;
+    /** A test ping from the console rather than a real event. */
+    test?: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+/** A store may keep this many endpoints. */
+export declare const ORDER_WEBHOOK_MAX_ENDPOINTS = 10;
+/** A receiver has this long to answer before the attempt counts as failed. */
+export declare const ORDER_WEBHOOK_TIMEOUT_MS = 8000;
+/** Attempts a delivery row keeps; older ones fall off. */
+export declare const ORDER_WEBHOOK_ATTEMPTS_KEPT = 10;
+/** The most a stored body may hold; a longer one is stored cut, and sent whole. */
+export declare const ORDER_WEBHOOK_BODY_MAX = 200000;
+/** A signature is good this long after its timestamp, for a receiver checking it. */
+export declare const ORDER_WEBHOOK_TOLERANCE_SECONDS = 300;
+export declare const ORDER_WEBHOOK_SIGNATURE_HEADER = "Aglyn-Signature";
+export declare const ORDER_WEBHOOK_EVENT_HEADER = "Aglyn-Event";
+export declare const ORDER_WEBHOOK_EVENT_ID_HEADER = "Aglyn-Event-Id";
+/** The ping the console's Send test event posts. */
+export declare const ORDER_WEBHOOK_TEST_EVENT = "webhook.test";
+/** The document id of one event's delivery to one endpoint. */
+export declare function orderWebhookDeliveryId(eventId: string, endpointId: string): string;
+/** The event names a merchant picked, cleaned: known names only, in list order. */
+export declare function normalizeOrderWebhookEvents(raw: unknown): CommerceEventName[];
+/** Whether an endpoint should be handed an event that happened at `occurredAtMs`. */
+export declare function orderWebhookTakes(endpoint: Pick<OrderWebhookEndpoint, 'enabled' | 'events' | 'createdAtMs'>, event: string, occurredAtMs: number): boolean;
+/** A 2xx is a delivery; anything else, a redirect included, is a failure. */
+export declare function orderWebhookAccepted(httpStatus: number | null): boolean;
+/** The string a signature covers: `{timestamp}.{body}`, as Stripe's does. */
+export declare function orderWebhookSignedPayload(timestampSeconds: number, body: string): string;
+/** The `Aglyn-Signature` header value: `t={timestamp},v1={hex HMAC-SHA256}`. */
+export declare function formatOrderWebhookSignature(timestampSeconds: number, hexDigest: string): string;
+/** Reads `t` and every `v1` from a signature header, for a receiver's check. */
+export declare function parseOrderWebhookSignature(header: string): {
+    timestamp: number;
+    signatures: string[];
+} | null;
+/** The JSON a receiver is posted. `data` is the event's payload. */
+export interface OrderWebhookBody {
+    id: string;
+    type: string;
+    createdAt: string;
+    siteId: string;
+    data: unknown;
+}
+export declare function orderWebhookBody(input: {
+    eventId: string;
+    event: string;
+    occurredAtMs: number;
+    hostId: string;
+    payload: unknown;
+}): string;
+/** Appends an attempt, keeping the latest few. */
+export declare function appendOrderWebhookAttempt(attempts: readonly OrderWebhookAttempt[] | undefined, attempt: OrderWebhookAttempt): OrderWebhookAttempt[];
+export declare const ORDER_WEBHOOK_DELIVERY_STATUS_LABELS: Record<OrderWebhookDeliveryStatus, string>;
+export declare const ORDER_WEBHOOK_DELIVERY_STATUS_COLOR: Record<OrderWebhookDeliveryStatus, 'success' | 'warning' | 'error'>;

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

@@ -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 { COMMERCE_EVENT_NAMES } from "./order-events.js";
+/** A store may keep this many endpoints. */ export const ORDER_WEBHOOK_MAX_ENDPOINTS = 10;
+/** A receiver has this long to answer before the attempt counts as failed. */ export const ORDER_WEBHOOK_TIMEOUT_MS = 8000;
+/** Attempts a delivery row keeps; older ones fall off. */ export const ORDER_WEBHOOK_ATTEMPTS_KEPT = 10;
+/** The most a stored body may hold; a longer one is stored cut, and sent whole. */ export const ORDER_WEBHOOK_BODY_MAX = 200000;
+/** A signature is good this long after its timestamp, for a receiver checking it. */ export const ORDER_WEBHOOK_TOLERANCE_SECONDS = 300;
+export const ORDER_WEBHOOK_SIGNATURE_HEADER = 'Aglyn-Signature';
+export const ORDER_WEBHOOK_EVENT_HEADER = 'Aglyn-Event';
+export const ORDER_WEBHOOK_EVENT_ID_HEADER = 'Aglyn-Event-Id';
+/** The ping the console's Send test event posts. */ export const ORDER_WEBHOOK_TEST_EVENT = 'webhook.test';
+/** The document id of one event's delivery to one endpoint. */ export function orderWebhookDeliveryId(eventId, endpointId) {
+    return `${eventId}__${endpointId}`.replace(/\//g, '_').slice(0, 1400);
+}
+/** The event names a merchant picked, cleaned: known names only, in list order. */ export function normalizeOrderWebhookEvents(raw) {
+    const wanted = new Set(Array.isArray(raw) ? raw.map((value)=>String(value)) : []);
+    return COMMERCE_EVENT_NAMES.filter((name)=>wanted.has(name));
+}
+/** Whether an endpoint should be handed an event that happened at `occurredAtMs`. */ export function orderWebhookTakes(endpoint, event, occurredAtMs) {
+    var _endpoint_events;
+    if (!endpoint.enabled) return false;
+    if (!((_endpoint_events = endpoint.events) != null ? _endpoint_events : []).includes(event)) return false;
+    // An endpoint added after the fact does not receive it on a retry.
+    return !(Number(endpoint.createdAtMs) > occurredAtMs);
+}
+/** A 2xx is a delivery; anything else, a redirect included, is a failure. */ export function orderWebhookAccepted(httpStatus) {
+    return httpStatus !== null && httpStatus >= 200 && httpStatus < 300;
+}
+/** The string a signature covers: `{timestamp}.{body}`, as Stripe's does. */ export function orderWebhookSignedPayload(timestampSeconds, body) {
+    return `${timestampSeconds}.${body}`;
+}
+/** The `Aglyn-Signature` header value: `t={timestamp},v1={hex HMAC-SHA256}`. */ export function formatOrderWebhookSignature(timestampSeconds, hexDigest) {
+    return `t=${timestampSeconds},v1=${hexDigest}`;
+}
+/** Reads `t` and every `v1` from a signature header, for a receiver's check. */ export function parseOrderWebhookSignature(header) {
+    let timestamp = Number.NaN;
+    const signatures = [];
+    for (const part of String(header != null ? header : '').split(',')){
+        const [key, value] = part.split('=', 2).map((piece)=>piece.trim());
+        if (key === 't') timestamp = Number(value);
+        else if (key === 'v1' && value) signatures.push(value);
+    }
+    if (!Number.isInteger(timestamp) || signatures.length === 0) return null;
+    return {
+        timestamp,
+        signatures
+    };
+}
+export function orderWebhookBody(input) {
+    var _input_payload;
+    const body = {
+        id: input.eventId,
+        type: input.event,
+        createdAt: new Date(input.occurredAtMs).toISOString(),
+        siteId: input.hostId,
+        data: (_input_payload = input.payload) != null ? _input_payload : null
+    };
+    return JSON.stringify(body);
+}
+/** Appends an attempt, keeping the latest few. */ export function appendOrderWebhookAttempt(attempts, attempt) {
+    return [
+        ...attempts != null ? attempts : [],
+        attempt
+    ].slice(-ORDER_WEBHOOK_ATTEMPTS_KEPT);
+}
+export const ORDER_WEBHOOK_DELIVERY_STATUS_LABELS = {
+    delivered: 'Delivered',
+    retrying: 'Retrying',
+    failed: 'Failed'
+};
+export const ORDER_WEBHOOK_DELIVERY_STATUS_COLOR = {
+    delivered: 'success',
+    retrying: 'warning',
+    failed: 'error'
+};
+
+//# sourceMappingURL=order-webhooks.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/order-webhooks.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 { COMMERCE_EVENT_NAMES, type CommerceEventName } from './order-events'\n\n/**\n * Merchant order webhooks (AGL-3611): endpoints a store adds so its own\n * systems hear about orders — an ERP, a warehouse, a spreadsheet script.\n *\n * Three collections under the site, every one written only by\n * `/api/commerce/order-webhooks` and by the event subscriber:\n *\n *  - `orderWebhooks/{id}`: the endpoint — its URL, the events it takes,\n *    whether it is on, and the last few characters of its secret so a person\n *    can tell two apart. Read by the order book's readers.\n *  - `orderWebhookSecrets/{id}`: the signing secret, sealed with the shared\n *    secret box. No client reads it; the merchant sees the secret once, when\n *    it is made or rolled.\n *  - `orderWebhookDeliveries/{id}`: the delivery log, one row per event per\n *    endpoint, with each attempt's status. Read by the order book's readers.\n *\n * Each event commerce raises reaches each endpoint that takes it AT LEAST\n * ONCE, through the plugin event outbox, which retries with backoff. A\n * receiver dedupes on the `Aglyn-Event-Id` header, which is the same on every\n * attempt.\n */\n\n/** `hosts/{hostId}/orderWebhooks/{id}`. */\nexport interface OrderWebhookEndpoint {\n  url: string\n  /** The event names this endpoint takes. */\n  events: CommerceEventName[]\n  enabled: boolean\n  /** An optional label, e.g. \"Warehouse\". */\n  description?: string\n  /** The secret's last four characters, to tell secrets apart. */\n  secretHint: string\n  /** Deliveries that failed in a row; any success resets it. */\n  consecutiveFailures: number\n  lastDeliveryAtMs?: number\n  lastDeliveryStatus?: OrderWebhookDeliveryStatus\n  createdAtMs: number\n  updatedAtMs: number\n  createdBy: string\n}\n\n/** `hosts/{hostId}/orderWebhookSecrets/{id}`, Admin SDK only. */\nexport interface OrderWebhookSecretRecord {\n  /** The signing secret, sealed (`sealSecret`), bound to this endpoint. */\n  sealedSecret: string\n  /** The id of the key that sealed it, for rotation. */\n  secretKeyId: string\n  updatedAtMs: number\n}\n\nexport type OrderWebhookDeliveryStatus = 'delivered' | 'retrying' | 'failed'\n\n/** One attempt at a delivery. */\nexport interface OrderWebhookAttempt {\n  atMs: number\n  /** The receiver's HTTP status; `null` when no answer came back. */\n  httpStatus: number | null\n  /** Why it failed, in words; absent on a success. */\n  error?: string\n  durationMs: number\n}\n\n/** `hosts/{hostId}/orderWebhookDeliveries/{eventId}__{endpointId}`. */\nexport interface OrderWebhookDelivery {\n  endpointId: string\n  /** The event's id, the same on every attempt: `Aglyn-Event-Id`. */\n  eventId: string\n  event: string\n  /** The order the event is about. */\n  orderId: string | null\n  status: OrderWebhookDeliveryStatus\n  attempts: OrderWebhookAttempt[]\n  /** The JSON body as sent, so a resend sends the same bytes' meaning. */\n  body: string\n  /** A test ping from the console rather than a real event. */\n  test?: boolean\n  createdAtMs: number\n  updatedAtMs: number\n}\n\n/** A store may keep this many endpoints. */\nexport const ORDER_WEBHOOK_MAX_ENDPOINTS = 10\n\n/** A receiver has this long to answer before the attempt counts as failed. */\nexport const ORDER_WEBHOOK_TIMEOUT_MS = 8_000\n\n/** Attempts a delivery row keeps; older ones fall off. */\nexport const ORDER_WEBHOOK_ATTEMPTS_KEPT = 10\n\n/** The most a stored body may hold; a longer one is stored cut, and sent whole. */\nexport const ORDER_WEBHOOK_BODY_MAX = 200_000\n\n/** A signature is good this long after its timestamp, for a receiver checking it. */\nexport const ORDER_WEBHOOK_TOLERANCE_SECONDS = 300\n\nexport const ORDER_WEBHOOK_SIGNATURE_HEADER = 'Aglyn-Signature'\nexport const ORDER_WEBHOOK_EVENT_HEADER = 'Aglyn-Event'\nexport const ORDER_WEBHOOK_EVENT_ID_HEADER = 'Aglyn-Event-Id'\n\n/** The ping the console's Send test event posts. */\nexport const ORDER_WEBHOOK_TEST_EVENT = 'webhook.test'\n\n/** The document id of one event's delivery to one endpoint. */\nexport function orderWebhookDeliveryId(eventId: string, endpointId: string): string {\n  return `${eventId}__${endpointId}`.replace(/\\//g, '_').slice(0, 1400)\n}\n\n/** The event names a merchant picked, cleaned: known names only, in list order. */\nexport function normalizeOrderWebhookEvents(raw: unknown): CommerceEventName[] {\n  const wanted = new Set(Array.isArray(raw) ? (raw as unknown[]).map((value) => String(value)) : [])\n  return COMMERCE_EVENT_NAMES.filter((name) => wanted.has(name))\n}\n\n/** Whether an endpoint should be handed an event that happened at `occurredAtMs`. */\nexport function orderWebhookTakes(\n  endpoint: Pick<OrderWebhookEndpoint, 'enabled' | 'events' | 'createdAtMs'>,\n  event: string,\n  occurredAtMs: number,\n): boolean {\n  if (!endpoint.enabled) return false\n  if (!(endpoint.events ?? []).includes(event as CommerceEventName)) return false\n  // An endpoint added after the fact does not receive it on a retry.\n  return !(Number(endpoint.createdAtMs) > occurredAtMs)\n}\n\n/** A 2xx is a delivery; anything else, a redirect included, is a failure. */\nexport function orderWebhookAccepted(httpStatus: number | null): boolean {\n  return httpStatus !== null && httpStatus >= 200 && httpStatus < 300\n}\n\n/** The string a signature covers: `{timestamp}.{body}`, as Stripe's does. */\nexport function orderWebhookSignedPayload(timestampSeconds: number, body: string): string {\n  return `${timestampSeconds}.${body}`\n}\n\n/** The `Aglyn-Signature` header value: `t={timestamp},v1={hex HMAC-SHA256}`. */\nexport function formatOrderWebhookSignature(timestampSeconds: number, hexDigest: string): string {\n  return `t=${timestampSeconds},v1=${hexDigest}`\n}\n\n/** Reads `t` and every `v1` from a signature header, for a receiver's check. */\nexport function parseOrderWebhookSignature(header: string): { timestamp: number; signatures: string[] } | null {\n  let timestamp = Number.NaN\n  const signatures: string[] = []\n  for (const part of String(header ?? '').split(',')) {\n    const [key, value] = part.split('=', 2).map((piece) => piece.trim())\n    if (key === 't') timestamp = Number(value)\n    else if (key === 'v1' && value) signatures.push(value)\n  }\n  if (!Number.isInteger(timestamp) || signatures.length === 0) return null\n  return { timestamp, signatures }\n}\n\n/** The JSON a receiver is posted. `data` is the event's payload. */\nexport interface OrderWebhookBody {\n  id: string\n  type: string\n  createdAt: string\n  siteId: string\n  data: unknown\n}\n\nexport function orderWebhookBody(input: {\n  eventId: string\n  event: string\n  occurredAtMs: number\n  hostId: string\n  payload: unknown\n}): string {\n  const body: OrderWebhookBody = {\n    id: input.eventId,\n    type: input.event,\n    createdAt: new Date(input.occurredAtMs).toISOString(),\n    siteId: input.hostId,\n    data: input.payload ?? null,\n  }\n  return JSON.stringify(body)\n}\n\n/** Appends an attempt, keeping the latest few. */\nexport function appendOrderWebhookAttempt(\n  attempts: readonly OrderWebhookAttempt[] | undefined,\n  attempt: OrderWebhookAttempt,\n): OrderWebhookAttempt[] {\n  return [...(attempts ?? []), attempt].slice(-ORDER_WEBHOOK_ATTEMPTS_KEPT)\n}\n\nexport const ORDER_WEBHOOK_DELIVERY_STATUS_LABELS: Record<OrderWebhookDeliveryStatus, string> = {\n  delivered: 'Delivered',\n  retrying: 'Retrying',\n  failed: 'Failed',\n}\n\nexport const ORDER_WEBHOOK_DELIVERY_STATUS_COLOR: Record<OrderWebhookDeliveryStatus, 'success' | 'warning' | 'error'> = {\n  delivered: 'success',\n  retrying: 'warning',\n  failed: 'error',\n}\n"],"names":["COMMERCE_EVENT_NAMES","ORDER_WEBHOOK_MAX_ENDPOINTS","ORDER_WEBHOOK_TIMEOUT_MS","ORDER_WEBHOOK_ATTEMPTS_KEPT","ORDER_WEBHOOK_BODY_MAX","ORDER_WEBHOOK_TOLERANCE_SECONDS","ORDER_WEBHOOK_SIGNATURE_HEADER","ORDER_WEBHOOK_EVENT_HEADER","ORDER_WEBHOOK_EVENT_ID_HEADER","ORDER_WEBHOOK_TEST_EVENT","orderWebhookDeliveryId","eventId","endpointId","replace","slice","normalizeOrderWebhookEvents","raw","wanted","Set","Array","isArray","map","value","String","filter","name","has","orderWebhookTakes","endpoint","event","occurredAtMs","enabled","events","includes","Number","createdAtMs","orderWebhookAccepted","httpStatus","orderWebhookSignedPayload","timestampSeconds","body","formatOrderWebhookSignature","hexDigest","parseOrderWebhookSignature","header","timestamp","NaN","signatures","part","split","key","piece","trim","push","isInteger","length","orderWebhookBody","input","id","type","createdAt","Date","toISOString","siteId","hostId","data","payload","JSON","stringify","appendOrderWebhookAttempt","attempts","attempt","ORDER_WEBHOOK_DELIVERY_STATUS_LABELS","delivered","retrying","failed","ORDER_WEBHOOK_DELIVERY_STATUS_COLOR"],"mappings":"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"}

package/src/lib/model/product-channel.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @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.
+ */
+/**
+ * What shopping channels ask of a product beyond what the store shows
+ * (AGL-3637): the brand, the manufacturer's identifiers, the condition and
+ * Google's category. Entered in the product editor's channel fields and read
+ * by the product catalog the store publishes to other plugins
+ * (`server/product-catalog.ts`). Every field is optional: a channel feed
+ * falls back to the store's defaults and says what is missing.
+ */
+export interface ProductChannelFacts {
+    /** The brand a shopper knows it by; at most 70 characters. */
+    brand?: string;
+    /**
+     * The product's GTIN (UPC, EAN, ISBN, JAN or ITF-14), digits only. For a
+     * product with several configurations each variant's barcode is its own.
+     */
+    gtin?: string;
+    /** The manufacturer's part number; at most 70 characters. */
+    mpn?: string;
+    condition?: 'new' | 'refurbished' | 'used';
+    /** A Google product taxonomy id (`2271`) or full path. */
+    googleProductCategory?: string;
+}
+export declare const PRODUCT_CHANNEL_CONDITIONS: readonly ["new", "refurbished", "used"];
+/** Digits only, at most 14: what a barcode field holds once spaces and dashes are gone. */
+export declare function normalizeGtin(value: unknown): string;
+/**
+ * A stored product's channel facts made safe; `undefined` when nothing is
+ * set. Never throws: the field is written by the editor, the importer and the
+ * REST API, and read on every feed fetch.
+ */
+export declare function normalizeProductChannelFacts(value: unknown): ProductChannelFacts | undefined;
+/**
+ * Channel facts as the product editor stages them, keystroke by keystroke:
+ * what {@link normalizeProductChannelFacts} keeps, except that a field being
+ * typed is kept as typed — a barcode shorter than eight digits, a brand with
+ * the space before its next word. The editor runs this on every keystroke, so
+ * the strict form would erase the field under the cursor; readers normalize
+ * what is stored, so a half-typed value never reaches a channel.
+ */
+export declare function draftProductChannelFacts(value: unknown): ProductChannelFacts | undefined;