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

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

@@ -0,0 +1,154 @@
+/**
+ * @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 PluginDomainEvent, type PluginDomainEventDeclaration } from '@aglyn/aglyn/plugin-manager/plugin-domain-events';
+/**
+ * The order and return events commerce raises (AGL-3611), for other plugins
+ * — accounting, shipping, workflows — and for the merchant's own webhooks.
+ *
+ * Each payload carries `order` in the public API's shape (`GET
+ * /v1/sites/{siteId}/orders/{orderId}`), as it stood once the fact was
+ * written, so a subscriber reads one documented object rather than the
+ * plugin's storage. A subscriber in another plugin restates the fields it
+ * reads; these types are this plugin's own.
+ */
+/** An order as the public API returns it. Money is integer cents. */
+export interface OrderEventOrder {
+    id: string;
+    object: 'order';
+    number: number | null;
+    status: string | null;
+    channel: string;
+    currency: string;
+    customerEmail: string | null;
+    customerName: string | null;
+    lineItems: unknown;
+    totals: {
+        itemsCents: number;
+        shippingCents: number;
+        taxCents: number;
+        discountCents: number;
+        totalCents: number | null;
+        feeCents: number;
+    };
+    refundedCents: number;
+    /** The tax regime: `stripe-automatic`, `manual`, `none`, or `null` when not recorded. */
+    taxMode: string | null;
+    [key: string]: unknown;
+}
+/** A shipment as an event carries it. */
+export interface OrderEventFulfillment {
+    id: string;
+    lines: Array<{
+        lineItemId: number;
+        quantity: number;
+    }>;
+    carrier: string | null;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    labelUrl: string | null;
+    at: string;
+}
+/** A refund as an event carries it: what THIS refund moved. */
+export interface OrderEventRefund {
+    /** Stripe's refund id, when there is one. */
+    id: string | null;
+    amountCents: number;
+    /** The line indexes refunded by name; empty for an amount-only refund. */
+    lineItemIds: number[];
+    /** Whether this refund left nothing more to refund. */
+    full: boolean;
+}
+/** A return as an event carries it. */
+export interface OrderEventReturn {
+    id: string;
+    status: string;
+    lines: Array<{
+        lineItemId: number;
+        quantity: number;
+        reason: string;
+    }>;
+    refundCents: number | null;
+    /** What went back in stock when the parcel arrived; `null` before then. */
+    restock?: Array<{
+        lineItemId: number;
+        quantity: number;
+    }> | null;
+}
+export interface OrderEventPayload {
+    order: OrderEventOrder;
+}
+export interface OrderFulfilledEventPayload extends OrderEventPayload {
+    fulfillment: OrderEventFulfillment;
+}
+export interface OrderRefundedEventPayload extends OrderEventPayload {
+    refund: OrderEventRefund;
+}
+export interface ReturnEventPayload extends OrderEventPayload {
+    return: OrderEventReturn;
+}
+export declare const ORDER_PAID_EVENT: PluginDomainEvent<OrderEventPayload>;
+export declare const ORDER_FULFILLED_EVENT: PluginDomainEvent<OrderFulfilledEventPayload>;
+export declare const ORDER_DELIVERED_EVENT: PluginDomainEvent<OrderEventPayload>;
+export declare const ORDER_REFUNDED_EVENT: PluginDomainEvent<OrderRefundedEventPayload>;
+export declare const ORDER_CANCELLED_EVENT: PluginDomainEvent<OrderEventPayload>;
+export declare const RETURN_REQUESTED_EVENT: PluginDomainEvent<ReturnEventPayload>;
+export declare const RETURN_APPROVED_EVENT: PluginDomainEvent<ReturnEventPayload>;
+export declare const RETURN_DECLINED_EVENT: PluginDomainEvent<ReturnEventPayload>;
+export declare const RETURN_RECEIVED_EVENT: PluginDomainEvent<ReturnEventPayload>;
+export declare const RETURN_REFUNDED_EVENT: PluginDomainEvent<ReturnEventPayload>;
+/**
+ * A checkout a shopper reached with an address (AGL-3639): the fact an
+ * abandoned-cart flow in a merchant's own email platform starts from. Not an
+ * order event — nothing was bought — so it is raised beside them rather than
+ * among them: it is not a workflow trigger and not offered to the merchant's
+ * outbound webhooks, whose events are about orders.
+ */
+export interface CheckoutStartedEventPayload {
+    checkout: {
+        /** The checkout session's id: one event per checkout. */
+        id: string;
+        email: string;
+        /** Whether the shopper ticked the store's marketing box at checkout. */
+        marketingOptIn: boolean;
+        currency: string;
+        /** The basket's list value, integer cents, before discounts and shipping. */
+        itemsCents: number;
+        /** Where the shopper can pick the checkout up again. */
+        resumeUrl: string | null;
+        items: Array<{
+            productId: string;
+            variantId: string | null;
+            name: string;
+            sku: string | null;
+            quantity: number;
+            unitCents: number;
+        }>;
+    };
+}
+export declare const CHECKOUT_STARTED_EVENT: PluginDomainEvent<CheckoutStartedEventPayload>;
+export declare const CHECKOUT_STARTED_EVENT_DECLARATION: PluginDomainEventDeclaration;
+/** Every event commerce raises, by name. */
+export type CommerceEventName = 'order.paid' | 'order.fulfilled' | 'order.delivered' | 'order.refunded' | 'order.cancelled' | 'return.requested' | 'return.approved' | 'return.declined' | 'return.received' | 'return.refunded';
+/** The events, in the order pickers list them, with their words. */
+export declare const COMMERCE_EVENT_DECLARATIONS: ReadonlyArray<PluginDomainEventDeclaration & {
+    event: PluginDomainEvent<unknown>;
+    hostEvent: string;
+}>;
+/** The workflow trigger an event is offered as. */
+export declare function commerceHostEventFor(event: string): string | null;
+/** The event names, for a webhook's event picker. */
+export declare const COMMERCE_EVENT_NAMES: readonly CommerceEventName[];

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

