@blamejs/blamejs-shop 0.3.69 → 0.3.71

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.71 (2026-06-05) — **Vendored blamejs framework refreshed from v0.14.19 to v0.14.21.** The storefront runs on a vendored copy of the blamejs framework; this refreshes it across two upstream patch releases. The most operator-relevant upstream changes for this shop: the OAuth client — which Sign in with Google and Apple compose — gains RFC 9396 Rich Authorization Request validation and attestation-based client authentication primitives, and refuses token grants an identity provider broadened beyond what was requested; HEAD requests now conform by carrying no response body; the sealed-field store gains an unseal rate cap; and a framework-wide sweep ensures every accepted option is actually read, surfacing configuration typos that were previously silent. The remaining upstream changes are in framework areas the storefront does not expose (SCIM bulk operations, OID4VCI credential proofs, DMARC forensic-report parsing). The storefront's own behavior is unchanged, verified by the full test suite — including the regression guards that pin the CSRF origin posture, the referrer policy, and the payment-processor TLS agent against vendor drift — and the vendored-tree integrity manifest was re-stamped as part of the refresh. **Changed:** *Updated the vendored framework to blamejs v0.14.21* — The vendored framework moves from v0.14.19 to v0.14.21 (two upstream patch releases of fixes and additive, opt-in changes). Notable for this shop: hardened OAuth client validation behind federated sign-in, HTTP HEAD conformance, a sealed-field unseal rate cap, and boot-time validation of previously-unread options. The integrity manifest over the vendored tree was re-stamped as part of the refresh.
+
+- v0.3.70 (2026-06-05) — **An Analytics screen in the admin console: funnel, search terms, and product views.** The admin console gains a read-only Analytics screen at /admin/analytics showing the pre-purchase signal the sales report cannot see: the browse-to-buy funnel (product views to cart adds to checkout starts to completed orders) with a conversion rate, top search terms, most-viewed products, top SKUs ranked by units sold, and a revenue-by-day sparkline. It complements rather than duplicates the existing Reports screen — revenue totals stay there, and the two screens link to each other. The same path answers a bearer-token request with JSON, and three JSON endpoints expose the funnel, search terms, and viewed products individually for tooling. Every aggregate is window-bounded (one year maximum, thirty-day default) and limit-bounded; the screen adds no write path anywhere. **Added:** *Read-only analytics dashboard* — The analytics primitive's aggregates are now wired into the console: a date-windowed view with the conversion funnel, top search terms, most-viewed products, units-ranked top SKUs, recent revenue trend, and cross-links with the Reports screen. The HTML view degrades a malformed date window to the default with a notice; the JSON surfaces reject it with a 400. Limits clamp to the primitive's own bounds, a refund-heavy window renders a signed negative total instead of failing, and every operator- or customer-derived string on the screen is escaped. The screen appears in the navigation only when the primitive is wired.
+
 - v0.3.69 (2026-06-05) — **Discount codes on the cart page, and the full shipment timeline on the order page.** Shoppers can now redeem a discount code: an automatic-discount rule may carry an unlock code, leaving it dormant until a shopper enters that code on the cart page — the code persists on the cart, survives signing in, and flows through the exact same evaluation, quoting, and charge path as every other discount rule, so there is one discount system, not two. The cart shows the applied code with a remove control, totals re-render with the savings, and an unknown code gets one uniform message. Separately, the customer order page now shows the full shipment tracking timeline — every recorded carrier event with its status, location, and time, newest first — instead of only the latest event. Two schema migrations apply on deploy. **Added:** *Code-unlocked discount rules with cart-page redemption* — An automatic-discount rule can now carry an unlock code (one active rule per code). The rule stays dormant until a shopper enters its code in the new entry form on the cart page; the code is stored on the cart (capped, idempotent, carried across sign-in by the cart merge), totals re-render with the rule applied, and checkout's quote and confirm honor it on every payment path. The applied code renders as a chip with a remove control; unknown, malformed, or inactive codes all get the same message, so the endpoint reveals nothing about which codes exist. The redemption form is CSRF-tokened like the other cart configuration forms, and the cart page's edge-cached anonymous shell is unaffected — code state renders only on the container. · *Full shipment tracking timeline for customers* — The order page's tracking card previously showed the carrier, tracking number, status, and only the most recent event. It now renders the full event timeline newest-first — status, optional carrier location, optional note, and the event time — bounded to the newest twenty events. Orders without shipment events render exactly as before.
 
 - v0.3.68 (2026-06-05) — **Delivery estimates: "Get it by" dates on the product and cart pages.** The product page and cart can now promise a delivery date. Operators configure the inputs at /admin/delivery-estimates — carrier transit times, warehouse cutoff hours, shipping holidays, and postal-prefix zones — and name the origin warehouse via the SHOP_ESTIMATE_ORIGIN environment variable or the shop.estimate_origin config row. A signed-in customer with a saved shipping address then sees "Get it by <date>" computed from the cutoff clock, transit days, and the holiday calendar. Anonymous visitors served from the edge cache deliberately see no date: an estimate is destination-specific, and a date baked into a shared cached page would show one visitor's delivery promise to everyone while going stale in the cache. The product and cart markup builders are byte-identical across the edge and container renderers with a deterministic date formatter, locked by a parity test. A store that has not configured estimates renders exactly what it does today — nothing — and a configuration gap can never produce a customer-facing error. **Added:** *Configurable delivery-date estimates* — The delivery-estimate primitive is wired end to end: an /admin/delivery-estimates console manages carrier transit times, order-cutoff hours per warehouse, shipping holidays, and postal-prefix zone mappings, with each mutation audited; the product and cart pages render "Get it by <date>" for signed-in customers with a saved shipping address once an origin warehouse is configured. Estimates render only where the destination is actually known — never on shared edge-cached pages — and every estimate read is fail-quiet: missing configuration, an unmatched destination, or a computation error renders no estimate rather than an error. Operators enable it by setting the origin (SHOP_ESTIMATE_ORIGIN or the shop.estimate_origin config row) and authoring at least one cutoff, transit time, and postal zone.

