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

package/src/lib/server/order-event-triggers.js

@@ -0,0 +1,119 @@
+/**
+ * @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 { declarePluginDomainEvents, subscribePluginDomainEvent } from "@aglyn/aglyn/plugin-manager/plugin-domain-events";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { CHECKOUT_STARTED_EVENT_DECLARATION, COMMERCE_EVENT_DECLARATIONS, ORDER_CANCELLED_EVENT, ORDER_PAID_EVENT, ORDER_REFUNDED_EVENT } from "../model/order-events.js";
+/**
+ * Commerce's events as workflow triggers (AGL-3611).
+ *
+ * The workflows plugin listens to host events, flat key/value payloads it
+ * puts in an automation's scope. Commerce subscribes to its own order and
+ * return events and raises each as the host event its declaration names
+ * (`orderPaid`, `orderFulfilled`, …), declared in `plugins.config.json` so
+ * every trigger picker lists them. The automation engine is never imported:
+ * the host event bus is the seam.
+ */ /** The flat scope an automation reads: the order's facts, then the event's own. */ export function hostEventPayloadFor(envelope) {
+    var _envelope_payload, _payload_order;
+    var _order_totals;
+    const payload = (_envelope_payload = envelope.payload) != null ? _envelope_payload : {};
+    const order = (_payload_order = payload.order) != null ? _payload_order : {};
+    const flat = {};
+    const put = (key, value)=>{
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            flat[key] = value;
+        }
+    };
+    put('orderId', order.id);
+    put('orderNumber', typeof order.number === 'number' ? `#${order.number}` : order.id);
+    put('status', order.status);
+    put('channel', order.channel);
+    put('email', order.customerEmail);
+    put('name', order.customerName);
+    put('totalCents', (_order_totals = order.totals) == null ? void 0 : _order_totals.totalCents);
+    put('currency', order.currency);
+    const fulfillment = payload.fulfillment;
+    if (fulfillment) {
+        put('fulfillmentId', fulfillment.id);
+        put('carrier', fulfillment.carrier);
+        put('trackingNumber', fulfillment.trackingNumber);
+        put('trackingUrl', fulfillment.trackingUrl);
+    }
+    const refund = payload.refund;
+    if (refund) {
+        put('refundCents', refund.amountCents);
+        put('fullRefund', refund.full);
+    }
+    const returned = payload.return;
+    if (returned) {
+        put('returnId', returned.id);
+        put('returnStatus', returned.status);
+        put('returnRefundCents', returned.refundCents);
+    }
+    return flat;
+}
+/**
+ * Declares commerce's events and subscribes the trigger bridge, from the
+ * server declarations. `emitHostEvent` arrives with the first event, not
+ * with the boot.
+ */ export function registerCommerceEventTriggers() {
+    declarePluginDomainEvents([
+        ...COMMERCE_EVENT_DECLARATIONS,
+        CHECKOUT_STARTED_EVENT_DECLARATION
+    ], {
+        pluginId: BUNDLE_ID
+    });
+    for (const declaration of COMMERCE_EVENT_DECLARATIONS){
+        subscribePluginDomainEvent(declaration.event, async (envelope)=>{
+            const { emitCommerceHostEvent } = await import("./order-event-host-emit.js");
+            await emitCommerceHostEvent(envelope.hostId, declaration.hostEvent, hostEventPayloadFor(envelope));
+        }, // Named, so the outbox records it apart from the webhook subscriber
+        // this plugin also registers.
+        {
+            pluginId: BUNDLE_ID,
+            name: 'workflow-triggers'
+        });
+        // The merchant's own webhooks (AGL-3611). Its own subscriber name, so a
+        // failing endpoint is retried without raising the workflow trigger again.
+        subscribePluginDomainEvent(declaration.event, async (envelope)=>{
+            const { deliverOrderEventToWebhooks } = await import("./order-webhooks.js");
+            await deliverOrderEventToWebhooks(envelope);
+        }, {
+            pluginId: BUNDLE_ID,
+            name: 'webhooks'
+        });
+    }
+    // ShippingEasy (AGL-3633): a paid order is sent to the merchant's
+    // ShippingEasy account, and a canceled or refunded one is canceled there.
+    // Its own subscriber name, so a ShippingEasy outage is retried without
+    // re-posting the merchant's webhooks. A site with no connection costs one
+    // document read.
+    for (const event of SHIPPINGEASY_EVENTS){
+        subscribePluginDomainEvent(event, async (envelope)=>{
+            const { deliverOrderEventToShippingEasy } = await import("./shippingeasy.js");
+            await deliverOrderEventToShippingEasy(envelope);
+        }, {
+            pluginId: BUNDLE_ID,
+            name: 'shippingeasy'
+        });
+    }
+}
+/** The order events that change what ShippingEasy should hold. */ export const SHIPPINGEASY_EVENTS = [
+    ORDER_PAID_EVENT,
+    ORDER_CANCELLED_EVENT,
+    ORDER_REFUNDED_EVENT
+];
+
+//# sourceMappingURL=order-event-triggers.js.map