@@ -0,0 +1,153 @@
+/**
+ * @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 { definePluginDomainEvent } from "@aglyn/aglyn/plugin-manager/plugin-domain-events";
+export const ORDER_PAID_EVENT = definePluginDomainEvent('order.paid');
+export const ORDER_FULFILLED_EVENT = definePluginDomainEvent('order.fulfilled');
+export const ORDER_DELIVERED_EVENT = definePluginDomainEvent('order.delivered');
+export const ORDER_REFUNDED_EVENT = definePluginDomainEvent('order.refunded');
+export const ORDER_CANCELLED_EVENT = definePluginDomainEvent('order.cancelled');
+export const RETURN_REQUESTED_EVENT = definePluginDomainEvent('return.requested');
+export const RETURN_APPROVED_EVENT = definePluginDomainEvent('return.approved');
+export const RETURN_DECLINED_EVENT = definePluginDomainEvent('return.declined');
+export const RETURN_RECEIVED_EVENT = definePluginDomainEvent('return.received');
+export const RETURN_REFUNDED_EVENT = definePluginDomainEvent('return.refunded');
+export const CHECKOUT_STARTED_EVENT = definePluginDomainEvent('checkout.started');
+export const CHECKOUT_STARTED_EVENT_DECLARATION = {
+    event: CHECKOUT_STARTED_EVENT,
+    label: 'Checkout started',
+    description: 'A shopper reached checkout with an email address: the basket, its value and the link back to it. Raised once per checkout, whether or not it is paid.',
+    payloadKeys: [
+        'checkout'
+    ]
+};
+/** The events, in the order pickers list them, with their words. */ export const COMMERCE_EVENT_DECLARATIONS = [
+    {
+        event: ORDER_PAID_EVENT,
+        hostEvent: 'orderPaid',
+        label: 'Order paid',
+        description: 'An order was paid: a storefront checkout, a buy-now, a paid payment link, a POS sale or a subscription renewal.',
+        payloadKeys: [
+            'order'
+        ]
+    },
+    {
+        event: ORDER_FULFILLED_EVENT,
+        hostEvent: 'orderFulfilled',
+        label: 'Order fulfilled',
+        description: 'A shipment was recorded on an order, once per shipment, with the units it carried.',
+        payloadKeys: [
+            'order',
+            'fulfillment'
+        ]
+    },
+    {
+        event: ORDER_DELIVERED_EVENT,
+        hostEvent: 'orderDelivered',
+        label: 'Order delivered',
+        description: 'An order was marked delivered.',
+        payloadKeys: [
+            'order'
+        ]
+    },
+    {
+        event: ORDER_REFUNDED_EVENT,
+        hostEvent: 'orderRefunded',
+        label: 'Order refunded',
+        description: 'Money went back to the buyer, in part or in full, once per refund.',
+        payloadKeys: [
+            'order',
+            'refund'
+        ]
+    },
+    {
+        event: ORDER_CANCELLED_EVENT,
+        hostEvent: 'orderCancelled',
+        label: 'Order canceled',
+        description: 'An order was canceled and its stock returned.',
+        payloadKeys: [
+            'order'
+        ]
+    },
+    {
+        event: RETURN_REQUESTED_EVENT,
+        hostEvent: 'returnRequested',
+        label: 'Return requested',
+        description: 'A buyer asked to return items, or the merchant opened a return for them.',
+        payloadKeys: [
+            'order',
+            'return'
+        ]
+    },
+    {
+        event: RETURN_APPROVED_EVENT,
+        hostEvent: 'returnApproved',
+        label: 'Return approved',
+        description: 'The store approved a return, or opened one itself.',
+        payloadKeys: [
+            'order',
+            'return'
+        ]
+    },
+    {
+        event: RETURN_DECLINED_EVENT,
+        hostEvent: 'returnDeclined',
+        label: 'Return declined',
+        description: 'The store declined a return request.',
+        payloadKeys: [
+            'order',
+            'return'
+        ]
+    },
+    {
+        event: RETURN_RECEIVED_EVENT,
+        hostEvent: 'returnReceived',
+        label: 'Return received',
+        description: 'The returned items arrived, with what went back in stock.',
+        payloadKeys: [
+            'order',
+            'return'
+        ]
+    },
+    {
+        event: RETURN_REFUNDED_EVENT,
+        hostEvent: 'returnRefunded',
+        label: 'Return refunded',
+        description: 'A return was refunded.',
+        payloadKeys: [
+            'order',
+            'return'
+        ]
+    }
+];
+/** The workflow trigger an event is offered as. */ export function commerceHostEventFor(event) {
+    var _ref;
+    var _COMMERCE_EVENT_DECLARATIONS_find;
+    return (_ref = (_COMMERCE_EVENT_DECLARATIONS_find = COMMERCE_EVENT_DECLARATIONS.find((entry)=>entry.event.id === event)) == null ? void 0 : _COMMERCE_EVENT_DECLARATIONS_find.hostEvent) != null ? _ref : null;
+}
+/** The event names, for a webhook's event picker. */ export const COMMERCE_EVENT_NAMES = [
+    'order.paid',
+    'order.fulfilled',
+    'order.delivered',
+    'order.refunded',
+    'order.cancelled',
+    'return.requested',
+    'return.approved',
+    'return.declined',
+    'return.received',
+    'return.refunded'
+];
+
+//# sourceMappingURL=order-events.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/order-events.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  definePluginDomainEvent,\n  type PluginDomainEvent,\n  type PluginDomainEventDeclaration,\n} from '@aglyn/aglyn/plugin-manager/plugin-domain-events'\n\n/**\n * The order and return events commerce raises (AGL-3611), for other plugins\n * — accounting, shipping, workflows — and for the merchant's own webhooks.\n *\n * Each payload carries `order` in the public API's shape (`GET\n * /v1/sites/{siteId}/orders/{orderId}`), as it stood once the fact was\n * written, so a subscriber reads one documented object rather than the\n * plugin's storage. A subscriber in another plugin restates the fields it\n * reads; these types are this plugin's own.\n */\n\n/** An order as the public API returns it. Money is integer cents. */\nexport interface OrderEventOrder {\n  id: string\n  object: 'order'\n  number: number | null\n  status: string | null\n  channel: string\n  currency: string\n  customerEmail: string | null\n  customerName: string | null\n  lineItems: unknown\n  totals: {\n    itemsCents: number\n    shippingCents: number\n    taxCents: number\n    discountCents: number\n    totalCents: number | null\n    feeCents: number\n  }\n  refundedCents: number\n  /** The tax regime: `stripe-automatic`, `manual`, `none`, or `null` when not recorded. */\n  taxMode: string | null\n  [key: string]: unknown\n}\n\n/** A shipment as an event carries it. */\nexport interface OrderEventFulfillment {\n  id: string\n  lines: Array<{ lineItemId: number; quantity: number }>\n  carrier: string | null\n  trackingNumber: string | null\n  trackingUrl: string | null\n  labelUrl: string | null\n  at: string\n}\n\n/** A refund as an event carries it: what THIS refund moved. */\nexport interface OrderEventRefund {\n  /** Stripe's refund id, when there is one. */\n  id: string | null\n  amountCents: number\n  /** The line indexes refunded by name; empty for an amount-only refund. */\n  lineItemIds: number[]\n  /** Whether this refund left nothing more to refund. */\n  full: boolean\n}\n\n/** A return as an event carries it. */\nexport interface OrderEventReturn {\n  id: string\n  status: string\n  lines: Array<{ lineItemId: number; quantity: number; reason: string }>\n  refundCents: number | null\n  /** What went back in stock when the parcel arrived; `null` before then. */\n  restock?: Array<{ lineItemId: number; quantity: number }> | null\n}\n\nexport interface OrderEventPayload {\n  order: OrderEventOrder\n}\nexport interface OrderFulfilledEventPayload extends OrderEventPayload {\n  fulfillment: OrderEventFulfillment\n}\nexport interface OrderRefundedEventPayload extends OrderEventPayload {\n  refund: OrderEventRefund\n}\nexport interface ReturnEventPayload extends OrderEventPayload {\n  return: OrderEventReturn\n}\n\nexport const ORDER_PAID_EVENT = definePluginDomainEvent<OrderEventPayload>('order.paid')\nexport const ORDER_FULFILLED_EVENT = definePluginDomainEvent<OrderFulfilledEventPayload>('order.fulfilled')\nexport const ORDER_DELIVERED_EVENT = definePluginDomainEvent<OrderEventPayload>('order.delivered')\nexport const ORDER_REFUNDED_EVENT = definePluginDomainEvent<OrderRefundedEventPayload>('order.refunded')\nexport const ORDER_CANCELLED_EVENT = definePluginDomainEvent<OrderEventPayload>('order.cancelled')\nexport const RETURN_REQUESTED_EVENT = definePluginDomainEvent<ReturnEventPayload>('return.requested')\nexport const RETURN_APPROVED_EVENT = definePluginDomainEvent<ReturnEventPayload>('return.approved')\nexport const RETURN_DECLINED_EVENT = definePluginDomainEvent<ReturnEventPayload>('return.declined')\nexport const RETURN_RECEIVED_EVENT = definePluginDomainEvent<ReturnEventPayload>('return.received')\nexport const RETURN_REFUNDED_EVENT = definePluginDomainEvent<ReturnEventPayload>('return.refunded')\n\n/**\n * A checkout a shopper reached with an address (AGL-3639): the fact an\n * abandoned-cart flow in a merchant's own email platform starts from. Not an\n * order event — nothing was bought — so it is raised beside them rather than\n * among them: it is not a workflow trigger and not offered to the merchant's\n * outbound webhooks, whose events are about orders.\n */\nexport interface CheckoutStartedEventPayload {\n  checkout: {\n    /** The checkout session's id: one event per checkout. */\n    id: string\n    email: string\n    /** Whether the shopper ticked the store's marketing box at checkout. */\n    marketingOptIn: boolean\n    currency: string\n    /** The basket's list value, integer cents, before discounts and shipping. */\n    itemsCents: number\n    /** Where the shopper can pick the checkout up again. */\n    resumeUrl: string | null\n    items: Array<{\n      productId: string\n      variantId: string | null\n      name: string\n      sku: string | null\n      quantity: number\n      unitCents: number\n    }>\n  }\n}\n\nexport const CHECKOUT_STARTED_EVENT = definePluginDomainEvent<CheckoutStartedEventPayload>('checkout.started')\n\nexport const CHECKOUT_STARTED_EVENT_DECLARATION: PluginDomainEventDeclaration = {\n  event: CHECKOUT_STARTED_EVENT as PluginDomainEvent<unknown>,\n  label: 'Checkout started',\n  description:\n    'A shopper reached checkout with an email address: the basket, its value and the link back to it. Raised once per checkout, whether or not it is paid.',\n  payloadKeys: ['checkout'],\n}\n\n/** Every event commerce raises, by name. */\nexport type CommerceEventName =\n  | 'order.paid'\n  | 'order.fulfilled'\n  | 'order.delivered'\n  | 'order.refunded'\n  | 'order.cancelled'\n  | 'return.requested'\n  | 'return.approved'\n  | 'return.declined'\n  | 'return.received'\n  | 'return.refunded'\n\n/** The events, in the order pickers list them, with their words. */\nexport const COMMERCE_EVENT_DECLARATIONS: ReadonlyArray<\n  PluginDomainEventDeclaration & { event: PluginDomainEvent<unknown>; hostEvent: string }\n> = [\n  {\n    event: ORDER_PAID_EVENT,\n    hostEvent: 'orderPaid',\n    label: 'Order paid',\n    description:\n      'An order was paid: a storefront checkout, a buy-now, a paid payment link, a POS sale or a subscription renewal.',\n    payloadKeys: ['order'],\n  },\n  {\n    event: ORDER_FULFILLED_EVENT,\n    hostEvent: 'orderFulfilled',\n    label: 'Order fulfilled',\n    description: 'A shipment was recorded on an order, once per shipment, with the units it carried.',\n    payloadKeys: ['order', 'fulfillment'],\n  },\n  {\n    event: ORDER_DELIVERED_EVENT,\n    hostEvent: 'orderDelivered',\n    label: 'Order delivered',\n    description: 'An order was marked delivered.',\n    payloadKeys: ['order'],\n  },\n  {\n    event: ORDER_REFUNDED_EVENT,\n    hostEvent: 'orderRefunded',\n    label: 'Order refunded',\n    description: 'Money went back to the buyer, in part or in full, once per refund.',\n    payloadKeys: ['order', 'refund'],\n  },\n  {\n    event: ORDER_CANCELLED_EVENT,\n    hostEvent: 'orderCancelled',\n    label: 'Order canceled',\n    description: 'An order was canceled and its stock returned.',\n    payloadKeys: ['order'],\n  },\n  {\n    event: RETURN_REQUESTED_EVENT,\n    hostEvent: 'returnRequested',\n    label: 'Return requested',\n    description: 'A buyer asked to return items, or the merchant opened a return for them.',\n    payloadKeys: ['order', 'return'],\n  },\n  {\n    event: RETURN_APPROVED_EVENT,\n    hostEvent: 'returnApproved',\n    label: 'Return approved',\n    description: 'The store approved a return, or opened one itself.',\n    payloadKeys: ['order', 'return'],\n  },\n  {\n    event: RETURN_DECLINED_EVENT,\n    hostEvent: 'returnDeclined',\n    label: 'Return declined',\n    description: 'The store declined a return request.',\n    payloadKeys: ['order', 'return'],\n  },\n  {\n    event: RETURN_RECEIVED_EVENT,\n    hostEvent: 'returnReceived',\n    label: 'Return received',\n    description: 'The returned items arrived, with what went back in stock.',\n    payloadKeys: ['order', 'return'],\n  },\n  {\n    event: RETURN_REFUNDED_EVENT,\n    hostEvent: 'returnRefunded',\n    label: 'Return refunded',\n    description: 'A return was refunded.',\n    payloadKeys: ['order', 'return'],\n  },\n]\n\n/** The workflow trigger an event is offered as. */\nexport function commerceHostEventFor(event: string): string | null {\n  return COMMERCE_EVENT_DECLARATIONS.find((entry) => entry.event.id === event)?.hostEvent ?? null\n}\n\n/** The event names, for a webhook's event picker. */\nexport const COMMERCE_EVENT_NAMES: readonly CommerceEventName[] = [\n  'order.paid',\n  'order.fulfilled',\n  'order.delivered',\n  'order.refunded',\n  'order.cancelled',\n  'return.requested',\n  'return.approved',\n  'return.declined',\n  'return.received',\n  'return.refunded',\n]\n"],"names":["definePluginDomainEvent","ORDER_PAID_EVENT","ORDER_FULFILLED_EVENT","ORDER_DELIVERED_EVENT","ORDER_REFUNDED_EVENT","ORDER_CANCELLED_EVENT","RETURN_REQUESTED_EVENT","RETURN_APPROVED_EVENT","RETURN_DECLINED_EVENT","RETURN_RECEIVED_EVENT","RETURN_REFUNDED_EVENT","CHECKOUT_STARTED_EVENT","CHECKOUT_STARTED_EVENT_DECLARATION","event","label","description","payloadKeys","COMMERCE_EVENT_DECLARATIONS","hostEvent","commerceHostEventFor","find","entry","id","COMMERCE_EVENT_NAMES"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,uBAAuB,QAGlB,mDAAkD;AAmFzD,OAAO,MAAMC,mBAAmBD,wBAA2C,cAAa;AACxF,OAAO,MAAME,wBAAwBF,wBAAoD,mBAAkB;AAC3G,OAAO,MAAMG,wBAAwBH,wBAA2C,mBAAkB;AAClG,OAAO,MAAMI,uBAAuBJ,wBAAmD,kBAAiB;AACxG,OAAO,MAAMK,wBAAwBL,wBAA2C,mBAAkB;AAClG,OAAO,MAAMM,yBAAyBN,wBAA4C,oBAAmB;AACrG,OAAO,MAAMO,wBAAwBP,wBAA4C,mBAAkB;AACnG,OAAO,MAAMQ,wBAAwBR,wBAA4C,mBAAkB;AACnG,OAAO,MAAMS,wBAAwBT,wBAA4C,mBAAkB;AACnG,OAAO,MAAMU,wBAAwBV,wBAA4C,mBAAkB;AAgCnG,OAAO,MAAMW,yBAAyBX,wBAAqD,oBAAmB;AAE9G,OAAO,MAAMY,qCAAmE;IAC9EC,OAAOF;IACPG,OAAO;IACPC,aACE;IACFC,aAAa;QAAC;KAAW;AAC3B,EAAC;AAeD,kEAAkE,GAClE,OAAO,MAAMC,8BAET;IACF;QACEJ,OAAOZ;QACPiB,WAAW;QACXJ,OAAO;QACPC,aACE;QACFC,aAAa;YAAC;SAAQ;IACxB;IACA;QACEH,OAAOX;QACPgB,WAAW;QACXJ,OAAO;QACPC,aAAa;QACbC,aAAa;YAAC;YAAS;SAAc;IACvC;IACA;QACEH,OAAOV;QACPe,WAAW;QACXJ,OAAO;QACPC,aAAa;QACbC,aAAa;YAAC;SAAQ;IACxB;IACA;QACEH,OAAOT;QACPc,WAAW;QACXJ,OAAO;QACPC,aAAa;QACbC,aAAa;YAAC;YAAS;SAAS;IAClC;IACA;QACEH,OAAOR;QACPa,WAAW;QACXJ,OAAO;QACPC,aAAa;QACbC,aAAa;YAAC;SAAQ;IACxB;IACA;QACEH,OAAOP;QACPY,WAAW;QACXJ,OAAO;QACPC,aAAa;QACbC,aAAa;YAAC;YAAS;SAAS;IAClC;IACA;QACEH,OAAON;QACPW,WAAW;QACXJ,OAAO;QACPC,aAAa;QACbC,aAAa;YAAC;YAAS;SAAS;IAClC;IACA;QACEH,OAAOL;QACPU,WAAW;QACXJ,OAAO;QACPC,aAAa;QACbC,aAAa;YAAC;YAAS;SAAS;IAClC;IACA;QACEH,OAAOJ;QACPS,WAAW;QACXJ,OAAO;QACPC,aAAa;QACbC,aAAa;YAAC;YAAS;SAAS;IAClC;IACA;QACEH,OAAOH;QACPQ,WAAW;QACXJ,OAAO;QACPC,aAAa;QACbC,aAAa;YAAC;YAAS;SAAS;IAClC;CACD,CAAA;AAED,iDAAiD,GACjD,OAAO,SAASG,qBAAqBN,KAAa;;QACzCI;IAAP,gBAAOA,oCAAAA,4BAA4BG,IAAI,CAAC,CAACC,QAAUA,MAAMR,KAAK,CAACS,EAAE,KAAKT,2BAA/DI,kCAAuEC,SAAS,mBAAI;AAC7F;AAEA,mDAAmD,GACnD,OAAO,MAAMK,uBAAqD;IAChE;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAA"}

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

