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

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

@@ -0,0 +1,141 @@
+/**
+ * @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 { resolveHostToken } from "@aglyn/aglyn/app-utils/host-tokens";
+import { readClientIp } from "@aglyn/aglyn/app-utils/request-ip";
+import { consumeRateLimit, firebaseAdmin } from "@aglyn/tenant-data-admin";
+import * as CommerceModel from "../model/index.js";
+import { verifyOrderStatusToken } from "./order-status-token.js";
+import { resolvePluginTrackingPages } from "@aglyn/aglyn/plugin-manager/plugin-tracking-pages";
+/** How long the page waits for a tracking service's own page link (AGL-3635). */ export const TRACKING_PAGE_TIMEOUT_MS = 1500;
+/** Status lookups one address may make per site, per ten minutes. */ export const ORDER_STATUS_LOOKUPS_PER_WINDOW = 60;
+export const ORDER_STATUS_WINDOW_MS = 10 * 60000;
+const actionProviders = [];
+export function registerOrderStatusActions(provider) {
+    if (!actionProviders.includes(provider)) actionProviders.push(provider);
+}
+/** Specs only. */ export function clearOrderStatusActions() {
+    actionProviders.length = 0;
+}
+async function actionsFor(input) {
+    const answers = await Promise.all(actionProviders.map(async (provider)=>{
+        try {
+            var _ref;
+            return (_ref = await provider(input)) != null ? _ref : [];
+        } catch (error) {
+            console.error('[order-status] actions provider failed', error);
+            return [];
+        }
+    }));
+    return answers.flat().filter((action)=>action && action.id && action.label && /^(https:\/\/|\/)/.test(String(action.url)));
+}
+/**
+ * The guest order-status page's data (AGL-3610): `GET
+ * /api/commerce/order-status?hostId=…&o=<orderId>&t=<token>` on the store.
+ *
+ * The token is the whole credential — `verifyOrderStatusToken`, constant
+ * time — and a wrong one answers exactly as a missing order does (404), so
+ * the route cannot be used to learn which order ids exist. Rate-limited per
+ * address per site, durable, BEFORE the token check so guessing costs the
+ * same as looking. The answer is `buildOrderStatusView`, an allow-listed
+ * projection, never the order document; `Cache-Control: private, no-store`
+ * and `X-Robots-Tag: noindex` keep it out of shared caches and search.
+ *
+ * Registered as a `recipientLink` route: an emailed link has to keep working
+ * for the buyer it was sent to, so the per-site enablement gates do not
+ * stand between them and their order.
+ */ export const orderStatusHandler = async (req, res)=>{
+    var _req_query_hostId, _req_query_o, _req_query_t, _readClientIp;
+    var _req_socket;
+    res.setHeader('Cache-Control', 'private, no-store');
+    res.setHeader('X-Robots-Tag', 'noindex, nofollow');
+    if (req.method !== 'GET') {
+        return res.status(405).json({
+            error: 'Method not allowed'
+        });
+    }
+    const hostId = String((_req_query_hostId = req.query.hostId) != null ? _req_query_hostId : '');
+    const orderId = String((_req_query_o = req.query.o) != null ? _req_query_o : '').slice(0, 200);
+    const token = String((_req_query_t = req.query.t) != null ? _req_query_t : '').slice(0, 200);
+    if (!hostId || !orderId || !token || /^__.*__$/.test(hostId) || /^__.*__$/.test(orderId) || orderId.includes('/')) {
+        return res.status(400).json({
+            error: 'This link is incomplete.'
+        });
+    }
+    const ip = (_readClientIp = readClientIp(req.headers, {
+        remoteAddress: (_req_socket = req.socket) == null ? void 0 : _req_socket.remoteAddress
+    })) != null ? _readClientIp : 'no-address';
+    const rate = await consumeRateLimit(`commerce-order-status:${hostId}:${ip}`, {
+        limit: ORDER_STATUS_LOOKUPS_PER_WINDOW,
+        windowMs: ORDER_STATUS_WINDOW_MS
+    });
+    if (!rate.allowed) {
+        res.setHeader('Retry-After', String(Math.max(1, Math.ceil((rate.resetMs - Date.now()) / 1000))));
+        return res.status(429).json({
+            error: 'Too many lookups. Try again in a few minutes.'
+        });
+    }
+    const notFound = ()=>res.status(404).json({
+            error: 'We could not find that order. Check the link in your email.'
+        });
+    if (!verifyOrderStatusToken(hostId, orderId, token)) return notFound();
+    try {
+        var _orderSnapshot_data, _resolveHostToken, _settingsSnapshot_get;
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const [hostSnapshot, settingsSnapshot, orderSnapshot] = await Promise.all([
+            hostRef.get(),
+            hostRef.collection('settings').doc('store').get(),
+            hostRef.collection('orders').doc(orderId).get()
+        ]);
+        if (!hostSnapshot.exists || !orderSnapshot.exists) return notFound();
+        const order = CommerceModel.liftLegacyOrder((_orderSnapshot_data = orderSnapshot.data()) != null ? _orderSnapshot_data : {});
+        const view = CommerceModel.buildOrderStatusView({
+            order,
+            orderId,
+            storeName: String((_resolveHostToken = resolveHostToken('businessName', hostSnapshot.data())) != null ? _resolveHostToken : ''),
+            currency: String((_settingsSnapshot_get = settingsSnapshot.get('currency')) != null ? _settingsSnapshot_get : 'USD'),
+            number: CommerceModel.formatOrderNumber(order, orderId),
+            actions: await actionsFor({
+                hostId,
+                orderId,
+                order,
+                token
+            })
+        });
+        // A tracking service's own page for each parcel, where the merchant
+        // follows them through one (AGL-3635); the carrier's link otherwise.
+        const pages = await resolvePluginTrackingPages(view.shipments.filter((shipment)=>shipment.trackingNumber).map((shipment)=>({
+                hostId,
+                recordId: orderId,
+                carrier: shipment.carrier,
+                trackingNumber: String(shipment.trackingNumber)
+            })), {
+            timeoutMs: TRACKING_PAGE_TIMEOUT_MS
+        });
+        for (const shipment of view.shipments){
+            const page = shipment.trackingNumber ? pages.get(shipment.trackingNumber) : undefined;
+            if (page) shipment.trackingUrl = page;
+        }
+        return res.status(200).json(view);
+    } catch (error) {
+        console.error('orderStatus failed', error);
+        return res.status(500).json({
+            error: 'Your order could not be loaded. Try again.'
+        });
+    }
+};
+
+//# sourceMappingURL=order-status.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/order-status.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 {\n  resolveHostToken,\n  type HostTokenSource,\n} from '@aglyn/aglyn/app-utils/host-tokens'\nimport { readClientIp } from '@aglyn/aglyn/app-utils/request-ip'\nimport { consumeRateLimit, firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport * as CommerceModel from '../model'\nimport { verifyOrderStatusToken } from './order-status-token'\nimport { resolvePluginTrackingPages } from '@aglyn/aglyn/plugin-manager/plugin-tracking-pages'\n\n/** How long the page waits for a tracking service's own page link (AGL-3635). */\nexport const TRACKING_PAGE_TIMEOUT_MS = 1_500\n\n/** Status lookups one address may make per site, per ten minutes. */\nexport const ORDER_STATUS_LOOKUPS_PER_WINDOW = 60\nexport const ORDER_STATUS_WINDOW_MS = 10 * 60_000\n\n/**\n * Adds buyer actions to the status page (AGL-3610) — the typed extension\n * point for \"Request a return\", which the order-processing work (AGL-3611)\n * owns. A provider sees the verified order and answers the actions that apply\n * to it (none, usually); the page draws each as a button to its `url`. Kept\n * inside commerce: returns are this plugin's, so no cross-plugin seam is\n * needed, and a provider that throws costs the page its buttons, not the page.\n */\nexport type OrderStatusActionsProvider = (input: {\n  hostId: string\n  orderId: string\n  order: CommerceModel.HostOrder\n  /** The verified status token, for a provider building a signed follow-up link. */\n  token: string\n}) => CommerceModel.OrderStatusAction[] | Promise<CommerceModel.OrderStatusAction[]>\n\nconst actionProviders: OrderStatusActionsProvider[] = []\n\nexport function registerOrderStatusActions(provider: OrderStatusActionsProvider): void {\n  if (!actionProviders.includes(provider)) actionProviders.push(provider)\n}\n\n/** Specs only. */\nexport function clearOrderStatusActions(): void {\n  actionProviders.length = 0\n}\n\nasync function actionsFor(\n  input: Parameters<OrderStatusActionsProvider>[0],\n): Promise<CommerceModel.OrderStatusAction[]> {\n  const answers = await Promise.all(\n    actionProviders.map(async (provider) => {\n      try {\n        return (await provider(input)) ?? []\n      } catch (error) {\n        console.error('[order-status] actions provider failed', error)\n        return []\n      }\n    }),\n  )\n  return answers\n    .flat()\n    .filter(\n      (action) =>\n        action && action.id && action.label && /^(https:\\/\\/|\\/)/.test(String(action.url)),\n    )\n}\n\n/**\n * The guest order-status page's data (AGL-3610): `GET\n * /api/commerce/order-status?hostId=…&o=<orderId>&t=<token>` on the store.\n *\n * The token is the whole credential — `verifyOrderStatusToken`, constant\n * time — and a wrong one answers exactly as a missing order does (404), so\n * the route cannot be used to learn which order ids exist. Rate-limited per\n * address per site, durable, BEFORE the token check so guessing costs the\n * same as looking. The answer is `buildOrderStatusView`, an allow-listed\n * projection, never the order document; `Cache-Control: private, no-store`\n * and `X-Robots-Tag: noindex` keep it out of shared caches and search.\n *\n * Registered as a `recipientLink` route: an emailed link has to keep working\n * for the buyer it was sent to, so the per-site enablement gates do not\n * stand between them and their order.\n */\nexport const orderStatusHandler: PluginApiHandler = async (req, res) => {\n  res.setHeader('Cache-Control', 'private, no-store')\n  res.setHeader('X-Robots-Tag', 'noindex, nofollow')\n  if (req.method !== 'GET') {\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n  const hostId = String(req.query.hostId ?? '')\n  const orderId = String(req.query.o ?? '').slice(0, 200)\n  const token = String(req.query.t ?? '').slice(0, 200)\n  if (!hostId || !orderId || !token || /^__.*__$/.test(hostId) || /^__.*__$/.test(orderId) || orderId.includes('/')) {\n    return res.status(400).json({ error: 'This link is incomplete.' })\n  }\n  const ip =\n    readClientIp(req.headers, { remoteAddress: req.socket?.remoteAddress }) ??\n    'no-address'\n  const rate = await consumeRateLimit(`commerce-order-status:${hostId}:${ip}`, {\n    limit: ORDER_STATUS_LOOKUPS_PER_WINDOW,\n    windowMs: ORDER_STATUS_WINDOW_MS,\n  })\n  if (!rate.allowed) {\n    res.setHeader(\n      'Retry-After',\n      String(Math.max(1, Math.ceil((rate.resetMs - Date.now()) / 1000))),\n    )\n    return res.status(429).json({ error: 'Too many lookups. Try again in a few minutes.' })\n  }\n  const notFound = () =>\n    res.status(404).json({ error: 'We could not find that order. Check the link in your email.' })\n  if (!verifyOrderStatusToken(hostId, orderId, token)) return notFound()\n  try {\n    const firestore = firebaseAdmin.app().firestore()\n    const hostRef = firestore.collection('hosts').doc(hostId)\n    const [hostSnapshot, settingsSnapshot, orderSnapshot] = await Promise.all([\n      hostRef.get(),\n      hostRef.collection('settings').doc('store').get(),\n      hostRef.collection('orders').doc(orderId).get(),\n    ])\n    if (!hostSnapshot.exists || !orderSnapshot.exists) return notFound()\n    const order = CommerceModel.liftLegacyOrder((orderSnapshot.data() ?? {}) as never)\n    const view = CommerceModel.buildOrderStatusView({\n      order,\n      orderId,\n      storeName: String(\n        resolveHostToken('businessName', hostSnapshot.data() as HostTokenSource) ?? '',\n      ),\n      currency: String(settingsSnapshot.get('currency') ?? 'USD'),\n      number: CommerceModel.formatOrderNumber(order, orderId),\n      actions: await actionsFor({ hostId, orderId, order, token }),\n    })\n    // A tracking service's own page for each parcel, where the merchant\n    // follows them through one (AGL-3635); the carrier's link otherwise.\n    const pages = await resolvePluginTrackingPages(\n      view.shipments\n        .filter((shipment) => shipment.trackingNumber)\n        .map((shipment) => ({\n          hostId,\n          recordId: orderId,\n          carrier: shipment.carrier,\n          trackingNumber: String(shipment.trackingNumber),\n        })),\n      { timeoutMs: TRACKING_PAGE_TIMEOUT_MS },\n    )\n    for (const shipment of view.shipments) {\n      const page = shipment.trackingNumber ? pages.get(shipment.trackingNumber) : undefined\n      if (page) shipment.trackingUrl = page\n    }\n    return res.status(200).json(view)\n  } catch (error) {\n    console.error('orderStatus failed', error)\n    return res.status(500).json({ error: 'Your order could not be loaded. Try again.' })\n  }\n}\n"],"names":["resolveHostToken","readClientIp","consumeRateLimit","firebaseAdmin","CommerceModel","verifyOrderStatusToken","resolvePluginTrackingPages","TRACKING_PAGE_TIMEOUT_MS","ORDER_STATUS_LOOKUPS_PER_WINDOW","ORDER_STATUS_WINDOW_MS","actionProviders","registerOrderStatusActions","provider","includes","push","clearOrderStatusActions","length","actionsFor","input","answers","Promise","all","map","error","console","flat","filter","action","id","label","test","String","url","orderStatusHandler","req","res","setHeader","method","status","json","hostId","query","orderId","o","slice","token","t","ip","headers","remoteAddress","socket","rate","limit","windowMs","allowed","Math","max","ceil","resetMs","Date","now","notFound","orderSnapshot","settingsSnapshot","firestore","app","hostRef","collection","doc","hostSnapshot","get","exists","order","liftLegacyOrder","data","view","buildOrderStatusView","storeName","currency","number","formatOrderNumber","actions","pages","shipments","shipment","trackingNumber","recordId","carrier","timeoutMs","page","undefined","trackingUrl"],"mappings":"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"}

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

