@blamejs/blamejs-shop 0.3.74 → 0.3.75

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.75 (2026-06-05) — **The analytics funnel records real shopper events — only with analytics consent.** The admin Analytics screen's browse-to-buy funnel, top search terms, and most-viewed products read an event stream that nothing previously wrote, so those tables stayed empty. The storefront now records five events — product view, search, add to cart, checkout started, order completed — strictly gated on the visitor's analytics consent: no consent decision means no recording, Do Not Track and Global Privacy Control suppress recording even after an accept-all, session identifiers are stored only as keyed hashes, and no name or email ever rides an event. Recording is fire-and-forget and can never affect a request. Edge-cached anonymous pages are deliberately not recorded — the cache stays shared and fast — so the funnel reflects consented, container-served traffic, and the dashboard's own copy now says exactly that. **Added:** *Consent-gated shopper event recording* — Product views, searches, cart adds, checkout starts, and completed orders record into the analytics event stream when — and only when — the session's consent grants the analytics category. The gate is the consent primitive's own server-side read: default-deny without a decision, policy-version-aware, and honoring Do Not Track and Sec-GPC over a stored acceptance. Events carry a hashed session key and bounded payloads, never personal data. The Analytics screen's funnel now states that its counts cover consented, container-served traffic; anonymous edge-cached page views are not tracked by design.
+
 - v0.3.74 (2026-06-05) — **The payment form matches the shop's dark theme.** The Stripe Payment Element and the express wallet buttons on the pay page previously rendered in Stripe's default light style — a white card floating on the shop's near-black page. The elements now use Stripe's night appearance recolored with the shop's own design tokens: violet accent on focus and selected tabs, the shop's charcoal input surfaces, soft ink text, and matching corner radii. The Apple Pay, Google Pay, and PayPal express buttons switch to their white and outline variants, which keep each brand's contrast rules legible on the dark card. No payment behavior changes; this is purely the appearance configuration on the existing elements. **Changed:** *Dark-themed payment elements* — The pay page's Stripe elements adopt the night appearance with the shop's design tokens — violet primary, charcoal surfaces, soft ink, ten-pixel radii, violet focus rings — and the express wallet buttons render in their white and outline variants sized to the page's controls. Inside Stripe's cross-origin frame the typeface falls back to the system stack; everything else mirrors the storefront's stylesheet tokens.
 
 - v0.3.73 (2026-06-05) — **Unlock codes are manageable from the Discounts screen, and coupon guessing is rate-capped.** Code-unlocked discount rules shipped with an API-only gap: the Discounts console had no field for the unlock code, so creating a code-gated rule required a raw API call. The create and edit forms now carry an optional Unlock code input — clearing it on edit reverts the rule to purely automatic — and the rule list and detail show which rules are code-gated; the screen's description covers both kinds. The cart's code-apply endpoint joins the tight per-address rate budget that already guards gift-card balance lookups, capping coupon-namespace guessing at the same rate. Also fixed: a failed confirmation-resend in the browser console now lands in the error log with a clean notice instead of an unrecorded failure, and the signed-in cart page resolves the shopper's destination once instead of twice per view. **Fixed:** *Unlock codes editable in the Discounts console* — The create and edit forms gain an optional Unlock code field, threaded through the same validation as the API. On edit, submitting the field blank explicitly clears the code (the rule becomes purely automatic again), while the inline quick-edit leaves it untouched. The rule list and the detail view display each rule's code, escaped, so code-gated rules are visible at a glance, and the screen copy now describes both automatic and code-unlocked rules. · *Coupon-code guessing joins the tight rate budget* — POST /cart/coupon now sits in the per-address, per-path rate budget alongside gift-card balance lookups — both accept guessable secrets and answer uniformly, so both deserve the same throttle. The pinned integration test sprays the endpoint and asserts the cap engages. · *Failed confirmation resends are captured and surfaced* — A mailer fault during a browser-initiated confirmation resend previously escaped both the error log and the screen. It now records to the error log and redirects back to the order with an honest failure notice; the API path captures identically. The signed-in cart view also drops a duplicated destination lookup per render.

package/lib/admin.js

