@blamejs/blamejs-shop 0.1.18 → 0.1.20

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- v0.1.20 (2026-05-25) — **A "Customers also bought" rail on the order confirmation.** The order confirmation page now shows a recommendation rail. After a purchase, `/orders/:id` surfaces up to four products drawn from operator-curated pins first, then co-purchase signals from the order's own items (what other shoppers bought alongside them), then category-popular and in-stock fallbacks — always excluding what was just bought. The rail is best-effort: if the engine isn't wired it simply doesn't render. **Added:** *Order-confirmation recommendation rail* — The post-purchase page renders a "Customers also bought" rail beneath the order summary, anchored on the order's items. Picks come from the recommendations engine: operator-curated overrides first, then a co-purchase signal (products bought in the same orders), then category-popular and in-stock fallbacks to fill the rail; the order's own products are always excluded. Each pick reuses the storefront product-card markup (image, title, price) and links to the product page. The rail renders in both the default and file-backed theme layouts; a store without the recommendations primitive wired renders no rail (and a read failure degrades to none rather than erroring the confirmation page).
+
+- v0.1.19 (2026-05-25) — **Admin console — a webhooks screen, and order events now fan out.** Webhooks join the admin console. `/admin/webhooks` registers an endpoint (with a one-time signing-secret reveal), lists endpoints, enables / disables and deletes one, and opens an endpoint's delivery feed to retry a failed delivery. Order lifecycle transitions now fan out to registered endpoints — the order primitive is wired to the webhook dispatcher so a paid / fulfilled / shipped / delivered / cancelled / refunded transition produces a signed delivery. **Added:** *Webhooks management screen* — `/admin/webhooks` registers an outbound endpoint — an https:// URL plus the events to subscribe (or all) — and shows the HMAC-SHA3-512 signing secret once on creation; the secret is never rendered in the endpoint list afterward. The list shows each endpoint's URL, events, status, and per-minute rate, with actions to enable / disable, delete, and open its deliveries. The delivery feed lists each attempt (event, status, response code, attempt count, last error, time) and retries a failed delivery. The JSON API a bearer-token client already used — create / list / update / delete / deliveries / retry — is unchanged; the browser screen content-negotiates on the same paths. · *Order events fan out to webhooks* — The order primitive is now wired to the webhook dispatcher, so an order transition (`order.mark_paid`, `order.start_fulfillment`, `order.mark_shipped`, `order.mark_delivered`, `order.cancel`, `order.refund`) produces a signed delivery to every subscribed endpoint. Dispatch is post-persist — a delivery failure can never roll back the transition that landed — and a failed delivery is recorded for retry from the console rather than surfaced to the request that triggered it. **Changed:** *Console nav gains Webhooks* — The signed-in admin nav now includes Webhooks, shown when the webhooks primitive is wired. Endpoint create, list, enable / disable, delete, the delivery feed, and retry content-negotiate like the other console screens: a bearer-token client gets the JSON API, a signed-in browser gets HTML. A request without the bearer token returns the sign-in form on a GET and redirects on a write. An https-only URL or empty event set re-renders the form with the validator's message, and an unknown endpoint or delivery is a no-op notice rather than a 500.
+
 - v0.1.18 (2026-05-25) — **Admin console — a subscription-plans screen.** Subscription plans join the admin console. `/admin/subscription-plans` lists the recurring-offer catalog — price, interval, trial, and Stripe price id — with an active / archived filter, creates a plan from a signed-in browser, and archives one. As with the other console screens, the same path serves the existing JSON API to a bearer-token client unchanged. **Added:** *Subscription-plans management screen* — `/admin/subscription-plans` renders the plan catalog (price and interval, trial length, Stripe price id, linked variant, status) with an active / archived filter, when opened in a signed-in browser; the same path serves the JSON list to a bearer-token client. A form creates a plan — Stripe price id, interval, interval count, currency, amount, trial days, and an optional variant link — and each active row archives in one submit. A bad-shape create re-renders the form with the validator's message rather than a 500, and archiving an unknown plan is a no-op notice. Archiving is terminal from the console: because a plan mirrors a Stripe price id that can go stale, a retired plan is re-offered by creating a new one against a fresh price id. **Changed:** *Console nav gains Subscriptions* — The signed-in admin nav now includes Subscriptions alongside Products, Inventory, Orders, Returns, and Reviews, shown when the subscriptions primitive is wired. The `/admin/subscription-plans` list, create, and archive endpoints content-negotiate like the other screens: a bearer-token client gets the JSON API, a signed-in browser gets HTML. A request without the bearer token returns the sign-in form on a GET and redirects on a write.
 
 - v0.1.17 (2026-05-25) — **Admin console — an inventory screen.** Inventory joins the admin console. `/admin/inventory` lists stock per SKU — on hand, held, and available — with a low-stock filter, restocks a SKU, sets or clears its per-SKU low-stock threshold, and tracks a new SKU, all from a signed-in browser. As with the other console screens, the same path serves the existing JSON API to a bearer-token client unchanged. **Added:** *Inventory management screen* — `/admin/inventory` renders the inventory table (SKU, on-hand, held, available) with a low-stock filter (`?low=1`) that surfaces SKUs at or below their threshold, when opened in a signed-in browser; the same path serves a new JSON list to a bearer-token client. Each row's form restocks (add quantity) and sets the low-stock threshold (blank clears it) in one submit, and a form below tracks a new SKU. The create / restock JSON API is unchanged for tooling; the browser forms post and redirect (PRG), and a bad SKU is a no-op notice rather than a 500. · *catalog.inventory.list* — `catalog.inventory.list({ limit, low_only })` returns inventory rows (SKU ascending), optionally only those at or below their configured low-stock threshold — the read backing the console list and the JSON endpoint. **Changed:** *Console nav gains Inventory* — The signed-in admin nav now includes Inventory alongside Products, Orders, Returns, and Reviews. The `/admin/inventory` list and the create / restock endpoints content-negotiate like the other screens: a bearer-token client gets the JSON API, a signed-in browser gets HTML. A request without the bearer token on these paths now returns the sign-in form on a GET and redirects on a write, matching the other console screens.

