@blamejs/blamejs-shop 0.3.68 → 0.3.70

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- 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.
 
 - v0.3.67 (2026-06-05) — **Digital orders no longer require a shipping address, and search ranking shrugs off malformed weights.** A cart containing only digital goods completes checkout since 0.3.63, but the shipping form still demanded a street address and city the order would never use. For an all-digital cart, the form now marks the address fields optional with an honest note — email stays required for the receipt and country for tax — and the backend enforces exactly the same relaxed set, while any value the shopper does supply is still format-validated. Carts with any shippable item keep the full requirements. Separately, the search ranker now skips a non-numeric weight in a hand-edited weight set instead of letting it poison every score into NaN and garble the result order; the edge and container rankers apply the identical filter, keeping their orders locked together even on malformed configuration. **Fixed:** *Digital-only carts check out without a street address* — When no line in the cart requires shipping, the checkout form renders the address block as optional — the required markers move off street and city, a note explains that a digital order ships nothing and country is kept for tax, and the backend requires exactly email, name, and country. Values the shopper supplies anyway are still format-validated, including the per-field error rendering. A cart with any physical item keeps the full address requirements, and a missing variant record counts as physical, so the relaxation can never trigger on incomplete data. · *Search ranking ignores non-numeric weights instead of corrupting the order* — A weight set carrying a non-numeric value — possible through a hand-edited database row — multiplied into every product's score as NaN, making the result order effectively random on the container while the edge filtered the bad weight and produced a different order. Both rankers now skip non-numeric weights identically, so a malformed entry degrades to "that signal contributes nothing" with edge and container orders staying byte-identical.

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 + 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.68",
+  "version": "0.3.70",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",

package/lib/auto-discount.js

@@ -172,9 +172,15 @@ var MAX_LIST_LIMIT            = 500;
 var MAX_BASIS_POINTS          = 10000;
 var MAX_MINOR_VALUE           = 1e12;
 var MAX_BOGO_QTY              = 1000;
+var MAX_UNLOCK_CODE_LEN       = 64;
 
 // Slug shape — alnum + dot + hyphen + underscore, alnum leading.
 var SLUG_RE         = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+// Unlock-code shape — the string a shopper types on the cart page to
+// unlock a code-gated rule. Same alnum + dot + hyphen + underscore family
+// the couponStacking primitive accepts so the two surfaces agree on what a
+// "code" is; refuses whitespace + control bytes.
+var UNLOCK_CODE_RE  = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 // Sku shape — same family the catalog primitive uses (alnum + dot +
 // hyphen + underscore + slash + colon), tight enough to refuse
 // whitespace + control bytes.
@@ -214,6 +220,7 @@ var ALLOWED_PATCH_COLUMNS = Object.freeze([
   "max_redemptions_total",
   "max_redemptions_per_customer",
   "active",
+  "unlock_code",
 ]);
 
 var b = require("./vendor/blamejs");
@@ -227,6 +234,17 @@ function _slug(s) {
   return s;
 }
 
