@aglyn/plugins-commerce 1.0.0-beta.233 → 1.0.0-beta.235

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

@@ -0,0 +1,28 @@
+/**
+ * @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 PluginApiHandler } from '@aglyn/aglyn/server';
+import { type ProductsWriteDeps } from './products-write';
+/** Adds a note to an order's timeline. */
+export declare function createOrderNoteHandler(options?: ProductsWriteDeps): PluginApiHandler;
+/**
+ * Answers an order's open restock question. `flaggedAtMs` names the question
+ * the person saw; an answer never lands on a newer one. It moves no stock, as
+ * in the console: it only clears the question.
+ */
+export declare function createOrderRestockAnswerHandler(options?: ProductsWriteDeps): PluginApiHandler;
+export declare const orderNoteHandler: PluginApiHandler;
+export declare const orderRestockAnswerHandler: PluginApiHandler;

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

@@ -0,0 +1,143 @@
+/**
+ * @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 { liftLegacyOrder, orderNoteUpdate, restockAnswer } from "../model/index.js";
+import { bodyOf, gate, resolved, validId } from "./products-write.js";
+function missing(res) {
+    return res.status(400).json({
+        error: 'Missing site or order'
+    });
+}
+/** Adds a note to an order's timeline. */ export function createOrderNoteHandler(options = {}) {
+    return async (req, res)=>{
+        if (req.method !== 'POST') return res.status(405).json({
+            error: 'Method not allowed'
+        });
+        const deps = resolved(options);
+        const body = bodyOf(req);
+        const { hostId, orderId } = body;
+        if (!validId(hostId) || !validId(orderId)) return missing(res);
+        if (typeof body['note'] !== 'string' || !body['note'].trim()) return res.status(400).json({
+            error: 'Write a note first'
+        });
+        try {
+            const door = await gate(req, res, hostId, deps);
+            if (!door) return;
+            const db = deps.firestore();
+            const orderRef = db.collection('hosts').doc(hostId).collection('orders').doc(orderId);
+            const answer = await db.runTransaction(async (tx)=>{
+                var _stored_data;
+                const stored = await tx.get(orderRef);
+                if (!stored.exists) return {
+                    status: 404,
+                    body: {
+                        error: 'This order no longer exists'
+                    }
+                };
+                const order = liftLegacyOrder((_stored_data = stored.data()) != null ? _stored_data : {});
+                const update = orderNoteUpdate(order, body['note'], deps.now());
+                if (!update) return {
+                    status: 400,
+                    body: {
+                        error: 'Write a note first'
+                    }
+                };
+                tx.update(orderRef, update);
+                return {
+                    status: 200,
+                    body: {
+                        ok: true,
+                        timeline: update.timeline
+                    }
+                };
+            });
+            return res.status(answer.status).json(answer.body);
+        } catch (error) {
+            console.error('[commerce/order-note]', error);
+            return res.status(500).json({
+                error: 'The note could not be added'
+            });
+        }
+    };
+}
+const RESOLUTIONS = [
+    'restocked',
+    'dismissed'
+];
+/**
+ * Answers an order's open restock question. `flaggedAtMs` names the question
+ * the person saw; an answer never lands on a newer one. It moves no stock, as
+ * in the console: it only clears the question.
+ */ export function createOrderRestockAnswerHandler(options = {}) {
+    return async (req, res)=>{
+        if (req.method !== 'POST') return res.status(405).json({
+            error: 'Method not allowed'
+        });
+        const deps = resolved(options);
+        const body = bodyOf(req);
+        const { hostId, orderId } = body;
+        if (!validId(hostId) || !validId(orderId)) return missing(res);
+        const resolution = body['resolution'];
+        const flaggedAtMs = Number(body['flaggedAtMs']);
+        if (!RESOLUTIONS.includes(resolution) || !Number.isFinite(flaggedAtMs)) {
+            return res.status(400).json({
+                error: 'Choose restocked or no restock'
+            });
+        }
+        try {
+            const door = await gate(req, res, hostId, deps);
+            if (!door) return;
+            const db = deps.firestore();
+            const orderRef = db.collection('hosts').doc(hostId).collection('orders').doc(orderId);
+            const answer = await db.runTransaction(async (tx)=>{
+                var _stored_data;
+                const stored = await tx.get(orderRef);
+                if (!stored.exists) return {
+                    status: 404,
+                    body: {
+                        error: 'This order no longer exists'
+                    }
+                };
+                const order = liftLegacyOrder((_stored_data = stored.data()) != null ? _stored_data : {});
+                const verdict = restockAnswer(order, flaggedAtMs, resolution, door.uid, deps.now());
+                if (verdict.verdict !== 'recorded') return {
+                    status: 200,
+                    body: {
+                        ok: true,
+                        verdict: verdict.verdict
+                    }
+                };
+                tx.update(orderRef, verdict.update);
+                return {
+                    status: 200,
+                    body: {
+                        ok: true,
+                        verdict: 'recorded'
+                    }
+                };
+            });
+            return res.status(answer.status).json(answer.body);
+        } catch (error) {
+            console.error('[commerce/order-restock-answer]', error);
+            return res.status(500).json({
+                error: 'The answer could not be recorded'
+            });
+        }
+    };
+}
+export const orderNoteHandler = createOrderNoteHandler();
+export const orderRestockAnswerHandler = createOrderRestockAnswerHandler();
+
+//# sourceMappingURL=order-annotations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/order-annotations.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 PluginApiHandler } from '@aglyn/aglyn/server'\nimport { liftLegacyOrder, orderNoteUpdate, restockAnswer, type RestockResolution } from '../model'\nimport { bodyOf, gate, resolved, validId, type ProductsWriteDeps } from './products-write'\n\n/*\n * `POST /api/commerce/order-note` and `POST /api/commerce/order-restock-answer`\n * (AGL-3651, AGL-3652): the order dialog's \"Add note\" and its restock\n * question, for the native apps.\n *\n * The console makes both writes from the browser, as an `updateDoc` of the\n * order's `timeline` (and `restockCheck`), the only two fields the Firestore\n * rules let a member write on an order. Both are read-then-append, so a\n * stale seed would drop an event another tab wrote. These routes run the\n * console's own computation (`model/order-annotations.ts`, which the console\n * imports too) inside a transaction on the stored order, under the gate the\n * rules put on that write: a verified member with a write role on the site,\n * or staff, while the site, its org and the platform are not frozen.\n */\n\ntype Reply = Parameters<PluginApiHandler>[1]\n\nfunction missing(res: Reply) {\n  return res.status(400).json({ error: 'Missing site or order' })\n}\n\n/** Adds a note to an order's timeline. */\nexport function createOrderNoteHandler(options: ProductsWriteDeps = {}): PluginApiHandler {\n  return async (req, res) => {\n    if (req.method !== 'POST') return res.status(405).json({ error: 'Method not allowed' })\n    const deps = resolved(options)\n    const body = bodyOf(req)\n    const { hostId, orderId } = body\n    if (!validId(hostId) || !validId(orderId)) return missing(res)\n    if (typeof body['note'] !== 'string' || !body['note'].trim()) return res.status(400).json({ error: 'Write a note first' })\n    try {\n      const door = await gate(req, res, hostId, deps)\n      if (!door) return\n      const db = deps.firestore()\n      const orderRef = db.collection('hosts').doc(hostId).collection('orders').doc(orderId)\n      const answer = await db.runTransaction(async (tx) => {\n        const stored = await tx.get(orderRef)\n        if (!stored.exists) return { status: 404, body: { error: 'This order no longer exists' } }\n        const order = liftLegacyOrder((stored.data() ?? {}) as never)\n        const update = orderNoteUpdate(order, body['note'] as string, deps.now())\n        if (!update) return { status: 400, body: { error: 'Write a note first' } }\n        tx.update(orderRef, update)\n        return { status: 200, body: { ok: true, timeline: update.timeline } }\n      })\n      return res.status(answer.status).json(answer.body)\n    } catch (error) {\n      console.error('[commerce/order-note]', error)\n      return res.status(500).json({ error: 'The note could not be added' })\n    }\n  }\n}\n\nconst RESOLUTIONS: readonly RestockResolution[] = ['restocked', 'dismissed']\n\n/**\n * Answers an order's open restock question. `flaggedAtMs` names the question\n * the person saw; an answer never lands on a newer one. It moves no stock, as\n * in the console: it only clears the question.\n */\nexport function createOrderRestockAnswerHandler(options: ProductsWriteDeps = {}): PluginApiHandler {\n  return async (req, res) => {\n    if (req.method !== 'POST') return res.status(405).json({ error: 'Method not allowed' })\n    const deps = resolved(options)\n    const body = bodyOf(req)\n    const { hostId, orderId } = body\n    if (!validId(hostId) || !validId(orderId)) return missing(res)\n    const resolution = body['resolution'] as RestockResolution\n    const flaggedAtMs = Number(body['flaggedAtMs'])\n    if (!RESOLUTIONS.includes(resolution) || !Number.isFinite(flaggedAtMs)) {\n      return res.status(400).json({ error: 'Choose restocked or no restock' })\n    }\n    try {\n      const door = await gate(req, res, hostId, deps)\n      if (!door) return\n      const db = deps.firestore()\n      const orderRef = db.collection('hosts').doc(hostId).collection('orders').doc(orderId)\n      const answer = await db.runTransaction(async (tx) => {\n        const stored = await tx.get(orderRef)\n        if (!stored.exists) return { status: 404, body: { error: 'This order no longer exists' } }\n        const order = liftLegacyOrder((stored.data() ?? {}) as never)\n        const verdict = restockAnswer(order, flaggedAtMs, resolution, door.uid, deps.now())\n        if (verdict.verdict !== 'recorded') return { status: 200, body: { ok: true, verdict: verdict.verdict } }\n        tx.update(orderRef, verdict.update)\n        return { status: 200, body: { ok: true, verdict: 'recorded' } }\n      })\n      return res.status(answer.status).json(answer.body)\n    } catch (error) {\n      console.error('[commerce/order-restock-answer]', error)\n      return res.status(500).json({ error: 'The answer could not be recorded' })\n    }\n  }\n}\n\nexport const orderNoteHandler = createOrderNoteHandler()\nexport const orderRestockAnswerHandler = createOrderRestockAnswerHandler()\n"],"names":["liftLegacyOrder","orderNoteUpdate","restockAnswer","bodyOf","gate","resolved","validId","missing","res","status","json","error","createOrderNoteHandler","options","req","method","deps","body","hostId","orderId","trim","door","db","firestore","orderRef","collection","doc","answer","runTransaction","tx","stored","get","exists","order","data","update","now","ok","timeline","console","RESOLUTIONS","createOrderRestockAnswerHandler","resolution","flaggedAtMs","Number","includes","isFinite","verdict","uid","orderNoteHandler","orderRestockAnswerHandler"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,eAAe,EAAEC,eAAe,EAAEC,aAAa,QAAgC,oBAAU;AAClG,SAASC,MAAM,EAAEC,IAAI,EAAEC,QAAQ,EAAEC,OAAO,QAAgC,sBAAkB;AAmB1F,SAASC,QAAQC,GAAU;IACzB,OAAOA,IAAIC,MAAM,CAAC,KAAKC,IAAI,CAAC;QAAEC,OAAO;IAAwB;AAC/D;AAEA,wCAAwC,GACxC,OAAO,SAASC,uBAAuBC,UAA6B,CAAC,CAAC;IACpE,OAAO,OAAOC,KAAKN;QACjB,IAAIM,IAAIC,MAAM,KAAK,QAAQ,OAAOP,IAAIC,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAqB;QACrF,MAAMK,OAAOX,SAASQ;QACtB,MAAMI,OAAOd,OAAOW;QACpB,MAAM,EAAEI,MAAM,EAAEC,OAAO,EAAE,GAAGF;QAC5B,IAAI,CAACX,QAAQY,WAAW,CAACZ,QAAQa,UAAU,OAAOZ,QAAQC;QAC1D,IAAI,OAAOS,IAAI,CAAC,OAAO,KAAK,YAAY,CAACA,IAAI,CAAC,OAAO,CAACG,IAAI,IAAI,OAAOZ,IAAIC,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAqB;QACxH,IAAI;YACF,MAAMU,OAAO,MAAMjB,KAAKU,KAAKN,KAAKU,QAAQF;YAC1C,IAAI,CAACK,MAAM;YACX,MAAMC,KAAKN,KAAKO,SAAS;YACzB,MAAMC,WAAWF,GAAGG,UAAU,CAAC,SAASC,GAAG,CAACR,QAAQO,UAAU,CAAC,UAAUC,GAAG,CAACP;YAC7E,MAAMQ,SAAS,MAAML,GAAGM,cAAc,CAAC,OAAOC;oBAGbC;gBAF/B,MAAMA,SAAS,MAAMD,GAAGE,GAAG,CAACP;gBAC5B,IAAI,CAACM,OAAOE,MAAM,EAAE,OAAO;oBAAEvB,QAAQ;oBAAKQ,MAAM;wBAAEN,OAAO;oBAA8B;gBAAE;gBACzF,MAAMsB,QAAQjC,iBAAiB8B,eAAAA,OAAOI,IAAI,cAAXJ,eAAiB,CAAC;gBACjD,MAAMK,SAASlC,gBAAgBgC,OAAOhB,IAAI,CAAC,OAAO,EAAYD,KAAKoB,GAAG;gBACtE,IAAI,CAACD,QAAQ,OAAO;oBAAE1B,QAAQ;oBAAKQ,MAAM;wBAAEN,OAAO;oBAAqB;gBAAE;gBACzEkB,GAAGM,MAAM,CAACX,UAAUW;gBACpB,OAAO;oBAAE1B,QAAQ;oBAAKQ,MAAM;wBAAEoB,IAAI;wBAAMC,UAAUH,OAAOG,QAAQ;oBAAC;gBAAE;YACtE;YACA,OAAO9B,IAAIC,MAAM,CAACkB,OAAOlB,MAAM,EAAEC,IAAI,CAACiB,OAAOV,IAAI;QACnD,EAAE,OAAON,OAAO;YACd4B,QAAQ5B,KAAK,CAAC,yBAAyBA;YACvC,OAAOH,IAAIC,MAAM,CAAC,KAAKC,IAAI,CAAC;gBAAEC,OAAO;YAA8B;QACrE;IACF;AACF;AAEA,MAAM6B,cAA4C;IAAC;IAAa;CAAY;AAE5E;;;;CAIC,GACD,OAAO,SAASC,gCAAgC5B,UAA6B,CAAC,CAAC;IAC7E,OAAO,OAAOC,KAAKN;QACjB,IAAIM,IAAIC,MAAM,KAAK,QAAQ,OAAOP,IAAIC,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAqB;QACrF,MAAMK,OAAOX,SAASQ;QACtB,MAAMI,OAAOd,OAAOW;QACpB,MAAM,EAAEI,MAAM,EAAEC,OAAO,EAAE,GAAGF;QAC5B,IAAI,CAACX,QAAQY,WAAW,CAACZ,QAAQa,UAAU,OAAOZ,QAAQC;QAC1D,MAAMkC,aAAazB,IAAI,CAAC,aAAa;QACrC,MAAM0B,cAAcC,OAAO3B,IAAI,CAAC,cAAc;QAC9C,IAAI,CAACuB,YAAYK,QAAQ,CAACH,eAAe,CAACE,OAAOE,QAAQ,CAACH,cAAc;YACtE,OAAOnC,IAAIC,MAAM,CAAC,KAAKC,IAAI,CAAC;gBAAEC,OAAO;YAAiC;QACxE;QACA,IAAI;YACF,MAAMU,OAAO,MAAMjB,KAAKU,KAAKN,KAAKU,QAAQF;YAC1C,IAAI,CAACK,MAAM;YACX,MAAMC,KAAKN,KAAKO,SAAS;YACzB,MAAMC,WAAWF,GAAGG,UAAU,CAAC,SAASC,GAAG,CAACR,QAAQO,UAAU,CAAC,UAAUC,GAAG,CAACP;YAC7E,MAAMQ,SAAS,MAAML,GAAGM,cAAc,CAAC,OAAOC;oBAGbC;gBAF/B,MAAMA,SAAS,MAAMD,GAAGE,GAAG,CAACP;gBAC5B,IAAI,CAACM,OAAOE,MAAM,EAAE,OAAO;oBAAEvB,QAAQ;oBAAKQ,MAAM;wBAAEN,OAAO;oBAA8B;gBAAE;gBACzF,MAAMsB,QAAQjC,iBAAiB8B,eAAAA,OAAOI,IAAI,cAAXJ,eAAiB,CAAC;gBACjD,MAAMiB,UAAU7C,cAAc+B,OAAOU,aAAaD,YAAYrB,KAAK2B,GAAG,EAAEhC,KAAKoB,GAAG;gBAChF,IAAIW,QAAQA,OAAO,KAAK,YAAY,OAAO;oBAAEtC,QAAQ;oBAAKQ,MAAM;wBAAEoB,IAAI;wBAAMU,SAASA,QAAQA,OAAO;oBAAC;gBAAE;gBACvGlB,GAAGM,MAAM,CAACX,UAAUuB,QAAQZ,MAAM;gBAClC,OAAO;oBAAE1B,QAAQ;oBAAKQ,MAAM;wBAAEoB,IAAI;wBAAMU,SAAS;oBAAW;gBAAE;YAChE;YACA,OAAOvC,IAAIC,MAAM,CAACkB,OAAOlB,MAAM,EAAEC,IAAI,CAACiB,OAAOV,IAAI;QACnD,EAAE,OAAON,OAAO;YACd4B,QAAQ5B,KAAK,CAAC,mCAAmCA;YACjD,OAAOH,IAAIC,MAAM,CAAC,KAAKC,IAAI,CAAC;gBAAEC,OAAO;YAAmC;QAC1E;IACF;AACF;AAEA,OAAO,MAAMsC,mBAAmBrC,yBAAwB;AACxD,OAAO,MAAMsC,4BAA4BT,kCAAiC"}

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