package/README.md

@@ -97,7 +97,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/giftcards.js`** | Prepaid bearer gift cards. `issue({ amount_minor, currency })` generates a 16-char code (32-glyph alphabet, no ambiguous letters) via `b.crypto.generateBytes`, stores only its `namespaceHash` digest + a 4-char hint, and returns the plaintext code once. `balance(code)` / `lookup(code)` resolve a code to its live balance (constant-time hash compare); `redeem({ code, order_id, amount_minor })` decrements the balance with an atomic `balance >= amount` SQL guard so concurrent spends can't overdraw. Redeemed at checkout as a credit against the order grand total: the amount due drops by the applied balance (never below zero), the order still records the full total it owed, and the debit is recorded once per order — a card that fully covers the order is marked paid with no Stripe charge. Customers check a balance at `GET /gift-cards`; the page is not a code-existence oracle (unknown / malformed / expired all return the same generic not-found). |
 | **`lib/gift-card-ledger.js`** | Append-only credit / debit / expire history per gift card, with a denormalized `balance_after_minor` snapshot for O(1) balance reads. `credit` / `debit` / `expire` write one row each; `history(id)` paginates a card's transactions; `transactionsForOrder(id)` lists a card's movements for one order. The audit trail behind the admin gift-card ledger console; overdraft is refused at the primitive layer. |
 | **`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, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **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, and attaches a shipment (carrier + tracking number) with recorded shipment events that surface a public tracking link to the customer; **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); **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; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **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; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **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. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules — including code-unlocked rules a shopper redeems with a discount code on the cart page — + coupon-stacking policies — create / edit / archive each. **Audit** (`/admin/audit`) is a read-only activity log of every privileged action — filtered by outcome (success / failure / denied) and paginated — composed on the framework's tamper-evident `b.audit` chain; opening it is itself recorded as an `audit.read` event. **Errors** (`/admin/errors`) lists captured server-error detail — time, status, route, and a truncated message for scrubbed 500-class failures (checkout confirm, public API, admin actions) — newest-first, with the same path answering a bearer-token request with JSON so the log is one `curl` away. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, Discounts, Delivery estimates, and Errors 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. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