@@ -0,0 +1,117 @@
+/**
+ * @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.
+ */
+/**
+ * Quantity-level fulfillment (AGL-3611).
+ *
+ * A fulfillment used to name whole lines (`lineItemIds`), so "ship 2 of the 5
+ * mugs now, the rest next week" could not be said. A fulfillment now carries
+ * `lines: [{ lineItemId, quantity }]`; one written before that reads as every
+ * unit of each line it named, which is what it meant when it was written.
+ *
+ * Every figure here is computed from the order's own fulfillments, so the
+ * server's transaction and the console's panel ask the same question of the
+ * same record and cannot disagree about what is left to ship.
+ */
+import type { HostOrder, OrderFulfillment, OrderLineItem, OrderStatus } from './commerce-orders';
+/** One line of a fulfillment: which order line, and how many of its units. */
+export interface OrderFulfillmentLine {
+    /** The line's index in `order.lineItems`. */
+    lineItemId: number;
+    quantity: number;
+}
+/** A fulfillment's lifecycle; absent reads as `active`. */
+export type OrderFulfillmentStatus = 'active' | 'cancelled';
+/**
+ * Whether a line has to be shipped at all. Digital goods and services are
+ * delivered by other means, so they never hold an order in
+ * `partially_fulfilled`. A line with no recorded type predates types and is
+ * treated as physical, the only reading that cannot close an order early.
+ */
+export declare function lineRequiresShipping(line: Pick<OrderLineItem, 'productType'>): boolean;
+/** Whether a fulfillment still counts: a cancelled one ships nothing. */
+export declare function fulfillmentIsActive(fulfillment: Partial<OrderFulfillment> | null | undefined): boolean;
+/**
+ * The units one fulfillment covers, per line. A legacy fulfillment (no
+ * `lines`) covers every unit of each line it names.
+ */
+export declare function fulfillmentLineQuantities(order: Pick<HostOrder, 'lineItems'>, fulfillment: Partial<OrderFulfillment>): OrderFulfillmentLine[];
+/** Units already fulfilled per line index, over every active fulfillment. */
+export declare function fulfilledQuantities(order: Pick<HostOrder, 'lineItems' | 'fulfillments'>): Map<number, number>;
+/** A line as the fulfillment panel and the server both reason about it. */
+export interface OrderLineFulfillmentState {
+    lineItemId: number;
+    quantity: number;
+    fulfilledQuantity: number;
+    remainingQuantity: number;
+    requiresShipping: boolean;
+}
+/** Every line's fulfilled and remaining units. */
+export declare function orderLineFulfillmentStates(order: Pick<HostOrder, 'lineItems' | 'fulfillments'>): OrderLineFulfillmentState[];
+/**
+ * What is left to ship: every shippable line's remaining units. This is what
+ * a "fulfill everything" request covers.
+ */
+export declare function remainingFulfillmentLines(order: Pick<HostOrder, 'lineItems' | 'fulfillments'>): OrderFulfillmentLine[];
+/** Why a requested set of fulfillment lines was refused. */
+export type FulfillmentLinesProblem = {
+    problem: 'empty';
+} | {
+    problem: 'unknown_line';
+    lineItemId: number;
+} | {
+    problem: 'bad_quantity';
+    lineItemId: number;
+} | {
+    problem: 'over_fulfilled';
+    lineItemId: number;
+    remaining: number;
+    requested: number;
+};
+/**
+ * Validates and merges a requested set of lines against what is left.
+ *
+ * Duplicate entries for one line are summed before the check, so a request
+ * cannot slip past the remaining count by naming the line twice. A digital
+ * or service line may be fulfilled (a merchant marking a service done), but
+ * never beyond its quantity.
+ */
+export declare function resolveFulfillmentLines(order: Pick<HostOrder, 'lineItems' | 'fulfillments'>, requested: ReadonlyArray<{
+    lineItemId: unknown;
+    quantity: unknown;
+}>): {
+    lines: OrderFulfillmentLine[];
+} | FulfillmentLinesProblem;
+/** Words for a refused request, for the console and the API. */
+export declare function describeFulfillmentLinesProblem(problem: FulfillmentLinesProblem): string;
+/**
+ * The status an order's fulfillments put it in: `fulfilled` once every
+ * shippable unit is covered, `partially_fulfilled` while some are, and
+ * `paid` when none are. An order with nothing to ship reads as `fulfilled`
+ * once anything at all was recorded against it, and as `paid` before.
+ */
+export declare function statusFromFulfillments(order: Pick<HostOrder, 'lineItems' | 'fulfillments'>): Extract<OrderStatus, 'paid' | 'partially_fulfilled' | 'fulfilled'>;
+/**
+ * Whether a fulfillment on this order may be edited or cancelled. A delivered,
+ * refunded or cancelled order is history: its fulfillments are what happened.
+ */
+export declare function orderFulfillmentsEditable(order: Pick<HostOrder, 'status'>): boolean;
+/** A short "2× Mug, 1× Shirt" for a fulfillment, for timelines and emails. */
+export declare function describeFulfillmentLines(order: Pick<HostOrder, 'lineItems'>, lines: readonly OrderFulfillmentLine[]): string;
+/** The carriers the console offers by name; anything else is typed under Other. */
+export declare const FULFILLMENT_CARRIER_CHOICES: readonly string[];
+/** The words for a fulfillment's `trackingStatus`, or the status itself. */
+export declare function trackingStatusLabel(status: string | undefined | null): string;

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