@@ -11247,7 +11247,7 @@ function renderAdminAnalytics(opts) {
   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>" +
+      "<p class=\"meta\">Pre-purchase signal from the event stream — the sales report covers post-order status; this covers the path to it. Counts cover visitors who opted into analytics cookies and reflect container-served traffic: anonymous product and search pages are served from the edge cache and aren't recorded here.</p>" +
       "<div class=\"stat-grid\">" +
         _statCard("Product views", String(fn.pdp_views || 0)) +
         _statCard("Cart adds",     String(fn.cart_adds || 0)) +

package/lib/asset-manifest.json

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

package/lib/storefront.js

@@ -10114,6 +10114,53 @@ function mount(router, deps) {
     return lines.length;
   }
 
+  // Consent-gated browse→buy event recording (lib/analytics.js's event
+  // stream — the data behind /admin/analytics's funnel, top-search-terms,
+  // and most-viewed tables). Mounts only when deps.analytics is wired.
+  //
+  // GATE: a single byte is written ONLY when the visitor's stored decision
+  // opts the `analytics` category in. The gate is the SAME server-side read
+  // every other consent-gated behaviour uses — `_consentAllows(req,
+  // "analytics", _liveConsentPolicy())` — which reads the sealed
+  // `shop_consent` cookie, default-denies when there's no decision, and
+  // honours DNT / Sec-GPC as an implicit deny. No consent → nothing is
+  // recorded (no anonymised fallback row).
+  //
+  // PRIVACY: the only join key is the per-session `shop_sid` value, which
+  // recordEvent namespace-hashes before it touches the table (raw id never
+  // persists). No emails / names / customer ids are passed — session-scoped
+  // only. recordEvent itself refuses anything that looks like a raw email
+  // or IP, so a stray PII value loud-fails rather than leaking.
+  //
+  // EDGE NOTE: PDP + search GETs are edge-cached for anonymous visitors,
+  // and the edge cannot record per-visitor events (it has no DB write path
+  // and must stay cacheable) — it is deliberately NOT changed to. These
+  // events therefore fire on CONTAINER-served requests only, so the funnel
+  // reflects container-served traffic (a session-cookie-carrying visitor
+  // skips the edge cache, which is exactly the cohort whose consent we can
+  // read). The /admin/analytics screen copy states this honestly.
+  //
+  // HOT PATH: every call is fire-and-forget + drop-silent. We never await
+  // the write into the response and the whole body is wrapped so a recording
+  // failure (unmigrated table, write contention, validator throw) can never
+  // affect the request that triggered it.
+  function _recordAnalyticsEvent(req, fields, sidOverride) {
+    if (!deps.analytics) return;
+    try {
+      if (!_consentAllows(req, "analytics", _liveConsentPolicy())) return;
+      // `sidOverride` carries a session id the route just resolved/minted
+      // (e.g. cart-add creating a fresh session) — the request cookie can
+      // be stale or absent at that point.
+      var sid = sidOverride || null;
+      if (!sid) { try { sid = _readSidCookie(req); } catch (_e) { sid = null; } }
+      if (!sid) return;   // recordEvent needs a join key; no session → skip
+      var input = Object.assign({ session_id: sid }, fields);
+      // Fire-and-forget: kick the async write off and swallow any rejection
+      // so a slow / failing DB hop never delays or breaks the response.
+      Promise.resolve(deps.analytics.recordEvent(input)).catch(function () {});
+    } catch (_e) { /* drop-silent — analytics is supplementary to every request */ }
+  }
+
   // Resolve the active trust badges for a container-only placement and
   // concatenate each one's sanitized renderHtml. Fires an impression per
   // rendered badge (fire-and-forget — the counter is drop-silent on the hot
@@ -11717,6 +11764,13 @@ function mount(router, deps) {
       shop_name:       shopName,
       cart_count:      cartCount,
     }, _requestUrls(req), ccy)));
+    // Consent-gated funnel event — feeds the top-search-terms aggregate.
+    // Only a real (non-empty) query counts; the typed term is bounded to
+    // 200 chars above (recordEvent caps search_q at 256). Container-served
+    // only; fire-and-forget + drop-silent.
+    if (q.trim().length > 0) {
+      _recordAnalyticsEvent(req, { event_type: "search_query", search_q: q.trim() });
+    }
   });
 
   router.get("/products/:slug", async function (req, res) {
@@ -11886,6 +11940,10 @@ function mount(router, deps) {
       cart_count:     cartCount,
       theme:          theme,
     }, _requestUrls(req), ccy));