+| **`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, and each product opens a management screen that edits its fields, adds / edits / removes variants, sets a variant's price and shows its price history, and attaches / uploads / removes images — the full path to a sellable product; **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, and attaches a shipment (carrier + tracking number) with recorded shipment events that surface a public tracking link to the customer; **Customers** (`/admin/customers`) is a read-only roster, newest first — display name, short id, join date, sign-in method (passkey count + linked OAuth providers), and order count, with the count and sign-in methods resolved by bounded aggregate queries so a page of customers costs no per-row trips (email addresses aren't stored in the clear, so they're not shown); **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; **Q&A** (`/admin/questions`) is the question moderation queue — filter by status, open a question to its full answer thread, approve / reject the question, post the seller answer, and approve / reject / pin individual answers; **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; **Collections** (`/admin/collections`) manages manual + smart product collections — filter active / archived, create a collection (manual or smart with a starter rule), and per collection edit title / description / sort strategy, manage manual members (add by product id, remove, reorder) or edit a smart collection's rule set with a live preview of the products the rules currently match, and archive; **Gift cards** (`/admin/gift-cards`) is the gift-card ledger — list issued cards (masked code, original + remaining balance, status, issued date) filtered by lifecycle status, issue a new card (the bearer code shown once, right after creation), open a card to see its full credit / debit / expire ledger, and void an active card through a confirmation step; **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. **Tax** (`/admin/tax-rates`), **Shipping** (`/admin/shipping`), and **Discounts** (`/admin/discounts`) configure tax rates per jurisdiction, shipping zones + rates, and automatic-discount rules — including code-unlocked rules a shopper redeems with a discount code on the cart page — + coupon-stacking policies — create / edit / archive each. **Audit** (`/admin/audit`) is a read-only activity log of every privileged action — filtered by outcome (success / failure / denied) and paginated — composed on the framework's tamper-evident `b.audit` chain; opening it is itself recorded as an `audit.read` event. **Errors** (`/admin/errors`) lists captured server-error detail — time, status, route, and a truncated message for scrubbed 500-class failures (checkout confirm, public API, admin actions) — newest-first, with the same path answering a bearer-token request with JSON so the log is one `curl` away. **Analytics** (`/admin/analytics`) is the pre-purchase view the sales report can't see — browse-to-buy funnel with conversion rate, top search terms, most-viewed products, units-ranked top SKUs, and a revenue-by-day sparkline — cross-linked with the Reports screen, read-only, every aggregate window- and limit-bounded. The Customers, Returns, Reviews, Q&A, Subscriptions, Collections, Gift cards, Webhooks, Tax, Shipping, Discounts, Delivery estimates, Analytics, and Errors 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. The console's styling is an external, integrity-pinned stylesheet (`themes/default/assets/css/admin.css`) with the same self-hosted typeface — no inline styles and no third-party font host, so it renders correctly under the strict `style-src 'self'` / `font-src 'self'` CSP that governs the route. |
 | **`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. |
 

package/lib/admin.js

@@ -573,7 +573,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog };
+  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -7896,6 +7896,142 @@ function mount(router, deps) {
         nav_available: navAvailable,
       }));
     });
