@blamejs/blamejs-shop 0.1.28 → 0.1.29

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- v0.1.29 (2026-05-26) — **Category navigation goes live — public browse pages for the storefront's category tree, with breadcrumbs and sub-category grids.** The category tree now has a customer-facing surface. A new /categories index lists the active top-level categories as a card grid, and a new /categories/<slug> page renders a single category: its title and optional description, a breadcrumb chain from the catalog root down to the current category, and a grid of the category's direct child sub-categories. Each page reads fresh against the active tree, so archived or unpublished categories drop out of every surface. An unknown, archived, or malformed slug returns a 404, and a category with no children renders a graceful empty state. The pages are linked from the site footer's Shop column. **Added:** *Category index at /categories* — A public page listing the active top-level categories as a card grid, each card carrying the category's title, optional description, and optional hero image, and linking into its browse page. Archived and unpublished categories are excluded. Linked from the site footer's Shop column. · *Category browse page at /categories/<slug>* — A public page for a single category showing its title and optional description, a breadcrumb chain from the catalog root down to the current category (each ancestor linked, the current category shown as plain text), an optional hero image, and a card grid of the category's direct child sub-categories. A category with no children renders a graceful empty state. An unknown, archived, or malformed slug returns a 404.
+
 - v0.1.28 (2026-05-25) — **Refer-a-friend goes live — a shareable link, attributed signups, and conversions recorded when a referred friend's first order is paid.** The referrals ledger now has a customer-facing surface. A new /account/referrals page gives the signed-in customer a personal referral code, an absolute shareable link, the list of friends they've referred with each one's funnel stage, and an in-account top-referrer leaderboard. A new /r/<code> landing captures an inbound referral: it sets a short-lived sealed first-party cookie naming the code and sends the visitor home. When that visitor creates an account — by passkey, Google, or Apple — the new customer is attributed to the referrer, first-touch, with a self-referral guard so a code can never refer its own owner. When a referred customer's first order reaches paid, the order primitive marks that referral converted and bumps the referrer's count (the leaderboard key) — automatically, off the request path, and recorded once per order so a re-delivered payment webhook can't double-count. Issuing the actual reward (a gift card, store credit, or loyalty points — operator's choice) stays an explicit operator action through the referrals reward API, so the payout instrument and any fraud review are the operator's to control. **Added:** *Customer referrals page at /account/referrals* — A login-gated page showing the customer's referral code and an absolute shareable link (derived from the configured shop origin, falling back to the request host), the count of friends invited / joined / converted, the list of referred friends with each one's funnel stage (invited → visited → joined → converted) and dates, and an in-account top-referrer leaderboard. The friend list carries no personal data — referred emails are stored hash-only — and the leaderboard shows rank plus initials only, never names, emails, or account ids, with the signed-in customer's own row marked "You". Linked from the account dashboard as "Refer a friend". A customer with no code yet sees a one-click create control; a customer with one already gets the same page (creating is idempotent). · *Referral attribution landing at /r/<code>* — A public landing that captures an inbound referral: it sets a short-lived (30-day) sealed, first-party cookie naming the code, records the visit, and redirects the visitor to the home page. Attribution is first-touch — the first referral link a visitor follows wins, and a later link doesn't overwrite it. An unknown, malformed, or disabled code is silently ignored: the visitor still lands on the home page with no error and no cookie, so the route is never a code-existence oracle. · *Signups attributed to the referrer* — When a visitor who arrived through a referral link creates an account — passkey, Sign in with Google, or Sign in with Apple — the new customer is attributed to the referrer named in the referral cookie. A self-referral (the code belongs to the new account) is refused, a customer is attributed only once, and an existing customer signing in through Google or Apple is never attributed (only a genuinely new account is). Attribution is best-effort and never blocks account creation; the referral cookie is cleared after one signup so a stale link can't attribute a later one. · *Referral conversion recorded when a referred friend's first order is paid* — When a referred customer's first order reaches paid, the order primitive marks that referral converted and bumps the referrer's referral count (the leaderboard key). The update rides every paid path (card, wallet, PayPal, gift-card-covered), runs fire-and-forget off the request path, and is recorded once per order so a re-delivered payment webhook collapses onto a single conversion. Only orders carrying a customer account qualify; a guest order records nothing, and a customer's second and later orders don't re-trigger it. Issuing the payout itself — a gift card, store credit, or loyalty points — is a separate operator action through the referrals reward API, so the operator controls the reward instrument and can review before paying out.
 
 - v0.1.27 (2026-05-25) — **Loyalty rewards go live — points earned on purchase, viewed in the account, and redeemed at checkout.** The loyalty points ledger now has a customer-facing surface. A new /account/loyalty page shows the signed-in customer's balance, tier, and earn/redeem activity, explains how points are earned, and lists the reward catalog with a one-click redeem. Paid orders award points automatically: the order primitive fans its paid transition into the earn rules (per-dollar-spent + per-order), fire-and-forget and deduplicated so a re-delivered payment webhook never double-credits. At checkout, a signed-in customer can spend points for a storefront credit against the order total — capped at the order's value and the balance, recorded once, with the same atomic double-spend guard the gift-card credit uses. **Added:** *Customer rewards page at /account/loyalty* — A login-gated page showing the points balance, current tier, lifetime points, and the cash value of the balance; how points are earned (the active earn rules in plain language); the reward catalog with a Redeem control per reward (disabled when the balance is short); the customer's past redemptions; and the earn/redeem ledger, paginated newest-first. Linked from the account dashboard as "Rewards". A redeem that the customer can't complete (not enough points, reward unavailable, per-customer limit reached) re-renders the page with the reason rather than erroring; a malformed history cursor degrades to the first page. · *Points earned automatically on paid orders* — When an order reaches paid, the configured earn rules award points to the customer's balance — per dollar of order subtotal and a flat per-order bonus, whichever rules the operator has defined. The award rides the order's paid transition (so every paid path — card, PayPal, gift-card-covered, admin — earns), runs fire-and-forget off the request path, and is keyed to the order so a re-delivered payment webhook collapses onto a single award instead of double-crediting. Guest orders (no customer account) earn nothing, by design. · *Redeem points at checkout as a credit* — A signed-in customer with a balance sees a "Redeem loyalty points" field on the checkout form. The points are valued via the ledger's redemption ratio (100 points = $1 by default), capped at the order total so the credit never exceeds what the order is worth, and the credit reduces the amount due. The order still records the full grand total it owed; the points are debited once, after the order row exists, behind the same balance-guarded SQL decrement that prevents a double-spend. Points worth more than the order spend only what the granted credit is worth — the surplus stays in the balance. A request for more points than the balance, or from a guest cart, is refused with a clean re-prompt. A points credit stacks with a gift-card credit; together they can pay an order in full with no card charge.

package/README.md

@@ -73,6 +73,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/recently-viewed.js`** | Signed-in customer browse history. A product-page visit records the view server-side against the customer's account (drop-silent — never blocks the page); `/account/recently-viewed` lists them newest-first as a grid with a Clear-history control. De-duped + capped per customer, archived products drop out, login-gated. Guest/session history is opt-in (a client beacon) and not shipped — the lib's `forSession` + `merge` support it. |
 | **`lib/recommendations.js`** | Product-recommendation engine. Operator-curated override pins first (`setOverride` — "when viewing A, show B", kind-scoped + weight-ordered), then a signal-based fallback: co-purchase (products bought in the same orders), category-popular, and in-stock-random filler. `recommendForProduct` / `recommendForCart` / `recommendForCustomer` / `recommendForCategory` each return renderable picks (active + in-stock, source product excluded). The order confirmation page (`/orders/:id`) renders a "Customers also bought" rail from it — best-effort, anchored on the order's items, excluding what was just bought. |
 | **`lib/collections.js`** | Curated + smart product groupings. `GET /collections` lists the shop's active collections; `GET /collections/:slug` renders the grid — manual collections list hand-picked members, smart collections evaluate stored rules against the active catalog and apply the collection's sort strategy. Each product resolves fresh, so archived products drop out. Public, no sign-in; a bad or unknown slug is a 404 (never a 500). Linked from the footer on every page. |
+| **`lib/category-navigation.js`** | Hierarchical category tree surfaced as public browse pages. `GET /categories` lists the active top-level categories as a card grid; `GET /categories/:slug` renders one category — its title and optional description, a breadcrumb chain from the catalog root down to the current category, an optional hero image, and a grid of the category's direct child sub-categories. Each page reads fresh against the active tree, so archived / unpublished categories drop out of every surface. Public, no sign-in; an unknown, archived, or malformed slug is a 404 (never a 500), and a category with no children renders a graceful empty state. Linked from the footer on every page. The tree itself (define / move / reorder / archive, with cycle defense bounded by `MAX_TREE_DEPTH`) is operator-managed through the primitive's write API. |
 | **`lib/subscriptions.js`** | Stripe-backed recurring billing — `subscription_plans` (interval / amount / trial) + `subscriptions` (mirrors Stripe's object byte-for-byte). `subscriptions.create` POSTs to Stripe via the payment dep, then persists the returned object locally. `handleStripeEvent` replays `customer.subscription.*` events into the local row so the shop has an authoritative view without round-tripping. Customers view + cancel their own subscriptions at `/account/subscriptions` (ownership-checked; cancel mounts when the payment handle is wired). |
 | **`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. |
@@ -109,6 +110,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 - `migrations-d1/0163_loyalty_earn_rules.sql` — per-event earn rules + dedup-keyed award log
 - `migrations-d1/0025_referrals.sql` — referral codes (one active per customer) + invitation funnel (hash-only referred email)
 - `migrations-d1/0182_referral_leaderboard.sql` — referral tier thresholds (singleton config) + tiered-bonus payout log
+- `migrations-d1/0201_category_navigation.sql` — hierarchical category tree (self-referential parent_slug, sibling position, soft-delete tombstone)
 
 ### Demo seed
 

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.28",
+  "version": "0.1.29",
   "assets": {
     "css/admin.css": "sha384-rvjL1QySBgNJGEUDusbbMCkL3fsjmzcwUvTp9pljo/0Nn/lErxq2AbY8EYvDF9Ch",
     "css/main.css": "sha384-qBY97FWZDGOploZRppwrDi0A/+R4R3iCFtyS1dfrAlqHNEPluPmY0R3HB9cJntyV",

package/lib/storefront.js

@@ -162,6 +162,7 @@ var LAYOUT =
   "        <ul>\n" +
   "          <li><a href=\"/\">All products</a></li>\n" +
   "          <li><a href=\"/collections\">Collections</a></li>\n" +
+  "          <li><a href=\"/categories\">Categories</a></li>\n" +
   "          <li><a href=\"/?sort=new\">New arrivals</a></li>\n" +
   "          <li><a href=\"/?sort=sale\">On sale</a></li>\n" +
   "          <li><a href=\"/cart\">Cart</a></li>\n" +
@@ -1265,6 +1266,123 @@ function renderCollection(opts) {
   });
 }
 