+// Optional shopper-typed code that gates a rule. null/"" clears it (the
+// rule reverts to a pure automatic). A non-empty value must match the
+// code shape; stored as authored, matched case-insensitively at evaluate.
+function _unlockCode(s) {
+  if (s == null || s === "") return null;
+  if (typeof s !== "string" || !UNLOCK_CODE_RE.test(s)) {
+    throw new TypeError("autoDiscount: unlock_code must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/ (<= " + MAX_UNLOCK_CODE_LEN + " chars)");
+  }
+  return s;
+}
+
 function _title(s) {
   if (typeof s !== "string" || !s.length || s.length > MAX_TITLE_LEN) {
     throw new TypeError("autoDiscount: title must be a non-empty string <= " + MAX_TITLE_LEN + " chars");
@@ -493,6 +511,7 @@ function _hydrateRow(r) {
     active:                        r.active === 1 || r.active === true,
     archived_at:                   r.archived_at == null ? null : Number(r.archived_at),
     redemptions_used:              Number(r.redemptions_used) || 0,
+    unlock_code:                   r.unlock_code == null ? null : String(r.unlock_code),
     created_at:                    Number(r.created_at),
     updated_at:                    Number(r.updated_at),
   };
@@ -617,6 +636,7 @@ function create(opts) {
     }
     var maxTotal            = input.max_redemptions_total        == null ? null : _nonNegInt(input.max_redemptions_total,        "max_redemptions_total");
     var maxPerCustomer      = input.max_redemptions_per_customer == null ? null : _nonNegInt(input.max_redemptions_per_customer, "max_redemptions_per_customer");
+    var unlockCode          = _unlockCode(input.unlock_code);
 
     var existing = (await query(
       "SELECT slug FROM auto_discount_rules WHERE slug = ?1 LIMIT 1",
@@ -625,14 +645,28 @@ function create(opts) {
     if (existing) {
       throw new TypeError("autoDiscount.defineRule: slug " + JSON.stringify(slug) + " already exists -- use updateRule");
     }
+    // Reject a duplicate active code up front so the caller gets a clean
+    // TypeError rather than a raw UNIQUE-constraint bubble. The partial
+    // unique index is the authoritative guard; this is the friendly check.
+    if (unlockCode != null) {
+      var clash = (await query(
+        "SELECT slug FROM auto_discount_rules " +
+        "WHERE lower(unlock_code) = lower(?1) AND archived_at IS NULL LIMIT 1",
+        [unlockCode],
+      )).rows[0];
+      if (clash) {
+        throw new TypeError("autoDiscount.defineRule: unlock_code " + JSON.stringify(unlockCode) +
+          " already claimed by an active rule");
+      }
+    }
 
     var ts = _now();
     await query(
       "INSERT INTO auto_discount_rules (slug, title, trigger_json, value_json, applies_to_json, " +
       "customer_segment_in_json, exclusions_json, priority, starts_at, expires_at, " +
       "max_redemptions_total, max_redemptions_per_customer, active, archived_at, " +
-      "redemptions_used, created_at, updated_at) " +
-      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, 1, NULL, 0, ?13, ?13)",
+      "redemptions_used, unlock_code, created_at, updated_at) " +
+      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, 1, NULL, 0, ?13, ?14, ?14)",
       [
         slug,
         title,
@@ -646,6 +680,7 @@ function create(opts) {
         expiresAt,
         maxTotal,
         maxPerCustomer,
+        unlockCode,
         ts,
       ],
     );
@@ -746,6 +781,24 @@ function create(opts) {
       } else if (col === "max_redemptions_per_customer") {
         sets.push("max_redemptions_per_customer = ?" + idx);
         params.push(patch[col] == null ? null : _nonNegInt(patch[col], "max_redemptions_per_customer"));
+      } else if (col === "unlock_code") {
+        var nextCode = _unlockCode(patch[col]);
+        if (nextCode != null) {
+          // Don't let an update steal another active rule's code. A
+          // re-assert of THIS rule's own code is fine (the clash row is
+          // itself).
+          var codeClash = (await query(
+            "SELECT slug FROM auto_discount_rules " +
+            "WHERE lower(unlock_code) = lower(?1) AND archived_at IS NULL AND slug != ?2 LIMIT 1",
+            [nextCode, slug],
+          )).rows[0];
+          if (codeClash) {
+            throw new TypeError("autoDiscount.updateRule: unlock_code " + JSON.stringify(nextCode) +
+              " already claimed by an active rule");
+          }
+        }
+        sets.push("unlock_code = ?" + idx);
+        params.push(nextCode);
       } else /* active */ {
         sets.push("active = ?" + idx);
         params.push(_bool(patch[col], "active") ? 1 : 0);
@@ -789,6 +842,30 @@ function create(opts) {
     return await getRule(slug);
   }
 
+  // ---- ruleForCode ---------------------------------------------------
+
+  // Resolve a shopper-typed code to its active, code-gated rule (the row
+  // whose unlock_code matches case-insensitively, not archived). Returns
+  // the hydrated rule or null when no active rule claims the code. The
+  // cart-page coupon entry calls this to validate a typed code before
+  // persisting it — a non-empty result means "this is a real code"; null
+  // is the uniform "unknown code" answer. A malformed code (whitespace /
+  // control bytes / over-length) returns null rather than throwing, so the
+  // cart route gives one message for "doesn't match a rule" regardless of
+  // whether the input was garbage or simply unknown (no code-shape oracle).
+  async function ruleForCode(code) {
+    if (typeof code !== "string" || !UNLOCK_CODE_RE.test(code)) return null;
+    var r = (await query(
+      "SELECT * FROM auto_discount_rules " +
+      "WHERE lower(unlock_code) = lower(?1) AND active = 1 AND archived_at IS NULL " +
+      "  AND (starts_at IS NULL OR starts_at <= ?2) " +
+      "  AND (expires_at IS NULL OR expires_at > ?2) " +
+      "LIMIT 1",
+      [code, _now()],
+    )).rows[0];
+    return _hydrateRow(r);
+  }
+
   // ---- evaluate ------------------------------------------------------
 
   async function evaluate(input) {
@@ -800,6 +877,21 @@ function create(opts) {
     if (customerId != null && (typeof customerId !== "string" || !customerId.length)) {
       throw new TypeError("autoDiscount.evaluate: customer_id must be a non-empty string when provided");
     }
+    // Shopper-presented codes that unlock code-gated rules. A defensive
+    // request-shape reader: any non-string / malformed entry is dropped
+    // (never throws on the buy path), each kept entry is lower-cased into a
+    // lookup set so the code gate is a case-insensitive membership test. A
+    // pure-automatic rule (unlock_code IS NULL) ignores this set entirely.
+    var presentedCodes = Object.create(null);
+    if (input.codes != null) {
+      if (!Array.isArray(input.codes)) {
+        throw new TypeError("autoDiscount.evaluate: codes must be an array when provided");
+      }
+      for (var pc = 0; pc < input.codes.length; pc += 1) {
+        var raw = input.codes[pc];
+        if (typeof raw === "string" && raw.length) presentedCodes[raw.toLowerCase()] = true;
+      }
+    }
 
     var ts = _now();
     var rows = (await query(
@@ -839,6 +931,15 @@ function create(opts) {
     for (var ri = 0; ri < rows.length; ri += 1) {
       var rule = _hydrateRow(rows[ri]);
 
+      // 0. Code gate — a rule with an unlock_code is dormant until the
+      // shopper presents that code (case-insensitive). A pure-automatic
+      // rule (unlock_code IS NULL) skips this gate and fires on shape alone,
+      // so the legacy code-less behaviour is unchanged.
+      if (rule.unlock_code != null && !presentedCodes[rule.unlock_code.toLowerCase()]) {
+        skipped.push({ rule_slug: rule.slug, reason: "unlock_code_not_presented" });
+        continue;
+      }
+
       // 1. Total-redemption cap
       if (rule.max_redemptions_total != null && rule.redemptions_used >= rule.max_redemptions_total) {
         skipped.push({ rule_slug: rule.slug, reason: "max_redemptions_total_reached" });
@@ -1118,6 +1219,7 @@ function create(opts) {
     listRules:          listRules,
     updateRule:         updateRule,
     archiveRule:        archiveRule,
+    ruleForCode:        ruleForCode,
     evaluate:           evaluate,
     recordApplication:  recordApplication,
     metricsForRule:     metricsForRule,

package/lib/cart.js

@@ -35,6 +35,12 @@ var DEFAULT_TTL_MS  = C.TIME.days(30);
 var MAX_QTY         = 99999;
 var SESSION_ID_RE   = /^[A-Za-z0-9_-]{16,64}$/;   // shape-only; sealed-cookie origin
 var CURRENCY_RE     = /^[A-Z]{3}$/;
+// Discount-code shape — the string a shopper types on the cart page. Same
+// alnum + dot + hyphen + underscore family the autoDiscount unlock_code +
+// couponStacking primitives accept, so the three surfaces agree on what a
+// "code" is. Refuses whitespace + control bytes; caps length.
+var DISCOUNT_CODE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+var MAX_CODES_PER_CART = 16;
 
 // ---- validators ---------------------------------------------------------
 
@@ -62,6 +68,12 @@ function _status(s) {
     throw new TypeError("cart: status must be one of " + CART_STATUSES.join(", "));
   }
 }
+function _discountCode(s) {
+  if (typeof s !== "string" || !DISCOUNT_CODE_RE.test(s)) {
+    throw new TypeError("cart: discount code must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/ (≤ 64 chars)");
+  }
+  return s;
+}
 
 function _now() { return Date.now(); }
 
@@ -255,6 +267,27 @@ function create(opts) {
           );
         }
       }
+      // Carry the anonymous cart's applied discount codes onto the
+      // surviving cart so a code typed before sign-in isn't silently
+      // dropped on login. A code already on the destination cart wins
+      // (INSERT OR IGNORE against the UNIQUE (cart_id, code_lower)).
+      // Best-effort: the cart_discount_codes table may not be migrated on a
+      // given deploy (the coupon feature is additive), so a missing table
+      // degrades to "codes not carried" rather than failing the whole login
+      // merge — the line merge is the load-bearing part.
+      try {
+        var fromCodes = (await query(
+          "SELECT * FROM cart_discount_codes WHERE cart_id = ?1", [fromCartId],
+        )).rows;
+        for (var ci = 0; ci < fromCodes.length; ci += 1) {
+          var fc = fromCodes[ci];
+          await query(
+            "INSERT OR IGNORE INTO cart_discount_codes (id, cart_id, code, code_lower, rule_slug, applied_at) " +
+            "VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+            [b.uuid.v7(), toCartId, fc.code, fc.code_lower, fc.rule_slug, ts],
+          );
+        }
+      } catch (_e) { /* cart_discount_codes unmigrated — codes simply don't carry */ }
       await query("UPDATE carts SET status = 'abandoned', updated_at = ?1 WHERE id = ?2", [ts, fromCartId]);
       await query("UPDATE carts SET updated_at = ?1 WHERE id = ?2", [ts, toCartId]);
       return (await query("SELECT * FROM carts WHERE id = ?1", [toCartId])).rows[0];
@@ -283,6 +316,77 @@ function create(opts) {
       if (r.rowCount === 0) return null;
       return (await query("SELECT * FROM carts WHERE id = ?1", [cartId])).rows[0];
     },
+
+    // ---- applied discount codes ---------------------------------------
+    //
+    // A cart carries the discount codes a shopper applied on the cart page.
+    // The codes are stored as typed; `code_lower` is the case-insensitive
+    // key the UNIQUE (cart_id, code_lower) constraint + the rule lookup
+    // both use, so applying the same code twice is idempotent rather than
+    // stacking duplicate rows. These methods own ONLY the storage; the
+    // caller validates a code against the discount engine before applying
+    // (the cart never decides a code is valid — it persists what the
+    // storefront route accepted).
+
+    // Persist an accepted code on the cart. `rule_slug` snapshots which
+    // discount rule the code resolved to at apply time (audit convenience).
+    // Idempotent on (cart_id, code_lower): re-applying refreshes the
+    // snapshot + timestamp rather than erroring. Returns the stored row.
+    addDiscountCode: async function (cartId, code, ruleSlug) {
+      _uuid(cartId, "cart_id");
+      _discountCode(code);
+      var lower = code.toLowerCase();
+      var ts = _now();
+      var existing = (await query(
+        "SELECT id FROM cart_discount_codes WHERE cart_id = ?1 AND code_lower = ?2 LIMIT 1",
+        [cartId, lower],
+      )).rows[0];
+      if (existing) {
+        await query(
+          "UPDATE cart_discount_codes SET code = ?1, rule_slug = ?2, applied_at = ?3 WHERE id = ?4",
+          [code, ruleSlug == null ? null : String(ruleSlug), ts, existing.id],
+        );
+        return { id: existing.id, cart_id: cartId, code: code, code_lower: lower, rule_slug: ruleSlug == null ? null : String(ruleSlug), applied_at: ts };
+      }
+      // Cap the codes a single cart can carry so a scripted apply loop can't
+      // grow the row set unbounded.
+      var countRow = (await query(
+        "SELECT COUNT(*) AS n FROM cart_discount_codes WHERE cart_id = ?1",
+        [cartId],
+      )).rows[0] || {};
+      if ((Number(countRow.n) || 0) >= MAX_CODES_PER_CART) {
+        throw new TypeError("cart.addDiscountCode: cart already carries the maximum of " + MAX_CODES_PER_CART + " codes");
+      }
+      var id = b.uuid.v7();
+      await query(
+        "INSERT INTO cart_discount_codes (id, cart_id, code, code_lower, rule_slug, applied_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+        [id, cartId, code, lower, ruleSlug == null ? null : String(ruleSlug), ts],
+      );
+      return { id: id, cart_id: cartId, code: code, code_lower: lower, rule_slug: ruleSlug == null ? null : String(ruleSlug), applied_at: ts };
+    },
+
+    // The cart's applied codes, apply order. Returns the stored rows.
+    listDiscountCodes: async function (cartId) {
+      _uuid(cartId, "cart_id");
+      var r = await query(
+        "SELECT * FROM cart_discount_codes WHERE cart_id = ?1 ORDER BY applied_at ASC, id ASC",
+        [cartId],
+      );
+      return r.rows;
+    },
+
+    // Remove one applied code (case-insensitive). Returns true when a row
+    // was removed, false when the code wasn't on the cart.
+    removeDiscountCode: async function (cartId, code) {
+      _uuid(cartId, "cart_id");
+      _discountCode(code);
+      var r = await query(
+        "DELETE FROM cart_discount_codes WHERE cart_id = ?1 AND code_lower = ?2",
+        [cartId, code.toLowerCase()],
+      );
+      return Number(r.rowCount || 0) > 0;
+    },
   };
 }
 

package/lib/checkout.js

@@ -284,7 +284,7 @@ function create(deps) {
   // the subtotal — the order total can therefore never go negative,
   // and a customer can never be charged less than zero or credited
   // more than the cart is worth.
-  async function _resolveAutoDiscount(lines, subtotalMinor, customerId) {
+  async function _resolveAutoDiscount(lines, subtotalMinor, customerId, codes) {
     if (!autoDiscount || typeof autoDiscount.evaluate !== "function") {
       return { discount_minor: 0, applied: [] };
     }
@@ -304,6 +304,10 @@ function create(deps) {
           lines:          evalLines,
         },
         customer_id: customerId || undefined,
+        // Shopper-presented coupon codes unlock code-gated rules. Absent /
+        // empty leaves only the pure-automatic rules in play, so a quote
+        // with no codes is byte-identical to the pre-code behaviour.
+        codes: Array.isArray(codes) && codes.length ? codes : undefined,
       });
       var appliedRaw = res && Array.isArray(res.applied) ? res.applied : [];
       var total   = 0;
@@ -660,7 +664,7 @@ function create(deps) {
     // resolver clamps the result to [0, subtotal] and falls back to 0
     // on any failure, so the total math below is identical to the
     // un-wired flow whenever no rule applies.
-    var autoDisc = await _resolveAutoDiscount(lines, sub.amount_minor, c.customer_id || null);
+    var autoDisc = await _resolveAutoDiscount(lines, sub.amount_minor, c.customer_id || null, input.codes);
 
     var totals = pricing.totals(c, lines, {
       tax_minor:      taxRow.tax_minor,

package/lib/storefront.js

@@ -7186,11 +7186,51 @@ function _orderTimelineBlock(status) {
     "<ol class=\"order-timeline__steps\">" + steps + "</ol></div>";
 }
 
+// Cap on how many carrier events the per-shipment timeline renders. A
+// long-haul international parcel can accumulate dozens of scans; the
+// customer-facing panel shows the most recent MAX_SHIPMENT_TIMELINE
+// (newest-first) so the page stays bounded regardless of stream length.
+// getShipment hydrates the FULL event list (it has no LIMIT of its own),
+// so the bound is applied here at the render sink.
+var MAX_SHIPMENT_TIMELINE = 20;
+
+// Render one shipment's carrier-event timeline, newest-first. Events
+// arrive oldest-first from getShipment (occurred_at ASC, recorded_at ASC),
+// so the list is reversed, then capped at MAX_SHIPMENT_TIMELINE. Each row
+// shows the status, an optional carrier location, an optional operator-
+// recorded detail note, and the event time. status / location / detail are
+// carrier- or operator-supplied free text → escaped at the sink. Returns ""
+// for a shipment with no events so the panel falls back to the carrier line
+// alone (exactly what the pre-timeline block rendered).
+function _shipmentTimeline(events) {
+  if (!Array.isArray(events) || !events.length) return "";
+  var esc = b.template.escapeHtml;
+  // Newest-first: copy + reverse (never mutate the hydrated row's array),
+  // then bound the render.
+  var ordered = events.slice().reverse().slice(0, MAX_SHIPMENT_TIMELINE);
+  var rows = ordered.map(function (ev) {
+    var when = ev && ev.occurred_at != null
+      ? new Date(Number(ev.occurred_at)).toISOString().slice(0, 16).replace("T", " ")
+      : "";
+    var loc    = ev && ev.location ? String(ev.location) : "";
+    var detail = ev && ev.detail   ? String(ev.detail)   : "";
+    return "<li class=\"order-shipment__event\">" +
+      "<span class=\"order-shipment__event-status\">" + esc(String(ev && ev.status)) + "</span>" +
+      (loc    ? " <span class=\"order-shipment__event-loc\">" + esc(loc) + "</span>" : "") +
+      (detail ? " <span class=\"order-shipment__event-detail\">" + esc(detail) + "</span>" : "") +
+      (when ? " <time class=\"order-shipment__event-when\" datetime=\"" + esc(when) + "\">" + esc(when) + "</time>" : "") +
+      "</li>";
+  }).join("");
+  return "<ol class=\"order-shipment__timeline\">" + rows + "</ol>";
+}
+
 // Render the shipment + carrier-tracking panel from order-tracking's
 // listForOrder() rows. Each shipment shows its carrier, status, the
 // tracking number (linked to the carrier's public tracking URL when one
-// is known), and the most-recent carrier event. Empty/absent shipments
-// render nothing so a digital or not-yet-shipped order shows no panel.
+// is known), and the FULL carrier-event timeline newest-first (bounded by
+// MAX_SHIPMENT_TIMELINE). Empty/absent shipments render nothing so a digital
+// or not-yet-shipped order shows no panel; a shipment with no events yet
+// shows just the carrier + status line (the pre-timeline shape).
 function _orderTrackingBlock(shipments) {
   if (!Array.isArray(shipments) || !shipments.length) return "";
   var esc = b.template.escapeHtml;
@@ -7205,24 +7245,20 @@ function _orderTrackingBlock(shipments) {
             "\" rel=\"noopener nofollow\" target=\"_blank\">" + esc(String(s.tracking_number)) + " ↗</a>"
         : "<span class=\"order-shipment__track\">" + esc(String(s.tracking_number)) + "</span>";
     }
-    // Latest carrier event (events arrive oldest-first from listForOrder's
-    // getShipment ordering; the panel's per-shipment events array, when
-    // hydrated, is the same order — take the last).
+    // Full carrier-event timeline (newest-first, bounded). getShipment
+    // hydrates the per-shipment events array oldest-first; the timeline
+    // builder reverses + caps it. An eventless shipment renders no timeline,
+    // so the card is the carrier + status line alone — identical to the
+    // block before the timeline shipped.
     var events = Array.isArray(s.events) ? s.events : [];
-    var latest = events.length ? events[events.length - 1] : null;
-    var latestHtml = latest
-      ? "<p class=\"order-shipment__event\">" +
-          esc(String(latest.status)) +
-          (latest.location ? " &middot; " + esc(String(latest.location)) : "") +
-        "</p>"
-      : "";
+    var timelineHtml = _shipmentTimeline(events);
     return "<li class=\"order-shipment\">" +
       "<div class=\"order-shipment__head\">" +
         "<span class=\"order-shipment__carrier\">" + esc(String(carrier)) + "</span>" +
         "<span class=\"pdp__badge\">" + esc(String(s.status)) + "</span>" +
       "</div>" +
       (trackingHtml ? "<p class=\"order-shipment__tracking\">Tracking: " + trackingHtml + "</p>" : "") +
-      latestHtml +
+      timelineHtml +
       "</li>";
   }).join("");
   return "<div class=\"order-tracking-panel\">" +
@@ -7783,6 +7819,62 @@ function _cartGiftBlock(opts) {
     "</section>";
 }
 
+// The cart-page coupon-code entry (CONTAINER-ONLY — like the gift block, it
+// is only reached for a cart WITH lines, which the edge never renders; the
+// edge cart is the cookie-less empty shell, see [[storefront-dual-render]]).
+// The form posts to /cart/coupon, which is NOT an EDGE_POST_PATHS prefix, so
+// _injectCsrfFields tokens it automatically — same posture as /cart/gift
+// (the closest sibling). It offers a single code input + Apply, lists each
+// already-applied code with a Remove control, and shows an inline PRG notice
+// (applied / removed / uniform error). The code echo is operator/shopper
+// free text → escaped at the sink. Returns "" when the coupon surface isn't
+// wired (no discount engine), so a store without discounts shows nothing.
+function _cartCouponBlock(opts) {
+  if (!opts.coupon_enabled) return "";
+  var esc = b.template.escapeHtml;
+  var applied = Array.isArray(opts.applied_codes) ? opts.applied_codes : [];
+  // Inline PRG notice — applied / removed succeed with a confirmation; an
+  // error is the uniform "couldn't apply" (no oracle on why).
+  var notice = "";
+  if (opts.code_applied) {
+    notice = "<p class=\"cart-coupon__notice cart-coupon__notice--ok\" role=\"status\">Discount code applied.</p>";
+  } else if (opts.code_removed) {
+    notice = "<p class=\"cart-coupon__notice cart-coupon__notice--ok\" role=\"status\">Discount code removed.</p>";
+  } else if (opts.code_err) {
+    notice = "<p class=\"cart-coupon__notice cart-coupon__notice--err\" role=\"status\">That code can't be applied to this cart.</p>";
+  }
+  // Already-applied codes, each with a Remove form (the code rides in a
+  // hidden field; the value is escaped). Shopper-typed free text → esc().
+  var appliedHtml = "";
+  if (applied.length) {
+    var items = applied.map(function (r) {
+      var codeStr = String(r.code);
+      return "<li class=\"cart-coupon__applied-item\">" +
+        "<code class=\"cart-coupon__code\">" + esc(codeStr) + "</code>" +
+        "<form method=\"post\" action=\"/cart/coupon/remove\" class=\"cart-coupon__remove\">" +
+          "<input type=\"hidden\" name=\"code\" value=\"" + esc(codeStr) + "\">" +
+          "<button type=\"submit\" class=\"cart-line__btn\">Remove</button>" +
+        "</form>" +
+      "</li>";
+    }).join("");
+    appliedHtml = "<ul class=\"cart-coupon__applied\">" + items + "</ul>";
+  }
+  return "<section class=\"cart-coupon\">" +
+    "<details class=\"cart-coupon__details\"" + (applied.length || opts.code_err ? " open" : "") + ">" +
+      "<summary class=\"cart-coupon__summary\">Have a discount code?</summary>" +
+      notice +
+      appliedHtml +
+      "<form method=\"post\" action=\"/cart/coupon\" class=\"cart-coupon__form\">" +
+        "<label class=\"form-field\"><span>Discount code</span>" +
+          "<input type=\"text\" name=\"code\" autocomplete=\"off\" autocapitalize=\"characters\" " +
+            "spellcheck=\"false\" maxlength=\"64\" placeholder=\"Enter code\">" +
+        "</label>" +
+        "<button type=\"submit\" class=\"btn-secondary\">Apply code</button>" +
+      "</form>" +
+    "</details>" +
+    "</section>";
+}
+
 function renderCart(opts) {
   if (!opts) throw new TypeError("storefront.renderCart: opts required");
   var lines  = opts.lines  || [];
@@ -7932,6 +8024,11 @@ function renderCart(opts) {
     // free text already escaped; appending — not String.replace — so a `$`
     // in a wrap title can't trip dollar substitution).
     body = body + _cartGiftBlock(opts);
+    // CONTAINER-ONLY coupon-code entry, same placement + edge-safety
+    // reasoning as the gift block (reached only for a cart with lines; the
+    // code echo is escaped at the sink; appended, not String.replace'd, so a
+    // `$` in a typed code can't trip dollar substitution).
+    body = body + _cartCouponBlock(opts);
   }
   return _wrap(Object.assign({
     title:      "Cart",
@@ -11274,6 +11371,18 @@ function mount(router, deps) {
   // subtotal-only breakdown with tax/shipping flagged unresolved — the
   // subtotal is always honest, and the renderer labels the rest
   // "calculated at checkout" rather than fabricating a number.
+  // The discount codes a cart carries, as plain strings, for threading into
+  // checkout.confirm / checkout.quote. Drop-silent: an unmigrated
+  // cart_discount_codes table / un-wired method → [] (no codes, no
+  // code-gated discount), never a throw on the buy path.
+  async function _cartAppliedCodeStrings(cartId) {
+    if (typeof deps.cart.listDiscountCodes !== "function") return [];
+    try {
+      var rows = await deps.cart.listDiscountCodes(cartId);
+      return rows.map(function (r) { return r.code; });
+    } catch (_e) { return []; }
+  }
+
   async function _estimateCartTotals(req, c, lines, opts) {
     opts = opts || {};
     var base = pricing.totals(c, lines, {});   // subtotal-only, always valid
@@ -11299,6 +11408,10 @@ function mount(router, deps) {
       var quote = await deps.checkout.quote({
         cart_id:  c.id,
         ship_to:  dest.ship_to,
+        // Shopper-applied coupon codes so the estimate reflects a code-
+        // gated discount (the same codes checkout.confirm honours). Absent
+        // / empty → only pure-automatic rules, byte-identical to before.
+        codes:    Array.isArray(opts.codes) && opts.codes.length ? opts.codes : undefined,
       });
       var taxMinor = quote.totals.tax_minor;
       result.tax_resolved = quote.tax_rate_bps > 0 ||
@@ -12133,6 +12246,17 @@ function mount(router, deps) {
     var cartUrl = req.url ? new URL(req.url, "http://localhost") : null;
     var added = (req.query && req.query.added === "1") ||
       (cartUrl && cartUrl.searchParams.get("added") === "1") || false;
+    // Coupon-entry PRG outcomes (set by POST /cart/coupon[/remove]). One of
+    // applied / removed / err so the cart shows an inline notice. `?code_err`
+    // carries no detail beyond "couldn't apply" — a uniform message, no
+    // code-existence oracle.
+    function _cartQp(name) {
+      return (req.query && req.query[name] === "1") ||
+        (cartUrl && cartUrl.searchParams.get(name) === "1") || false;
+    }
+    var codeApplied = _cartQp("code_applied");
+    var codeRemoved = _cartQp("code_removed");
+    var codeErr     = _cartQp("code_err");
     if (!sid) {
       return _send(res, 200, renderCart(Object.assign({
         lines: [], totals: { subtotal_minor: 0, grand_total_minor: 0, currency: "USD" },
@@ -12153,12 +12277,23 @@ function mount(router, deps) {
     // Recomputed every render (idempotent); the stored snapshot is never
     // mutated, so changing a line's quantity re-prices it automatically.
     var lines = await _repriceCartLines(rawLines);
+    // Applied coupon codes — the strings the shopper entered on the cart
+    // page, persisted on the cart. Threaded into the totals estimate so a
+    // code-gated discount shows in the breakdown, and echoed in the coupon
+    // block (with a remove control). Drop-silent: an unmigrated
+    // cart_discount_codes table → no applied codes, no coupon discount.
+    var appliedCodes = [];
+    if (typeof deps.cart.listDiscountCodes === "function") {
+      try { appliedCodes = await deps.cart.listDiscountCodes(c.id); }
+      catch (_e) { appliedCodes = []; }
+    }
+    var appliedCodeStrings = appliedCodes.map(function (r) { return r.code; });
     // Real total before pay: compose the same tax + shipping primitives the
     // charge runs through (estimated against the shopper's saved/default
     // destination until they confirm an address at checkout). Falls back to
     // a subtotal-only breakdown — with tax/shipping labelled "calculated at
     // checkout" — when checkout isn't wired or no zone matches.
-    var totalsDetail = await _estimateCartTotals(req, c, lines, {});
+    var totalsDetail = await _estimateCartTotals(req, c, lines, { codes: appliedCodeStrings });
     var totals = totalsDetail.totals;
     // Truthful per-line stock state (out / low / ok) so the cart never
     // implies a sold-out line is buyable.
@@ -12218,6 +12353,15 @@ function mount(router, deps) {
       gift_wraps:      giftWraps,
       gift_wrap_in_cart: giftWrapInCart,
       added:           added,
+      // Coupon entry: surfaced only when the discount engine is wired (the
+      // POST routes mount on the same condition). `applied_codes` echoes the
+      // typed codes so each gets a remove control; the *_notice flags drive
+      // the inline PRG banner.
+      coupon_enabled:  !!(deps.autoDiscount && typeof deps.cart.listDiscountCodes === "function"),
+      applied_codes:   appliedCodes,
+      code_applied:    codeApplied,
+      code_removed:    codeRemoved,
+      code_err:        codeErr,
       shop_name:       shopName,
       theme:           theme,
     }, ccy)));
@@ -12590,12 +12734,16 @@ function mount(router, deps) {
         } else {
           defaultShipId = deps.default_shipping_id;
         }
+        var coCodes = await _cartAppliedCodeStrings(c.id);
         var result = await deps.checkout.confirm({
           cart_id:              c.id,
           ship_to:              shipTo,
           selected_shipping_id: defaultShipId || "std",
           customer:             { email: body.email, name: body.name },
           gift_card_code:       body.gift_card_code || undefined,
+          // Shopper-applied coupon codes — honoured at charge time so the
+          // order total matches the cart-page estimate.
+          codes:                coCodes.length ? coCodes : undefined,
           loyalty_redeem_points: _parseRedeemPoints(body.loyalty_redeem_points),
           idempotency_key:      "checkout:" + c.id + ":" + b.uuid.v7(),
         });
@@ -12740,12 +12888,14 @@ function mount(router, deps) {
         try {
           var defaultShipId = typeof deps.default_shipping_id === "function"
             ? await deps.default_shipping_id() : deps.default_shipping_id;
+          var ppCodes = await _cartAppliedCodeStrings(c.id);
           var created = await deps.checkout.createPaypalOrder({
             cart_id:              c.id,
             ship_to:              shipTo,
             selected_shipping_id: body.selected_shipping_id || defaultShipId || "std",
             customer:             { email: body.email, name: body.name },
             gift_card_code:       body.gift_card_code || undefined,
+            codes:                ppCodes.length ? ppCodes : undefined,
             idempotency_key:      "paypal:" + c.id + ":" + b.uuid.v7(),
             return_url:           body.return_url || undefined,
             cancel_url:           body.cancel_url || undefined,
@@ -17714,6 +17864,67 @@ function mount(router, deps) {
     });
   }
 
+  // POST /cart/coupon — apply a shopper-typed discount code to the cart.
+  // The code is validated server-side against the discount engine
+  // (autoDiscount.ruleForCode): it must resolve to an active, code-gated
+  // rule. An accepted code is persisted on the cart (cart.addDiscountCode)
+  // so the cart totals re-render with the rule's savings and
+  // checkout.confirm honours it. An unknown / malformed / un-applicable
+  // code bounces back with ?code_err=1 and a UNIFORM message — no oracle on
+  // whether the code exists. PRG: always a 303 to /cart. CSRF: /cart/coupon
+  // is NOT an EDGE_POST_PATHS prefix, so _injectCsrfFields tokens the form +
+  // the csrf gate checks it (same posture as /cart/gift). Mounts only when
+  // the discount engine is wired.
+  if (deps.autoDiscount && typeof deps.cart.addDiscountCode === "function") {
+    router.post("/cart/coupon", async function (req, res) {
+      var body = req.body || {};
+      var typed = typeof body.code === "string" ? body.code.trim() : "";
+      var dest = "/cart?code_err=1";
+      try {
+        var resolved = await _getOrCreateCart(req, res, "USD");
+        var cartId = resolved.cart.id;
+        // ruleForCode returns null for anything that isn't an active, code-
+        // gated rule (including a malformed code) — one uniform "no" answer.
+        var rule = typed ? await deps.autoDiscount.ruleForCode(typed) : null;
+        if (rule && rule.unlock_code) {
+          // Persist the code as the operator authored it (canonical casing),
+          // not as the shopper typed it, so the applied chip + the engine
+          // lookup agree.
+          await deps.cart.addDiscountCode(cartId, rule.unlock_code, rule.slug);
+          dest = "/cart?code_applied=1";
+        }
+      } catch (e) {
+        // A malformed code (TypeError from addDiscountCode's validator) or a
+        // bad cart shape is the same uniform error — never a 500 on the cart.
+        if (!(e instanceof TypeError)) throw e;
+        dest = "/cart?code_err=1";
+      }
+      res.status(303);
+      res.setHeader && res.setHeader("location", dest);
+      return res.end ? res.end() : res.send("");
+    });
+
+    // POST /cart/coupon/remove — drop one applied code. Idempotent: removing
+    // a code that isn't on the cart still lands on the removed notice (no
+    // oracle). Same CSRF posture as /cart/coupon.
+    router.post("/cart/coupon/remove", async function (req, res) {
+      var body = req.body || {};
+      var typed = typeof body.code === "string" ? body.code.trim() : "";
+      var dest = "/cart?code_removed=1";
+      try {
+        var resolved = await _getOrCreateCart(req, res, "USD");
+        if (typed) await deps.cart.removeDiscountCode(resolved.cart.id, typed);
+      } catch (e) {
+        if (!(e instanceof TypeError)) throw e;
+        // A malformed code can't be on the cart anyway — treat as removed.
+        dest = "/cart?code_removed=1";
+      }
+      res.status(303);
+      res.setHeader && res.setHeader("location", dest);
+      return res.end ? res.end() : res.send("");
+    });
+  }
+
   // POST /cart/bundle — add every member of a bundle to the cart at the
   // bundle price, atomically. Reads `bundle_sku` from the form body.
   // The price is recomputed server-side from the catalog + the bundle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.3.68",
+  "version": "0.3.70",
   "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": {