@@ -0,0 +1,108 @@
+/**
+ * @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 { PluginDomainEventEnvelope } from '@aglyn/aglyn/plugin-manager/plugin-domain-events';
+import { fetchConfiguredPublicUrl } from '@aglyn/tenant-data-admin';
+import { type SecretBoxKeyring } from '@aglyn/shared-util-tools/secret-box';
+import * as Webhooks from '../model/order-webhooks';
+/**
+ * Merchant order webhooks (AGL-3611): the console's door and the delivery
+ * behind it. The model (`model/order-webhooks.ts`) says what is stored where.
+ *
+ * DELIVERY RIDES THE PLUGIN EVENT OUTBOX. Commerce subscribes to its own
+ * order and return events under the name `webhooks`; the subscriber posts the
+ * event to every endpoint that takes it and records each attempt in the
+ * delivery log. An endpoint that already took an event is not posted it
+ * again, so when one of three endpoints fails, the subscriber throws, the
+ * outbox retries it with its backoff (30s, 2m, 10m, 30m, 1h, 6h, 12h), and
+ * only the failing endpoint is called again. On the last attempt the delivery
+ * is marked failed and the site's managers are told.
+ *
+ * EVERY CALL GOES THROUGH `fetchConfiguredPublicUrl`: https on the default
+ * port, a public address pinned at connect time, no redirect followed. A
+ * merchant's endpoint is a stranger's server to us.
+ *
+ * THE SECRET IS SEALED with the shared secret box, under the keyring
+ * `readCommerceSecretKeyring` answers, bound to its endpoint by the seal's
+ * context. The plaintext leaves the server once, in the answer to the request
+ * that made or rolled it.
+ */
+export declare const COMMERCE_SECRET_KEY_ENV = "COMMERCE_SECRET_KEY";
+/** Delivery rows live this long, then Firestore's TTL removes them. */
+export declare const ORDER_WEBHOOK_LOG_RETENTION_MS: number;
+/** The id of the key derived from `TOKEN_SIGNING_SECRET`. */
+export declare const DERIVED_COMMERCE_KEY_ID = "tss1";
+/**
+ * The keyring commerce seals its stored secrets with. `COMMERCE_SECRET_KEY`
+ * (a secret-box keyring) when it is set, its first key sealing; otherwise the
+ * key derived from `TOKEN_SIGNING_SECRET`, which every deployment that sells
+ * already has. The derived key stays in the ring after a dedicated key is
+ * configured, so what it sealed still opens. `null` when neither is usable.
+ * Never throws.
+ */
+export declare function readCommerceSecretKeyring(): SecretBoxKeyring | null;
+/** Whether this deployment can sign webhooks at all. */
+export declare function orderWebhooksConfigured(): boolean;
+/** A fresh signing secret: `whsec_` and 32 random bytes. */
+export declare function mintOrderWebhookSecret(): string;
+/** The HMAC-SHA256 of `{t}.{body}` under the secret, as hex. */
+export declare function signOrderWebhook(secret: string, timestampSeconds: number, body: string): string;
+/** What one POST came to. */
+export interface OrderWebhookPostResult {
+    attempt: Webhooks.OrderWebhookAttempt;
+    delivered: boolean;
+}
+/**
+ * Posts one body to one endpoint, signed. Never throws: a refusal, a timeout
+ * or a reset is an attempt that failed, with the reason in words.
+ */
+export declare function postOrderWebhook(input: {
+    url: string;
+    secret: string;
+    event: string;
+    eventId: string;
+    body: string;
+    now?: () => number;
+    fetchImpl?: typeof fetchConfiguredPublicUrl;
+}): Promise<OrderWebhookPostResult>;
+/**
+ * The subscriber: posts one event to every endpoint of the site that takes
+ * it and has not taken it already. Throws when any endpoint still owes it, so
+ * the outbox retries; on the outbox's last attempt it records the failure and
+ * tells the site's managers instead.
+ */
+export declare function deliverOrderEventToWebhooks(envelope: PluginDomainEventEnvelope, deps?: {
+    fetchImpl?: typeof fetchConfiguredPublicUrl;
+    now?: () => number;
+}): Promise<{
+    delivered: number;
+    failed: number;
+}>;
+/**
+ * `POST /api/commerce/order-webhooks` with `{ hostId, action, … }`. Endpoints
+ * post the order book to an outside server, so only an admin of the whole
+ * workspace manages them — the bar a refund sets.
+ *
+ *  - `status` → `{ configured, events: [{ event, label, description }] }`
+ *  - `create` `{ url, events, description? }` → `{ id, secret }` (shown once)
+ *  - `update` `{ endpointId, url?, events?, enabled?, description? }`
+ *  - `roll-secret` `{ endpointId }` → `{ secret }`
+ *  - `delete` `{ endpointId }`; the delivery log stays until it expires
+ *  - `test` `{ endpointId }` → posts a `webhook.test` event now
+ *  - `resend` `{ deliveryId }` → posts a logged delivery again now
+ */
+export declare const orderWebhooksHandler: PluginApiHandler;