+
+    // Product-performance + behaviour screen at /admin/analytics. Complements
+    // /admin/reports: the report screen owns the orders-derived money view
+    // (gross/net/AOV/refund-rate, the order-FSM status funnel, top products
+    // by revenue, the by-day money table). This screen owns what the report
+    // does NOT show — units-ranked SKU performance, the pre-purchase
+    // browse→buy funnel (PDP→cart→checkout→complete) and conversion rate,
+    // most-viewed products, top search terms, and a revenue-by-day trend
+    // sparkline. The two link to each other.
+    //
+    // Date range mirrors /admin/reports: `from`/`to` epoch-ms OR
+    // `from-date`/`to-date` calendar-date params (the browser date inputs),
+    // default last 30 days. The analytics primitive re-validates each window
+    // (since < until, span ≤ 1 year) and refuses an unbounded scan, so the
+    // worst an operator typo does is a 400-with-correction re-render — never
+    // a 500, never an unbounded query.
+
+    // Resolve the analytics window from the query string into BOTH the
+    // orders-derived `{ since, until }` shape and the event-stream
+    // `{ from, to }` shape (the primitive uses different bound names per
+    // surface). Accepts the raw epoch-ms `from`/`to` pair (machine clients)
+    // or the calendar-date `from-date`/`to-date` pair (browser date inputs);
+    // epoch-ms wins when both are present. Throws TypeError on a malformed
+    // value so the config/entry-tier 400 path catches it; the primitive's own
+    // span/order re-validation is the second gate.
+    function _parseAnalyticsWindow(url) {
+      var from = _parseEpochMs(url && url.searchParams.get("from"), "from");
+      var to   = _parseEpochMs(url && url.searchParams.get("to"),   "to");
+      if (from == null) from = _parseDateParam(url && url.searchParams.get("from-date"), "from");
+      if (to == null) {
+        var toDate = _parseDateParam(url && url.searchParams.get("to-date"), "to");
+        // `to-date` is the inclusive end day — advance to the next UTC
+        // midnight so the window covers the whole selected day (the primitive
+        // treats `until`/`to` as exclusive).
+        if (toDate != null) to = toDate + b.constants.TIME.days(1);
+      }
+      var now = Date.now();
+      if (to   == null) to   = now;
+      if (from == null) from = now - b.constants.TIME.days(30);
+      return { from: from, to: to };
+    }
+
+    // Compose the screen payload from the analytics primitive. Every read
+    // carries the primitive's own window/limit bound: `topSKUs` /
+    // `topViewedProducts` / `topSearchTerms` are capped at limit 10 (the
+    // primitive enforces [1,100]); `revenueByDay` and `funnel` are window-
+    // bounded (the primitive enforces span ≤ 1 year). No unbounded read is
+    // exposed by this screen.
+    async function _buildAnalyticsView(win) {
+      var ordersWin = { since: win.from, until: win.to };
+      var eventsWin = { from:  win.from, to:    win.to  };
+      var topSkus  = await analytics.topSKUs(Object.assign({}, ordersWin, { limit: 10 }));
+      var byDay    = await analytics.revenueByDay(ordersWin);
+      var viewed   = await analytics.topViewedProducts(Object.assign({}, eventsWin, { limit: 10 }));
+      var searches = await analytics.topSearchTerms(Object.assign({}, eventsWin, { limit: 10 }));
+      var funnel   = await analytics.funnel(eventsWin);
+      // Headline currency for the sparkline + SKU revenue column: the first
+      // currency the by-day series touched (alphabetical), USD when empty.
+      var currency = "USD";
+      for (var i = 0; i < byDay.length; i += 1) {
+        if (byDay[i].currency) { currency = byDay[i].currency; break; }
+      }
+      return {
+        from:                win.from,
+        to:                  win.to,
+        currency:            currency,
+        top_skus:            topSkus,
+        by_day:              byDay,
+        top_viewed_products: viewed,
+        top_search_terms:    searches,
+        funnel:              funnel,
+      };
+    }
+
+    // JSON-only complements to the existing /admin/analytics/* API — the
+    // pre-purchase aggregates the dashboard/reports JSON never exposed.
+    router.get("/admin/analytics/top-search-terms", R(async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var w   = _parseWindow(url);
+      w.from = w.since; w.to = w.until; delete w.since; delete w.until;
+      w.limit = _parseLimit(url && url.searchParams.get("limit"), "limit", 100, 10);
+      var rows = await analytics.topSearchTerms(w);
+      _json(res, 200, { rows: rows });
+    }));
+
+    router.get("/admin/analytics/top-viewed-products", R(async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var w   = _parseWindow(url);
+      w.from = w.since; w.to = w.until; delete w.since; delete w.until;
+      w.limit = _parseLimit(url && url.searchParams.get("limit"), "limit", 100, 10);
+      var rows = await analytics.topViewedProducts(w);
+      _json(res, 200, { rows: rows });
+    }));
+
+    router.get("/admin/analytics/funnel", R(async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var w   = _parseWindow(url);
+      var f   = await analytics.funnel({ from: w.since, to: w.until });
+      _json(res, 200, f);
+    }));
+
+    // The product-performance screen — bearer → JSON contract, signed-in
+    // browser → rendered console page.
+    router.get("/admin/analytics", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var win;
+        try { win = _parseAnalyticsWindow(url); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        var view;
+        try { view = await _buildAnalyticsView(win); }
+        catch (e2) { if (e2 instanceof TypeError) return _problem(res, 400, "bad-request", e2.message); throw e2; }
+        _json(res, 200, view);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var win, notice = null;
+        try { win = _parseAnalyticsWindow(url); }
+        catch (e) {
+          // Bad range → default window + a correction notice (config/entry
+          // tier: the operator fixes the typo, the screen never 500s).
+          win = { to: Date.now(), from: Date.now() - b.constants.TIME.days(30) };
+          notice = _safeNotice(e, "analytics.view").message.replace(/^admin:\s*/, "");
+        }
+        var view;
+        try { view = await _buildAnalyticsView(win); }
+        catch (e2) {
+          win = { to: Date.now(), from: Date.now() - b.constants.TIME.days(30) };
+          notice = _safeNotice(e2, "analytics.view").message.replace(/^analytics:\s*/, "");
+          view = await _buildAnalyticsView(win);
+        }
+        _sendHtml(res, 200, renderAdminAnalytics({
+          shop_name: deps.shop_name, nav_available: navAvailable, view: view, notice: notice,
+        }));
+      },
+    ));
   }
 
   // ---- subscriptions --------------------------------------------------