+    // Consent-gated funnel event — the top of the browse→buy funnel +
+    // most-viewed-products aggregate. Container-served only (anonymous PDPs
+    // are edge-cached and never reach here); fire-and-forget + drop-silent.
+    _recordAnalyticsEvent(req, { event_type: "pdp_view", product_id: product.id });
     _send(res, 200, html);
   });
 
@@ -12681,6 +12739,10 @@ function mount(router, deps) {
       var lines = await _repriceCartLines(rawLines);
       _setCheckoutCsp(res);
       _send(res, 200, renderCheckoutForm(await _checkoutRenderOpts(req, c, lines, null)));
+      // Consent-gated funnel event — the checkout_start step (the visitor
+      // reached the checkout form with a non-empty cart). Container-served
+      // (checkout is never edge-cached); fire-and-forget + drop-silent.
+      _recordAnalyticsEvent(req, { event_type: "checkout_start" });
     });
 
     router.post("/checkout", async function (req, res) {
@@ -12768,6 +12830,20 @@ function mount(router, deps) {
         // schedule land here. A failure must never roll back a paid order, so
         // each is its own try/catch (mirrors _recordAutoDiscounts).
         await _persistGiftAndPickup(c, result.order, body);
+        // Consent-gated funnel event — checkout_complete (an order was
+        // placed: the cart converted via checkout.confirm). Fires for both
+        // the gift-card-fully-paid path and the Stripe-intent path (the
+        // async pending→paid webhook carries no visitor session/consent, so
+        // it is deliberately NOT a recording point — the order placed here
+        // is the conversion the funnel counts). Container-served; fire-and-
+        // forget + drop-silent.
+        // A fully-covered order (gift card / loyalty pays it all) settles AT
+        // confirm; a Stripe-path order is only PENDING here — its completion
+        // records on the post-payment return (/orders/:id) instead, so the
+        // funnel never counts a payment the shopper abandoned at /pay.
+        if (!result.payment_intent) {
+          _recordAnalyticsEvent(req, { event_type: "checkout_complete", payload: { order_id: result.order.id } });
+        }
         // When a gift card fully covered the order there's no Stripe
         // intent — the order is already paid. Skip the pay-cookie +
         // pay page and land the customer straight on the confirmation.
@@ -13060,6 +13136,19 @@ function mount(router, deps) {
       if (o.customer_id && (!orderAuth || o.customer_id !== orderAuth.customer_id)) {
         return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
       }
+      // Stripe's post-payment return lands here with ?redirect_status=
+      // succeeded — the moment the payment actually settled client-side,
+      // with the shopper's session + consent readable. Record the funnel's
+      // checkout_complete HERE (the confirm POST only records fully-covered
+      // orders), then 303 to the param-less URL: the redirect both cleans
+      // the confirmation link and acts as the dedupe — a refresh or revisit
+      // hits the bare URL and records nothing.
+      if (req.query && req.query.redirect_status === "succeeded") {
+        _recordAnalyticsEvent(req, { event_type: "checkout_complete", payload: { order_id: o.id } });
+        res.status(303);
+        if (res.setHeader) res.setHeader("location", "/orders/" + o.id);
+        return res.end ? res.end() : res.send("");
+      }
       // Same variant_id → {product, hero_media} lookup pattern as the
       // cart route, applied to the order's frozen line items so the
       // post-checkout page shows what the customer bought visually.
@@ -17823,6 +17912,12 @@ function mount(router, deps) {
         back_href: "/cart", back_label: "Back to cart",
       }));
     }
+    // Consent-gated funnel event — the cart_add step of the browse→buy
+    // funnel. The added variant rides in the payload (the funnel counts by
+    // event_type; product_id is reserved for pdp_view's most-viewed
+    // aggregate). Fire-and-forget + drop-silent.
+    _recordAnalyticsEvent(req, { event_type: "cart_add", payload: { variant_id: variantId, qty: qty } },
+      resolved && resolved.cart && resolved.cart.session_id);
     // `?added=1` so the cart page can confirm the item landed (the page
     // surfaces an "Added to cart" status banner). Still a 303 so a refresh
     // re-issues the GET, not the POST.

package/package.json

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