+// Storefront category index — the top-level category tree. Each card
+// links into a category browse page. Reuses the collection-index card
+// shell (same visual contract) so no new CSS ships. `opts.categories`
+// is the hydrated [{ slug, title, description, hero_image_url }] list of
+// active top-level categories (archived rows are dropped by the lib).
+function renderCategoryIndex(opts) {
+  var esc = b.template.escapeHtml;
+  var cats = opts.categories || [];
+  var cardsHtml = "";
+  for (var i = 0; i < cats.length; i += 1) {
+    var c = cats[i];
+    var media = c.hero_image_url
+      ? "<figure class=\"collection-index-card__media\"><img src=\"" + esc(_categoryHeroSrc(c.hero_image_url, opts.asset_prefix)) + "\" alt=\"" + esc(c.title) + "\" loading=\"lazy\"></figure>"
+      : "<figure class=\"collection-index-card__media collection-index-card__media--empty\" aria-hidden=\"true\"></figure>";
+    cardsHtml +=
+      "<a class=\"collection-index-card\" href=\"/categories/" + esc(c.slug) + "\">" +
+        media +
+        "<div class=\"collection-index-card__meta\">" +
+          "<h2 class=\"collection-index-card__title\">" + esc(c.title) + "</h2>" +
+          (c.description ? "<p class=\"collection-index-card__desc\">" + esc(c.description) + "</p>" : "") +
+        "</div>" +
+      "</a>";
+  }
+  var inner = cardsHtml
+    ? "<div class=\"collection-index-grid\">" + cardsHtml + "</div>"
+    : "<p class=\"collection-empty\">No categories yet.</p>";
+  var body =
+    "<section class=\"collection-index\">" +
+      "<header class=\"section-head\"><p class=\"eyebrow\">Browse</p>" +
+        "<h1 class=\"section-head__title\">Categories</h1></header>" +
+      inner +
+    "</section>";
+  return _wrap({
+    title: "Categories", shop_name: opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count, theme_css: opts.theme_css, body: body,
+  });
+}
+
+// A single category's page — breadcrumb (root -> current), title,
+// optional description + hero, and a grid of the category's direct
+// child sub-categories. `opts.breadcrumbs` is the root->current chain
+// (the last entry is the current category, rendered as plain text);
+// `opts.children` is the hydrated direct-child list (empty -> graceful
+// empty state). Reuses the collection-page + collection-index card
+// shells so no new CSS ships.
+function renderCategory(opts) {
+  var esc = b.template.escapeHtml;
+  var cat = opts.category;
+  var crumbs = opts.breadcrumbs || [];
+  var children = opts.children || [];
+
+  var crumbHtml = "<li><a href=\"/\">Shop</a></li><li><a href=\"/categories\">Categories</a></li>";
+  for (var ci = 0; ci < crumbs.length; ci += 1) {
+    var bc = crumbs[ci];
+    if (ci === crumbs.length - 1) {
+      crumbHtml += "<li aria-current=\"page\">" + esc(bc.title) + "</li>";
+    } else {
+      crumbHtml += "<li><a href=\"/categories/" + esc(bc.slug) + "\">" + esc(bc.title) + "</a></li>";
+    }
+  }
+
+  // Hero reuses the collection-index card media shell (aspect-ratio +
+  // object-fit cover) so no new CSS ships; it's a standalone figure
+  // rather than a card link here.
+  var hero = cat.hero_image_url
+    ? "<figure class=\"collection-index-card__media\"><img src=\"" + esc(_categoryHeroSrc(cat.hero_image_url, opts.asset_prefix)) + "\" alt=\"" + esc(cat.title) + "\"></figure>"
+    : "";
+
+  var cardsHtml = "";
+  for (var i = 0; i < children.length; i += 1) {
+    var ch = children[i];
+    var media = ch.hero_image_url
+      ? "<figure class=\"collection-index-card__media\"><img src=\"" + esc(_categoryHeroSrc(ch.hero_image_url, opts.asset_prefix)) + "\" alt=\"" + esc(ch.title) + "\" loading=\"lazy\"></figure>"
+      : "<figure class=\"collection-index-card__media collection-index-card__media--empty\" aria-hidden=\"true\"></figure>";
+    cardsHtml +=
+      "<a class=\"collection-index-card\" href=\"/categories/" + esc(ch.slug) + "\">" +
+        media +
+        "<div class=\"collection-index-card__meta\">" +
+          "<h2 class=\"collection-index-card__title\">" + esc(ch.title) + "</h2>" +
+          (ch.description ? "<p class=\"collection-index-card__desc\">" + esc(ch.description) + "</p>" : "") +
+        "</div>" +
+      "</a>";
+  }
+  var grid = cardsHtml
+    ? "<div class=\"collection-index-grid\">" + cardsHtml + "</div>"
+    : "<p class=\"collection-empty\">No sub-categories here yet.</p>";
+
+  var body =
+    "<section class=\"collection-page\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        crumbHtml +
+      "</ol></nav>" +
+      "<header class=\"collection-page__head\">" +
+        "<h1 class=\"collection-page__title\">" + esc(cat.title) + "</h1>" +
+        (cat.description ? "<p class=\"collection-page__desc\">" + esc(cat.description) + "</p>" : "") +
+      "</header>" +
+      hero +
+      grid +
+    "</section>";
+  return _wrap({
+    title: cat.title, shop_name: opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count, theme_css: opts.theme_css, body: body,
+  });
+}
+
+// Resolve a category hero_image_url into a renderable src. The lib gates
+// hero_image_url to https:// OR a /-rooted absolute path at write time,
+// so an absolute https URL or a /-rooted path is used as-is; any other
+// value (a bare R2 key) is prefixed with the card asset prefix the same
+// way collection hero media resolves.
+function _categoryHeroSrc(url, assetPrefix) {
+  if (typeof url !== "string" || !url.length) return "";
+  if (url.charCodeAt(0) === 47 /* "/" */) return url;
+  if (/^https:\/\//i.test(url)) return url;
+  return (assetPrefix || "/assets/") + url;
+}
+
 // Account "Recently viewed" page — a newest-first grid of products the
 // signed-in customer has opened, reusing the standard product card.
 // `opts.products` is a resolved [{ slug, title, price, image_url,
@@ -3356,6 +3474,60 @@ function mount(router, deps) {
     });
   }
 