package/src/lib/server/order-event-triggers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/order-event-triggers.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  declarePluginDomainEvents,\n  subscribePluginDomainEvent,\n  type PluginDomainEventEnvelope,\n} from '@aglyn/aglyn/plugin-manager/plugin-domain-events'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport {\n  CHECKOUT_STARTED_EVENT_DECLARATION,\n  COMMERCE_EVENT_DECLARATIONS,\n  ORDER_CANCELLED_EVENT,\n  ORDER_PAID_EVENT,\n  ORDER_REFUNDED_EVENT,\n} from '../model/order-events'\n\n/**\n * Commerce's events as workflow triggers (AGL-3611).\n *\n * The workflows plugin listens to host events, flat key/value payloads it\n * puts in an automation's scope. Commerce subscribes to its own order and\n * return events and raises each as the host event its declaration names\n * (`orderPaid`, `orderFulfilled`, …), declared in `plugins.config.json` so\n * every trigger picker lists them. The automation engine is never imported:\n * the host event bus is the seam.\n */\n\n/** The flat scope an automation reads: the order's facts, then the event's own. */\nexport function hostEventPayloadFor(\n  envelope: Pick<PluginDomainEventEnvelope, 'event' | 'payload'>,\n): Record<string, string | number | boolean> {\n  const payload = (envelope.payload ?? {}) as Record<string, any>\n  const order = (payload.order ?? {}) as Record<string, any>\n  const flat: Record<string, string | number | boolean> = {}\n  const put = (key: string, value: unknown) => {\n    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {\n      flat[key] = value\n    }\n  }\n  put('orderId', order.id)\n  put('orderNumber', typeof order.number === 'number' ? `#${order.number}` : order.id)\n  put('status', order.status)\n  put('channel', order.channel)\n  put('email', order.customerEmail)\n  put('name', order.customerName)\n  put('totalCents', order.totals?.totalCents)\n  put('currency', order.currency)\n  const fulfillment = payload.fulfillment as Record<string, any> | undefined\n  if (fulfillment) {\n    put('fulfillmentId', fulfillment.id)\n    put('carrier', fulfillment.carrier)\n    put('trackingNumber', fulfillment.trackingNumber)\n    put('trackingUrl', fulfillment.trackingUrl)\n  }\n  const refund = payload.refund as Record<string, any> | undefined\n  if (refund) {\n    put('refundCents', refund.amountCents)\n    put('fullRefund', refund.full)\n  }\n  const returned = payload.return as Record<string, any> | undefined\n  if (returned) {\n    put('returnId', returned.id)\n    put('returnStatus', returned.status)\n    put('returnRefundCents', returned.refundCents)\n  }\n  return flat\n}\n\n/**\n * Declares commerce's events and subscribes the trigger bridge, from the\n * server declarations. `emitHostEvent` arrives with the first event, not\n * with the boot.\n */\nexport function registerCommerceEventTriggers(): void {\n  declarePluginDomainEvents([...COMMERCE_EVENT_DECLARATIONS, CHECKOUT_STARTED_EVENT_DECLARATION], { pluginId: BUNDLE_ID })\n  for (const declaration of COMMERCE_EVENT_DECLARATIONS) {\n    subscribePluginDomainEvent(\n      declaration.event,\n      async (envelope) => {\n        const { emitCommerceHostEvent } = await import('./order-event-host-emit')\n        await emitCommerceHostEvent(envelope.hostId, declaration.hostEvent, hostEventPayloadFor(envelope))\n      },\n      // Named, so the outbox records it apart from the webhook subscriber\n      // this plugin also registers.\n      { pluginId: BUNDLE_ID, name: 'workflow-triggers' },\n    )\n    // The merchant's own webhooks (AGL-3611). Its own subscriber name, so a\n    // failing endpoint is retried without raising the workflow trigger again.\n    subscribePluginDomainEvent(\n      declaration.event,\n      async (envelope) => {\n        const { deliverOrderEventToWebhooks } = await import('./order-webhooks')\n        await deliverOrderEventToWebhooks(envelope)\n      },\n      { pluginId: BUNDLE_ID, name: 'webhooks' },\n    )\n  }\n  // ShippingEasy (AGL-3633): a paid order is sent to the merchant's\n  // ShippingEasy account, and a canceled or refunded one is canceled there.\n  // Its own subscriber name, so a ShippingEasy outage is retried without\n  // re-posting the merchant's webhooks. A site with no connection costs one\n  // document read.\n  for (const event of SHIPPINGEASY_EVENTS) {\n    subscribePluginDomainEvent(\n      event,\n      async (envelope) => {\n        const { deliverOrderEventToShippingEasy } = await import('./shippingeasy')\n        await deliverOrderEventToShippingEasy(envelope)\n      },\n      { pluginId: BUNDLE_ID, name: 'shippingeasy' },\n    )\n  }\n}\n\n/** The order events that change what ShippingEasy should hold. */\nexport const SHIPPINGEASY_EVENTS = [ORDER_PAID_EVENT, ORDER_CANCELLED_EVENT, ORDER_REFUNDED_EVENT] as const\n"],"names":["declarePluginDomainEvents","subscribePluginDomainEvent","BUNDLE_ID","CHECKOUT_STARTED_EVENT_DECLARATION","COMMERCE_EVENT_DECLARATIONS","ORDER_CANCELLED_EVENT","ORDER_PAID_EVENT","ORDER_REFUNDED_EVENT","hostEventPayloadFor","envelope","payload","order","flat","put","key","value","id","number","status","channel","customerEmail","customerName","totals","totalCents","currency","fulfillment","carrier","trackingNumber","trackingUrl","refund","amountCents","full","returned","return","refundCents","registerCommerceEventTriggers","pluginId","declaration","event","emitCommerceHostEvent","hostId","hostEvent","name","deliverOrderEventToWebhooks","SHIPPINGEASY_EVENTS","deliverOrderEventToShippingEasy"],"mappings":"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"}

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

@@ -0,0 +1,62 @@
+/**
+ * @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 } from '@aglyn/aglyn/plugin-manager/plugin-domain-events';
+import { type PluginEventWriter } from '@aglyn/tenant-data-admin/server/plugin-event-outbox';
+import type { OrderFulfillment } from '../model/commerce-orders';
+import { type CheckoutStartedEventPayload } from '../model/order-events';
+import type { OrderEventFulfillment, OrderEventPayload } from '../model/order-events';
+/**
+ * Raising commerce's order events (AGL-3611). Two doors, one per kind of
+ * caller, so every status-change site raises its event in one line:
+ *
+ *  - `stageOrderEvent` rides the caller's transaction, so the event exists
+ *    exactly when the status does. For a write that already holds the order
+ *    it is about to store.
+ *  - `raiseOrderEvent` reads the order once the write has landed and queues
+ *    the event, keyed so a redelivered webhook or a retried request raises it
+ *    once. For a write with no transaction to ride.
+ *
+ * Neither ever throws into the write it reports: a fact that happened is not
+ * undone because its announcement could not be queued.
+ */
+/** A shipment in the event's words. */
+export declare function fulfillmentEventView(order: {
+    lineItems?: unknown;
+}, fulfillment: OrderFulfillment): OrderEventFulfillment;
+export interface OrderEventRequest<Payload extends OrderEventPayload> {
+    hostId: string;
+    orderId: string;
+    /** The occurrence: the same key raises the event once. */
+    key: string;
+    /** Everything the payload carries beside `order`. */
+    extra?: Omit<Payload, 'order'>;
+}
+/**
+ * Stages an event inside the caller's transaction, from the order data the
+ * transaction is about to store (the read merged with its patch).
+ */
+export declare function stageOrderEvent<Payload extends OrderEventPayload>(writer: PluginEventWriter, event: PluginDomainEvent<Payload>, request: OrderEventRequest<Payload> & {
+    order: Record<string, unknown>;
+}): void;
+/** Queues an event after the write, reading the order as it now stands. */
+export declare function raiseOrderEvent<Payload extends OrderEventPayload>(event: PluginDomainEvent<Payload>, request: OrderEventRequest<Payload>): Promise<void>;
+/**
+ * Raises `checkout.started` (AGL-3639) for a checkout a shopper reached with
+ * an address, keyed by the session so a retried request raises it once.
+ * Never throws into the checkout it reports.
+ */
+export declare function raiseCheckoutStarted(hostId: string, checkout: CheckoutStartedEventPayload['checkout']): Promise<void>;

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

@@ -0,0 +1,109 @@
+/**
+ * @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 { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { raisePluginEvent, stagePluginEvent } from "@aglyn/tenant-data-admin/server/plugin-event-outbox";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { CHECKOUT_STARTED_EVENT } from "../model/order-events.js";
+import { fulfillmentLineQuantities } from "../model/order-fulfillment.js";
+import { fulfillmentTrackingUrl } from "../model/tracking-url.js";
+import { orderViewFromData } from "./api-v1/order-view.js";
+/**
+ * Raising commerce's order events (AGL-3611). Two doors, one per kind of
+ * caller, so every status-change site raises its event in one line:
+ *
+ *  - `stageOrderEvent` rides the caller's transaction, so the event exists
+ *    exactly when the status does. For a write that already holds the order
+ *    it is about to store.
+ *  - `raiseOrderEvent` reads the order once the write has landed and queues
+ *    the event, keyed so a redelivered webhook or a retried request raises it
+ *    once. For a write with no transaction to ride.
+ *
+ * Neither ever throws into the write it reports: a fact that happened is not
+ * undone because its announcement could not be queued.
+ */ /** A shipment in the event's words. */ export function fulfillmentEventView(order, fulfillment) {
+    var _fulfillment_carrier, _fulfillment_trackingNumber, _fulfillment_labelUrl;
+    return {
+        id: fulfillment.id,
+        lines: fulfillmentLineQuantities(order, fulfillment),
+        carrier: (_fulfillment_carrier = fulfillment.carrier) != null ? _fulfillment_carrier : null,
+        trackingNumber: (_fulfillment_trackingNumber = fulfillment.trackingNumber) != null ? _fulfillment_trackingNumber : null,
+        trackingUrl: fulfillmentTrackingUrl(fulfillment),
+        labelUrl: (_fulfillment_labelUrl = fulfillment.labelUrl) != null ? _fulfillment_labelUrl : null,
+        at: new Date(fulfillment.atMs).toISOString()
+    };
+}
+/**
+ * Stages an event inside the caller's transaction, from the order data the
+ * transaction is about to store (the read merged with its patch).
+ */ export function stageOrderEvent(writer, event, request) {
+    try {
+        var _request_extra;
+        const firestore = firebaseAdmin.app().firestore();
+        stagePluginEvent(writer, firestore, {
+            event,
+            pluginId: BUNDLE_ID,
+            hostId: request.hostId,
+            key: `${request.orderId}:${request.key}`,
+            payload: _extends({
+                order: orderViewFromData(request.orderId, request.order)
+            }, (_request_extra = request.extra) != null ? _request_extra : {})
+        });
+    } catch (error) {
+        console.error(`[commerce] ${event.id} not staged for ${request.orderId}`, error);
+    }
+}
+/** Queues an event after the write, reading the order as it now stands. */ export async function raiseOrderEvent(event, request) {
+    try {
+        var _snapshot_data, _request_extra;
+        const firestore = firebaseAdmin.app().firestore();
+        const snapshot = await firestore.collection('hosts').doc(request.hostId).collection('orders').doc(request.orderId).get();
+        if (!snapshot.exists) return;
+        await raisePluginEvent(firestore, {
+            event,
+            pluginId: BUNDLE_ID,
+            hostId: request.hostId,
+            key: `${request.orderId}:${request.key}`,
+            payload: _extends({
+                order: orderViewFromData(request.orderId, (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {})
+            }, (_request_extra = request.extra) != null ? _request_extra : {})
+        });
+    } catch (error) {
+        console.error(`[commerce] ${event.id} not raised for ${request.orderId}`, error);
+    }
+}
+/**
+ * Raises `checkout.started` (AGL-3639) for a checkout a shopper reached with
+ * an address, keyed by the session so a retried request raises it once.
+ * Never throws into the checkout it reports.
+ */ export async function raiseCheckoutStarted(hostId, checkout) {
+    if (!checkout.email) return;
+    try {
+        await raisePluginEvent(firebaseAdmin.app().firestore(), {
+            event: CHECKOUT_STARTED_EVENT,
+            pluginId: BUNDLE_ID,
+            hostId,
+            key: `checkout:${checkout.id}`,
+            payload: {
+                checkout
+            }
+        });
+    } catch (error) {
+        console.error(`[commerce] checkout.started not raised for ${checkout.id}`, error);
+    }
+}
+
+//# sourceMappingURL=order-events.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/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 type { PluginDomainEvent } from '@aglyn/aglyn/plugin-manager/plugin-domain-events'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport {\n  type PluginEventWriter,\n  raisePluginEvent,\n  stagePluginEvent,\n} from '@aglyn/tenant-data-admin/server/plugin-event-outbox'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport type { OrderFulfillment } from '../model/commerce-orders'\nimport {\n  CHECKOUT_STARTED_EVENT,\n  type CheckoutStartedEventPayload,\n} from '../model/order-events'\nimport type {\n  OrderEventFulfillment,\n  OrderEventOrder,\n  OrderEventPayload,\n} from '../model/order-events'\nimport { fulfillmentLineQuantities } from '../model/order-fulfillment'\nimport { fulfillmentTrackingUrl } from '../model/tracking-url'\nimport { orderViewFromData } from './api-v1/order-view'\n\n/**\n * Raising commerce's order events (AGL-3611). Two doors, one per kind of\n * caller, so every status-change site raises its event in one line:\n *\n *  - `stageOrderEvent` rides the caller's transaction, so the event exists\n *    exactly when the status does. For a write that already holds the order\n *    it is about to store.\n *  - `raiseOrderEvent` reads the order once the write has landed and queues\n *    the event, keyed so a redelivered webhook or a retried request raises it\n *    once. For a write with no transaction to ride.\n *\n * Neither ever throws into the write it reports: a fact that happened is not\n * undone because its announcement could not be queued.\n */\n\n/** A shipment in the event's words. */\nexport function fulfillmentEventView(\n  order: { lineItems?: unknown },\n  fulfillment: OrderFulfillment,\n): OrderEventFulfillment {\n  return {\n    id: fulfillment.id,\n    lines: fulfillmentLineQuantities(order as never, fulfillment),\n    carrier: fulfillment.carrier ?? null,\n    trackingNumber: fulfillment.trackingNumber ?? null,\n    trackingUrl: fulfillmentTrackingUrl(fulfillment),\n    labelUrl: fulfillment.labelUrl ?? null,\n    at: new Date(fulfillment.atMs).toISOString(),\n  }\n}\n\nexport interface OrderEventRequest<Payload extends OrderEventPayload> {\n  hostId: string\n  orderId: string\n  /** The occurrence: the same key raises the event once. */\n  key: string\n  /** Everything the payload carries beside `order`. */\n  extra?: Omit<Payload, 'order'>\n}\n\n/**\n * Stages an event inside the caller's transaction, from the order data the\n * transaction is about to store (the read merged with its patch).\n */\nexport function stageOrderEvent<Payload extends OrderEventPayload>(\n  writer: PluginEventWriter,\n  event: PluginDomainEvent<Payload>,\n  request: OrderEventRequest<Payload> & { order: Record<string, unknown> },\n): void {\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    stagePluginEvent(writer, firestore, {\n      event,\n      pluginId: BUNDLE_ID,\n      hostId: request.hostId,\n      key: `${request.orderId}:${request.key}`,\n      payload: {\n        order: orderViewFromData(request.orderId, request.order) as OrderEventOrder,\n        ...(request.extra ?? {}),\n      },\n    })\n  } catch (error) {\n    console.error(`[commerce] ${event.id} not staged for ${request.orderId}`, error)\n  }\n}\n\n/** Queues an event after the write, reading the order as it now stands. */\nexport async function raiseOrderEvent<Payload extends OrderEventPayload>(\n  event: PluginDomainEvent<Payload>,\n  request: OrderEventRequest<Payload>,\n): Promise<void> {\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    const snapshot = await firestore\n      .collection('hosts')\n      .doc(request.hostId)\n      .collection('orders')\n      .doc(request.orderId)\n      .get()\n    if (!snapshot.exists) return\n    await raisePluginEvent(firestore, {\n      event,\n      pluginId: BUNDLE_ID,\n      hostId: request.hostId,\n      key: `${request.orderId}:${request.key}`,\n      payload: {\n        order: orderViewFromData(request.orderId, snapshot.data() ?? {}) as OrderEventOrder,\n        ...(request.extra ?? {}),\n      },\n    })\n  } catch (error) {\n    console.error(`[commerce] ${event.id} not raised for ${request.orderId}`, error)\n  }\n}\n\n/**\n * Raises `checkout.started` (AGL-3639) for a checkout a shopper reached with\n * an address, keyed by the session so a retried request raises it once.\n * Never throws into the checkout it reports.\n */\nexport async function raiseCheckoutStarted(\n  hostId: string,\n  checkout: CheckoutStartedEventPayload['checkout'],\n): Promise<void> {\n  if (!checkout.email) return\n  try {\n    await raisePluginEvent(firebaseAdmin.app().firestore(), {\n      event: CHECKOUT_STARTED_EVENT,\n      pluginId: BUNDLE_ID,\n      hostId,\n      key: `checkout:${checkout.id}`,\n      payload: { checkout },\n    })\n  } catch (error) {\n    console.error(`[commerce] checkout.started not raised for ${checkout.id}`, error)\n  }\n}\n"],"names":["firebaseAdmin","raisePluginEvent","stagePluginEvent","BUNDLE_ID","CHECKOUT_STARTED_EVENT","fulfillmentLineQuantities","fulfillmentTrackingUrl","orderViewFromData","fulfillmentEventView","order","fulfillment","id","lines","carrier","trackingNumber","trackingUrl","labelUrl","at","Date","atMs","toISOString","stageOrderEvent","writer","event","request","firestore","app","pluginId","hostId","key","orderId","payload","extra","error","console","raiseOrderEvent","snapshot","collection","doc","get","exists","data","raiseCheckoutStarted","checkout","email"],"mappings":"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"}

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

@@ -0,0 +1,23 @@
+/**
+ * @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 { OrderHistoryEntry, OrderHistoryPageRequest } from '../model/order-history';
+/** The most one page hands out. */
+export declare const ORDER_HISTORY_MAX_PAGE = 200;
+/** One stored order → its history entry. */
+export declare function orderHistoryEntry(id: string, data: Record<string, unknown>): OrderHistoryEntry;
+/** A page of a site's orders created in [fromMs, untilMs), oldest first. */
+export declare function listOrderHistory(request: OrderHistoryPageRequest, firestore?: FirebaseFirestore.Firestore): Promise<OrderHistoryEntry[]>;

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

@@ -0,0 +1,65 @@
+/**
+ * @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.
+ */ /**
+ * The order history another plugin reads (AGL-3614): a page of a site's
+ * orders by when they were created, in the public API's shape. See
+ * `model/order-history.ts` for the contract.
+ */ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { orderViewFromData } from "./api-v1/order-view.js";
+/** The statuses of an order that was paid. */ const PAID_STATUSES = new Set([
+    'paid',
+    'partially_fulfilled',
+    'fulfilled',
+    'delivered',
+    'refunded'
+]);
+/** The most one page hands out. */ export const ORDER_HISTORY_MAX_PAGE = 200;
+const finiteMs = (value)=>{
+    const ms = Number(value);
+    return Number.isFinite(ms) && ms > 0 ? ms : null;
+};
+/** One stored order → its history entry. */ export function orderHistoryEntry(id, data) {
+    var _finiteMs, _data_status, _data_refundedCents, _finiteMs1;
+    const timeline = Array.isArray(data['timeline']) ? data['timeline'] : [];
+    const refunds = timeline.filter((event)=>{
+        var _event_event;
+        return /refund/i.test(String((_event_event = event['event']) != null ? _event_event : ''));
+    }).map((event)=>finiteMs(event['atMs'])).filter((at)=>at !== null);
+    const createdAtMs = (_finiteMs = finiteMs(data['createdAtMs'])) != null ? _finiteMs : 0;
+    const status = String((_data_status = data['status']) != null ? _data_status : '');
+    // An order is paid as it is created; a cancelled one was paid only if
+    // money came back from it.
+    const paid = PAID_STATUSES.has(status) || status === 'cancelled' && Number((_data_refundedCents = data['refundedCents']) != null ? _data_refundedCents : 0) > 0;
+    return {
+        id,
+        createdAtMs,
+        paidAtMs: paid ? (_finiteMs1 = finiteMs(data['paidAtMs'])) != null ? _finiteMs1 : createdAtMs : null,
+        lastRefundAtMs: refunds.length ? Math.max(...refunds) : null,
+        taxInclusive: data['taxInclusive'] === true,
+        taxRateId: typeof data['taxRateId'] === 'string' && data['taxRateId'] ? data['taxRateId'] : null,
+        order: orderViewFromData(id, data)
+    };
+}
+/** A page of a site's orders created in [fromMs, untilMs), oldest first. */ export async function listOrderHistory(request, firestore = firebaseAdmin.app().firestore()) {
+    var _request_hostId;
+    const hostId = String((_request_hostId = request.hostId) != null ? _request_hostId : '').trim();
+    if (!hostId || !(request.untilMs > request.fromMs)) return [];
+    const limit = Math.max(1, Math.min(ORDER_HISTORY_MAX_PAGE, Math.floor(request.limit) || 1));
+    const page = await firestore.collection('hosts').doc(hostId).collection('orders').where('createdAtMs', '>=', request.fromMs).where('createdAtMs', '<', request.untilMs).orderBy('createdAtMs', 'asc').limit(limit).get();
+    return page.docs.map((doc)=>orderHistoryEntry(doc.id, doc.data()));
+}
+
+//# sourceMappingURL=order-history.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/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\n/**\n * The order history another plugin reads (AGL-3614): a page of a site's\n * orders by when they were created, in the public API's shape. See\n * `model/order-history.ts` for the contract.\n */\n\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport type { OrderHistoryEntry, OrderHistoryPageRequest } from '../model/order-history'\nimport type { OrderStatus } from '../model/commerce-orders'\nimport type { OrderEventOrder } from '../model/order-events'\nimport { orderViewFromData } from './api-v1/order-view'\n\n/** The statuses of an order that was paid. */\nconst PAID_STATUSES: ReadonlySet<string> = new Set<OrderStatus>(['paid', 'partially_fulfilled', 'fulfilled', 'delivered', 'refunded'])\n\n/** The most one page hands out. */\nexport const ORDER_HISTORY_MAX_PAGE = 200\n\nconst finiteMs = (value: unknown): number | null => {\n  const ms = Number(value)\n  return Number.isFinite(ms) && ms > 0 ? ms : null\n}\n\n/** One stored order → its history entry. */\nexport function orderHistoryEntry(id: string, data: Record<string, unknown>): OrderHistoryEntry {\n  const timeline = Array.isArray(data['timeline']) ? (data['timeline'] as Array<Record<string, unknown>>) : []\n  const refunds = timeline\n    .filter((event) => /refund/i.test(String(event['event'] ?? '')))\n    .map((event) => finiteMs(event['atMs']))\n    .filter((at): at is number => at !== null)\n  const createdAtMs = finiteMs(data['createdAtMs']) ?? 0\n  const status = String(data['status'] ?? '')\n  // An order is paid as it is created; a cancelled one was paid only if\n  // money came back from it.\n  const paid = PAID_STATUSES.has(status) || (status === 'cancelled' && Number(data['refundedCents'] ?? 0) > 0)\n  return {\n    id,\n    createdAtMs,\n    paidAtMs: paid ? (finiteMs(data['paidAtMs']) ?? createdAtMs) : null,\n    lastRefundAtMs: refunds.length ? Math.max(...refunds) : null,\n    taxInclusive: data['taxInclusive'] === true,\n    taxRateId: typeof data['taxRateId'] === 'string' && data['taxRateId'] ? data['taxRateId'] : null,\n    order: orderViewFromData(id, data) as unknown as OrderEventOrder,\n  }\n}\n\n/** A page of a site's orders created in [fromMs, untilMs), oldest first. */\nexport async function listOrderHistory(\n  request: OrderHistoryPageRequest,\n  firestore: FirebaseFirestore.Firestore = firebaseAdmin.app().firestore(),\n): Promise<OrderHistoryEntry[]> {\n  const hostId = String(request.hostId ?? '').trim()\n  if (!hostId || !(request.untilMs > request.fromMs)) return []\n  const limit = Math.max(1, Math.min(ORDER_HISTORY_MAX_PAGE, Math.floor(request.limit) || 1))\n  const page = await firestore\n    .collection('hosts')\n    .doc(hostId)\n    .collection('orders')\n    .where('createdAtMs', '>=', request.fromMs)\n    .where('createdAtMs', '<', request.untilMs)\n    .orderBy('createdAtMs', 'asc')\n    .limit(limit)\n    .get()\n  return page.docs.map((doc) => orderHistoryEntry(doc.id, doc.data()))\n}\n"],"names":["firebaseAdmin","orderViewFromData","PAID_STATUSES","Set","ORDER_HISTORY_MAX_PAGE","finiteMs","value","ms","Number","isFinite","orderHistoryEntry","id","data","timeline","Array","isArray","refunds","filter","event","test","String","map","at","createdAtMs","status","paid","has","paidAtMs","lastRefundAtMs","length","Math","max","taxInclusive","taxRateId","order","listOrderHistory","request","firestore","app","hostId","trim","untilMs","fromMs","limit","min","floor","page","collection","doc","where","orderBy","get","docs"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;CAIC,GAED,SAASA,aAAa,QAAQ,2BAA0B;AAIxD,SAASC,iBAAiB,QAAQ,yBAAqB;AAEvD,4CAA4C,GAC5C,MAAMC,gBAAqC,IAAIC,IAAiB;IAAC;IAAQ;IAAuB;IAAa;IAAa;CAAW;AAErI,iCAAiC,GACjC,OAAO,MAAMC,yBAAyB,IAAG;AAEzC,MAAMC,WAAW,CAACC;IAChB,MAAMC,KAAKC,OAAOF;IAClB,OAAOE,OAAOC,QAAQ,CAACF,OAAOA,KAAK,IAAIA,KAAK;AAC9C;AAEA,0CAA0C,GAC1C,OAAO,SAASG,kBAAkBC,EAAU,EAAEC,IAA6B;QAMrDP,WACEO,cAGsDA,qBAIxDP;IAbpB,MAAMQ,WAAWC,MAAMC,OAAO,CAACH,IAAI,CAAC,WAAW,IAAKA,IAAI,CAAC,WAAW,GAAsC,EAAE;IAC5G,MAAMI,UAAUH,SACbI,MAAM,CAAC,CAACC;YAAgCA;eAAtB,UAAUC,IAAI,CAACC,QAAOF,eAAAA,KAAK,CAAC,QAAQ,YAAdA,eAAkB;OAC1DG,GAAG,CAAC,CAACH,QAAUb,SAASa,KAAK,CAAC,OAAO,GACrCD,MAAM,CAAC,CAACK,KAAqBA,OAAO;IACvC,MAAMC,eAAclB,YAAAA,SAASO,IAAI,CAAC,cAAc,aAA5BP,YAAiC;IACrD,MAAMmB,SAASJ,QAAOR,eAAAA,IAAI,CAAC,SAAS,YAAdA,eAAkB;IACxC,sEAAsE;IACtE,2BAA2B;IAC3B,MAAMa,OAAOvB,cAAcwB,GAAG,CAACF,WAAYA,WAAW,eAAehB,QAAOI,sBAAAA,IAAI,CAAC,gBAAgB,YAArBA,sBAAyB,KAAK;IAC1G,OAAO;QACLD;QACAY;QACAI,UAAUF,QAAQpB,aAAAA,SAASO,IAAI,CAAC,WAAW,aAAzBP,aAA8BkB,cAAe;QAC/DK,gBAAgBZ,QAAQa,MAAM,GAAGC,KAAKC,GAAG,IAAIf,WAAW;QACxDgB,cAAcpB,IAAI,CAAC,eAAe,KAAK;QACvCqB,WAAW,OAAOrB,IAAI,CAAC,YAAY,KAAK,YAAYA,IAAI,CAAC,YAAY,GAAGA,IAAI,CAAC,YAAY,GAAG;QAC5FsB,OAAOjC,kBAAkBU,IAAIC;IAC/B;AACF;AAEA,0EAA0E,GAC1E,OAAO,eAAeuB,iBACpBC,OAAgC,EAChCC,YAAyCrC,cAAcsC,GAAG,GAAGD,SAAS,EAAE;QAElDD;IAAtB,MAAMG,SAASnB,QAAOgB,kBAAAA,QAAQG,MAAM,YAAdH,kBAAkB,IAAII,IAAI;IAChD,IAAI,CAACD,UAAU,CAAEH,CAAAA,QAAQK,OAAO,GAAGL,QAAQM,MAAM,AAAD,GAAI,OAAO,EAAE;IAC7D,MAAMC,QAAQb,KAAKC,GAAG,CAAC,GAAGD,KAAKc,GAAG,CAACxC,wBAAwB0B,KAAKe,KAAK,CAACT,QAAQO,KAAK,KAAK;IACxF,MAAMG,OAAO,MAAMT,UAChBU,UAAU,CAAC,SACXC,GAAG,CAACT,QACJQ,UAAU,CAAC,UACXE,KAAK,CAAC,eAAe,MAAMb,QAAQM,MAAM,EACzCO,KAAK,CAAC,eAAe,KAAKb,QAAQK,OAAO,EACzCS,OAAO,CAAC,eAAe,OACvBP,KAAK,CAACA,OACNQ,GAAG;IACN,OAAOL,KAAKM,IAAI,CAAC/B,GAAG,CAAC,CAAC2B,MAAQtC,kBAAkBsC,IAAIrC,EAAE,EAAEqC,IAAIpC,IAAI;AAClE"}

package/src/lib/server/order-notifications.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @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 CommerceModel from '../model';
+/**
+ * Every message a buyer gets about their order, through ONE door (AGL-3610).
+ *
+ * Before this, the buyer heard about their order once — the online receipt —
+ * and never again: a register sale sent nothing, a paid payment link sent
+ * nothing, and shipping, delivery, refunds and cancellations were silent
+ * (`fulfill-order.ts` said so on purpose). Every path that moves an order now
+ * makes one call here, and this decides what that moment owes the buyer:
+ *
+ *   - whether the store turned the moment off (`buyerNotifications` on the
+ *     store settings; ON unless explicitly off — see the model),
+ *   - which channels can carry it (email when mail is configured and the
+ *     order has an address; a text when the platform's SMS provider is
+ *     configured and the order carries the buyer's phone),
+ *   - and whether it was already sent.
+ *
+ * ## ONCE PER MOMENT, PER OCCURRENCE, PER CHANNEL
+ *
+ * Stripe redelivers webhooks, admins click twice, a lost response is retried.
+ * Each message is CLAIMED before it is sent: a transaction reads the order's
+ * `buyerNotifications` map and writes a `sending` marker for
+ * `event__occurrence__channel` only if none is there. Exactly one of two
+ * racing callers wins the claim; the other returns `already`. The occurrence
+ * is the shipment id for `shipped` and the refund id for `refunded`, so a
+ * second parcel or a second partial refund is a new message, while a
+ * redelivered one is not.
+ *
+ * A send that fails RELEASES its claim so the next attempt can try again. A
+ * process that dies between claim and send leaves the marker in `sending` and
+ * the message unsent — at most once, never twice, which is the right side to
+ * fail on for mail a buyer reads as "did they charge me again?".
+ *
+ * ## NEVER THROWS
+ *
+ * Every caller is past its point of no return — money moved, an order
+ * shipped — so a mail outage must not turn into a 500 that invites the
+ * merchant to do it again. Failures are logged and returned as outcomes.
+ *
+ * Shared with the order-processing and POS lanes (AGL-3611, AGL-3607): call
+ * {@link notifyOrderBuyer} from any new path that moves an order, and
+ * {@link sendOrderReceipt} for an explicit, merchant-asked send.
+ */
+export type OrderBuyerEvent = CommerceModel.BuyerNotificationEvent;
+export interface OrderRef {
+    hostId: string;
+    orderId: string;
+}
+export interface NotifyOrderBuyerOptions {
+    /** `shipped`: which shipment. Absent means the order's latest one. */
+    fulfillmentId?: string;
+    /** `refunded`: the refund's own id (Stripe's), the occurrence key. */
+    refundId?: string;
+    /** `refunded`: what THIS refund moved, in cents. */
+    refundCents?: number;
+    /** `refunded`: the line indexes refunded by name, when any were. */
+    refundLineIndexes?: readonly number[];
+    /** `refunded`: whether this refund closed the order. */
+    fullyRefunded?: boolean;
+    /**
+     * The buyer's address when the order document does not carry it — a POS
+     * folio sale attributed to the reservation's guest, a payment link whose
+     * payer Stripe named. The order's own `customerEmail` wins when present.
+     */
+    email?: string | null;
+    /** Injected in specs. */
+    firestore?: FirebaseFirestore.Firestore;
+}
+export type OrderBuyerChannelOutcome = {
+    channel: CommerceModel.BuyerNotificationChannel;
+    outcome: 'sent';
+} | {
+    channel: CommerceModel.BuyerNotificationChannel;
+    outcome: 'already';
+} | {
+    channel: CommerceModel.BuyerNotificationChannel;
+    outcome: 'failed';
+    error: string;
+};
+export type NotifyOrderBuyerOutcome = {
+    outcome: 'disabled';
+} | {
+    outcome: 'no_such_order';
+}
+/** The moment does not apply to this order (a counter sale "shipping"). */
+ | {
+    outcome: 'not_applicable';
+}
+/** No channel could carry it: no address, no mail or text configured. */
+ | {
+    outcome: 'no_recipient';
+} | {
+    outcome: 'handled';
+    channels: OrderBuyerChannelOutcome[];
+};
+interface ComposedMessage {
+    emailKey: string;
+    /** Tokens for the designed email. */
+    tokens: Record<string, string>;
+    /** Subject when the template renders none. */
+    subject: string;
+    /** Plain-text body when the template renders none. */
+    text: string;
+    /** The text message, kept short: one or two segments. */
+    sms: string;
+    /** The order timeline line recording the send, channel appended. */
+    timelineDetail: string;
+}
+/** What the moment says. `null` when it does not apply to this order. */
+export declare function composeOrderBuyerMessage(input: {
+    event: OrderBuyerEvent;
+    order: CommerceModel.HostOrder;
+    orderId: string;
+    businessName: string;
+    currency: string;
+    statusUrl: string;
+    receiptFooter?: string;
+    /** Absolute digital-delivery links for a receipt, by product id. */
+    downloadLinks?: Record<string, string>;
+    options?: NotifyOrderBuyerOptions;
+}): (ComposedMessage & {
+    occurrence: string;
+}) | null;
+/**
+ * Tells the buyer about one moment in their order's life, once. See the
+ * module header. Never throws.
+ */
+export declare function notifyOrderBuyer(ref: OrderRef, event: OrderBuyerEvent, options?: NotifyOrderBuyerOptions): Promise<NotifyOrderBuyerOutcome>;
+export type SendOrderReceiptOutcome = {
+    outcome: 'sent';
+    channel: CommerceModel.BuyerNotificationChannel;
+} | {
+    outcome: 'no_such_order';
+} | {
+    outcome: 'not_configured';
+} | {
+    outcome: 'invalid_recipient';
+} | {
+    outcome: 'failed';
+    error: string;
+};
+/**
+ * Sends the receipt again, on the merchant's say-so, to the address or number
+ * they gave (AGL-3610) — the order dialog's "Resend receipt".
+ *
+ * NOT idempotent, on purpose: a resend IS the second send. The route in front
+ * of it is rate-limited instead, and the send is recorded on the timeline so
+ * the merchant can see it went. It does not consult the store's moment
+ * switches either — a merchant who turned automatic receipts off can still
+ * hand one to a customer who asks.
+ */
+export declare function sendOrderReceipt(ref: OrderRef, input: {
+    channel: CommerceModel.BuyerNotificationChannel;
+    to: string;
+    firestore?: FirebaseFirestore.Firestore;
+}): Promise<SendOrderReceiptOutcome>;
+/**
+ * What the online receipt sends needs from this module (AGL-3610): whether
+ * the store left receipts on, and the `order.number` / `order.statusUrl`
+ * tokens. The cart and buy-now receipts compose their own summary (license
+ * keys and download links built from the Stripe session) inside the
+ * webhook's redelivery guard, so they ask here rather than route through
+ * {@link notifyOrderBuyer}.
+ */
+export declare function onlineReceiptExtras(hostId: string, orderId: string, firestore?: FirebaseFirestore.Firestore): Promise<{
+    enabled: boolean;
+    tokens: Record<string, string>;
+}>;
+export {};