@@ -0,0 +1,217 @@
+/**
+ * @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.
+ */ /**
+ * Quantity-level fulfillment (AGL-3611).
+ *
+ * A fulfillment used to name whole lines (`lineItemIds`), so "ship 2 of the 5
+ * mugs now, the rest next week" could not be said. A fulfillment now carries
+ * `lines: [{ lineItemId, quantity }]`; one written before that reads as every
+ * unit of each line it named, which is what it meant when it was written.
+ *
+ * Every figure here is computed from the order's own fulfillments, so the
+ * server's transaction and the console's panel ask the same question of the
+ * same record and cannot disagree about what is left to ship.
+ */ /**
+ * Whether a line has to be shipped at all. Digital goods and services are
+ * delivered by other means, so they never hold an order in
+ * `partially_fulfilled`. A line with no recorded type predates types and is
+ * treated as physical, the only reading that cannot close an order early.
+ */ export function lineRequiresShipping(line) {
+    return line.productType !== 'digital' && line.productType !== 'service';
+}
+const wholeUnits = (value)=>{
+    const units = Math.floor(Number(value != null ? value : 0));
+    return Number.isFinite(units) && units > 0 ? units : 0;
+};
+/** Whether a fulfillment still counts: a cancelled one ships nothing. */ export function fulfillmentIsActive(fulfillment) {
+    return Boolean(fulfillment) && (fulfillment == null ? void 0 : fulfillment.status) !== 'cancelled';
+}
+/**
+ * The units one fulfillment covers, per line. A legacy fulfillment (no
+ * `lines`) covers every unit of each line it names.
+ */ export function fulfillmentLineQuantities(order, fulfillment) {
+    var _order_lineItems, _fulfillment_lineItemIds;
+    const lines = (_order_lineItems = order.lineItems) != null ? _order_lineItems : [];
+    if (Array.isArray(fulfillment.lines) && fulfillment.lines.length > 0) {
+        return fulfillment.lines.map((entry)=>({
+                lineItemId: Math.round(Number(entry == null ? void 0 : entry.lineItemId)),
+                quantity: wholeUnits(entry == null ? void 0 : entry.quantity)
+            })).filter((entry)=>Number.isInteger(entry.lineItemId) && entry.lineItemId >= 0 && entry.lineItemId < lines.length && entry.quantity > 0);
+    }
+    return ((_fulfillment_lineItemIds = fulfillment.lineItemIds) != null ? _fulfillment_lineItemIds : []).map((index)=>Math.round(Number(index))).filter((index)=>Number.isInteger(index) && index >= 0 && index < lines.length).map((index)=>{
+        var _lines_index;
+        return {
+            lineItemId: index,
+            quantity: wholeUnits((_lines_index = lines[index]) == null ? void 0 : _lines_index.quantity)
+        };
+    }).filter((entry)=>entry.quantity > 0);
+}
+/** Units already fulfilled per line index, over every active fulfillment. */ export function fulfilledQuantities(order) {
+    var _order_fulfillments;
+    const totals = new Map();
+    for (const fulfillment of (_order_fulfillments = order.fulfillments) != null ? _order_fulfillments : []){
+        if (!fulfillmentIsActive(fulfillment)) continue;
+        for (const entry of fulfillmentLineQuantities(order, fulfillment)){
+            var _totals_get;
+            totals.set(entry.lineItemId, ((_totals_get = totals.get(entry.lineItemId)) != null ? _totals_get : 0) + entry.quantity);
+        }
+    }
+    return totals;
+}
+/** Every line's fulfilled and remaining units. */ export function orderLineFulfillmentStates(order) {
+    var _order_lineItems;
+    const fulfilled = fulfilledQuantities(order);
+    return ((_order_lineItems = order.lineItems) != null ? _order_lineItems : []).map((line, index)=>{
+        var _fulfilled_get;
+        const quantity = wholeUnits(line.quantity);
+        const done = Math.min(quantity, (_fulfilled_get = fulfilled.get(index)) != null ? _fulfilled_get : 0);
+        return {
+            lineItemId: index,
+            quantity,
+            fulfilledQuantity: done,
+            remainingQuantity: quantity - done,
+            requiresShipping: lineRequiresShipping(line)
+        };
+    });
+}
+/**
+ * What is left to ship: every shippable line's remaining units. This is what
+ * a "fulfill everything" request covers.
+ */ export function remainingFulfillmentLines(order) {
+    return orderLineFulfillmentStates(order).filter((state)=>state.requiresShipping && state.remainingQuantity > 0).map((state)=>({
+            lineItemId: state.lineItemId,
+            quantity: state.remainingQuantity
+        }));
+}
+/**
+ * Validates and merges a requested set of lines against what is left.
+ *
+ * Duplicate entries for one line are summed before the check, so a request
+ * cannot slip past the remaining count by naming the line twice. A digital
+ * or service line may be fulfilled (a merchant marking a service done), but
+ * never beyond its quantity.
+ */ export function resolveFulfillmentLines(order, requested) {
+    const states = orderLineFulfillmentStates(order);
+    const merged = new Map();
+    for (const entry of requested){
+        var _merged_get;
+        const lineItemId = Number(entry == null ? void 0 : entry.lineItemId);
+        if (!Number.isInteger(lineItemId) || lineItemId < 0 || lineItemId >= states.length) {
+            return {
+                problem: 'unknown_line',
+                lineItemId: Number.isFinite(lineItemId) ? lineItemId : -1
+            };
+        }
+        const quantity = Number(entry == null ? void 0 : entry.quantity);
+        if (!Number.isInteger(quantity) || quantity <= 0) {
+            return {
+                problem: 'bad_quantity',
+                lineItemId
+            };
+        }
+        merged.set(lineItemId, ((_merged_get = merged.get(lineItemId)) != null ? _merged_get : 0) + quantity);
+    }
+    if (merged.size === 0) return {
+        problem: 'empty'
+    };
+    const lines = [];
+    for (const [lineItemId, quantity] of [
+        ...merged.entries()
+    ].sort((a, b)=>a[0] - b[0])){
+        const remaining = states[lineItemId].remainingQuantity;
+        if (quantity > remaining) {
+            return {
+                problem: 'over_fulfilled',
+                lineItemId,
+                remaining,
+                requested: quantity
+            };
+        }
+        lines.push({
+            lineItemId,
+            quantity
+        });
+    }
+    return {
+        lines
+    };
+}
+/** Words for a refused request, for the console and the API. */ export function describeFulfillmentLinesProblem(problem) {
+    switch(problem.problem){
+        case 'empty':
+            return 'Choose at least one item to fulfill';
+        case 'unknown_line':
+            return `Line ${problem.lineItemId} is not on this order`;
+        case 'bad_quantity':
+            return `The quantity for line ${problem.lineItemId} must be a whole number above zero`;
+        case 'over_fulfilled':
+            return problem.remaining === 0 ? `Line ${problem.lineItemId} is already fully fulfilled` : `Line ${problem.lineItemId} has only ${problem.remaining} left to fulfill, not ${problem.requested}`;
+    }
+}
+/**
+ * The status an order's fulfillments put it in: `fulfilled` once every
+ * shippable unit is covered, `partially_fulfilled` while some are, and
+ * `paid` when none are. An order with nothing to ship reads as `fulfilled`
+ * once anything at all was recorded against it, and as `paid` before.
+ */ export function statusFromFulfillments(order) {
+    const states = orderLineFulfillmentStates(order);
+    const shippable = states.filter((state)=>state.requiresShipping);
+    const anything = states.some((state)=>state.fulfilledQuantity > 0);
+    if (shippable.length === 0) return anything ? 'fulfilled' : 'paid';
+    if (shippable.every((state)=>state.remainingQuantity === 0)) return 'fulfilled';
+    return shippable.some((state)=>state.fulfilledQuantity > 0) || anything ? 'partially_fulfilled' : 'paid';
+}
+/** Statuses whose fulfillments may still be added to, edited or cancelled. */ const FULFILLMENT_OPEN_STATUSES = [
+    'paid',
+    'partially_fulfilled',
+    'fulfilled'
+];
+/**
+ * Whether a fulfillment on this order may be edited or cancelled. A delivered,
+ * refunded or cancelled order is history: its fulfillments are what happened.
+ */ export function orderFulfillmentsEditable(order) {
+    return FULFILLMENT_OPEN_STATUSES.includes(order.status);
+}
+/** A short "2× Mug, 1× Shirt" for a fulfillment, for timelines and emails. */ export function describeFulfillmentLines(order, lines) {
+    return lines.map((entry)=>{
+        var _ref;
+        var _order_lineItems_entry_lineItemId, _order_lineItems;
+        return `${entry.quantity}× ${(_ref = (_order_lineItems = order.lineItems) == null ? void 0 : (_order_lineItems_entry_lineItemId = _order_lineItems[entry.lineItemId]) == null ? void 0 : _order_lineItems_entry_lineItemId.name) != null ? _ref : `line ${entry.lineItemId}`}`;
+    }).join(', ');
+}
+/** The carriers the console offers by name; anything else is typed under Other. */ export const FULFILLMENT_CARRIER_CHOICES = [
+    'USPS',
+    'UPS',
+    'FedEx',
+    'DHL',
+    'Canada Post',
+    'Royal Mail',
+    'Australia Post'
+];
+/** What a merchant reads for a carrier's tracking status (AGL-3612). */ const TRACKING_STATUS_LABELS = {
+    pre_transit: 'Label created',
+    in_transit: 'In transit',
+    out_for_delivery: 'Out for delivery',
+    delivered: 'Delivered',
+    exception: 'Delivery problem',
+    returned: 'Returned to sender'
+};
+/** The words for a fulfillment's `trackingStatus`, or the status itself. */ export function trackingStatusLabel(status) {
+    var _TRACKING_STATUS_LABELS_status;
+    return status ? (_TRACKING_STATUS_LABELS_status = TRACKING_STATUS_LABELS[status]) != null ? _TRACKING_STATUS_LABELS_status : status : '';
+}
+
+//# sourceMappingURL=order-fulfillment.js.map