+  // Category navigation — the hierarchical category tree surfaced as
+  // public browse pages. The index lists the top-level categories; each
+  // category page renders its breadcrumb chain + direct child sub-
+  // categories. Mounted when the categoryNavigation primitive is wired.
+  if (deps.categoryNavigation) {
+    router.get("/categories", async function (req, res) {
+      // Top-level categories only (parent_slug omitted). The lib drops
+      // archived rows from every read, so the index is fresh against the
+      // active tree.
+      var cats = await deps.categoryNavigation.categoriesByParent({});
+      var active = [];
+      for (var i = 0; i < cats.length; i += 1) {
+        if (cats[i].active) active.push(cats[i]);
+      }
+      var cartCount = await _cartCountForReq(req);
+      _send(res, 200, renderCategoryIndex({
+        categories: active, shop_name: shopName, cart_count: cartCount, asset_prefix: _cardAssetPrefix,
+      }));
+    });
+
+    router.get("/categories/:slug", async function (req, res) {
+      var slug = req.params && req.params.slug;
+      // getCategory() / breadcrumbsFor() / categoriesByParent() throw a
+      // TypeError on a malformed slug shape (the primitive validates the
+      // slug regex). A bad path segment, an unknown slug, or an archived
+      // category is a 404, not a 500 — this is a defensive request-shape
+      // reader.
+      var cat, crumbs, children;
+      try {
+        cat = slug ? await deps.categoryNavigation.getCategory(slug) : null;
+        if (!cat || !cat.active) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+        crumbs = await deps.categoryNavigation.breadcrumbsFor({ slug: slug });
+        children = await deps.categoryNavigation.categoriesByParent({ parent_slug: slug });
+      } catch (e) {
+        if (e instanceof TypeError) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+        // A CATEGORY_NOT_FOUND from breadcrumbsFor / categoriesByParent
+        // (e.g. the row was archived between reads) is also a 404.
+        if (e && e.code === "CATEGORY_NOT_FOUND") return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+        throw e;
+      }
+      // Only surface active sub-categories (the lib already drops archived
+      // rows; this also hides operator-unpublished ones).
+      var activeChildren = [];
+      for (var i = 0; i < children.length; i += 1) {
+        if (children[i].active) activeChildren.push(children[i]);
+      }
+      var cartCount = await _cartCountForReq(req);
+      _send(res, 200, renderCategory({
+        category: cat, breadcrumbs: crumbs, children: activeChildren,
+        shop_name: shopName, cart_count: cartCount, asset_prefix: _cardAssetPrefix,
+      }));
+    });
+  }
+
   router.get("/cart", async function (req, res) {
     var sid = _readSidCookie(req);
     if (!sid) {

package/package.json

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