package/README.md

@@ -69,10 +69,11 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/addresses.js`** | Per-customer address book at `/account/addresses` — add / edit / set default shipping or billing / remove. One-default-per-role invariant (promoting clears the prior). Every by-id route confirms the address belongs to the signed-in customer before acting (a guessed id returns 404). `b.guardUuid` ids, 2-char ISO country. |
 | **`lib/returns.js`** | Self-serve RMAs. Customer requests a return against their own order at `/account/orders/:id/return` (items + reason, ownership-checked, lines built from the order's own records) and tracks status at `/account/returns`. Operators work `/admin/returns` — approve (refund amount) / mark received / refund / reject — over the pending → approved → received → refunded FSM; illegal transitions are 409, bad ids 404. |
 | **`lib/recently-viewed.js`** | Signed-in customer browse history. A product-page visit records the view server-side against the customer's account (drop-silent — never blocks the page); `/account/recently-viewed` lists them newest-first as a grid with a Clear-history control. De-duped + capped per customer, archived products drop out, login-gated. Guest/session history is opt-in (a client beacon) and not shipped — the lib's `forSession` + `merge` support it. |
+| **`lib/recommendations.js`** | Product-recommendation engine. Operator-curated override pins first (`setOverride` — "when viewing A, show B", kind-scoped + weight-ordered), then a signal-based fallback: co-purchase (products bought in the same orders), category-popular, and in-stock-random filler. `recommendForProduct` / `recommendForCart` / `recommendForCustomer` / `recommendForCategory` each return renderable picks (active + in-stock, source product excluded). The order confirmation page (`/orders/:id`) renders a "Customers also bought" rail from it — best-effort, anchored on the order's items, excluding what was just bought. |
 | **`lib/collections.js`** | Curated + smart product groupings. `GET /collections` lists the shop's active collections; `GET /collections/:slug` renders the grid — manual collections list hand-picked members, smart collections evaluate stored rules against the active catalog and apply the collection's sort strategy. Each product resolves fresh, so archived products drop out. Public, no sign-in; a bad or unknown slug is a 404 (never a 500). Linked from the footer on every page. |
 | **`lib/subscriptions.js`** | Stripe-backed recurring billing — `subscription_plans` (interval / amount / trial) + `subscriptions` (mirrors Stripe's object byte-for-byte). `subscriptions.create` POSTs to Stripe via the payment dep, then persists the returned object locally. `handleStripeEvent` replays `customer.subscription.*` events into the local row so the shop has an authoritative view without round-tripping. |
 | **`lib/newsletter.js`** | Operator-collected email broadcast list — `signup({ email, source })` composes `b.guardEmail` for shape validation, `b.crypto.namespaceHash` for the dedup key, and `INSERT OR IGNORE` for idempotency. Storefront POST `/newsletter` route renders a designed thank-you card with separate copy for the `new` vs `dedup` branches. |
-| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, and tracks new SKUs; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM; **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale. The Returns, Reviews, and Subscriptions links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. |
+| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, and tracks new SKUs; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM; **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline; **Subscriptions** (`/admin/subscription-plans`) is the recurring-offer catalog — filter active / archived, create a plan (Stripe price id, interval, amount, trial), and archive one, with archiving terminal because the mirrored Stripe price can go stale; **Webhooks** (`/admin/webhooks`) registers outbound endpoints (https:// only) with a one-time signing-secret reveal, enables / disables / deletes them, and opens an endpoint's delivery feed to retry a failed delivery — the signing secret is shown once on create and never in the list, and order transitions fan out signed deliveries to subscribed endpoints. The Returns, Reviews, Subscriptions, and Webhooks links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. |
 | **`lib/catalog-import.js`** | Bulk CSV import — `POST /admin/catalog/import` accepts a `text/csv` body, parses via `b.csv`, content-safety-filters every cell through `b.guardCsv` (formula-injection / bidi / control / dangerous-function denylist), validates exact header order, de-dupes rows by `product_slug`, returns per-row errors without aborting. Default 1 MiB / 10000 rows caps. |
 | **`lib/theme.js`** | File-backed templates with fallback chain. Operators register a named theme under `<themesDir>/<name>/*.html` and the storefront dispatches every renderer through it. `assetUrl(path)` resolves to `/assets/themes/<name>/<path>`. The shipped `default` theme is the fallback. |
 
@@ -96,6 +97,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 - `migrations-d1/0206_orders_email_hash.sql` — queryable buyer-email hash on orders (guest-order reconciliation key)
 - `migrations-d1/0043_collections.sql` — manual + smart product collections (members + rules + sort strategy)
 - `migrations-d1/0050_recently_viewed.sql` — per-customer / per-session product browse history (dedup + per-subject cap)
+- `migrations-d1/0105_recommendations.sql` — operator-curated recommendation overrides (kind-scoped, weight-ordered)
 
 ### Demo seed
 

package/lib/admin.js

@@ -225,7 +225,7 @@ function mount(router, deps) {
   // Which optional console sections are wired — gates their nav links so a
   // signed-in admin is never sent to a route that wasn't mounted. Passed
   // into every authed render call as `nav_available`.
-  var navAvailable = { returns: !!returns, reviews: !!reviews, subscriptions: !!deps.subscriptions };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -1183,17 +1183,69 @@ function mount(router, deps) {
 
   var webhooks = deps.webhooks || null;
   if (webhooks) {
-    router.post("/admin/webhooks", W("webhook.create", async function (req, res) {
-      var body = req.body || {};
-      var ep = await webhooks.endpoints.create({ url: body.url, events: body.events });
-      _json(res, 201, ep);
-      return ep;
-    }));
+    var KNOWN_WH_EVENTS = webhooks.KNOWN_EVENTS || [];
 
-    router.get("/admin/webhooks", R(async function (_req, res) {
-      var rows = await webhooks.endpoints.list();
-      _json(res, 200, { rows: rows });
-    }));
+    // Create content-negotiates: bearer → JSON (unchanged for tooling);
+    // signed-in browser form → create, then a one-time secret reveal page.
+    // The HMAC signing secret is shown once here and never rendered in the
+    // list (endpoints.list returns it, so the list render omits it), the
+    // way Stripe / GitHub surface webhook secrets.
+    router.post("/admin/webhooks", _pageOrApi(false,
+      W("webhook.create", async function (req, res) {
+        var body = req.body || {};
+        var ep = await webhooks.endpoints.create({ url: body.url, events: body.events });
+        _json(res, 201, ep);
+        return ep;
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var events;
+        if (body.events_all === "on" || body.events_all === "1") {
+          events = "*";
+        } else {
+          events = KNOWN_WH_EVENTS.filter(function (ev) {
+            var v = body["evt_" + ev];
+            return v === "on" || v === "1";
+          }).join(",");
+        }
+        var ep;
+        try {
+          ep = await webhooks.endpoints.create({ url: (typeof body.url === "string" ? body.url.trim() : body.url), events: events });
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          var rows = await webhooks.endpoints.list();
+          return _sendHtml(res, 400, renderAdminWebhooks({
+            shop_name: deps.shop_name, nav_available: navAvailable, endpoints: rows,
+            known_events: KNOWN_WH_EVENTS, notice: e.message.replace(/^webhooks:\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".webhook.create", outcome: "success", metadata: { id: ep.id } });
+        // Direct 200, not a redirect — the one-time secret must never land
+        // in a URL / server log / browser history.
+        _sendHtml(res, 200, renderAdminWebhookSecret({
+          shop_name: deps.shop_name, nav_available: navAvailable, endpoint: ep,
+        }));
+      },
+    ));
+
+    router.get("/admin/webhooks", _pageOrApi(true,
+      R(async function (_req, res) {
+        var rows = await webhooks.endpoints.list();
+        _json(res, 200, { rows: rows });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var rows = await webhooks.endpoints.list();
+        _sendHtml(res, 200, renderAdminWebhooks({
+          shop_name: deps.shop_name, nav_available: navAvailable, endpoints: rows,
+          known_events: KNOWN_WH_EVENTS,
+          created: url && url.searchParams.get("created"),
+          toggled: url && url.searchParams.get("toggled"),
+          deleted: url && url.searchParams.get("deleted"),
+          notice:  (url && url.searchParams.get("err")) ? "That action couldn't be completed for the endpoint." : null,
+        }));
+      },
+    ));
 
     router.patch("/admin/webhooks/:id", W("webhook.update", async function (req, res) {
       var ep = await webhooks.endpoints.update(req.params.id, req.body || {});
@@ -1209,20 +1261,93 @@ function mount(router, deps) {
       return { id: req.params.id };
     }));
 
-    router.get("/admin/webhooks/:id/deliveries", R(async function (req, res) {
-      var url = req.url ? new URL(req.url, "http://localhost") : null;
-      var limitS = url && url.searchParams.get("limit");
-      var limit  = limitS == null ? 50 : parseInt(limitS, 10);
-      var rows = await webhooks.deliveries.list(req.params.id, { limit: limit });
-      _json(res, 200, { rows: rows });
-    }));
+    // Browser-form equivalents of PATCH active / DELETE (HTML forms can
+    // only GET/POST). Bearer clients keep using PATCH / DELETE above.
+    router.post("/admin/webhooks/:id/toggle", _pageOrApi(false,
+      W("webhook.update", async function (req, res) {
+        var cur = await webhooks.endpoints.get(req.params.id);
+        if (!cur) return _problem(res, 404, "webhook-not-found");
+        var ep = await webhooks.endpoints.update(req.params.id, { active: cur.active ? false : true });
+        _json(res, 200, ep);
+        return ep;
+      }),
+      async function (req, res) {
+        var ep = null;
+        try {
+          var cur = await webhooks.endpoints.get(req.params.id);
+          if (cur) ep = await webhooks.endpoints.update(req.params.id, { active: cur.active ? false : true });
+        } catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!ep) return _redirect(res, "/admin/webhooks?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".webhook.update", outcome: "success", metadata: { id: req.params.id } });
+        _redirect(res, "/admin/webhooks?toggled=1");
+      },
+    ));
 
-    router.post("/admin/webhooks/deliveries/:id/retry", W("webhook.retry", async function (req, res) {
-      var d = await webhooks.deliveries.retry(req.params.id);
-      if (!d) return _problem(res, 404, "delivery-not-found");
-      _json(res, 200, d);
-      return { id: req.params.id };
-    }));
+    router.post("/admin/webhooks/:id/delete", _pageOrApi(false,
+      W("webhook.delete", async function (req, res) {
+        var ok = await webhooks.endpoints.delete(req.params.id);
+        if (!ok) return _problem(res, 404, "webhook-not-found");
+        _json(res, 200, { ok: true });
+        return { id: req.params.id };
+      }),
+      async function (req, res) {
+        var ok = false;
+        try { ok = await webhooks.endpoints.delete(req.params.id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!ok) return _redirect(res, "/admin/webhooks?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".webhook.delete", outcome: "success", metadata: { id: req.params.id } });
+        _redirect(res, "/admin/webhooks?deleted=1");
+      },
+    ));
+
+    router.get("/admin/webhooks/:id/deliveries", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var limitS = url && url.searchParams.get("limit");
+        var limit  = limitS == null ? 50 : parseInt(limitS, 10);
+        var rows = await webhooks.deliveries.list(req.params.id, { limit: limit });
+        _json(res, 200, { rows: rows });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var ep, rows;
+        try {
+          ep = await webhooks.endpoints.get(req.params.id);
+          rows = ep ? await webhooks.deliveries.list(req.params.id, { limit: 100 }) : [];
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          ep = null; rows = [];
+        }
+        if (!ep) return _sendHtml(res, 404, renderAdminWebhookDeliveries({
+          shop_name: deps.shop_name, nav_available: navAvailable, endpoint: null, deliveries: [],
+        }));
+        _sendHtml(res, 200, renderAdminWebhookDeliveries({
+          shop_name: deps.shop_name, nav_available: navAvailable, endpoint: ep, deliveries: rows,
+          retried: url && url.searchParams.get("retried"),
+          notice:  (url && url.searchParams.get("err")) ? "That delivery couldn't be retried." : null,
+        }));
+      },
+    ));
+
+    // Retry composes the network transport (re-POSTs to the endpoint), so
+    // a bearer client gets the JSON contract; a browser form retries then
+    // PRGs back to the endpoint's delivery feed.
+    router.post("/admin/webhooks/deliveries/:id/retry", _pageOrApi(false,
+      W("webhook.retry", async function (req, res) {
+        var d = await webhooks.deliveries.retry(req.params.id);
+        if (!d) return _problem(res, 404, "delivery-not-found");
+        _json(res, 200, d);
+        return { id: req.params.id };
+      }),
+      async function (req, res) {
+        var d = null;
+        try { d = await webhooks.deliveries.retry(req.params.id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!d) return _redirect(res, "/admin/webhooks?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".webhook.retry", outcome: "success", metadata: { id: req.params.id } });
+        _redirect(res, "/admin/webhooks/" + encodeURIComponent(d.endpoint_id) + "/deliveries?retried=1");
+      },
+    ));
   }
 
   // ---- analytics ------------------------------------------------------
@@ -1821,6 +1946,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "returns",      href: "/admin/returns",      label: "Returns",      requires: "returns" },
   { key: "reviews",      href: "/admin/reviews",      label: "Reviews",      requires: "reviews" },
   { key: "subscriptions", href: "/admin/subscription-plans", label: "Subscriptions", requires: "subscriptions" },
+  { key: "webhooks",     href: "/admin/webhooks",     label: "Webhooks",     requires: "webhooks" },
   { key: "integrations", href: "/admin/integrations", label: "Integrations" },
   { key: "setup",        href: "/admin/setup",        label: "Setup" },
 ];
@@ -2434,6 +2560,118 @@ function renderAdminSubscriptionPlans(opts) {
   return _renderAdminShell(opts.shop_name, "Subscription plans", bodyHtml, "subscriptions", opts.nav_available);
 }
 
+function renderAdminWebhooks(opts) {
+  opts = opts || {};
+  var rows  = opts.endpoints    || [];
+  var known = opts.known_events || [];
+  var toggled = opts.toggled ? "<div class=\"banner banner--ok\">Endpoint updated.</div>" : "";
+  var deleted = opts.deleted ? "<div class=\"banner banner--ok\">Endpoint deleted.</div>" : "";
+  var notice  = opts.notice  ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  // The signing secret is intentionally absent from this table — it is
+  // shown once on create (renderAdminWebhookSecret) and never again.
+  var bodyRows = rows.map(function (e) {
+    var isActive = e.active === 1 || e.active === true;
+    var events = e.events === "*" ? "all events" : String(e.events || "").split(",").join(", ");
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(e.url) + "</code></td>" +
+      "<td>" + _htmlEscape(events) + "</td>" +
+      "<td><span class=\"status-pill " + (isActive ? "paid" : "cancelled") + "\">" + (isActive ? "active" : "disabled") + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(String(e.rate_limit_per_minute)) + "/min</td>" +
+      "<td>" +
+        "<a class=\"btn btn--ghost\" href=\"/admin/webhooks/" + _htmlEscape(e.id) + "/deliveries\">Deliveries</a> " +
+        "<form method=\"post\" action=\"/admin/webhooks/" + _htmlEscape(e.id) + "/toggle\" style=\"display:inline;\"><button class=\"btn btn--ghost\" type=\"submit\">" + (isActive ? "Disable" : "Enable") + "</button></form> " +
+        "<form method=\"post\" action=\"/admin/webhooks/" + _htmlEscape(e.id) + "/delete\" style=\"display:inline;\"><button class=\"btn btn--danger\" type=\"submit\">Delete</button></form>" +
+      "</td></tr>";
+  }).join("");
+
+  var table = rows.length
+    ? "<div class=\"panel\"><table><thead><tr><th>URL</th><th>Events</th><th>Status</th><th class=\"num\">Rate</th><th>Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No webhook endpoints yet.</p>";
+
+  var eventChecks = known.map(function (ev) {
+    return "<label style=\"display:block; margin:.3rem 0;\"><input type=\"checkbox\" name=\"evt_" + _htmlEscape(ev) + "\"> <code>" + _htmlEscape(ev) + "</code></label>";
+  }).join("");
+
+  var createForm =
+    "<div class=\"panel\" style=\"margin-top:1.5rem; max-width:40rem;\">" +
+      "<h3 style=\"font-size:.95rem; margin-bottom:.75rem;\">Add an endpoint</h3>" +
+      "<p class=\"meta\">Deliveries are signed (HMAC-SHA3-512); the signing secret is shown once, right after you create the endpoint. Only https:// URLs are accepted.</p>" +
+      "<form method=\"post\" action=\"/admin/webhooks\">" +
+        _setupField("Endpoint URL", "url", "", "url", "Where deliveries are POSTed (https:// only).", " maxlength=\"2048\" required") +
+        "<fieldset style=\"border:1px solid var(--hair); border-radius:.5rem; padding:.75rem 1rem; margin:1rem 0;\">" +
+          "<legend style=\"padding:0 .4rem; font-size:.85rem;\">Events</legend>" +
+          "<label style=\"display:block; margin:.3rem 0;\"><input type=\"checkbox\" name=\"events_all\"> <strong>All events (*)</strong></label>" +
+          eventChecks +
+          "<small style=\"color:var(--mute);\">Pick specific events, or check “All events” to subscribe to everything.</small>" +
+        "</fieldset>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create endpoint</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var body = "<section><h2>Webhooks</h2>" + toggled + deleted + notice + table + createForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Webhooks", body, "webhooks", opts.nav_available);
+}
+
+function renderAdminWebhookSecret(opts) {
+  opts = opts || {};
+  var e = opts.endpoint || {};
+  var body =
+    "<section style=\"max-width:42rem;\">" +
+      "<h2>Endpoint created</h2>" +
+      "<div class=\"banner banner--ok\">Copy the signing secret now — it is shown once and cannot be retrieved again.</div>" +
+      "<div class=\"panel\">" +
+        "<p class=\"meta\">Endpoint</p><p><code class=\"order-id\">" + _htmlEscape(e.url || "") + "</code></p>" +
+        "<p class=\"meta\">Signing secret (HMAC-SHA3-512, key id <code>v1</code>)</p>" +
+        "<pre style=\"white-space:pre-wrap; word-break:break-all; background:var(--bg); border:1px solid var(--hair); border-radius:.5rem; padding:.75rem;\"><code>" + _htmlEscape(e.secret || "") + "</code></pre>" +
+        "<p class=\"meta\">Verify each delivery's signature with this secret using your framework's webhook verifier.</p>" +
+      "</div>" +
+      "<div class=\"actions-row\"><a class=\"btn\" href=\"/admin/webhooks\">Done</a></div>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Endpoint created", body, "webhooks", opts.nav_available);
+}
+
+function renderAdminWebhookDeliveries(opts) {
+  opts = opts || {};
+  var e = opts.endpoint;
+  if (!e) {
+    var nf = "<section><h2>Deliveries</h2><p class=\"empty\">Endpoint not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/webhooks\">Back to webhooks</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Deliveries", nf, "webhooks", opts.nav_available);
+  }
+  var rows = opts.deliveries || [];
+  var retried = opts.retried ? "<div class=\"banner banner--ok\">Delivery retried.</div>" : "";
+  var notice  = opts.notice  ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var bodyRows = rows.map(function (d) {
+    var ok = d.delivered_at != null;
+    var statusCell = ok
+      ? "<span class=\"status-pill paid\">delivered</span>"
+      : "<span class=\"status-pill " + (d.last_error ? "refunded" : "pending") + "\">" + (d.last_error ? "failed" : "pending") + "</span>";
+    var code = d.last_status != null ? _htmlEscape(String(d.last_status)) : "—";
+    var retry = ok ? "<span class=\"meta\">—</span>"
+      : "<form method=\"post\" action=\"/admin/webhooks/deliveries/" + _htmlEscape(d.id) + "/retry\" style=\"display:inline;\"><button class=\"btn btn--ghost\" type=\"submit\">Retry</button></form>";
+    return "<tr>" +
+      "<td>" + _htmlEscape(d.event_type) + "</td>" +
+      "<td>" + statusCell + "</td>" +
+      "<td class=\"num\">" + code + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(d.attempts)) + "</td>" +
+      "<td>" + (d.last_error ? "<span class=\"meta\">" + _htmlEscape(d.last_error) + "</span>" : "") + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(d.created_at)) + "</td>" +
+      "<td>" + retry + "</td>" +
+    "</tr>";
+  }).join("");
+
+  var table = rows.length
+    ? "<div class=\"panel\"><table><thead><tr><th>Event</th><th>Status</th><th class=\"num\">Code</th><th class=\"num\">Attempts</th><th>Last error</th><th>Created</th><th></th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No deliveries recorded for this endpoint yet.</p>";
+
+  var head = "<p class=\"meta\">Endpoint <code class=\"order-id\">" + _htmlEscape(e.url) + "</code></p>";
+  var body = "<section><h2>Deliveries</h2>" + retried + notice + head + table +
+    "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/webhooks\">Back to webhooks</a></div></section>";
+  return _renderAdminShell(opts.shop_name, "Deliveries", body, "webhooks", opts.nav_available);
+}
+
 module.exports = {
   mount:           mount,
   AUDIT_NAMESPACE: AUDIT_NAMESPACE,

package/lib/order.js

@@ -280,25 +280,31 @@ function create(opts) {
         ],
       );
       var refreshed = await this.get(orderId);
-      // Fan-out to merchant webhook subscribers. The dispatch is
-      // post-persist so a delivery failure can never roll back the
-      // transition that just landed in the database. Errors from the
-      // dispatcher are swallowed — the failure already lives in
-      // `webhook_deliveries.last_error` for operator review.
+      // Fan-out to merchant webhook subscribers is fire-and-forget. The
+      // transition has already persisted; the request must not wait on
+      // outbound HTTP, or a slow / unreachable endpoint would block the
+      // transition for seconds (the HTTP client's idle timeout plus
+      // retry). send() persists a delivery row per subscriber and attempts
+      // delivery in the background; a failure lives in
+      // `webhook_deliveries.last_error` for retry from the admin console.
+      // The promise is detached with a swallowing .catch so a rejection —
+      // or a synchronous throw from send() — never becomes an
+      // unhandledRejection and never touches the transition's latency.
       if (webhooks && typeof webhooks.send === "function") {
-        try {
-          await webhooks.send("order." + event, {
-            order: refreshed,
-            transition: {
-              from:     result.from,
-              to:       result.to,
-              on_event: event,
-              reason:   (opts2 && opts2.reason) || null,
-              metadata: (opts2 && opts2.metadata) || {},
-              occurred_at: ts,
-            },
-          });
-        } catch (_e) { /* drop-silent — delivery rows hold the failure */ }
+        var _whPayload = {
+          order: refreshed,
+          transition: {
+            from:     result.from,
+            to:       result.to,
+            on_event: event,
+            reason:   (opts2 && opts2.reason) || null,
+            metadata: (opts2 && opts2.metadata) || {},
+            occurred_at: ts,
+          },
+        };
+        Promise.resolve().then(function () {
+          return webhooks.send("order." + event, _whPayload);
+        }).catch(function () { /* drop-silent — delivery rows hold the failure */ });
       }
       return refreshed;
     },