@@ -35,7 +35,7 @@ import { orderViewFromData } from "./api-v1/order-view.js";
  * 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;
+    var _fulfillment_carrier, _fulfillment_trackingNumber, _fulfillment_labelUrl, _fulfillment_labelCostCents;
     return {
         id: fulfillment.id,
         lines: fulfillmentLineQuantities(order, fulfillment),
@@ -43,6 +43,7 @@ import { orderViewFromData } from "./api-v1/order-view.js";
         trackingNumber: (_fulfillment_trackingNumber = fulfillment.trackingNumber) != null ? _fulfillment_trackingNumber : null,
         trackingUrl: fulfillmentTrackingUrl(fulfillment),
         labelUrl: (_fulfillment_labelUrl = fulfillment.labelUrl) != null ? _fulfillment_labelUrl : null,
+        labelCostCents: (_fulfillment_labelCostCents = fulfillment.labelCostCents) != null ? _fulfillment_labelCostCents : null,
         at: new Date(fulfillment.atMs).toISOString()
     };
 }

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

@@ -1 +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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"}
+{"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    labelCostCents: fulfillment.labelCostCents ?? 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","labelCostCents","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-notifications.js

@@ -19,8 +19,10 @@ import { pluginSmsMessaging } from "@aglyn/aglyn/plugin-manager/plugin-sms-messa
 import { resolveSiteTimeZone } from "@aglyn/aglyn/app-utils/collection-entry-date";
 import { resolveHostToken } from "@aglyn/aglyn/app-utils/host-tokens";
 import { firebaseAdmin, getOrgForHost, hostSendingIdentity, meterHostEmail, renderHostEmailWithTokens } from "@aglyn/tenant-data-admin";
-import { isEmailConfigured, sendEmail } from "@aglyn/shared-util-email";
+import { isEmailConfigured, renderTextEmailHtml, sendEmail } from "@aglyn/shared-util-email";
+import { resolvePluginOrderEmailCopies, withOrderEmailDataBlocks } from "@aglyn/aglyn/plugin-manager/plugin-order-email-copies";
 import * as CommerceModel from "../model/index.js";
+import { orderViewFromData } from "./api-v1/order-view.js";
 import { mintDownloadToken } from "./download.js";
 import { orderStatusUrl } from "./order-status-token.js";
 async function readStore(firestore, hostId) {
@@ -310,16 +312,41 @@ async function releaseMessage(orderRef, marker) {
         [`buyerNotifications.${marker}`]: firebaseAdmin.firestore.FieldValue.delete()
     }).catch(()=>undefined);
 }