@@ -10831,6 +10967,121 @@ function _statCard(label, value, accent) {
          "<div class=\"value" + (accent ? " accent" : "") + "\">" + _htmlEscape(value) + "</div></div>";
 }
 
+// Format a money amount that may be negative. `pricing.format` (composing
+// b.money) asserts a non-negative minor-unit; analytics net revenue
+// subtracts refunds, so a refund-dominated window can go negative. Render
+// the magnitude through the same formatter and carry the sign by hand so
+// the screen never 500s on a legitimately-negative aggregate.
+function _fmtSignedMoney(amountMinor, currency) {
+  var n = Number(amountMinor) || 0;
+  if (n < 0) return "-" + pricing.format(-n, currency);
+  return pricing.format(n, currency);
+}
+
+// Product-performance + behaviour screen for /admin/analytics. Surfaces the
+// aggregates /admin/reports does NOT: units-ranked SKU performance, the
+// browse→buy funnel + conversion rate, most-viewed products, top search
+// terms, and a revenue-by-day trend sparkline. `opts.view` is the
+// `_buildAnalyticsView` payload (never null — the route always builds a
+// view, falling back to the default window on a bad range). Each table
+// renders an honest empty state when its aggregate is empty.
+function renderAdminAnalytics(opts) {
+  opts = opts || {};
+  var view   = opts.view || {};
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var cur    = view.currency || "USD";
+
+  var fromVal = _dateInputValue(view.from);
+  // `to` is exclusive (next UTC midnight after the operator's chosen end
+  // day) — step back one day to render the inclusive end day into the input.
+  var toVal   = _dateInputValue((view.to || Date.now()) - b.constants.TIME.days(1));
+
+  // Date-range form (GET so the window lives in the URL — bookmarkable).
+  var rangeForm =
+    "<form method=\"get\" action=\"/admin/analytics\" class=\"order-filters\">" +
+      "<label class=\"form-field\"><span>From</span><input type=\"date\" name=\"from-date\" value=\"" + _htmlEscape(fromVal) + "\"></label>" +
+      "<label class=\"form-field\"><span>To</span><input type=\"date\" name=\"to-date\" value=\"" + _htmlEscape(toVal) + "\"></label>" +
+      "<button class=\"btn\" type=\"submit\">Apply</button>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/reports\">Open sales report →</a>" +
+    "</form>";
+
+  // ---- conversion funnel + rate (pre-purchase, from the event stream).
+  var fn = view.funnel || { pdp_views: 0, cart_adds: 0, checkout_starts: 0, checkout_completes: 0, conversion_rate: 0 };
+  var ratePct = (Number(fn.conversion_rate) || 0) * 100;
+  var funnelStats =
+    "<section><h2>Browse-to-buy funnel</h2>" +
+      "<p class=\"meta\">Pre-purchase signal from the event stream — the sales report covers post-order status; this covers the path to it.</p>" +
+      "<div class=\"stat-grid\">" +
+        _statCard("Product views", String(fn.pdp_views || 0)) +
+        _statCard("Cart adds",     String(fn.cart_adds || 0)) +
+        _statCard("Checkouts started",  String(fn.checkout_starts || 0)) +
+        _statCard("Checkouts completed", String(fn.checkout_completes || 0)) +
+        _statCard("Conversion rate", ratePct.toFixed(2) + "%", true) +
+      "</div>" +
+    "</section>";
+
+  // ---- revenue-by-day trend sparkline (server-rendered SVG, same
+  // mechanism the dashboard uses).
+  var sparkBlock =
+    "<section><h2>Revenue trend</h2><div class=\"panel\">" +
+      _sparkSvg(view.by_day || [], cur) +
+    "</div></section>";
+
+  // ---- top SKUs by units sold (reports ranks top products by revenue;
+  // this ranks by units, the complementary view).
+  var topSkus = view.top_skus || [];
+  var skuRows = topSkus.length
+    ? topSkus.map(function (r) {
+        return "<tr><td>" + _htmlEscape(r.sku) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(String(r.units_sold)) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(_fmtSignedMoney(r.revenue_minor, r.currency)) + "</td></tr>";
+      }).join("")
+    : "<tr><td colspan=\"3\" class=\"empty\">No sales in this window.</td></tr>";
+  var skuBlock =
+    "<section><h2>Top SKUs by units sold</h2><div class=\"panel\">" +
+      _tableWrap("<table><thead><tr><th scope=\"col\">SKU</th><th scope=\"col\" class=\"num\">Units</th><th scope=\"col\" class=\"num\">Revenue</th></tr></thead><tbody>" + skuRows + "</tbody></table>") +
+    "</div></section>";
+
+  // ---- most-viewed products (event stream, pre-purchase).
+  var viewed = view.top_viewed_products || [];
+  var viewedRows = viewed.length
+    ? viewed.map(function (r) {
+        return "<tr><td>" + _htmlEscape(r.product_id) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(String(r.count)) + "</td></tr>";
+      }).join("")
+    : "<tr><td colspan=\"2\" class=\"empty\">No product views in this window.</td></tr>";
+
+  // ---- top search terms (event stream, pre-purchase).
+  var searches = view.top_search_terms || [];
+  var searchRows = searches.length
+    ? searches.map(function (r) {
+        return "<tr><td>" + _htmlEscape(r.search_q) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(String(r.count)) + "</td></tr>";
+      }).join("")
+    : "<tr><td colspan=\"2\" class=\"empty\">No searches in this window.</td></tr>";
+
+  var twoCol =
+    "<section><h2>Demand signal</h2><div class=\"two-col\">" +
+      "<div class=\"panel\">" +
+        "<h3 class=\"subhead\">Most-viewed products</h3>" +
+        _tableWrap("<table><thead><tr><th scope=\"col\">Product</th><th scope=\"col\" class=\"num\">Views</th></tr></thead><tbody>" + viewedRows + "</tbody></table>") +
+      "</div>" +
+      "<div class=\"panel\">" +
+        "<h3 class=\"subhead\">Top search terms</h3>" +
+        _tableWrap("<table><thead><tr><th scope=\"col\">Query</th><th scope=\"col\" class=\"num\">Searches</th></tr></thead><tbody>" + searchRows + "</tbody></table>") +
+      "</div>" +
+    "</div></section>";
+
+  var body =
+    "<section><h2>Analytics</h2>" + notice +
+      "<p class=\"meta\">Window: " + _htmlEscape(_fmtDate(view.from)) + " → " + _htmlEscape(_fmtDate(view.to)) + "</p>" +
+      "<p class=\"meta\">Product performance and pre-purchase behaviour. For order revenue totals, AOV, and refund rate see the <a href=\"/admin/reports\">sales report</a>.</p>" +
+      rangeForm +
+    "</section>" +
+    funnelStats + sparkBlock + skuBlock + twoCol;
+  return _renderAdminShell(opts.shop_name, "Analytics", body, "analytics", opts.nav_available);
+}
+
 // ---- admin web pages (login / landing / setup wizard) -------------------
 
 // Console nav — one entry per HTML console screen. `active` highlights
@@ -10847,6 +11098,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "inventory",    href: "/admin/inventory",    label: "Inventory" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
+  { key: "analytics",    href: "/admin/analytics",    label: "Analytics",    requires: "analytics" },
   { key: "audit",        href: "/admin/audit",        label: "Audit",        requires: "auditLog" },
   { key: "errors",       href: "/admin/errors",       label: "Errors",       requires: "errorLog" },
   { key: "exports",      href: "/admin/exports",      label: "Exports",      requires: "orderExport" },
@@ -17662,6 +17914,7 @@ module.exports = {
   mount:           mount,
   AUDIT_NAMESPACE: AUDIT_NAMESPACE,
   renderDashboard: renderDashboard,
+  renderAdminAnalytics:    renderAdminAnalytics,
   renderAdminLogin:        renderAdminLogin,
   renderAdminLanding:      renderAdminLanding,
   renderAdminSetup:        renderAdminSetup,

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.69",
+  "version": "0.3.71",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",