package/lib/storefront.js

@@ -1818,20 +1818,23 @@ function renderOrder(opts) {
   var tax      = pricing.format(o.tax_minor,         o.currency);
   var shipping = pricing.format(o.shipping_minor,    o.currency);
   var total    = pricing.format(o.grand_total_minor, o.currency);
+  var recs = opts.recommendations || [];
   if (opts.theme) {
     return opts.theme.render("order", {
-      title:          "Order " + o.id,
-      shop_name:      shopName,
-      cart_count:     cartCount,
-      order_id:       o.id,
-      status:         o.status,
-      lines:          rendered,
-      has_lines:      rendered.length > 0,
-      subtotal:       subtotal,
-      tax:            tax,
-      shipping:       shipping,
-      total:          total,
-      asset_css_main: opts.theme.assetUrl("css/main.css"),
+      title:               "Order " + o.id,
+      shop_name:           shopName,
+      cart_count:          cartCount,
+      order_id:            o.id,
+      status:              o.status,
+      lines:               rendered,
+      has_lines:           rendered.length > 0,
+      subtotal:            subtotal,
+      tax:                 tax,
+      shipping:            shipping,
+      total:               total,
+      recommendations:     recs,
+      has_recommendations: recs.length > 0,
+      asset_css_main:      opts.theme.assetUrl("css/main.css"),
     });
   }
   function _orderEsc(s) { return b.template.escapeHtml(s); }
@@ -1858,12 +1861,24 @@ function renderOrder(opts) {
     shipping:  shipping,
     total:     total,
   }).replace("RAW_LINES", rows);