-async function deliverEmail(store, ref, to, message, context) {
+/** How long a buyer email waits on plugins asking to be copied on it. */ const EMAIL_COPIES_TIMEOUT_MS = 3000;
+async function deliverEmail(store, ref, to, message, context, /** The moment and order, for plugins copied on it; absent for a merchant-asked resend. */ about) {
     var _ref;
     const designed = await renderHostEmailWithTokens(store.firestore, ref.hostId, message.emailKey, message.tokens);
     const org = await getOrgForHost(ref.hostId).catch(()=>null);
-    await sendEmail(_extends({
+    // Plugins copied on this email (AGL-3699): a review platform's invitation
+    // address, with the data block it reads. Asked through core's seam, by
+    // the email's key and moment; nothing answers unless a site connected one.
+    const copies = about ? await resolvePluginOrderEmailCopies({
+        hostId: ref.hostId,
+        recordId: ref.orderId,
+        emailKey: message.emailKey,
+        moment: about.event,
+        recipient: to,
+        order: orderViewFromData(ref.orderId, about.order)
+    }, {
+        timeoutMs: EMAIL_COPIES_TIMEOUT_MS
+    }) : {
+        bcc: [],
+        html: '',
+        settle: async ()=>undefined
+    };
+    const subject = (_ref = designed == null ? void 0 : designed.subject) != null ? _ref : message.subject;
+    const text = (designed == null ? void 0 : designed.text) || message.text;
+    // A data block lives in the HTML part, so a text-only email gets the same
+    // HTML part `sendEmail` would have synthesized, carrying it.
+    const html = copies.html ? withOrderEmailDataBlocks((designed == null ? void 0 : designed.html) || renderTextEmailHtml(text, subject), copies.html) : designed == null ? void 0 : designed.html;
+    const result = await sendEmail(_extends({
         to,
-        subject: (_ref = designed == null ? void 0 : designed.subject) != null ? _ref : message.subject,
-        text: (designed == null ? void 0 : designed.text) || message.text
-    }, (designed == null ? void 0 : designed.html) ? {
-        html: designed.html
+        subject,
+        text
+    }, html ? {
+        html
+    } : {}, copies.bcc.length ? {
+        bcc: copies.bcc
     } : {}, {
         fromName: Aglyn.resolveBrandingProfile(org == null ? void 0 : org.org).fromName,
         sendingIdentity: await hostSendingIdentity(ref.hostId),
@@ -329,6 +356,7 @@ async function deliverEmail(store, ref, to, message, context) {
         // rules never hold it (AGL-3356).
         owedFor: 'order'
     }));
+    await copies.settle(Boolean(result == null ? void 0 : result.sent));
     // Cost meter (AGL-1438), as every transactional store email.
     await meterHostEmail(ref.hostId);
 }
@@ -473,7 +501,10 @@ function emailOf(value) {
             let held = null;
             try {
                 if (target.channel === 'email') {
-                    await deliverEmail(store, ref, target.to, message, context);
+                    await deliverEmail(store, ref, target.to, message, context, {
+                        event,
+                        order
+                    });
                 } else {
                     var _sent_scheduledForMs;
                     const sent = await deliverSms(ref, target.to, message, context, event === 'receipt' ? null : {