+  // Post-purchase cross-sell rail — reuses the catalog grid + product-card
+  // markup (so it inherits the storefront's card styling), rendered only
+  // when the picker returned something.
+  var railHtml = "";
+  if (recs.length) {
+    var railCards = recs.map(function (p) { return _buildProductCard(p); }).join("");
+    railHtml =
+      "<section class=\"catalog-section order-recommendations\">" +
+        "<header class=\"section-head\"><h2 class=\"section-head__title\">Customers also bought</h2></header>" +
+        "<div class=\"grid\">" + railCards + "</div>" +
+      "</section>";
+  }
   return _wrap({
     title:      "Order " + o.id,
     shop_name:  shopName,
     cart_count: cartCount,
     theme_css: opts.theme_css,
-    body:       body,
+    body:       body + railHtml,
   });
 }
 
@@ -3019,11 +3034,41 @@ function mount(router, deps) {
           hero_media: media.length ? media[0] : null,
         };
       }
+      // "Customers also bought" rail — co-purchase signals anchored on the
+      // order's own items (and excluding them, so we never recommend what
+      // was just bought). Best-effort: a read failure (engine not wired /
+      // tables not migrated) degrades to no rail rather than 500-ing the
+      // confirmation page.
+      var recommendations = [];
+      if (deps.recommendations) {
+        try {
+          var orderProductIds = [];
+          for (var li = 0; li < (o.lines || []).length; li += 1) {
+            var look = productLookup[o.lines[li].variant_id];
+            if (look && look.product && orderProductIds.indexOf(look.product.id) === -1) {
+              orderProductIds.push(look.product.id);
+            }
+          }
+          if (orderProductIds.length) {
+            // recommendForCart aggregates the co-purchase signal across
+            // EVERY purchased product (not just the first) and pivots the
+            // category-popular fallback off the order's dominant
+            // collection; it also self-excludes the order's own products,
+            // so a multi-item order's rail reflects the whole order.
+            var picks = await deps.recommendations.recommendForCart(orderProductIds, { limit: 4 });
+            for (var pi = 0; pi < picks.length; pi += 1) {
+              var card = await _decorateProductCard(picks[pi].product_id);
+              if (card) recommendations.push(card);
+            }
+          }
+        } catch (_e) { recommendations = []; }
+      }
       _send(res, 200, renderOrder({
-        order:          o,
-        product_lookup: productLookup,
-        shop_name:      shopName,
-        theme:          theme,
+        order:           o,
+        product_lookup:  productLookup,
+        recommendations: recommendations,
+        shop_name:       shopName,
+        theme:           theme,
       }));
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {