@blamejs/blamejs-shop 0.4.53 → 0.4.54

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.54 (2026-06-14) — **The rewards page now shows what a customer's loyalty tier includes and their progress to the next tier.** A signed-in customer's rewards page now shows their current loyalty tier, how many points remain to reach the next tier (with a progress bar), and the perks their tier includes. Operators author the per-tier perks from a new console screen — free shipping over a threshold, a percent discount, early or exclusive access, priority support, or a birthday bonus. The perks are presented to customers as what their tier includes and that the shop honours them; they are not applied automatically at checkout, so the wording never promises an automatic discount the store doesn't yet apply. No migration to apply. **Added:** *Loyalty tier perks and next-tier progress on the rewards page* — The /account rewards page gains two sections: a tier-progress panel naming the customer's current tier and the points still needed to reach the next one (with a labelled progress bar, or a top-tier acknowledgement), and a list of the perks the customer's tier includes. The tier is resolved from the customer's own loyalty balance; the perks come from the operator-authored tier-benefit definitions. The perks are framed as tier inclusions the shop honours — the copy directs the customer to ask at checkout or contact support to have a perk applied — rather than implying an automatic discount. · *Tier-benefit authoring in the loyalty console* — A new admin screen under the loyalty console lets operators define the perks each tier includes: free shipping (optionally over a minimum order), a percent discount, early access (hours before general release), priority support (an SLA in minutes), exclusive access to a collection, or a birthday bonus. Benefits are created and archived from the screen, each change recorded to the audit trail under the loyalty permission. The screen states that these perks are shown to customers as tier inclusions the shop honours and are not applied automatically at checkout.
+
 - v0.4.53 (2026-06-14) — **A signed-in customer's cookie choices and newsletter unsubscribe now land in the durable consent record.** The durable, per-customer consent ledger — the GDPR Article 7(1) record a controller keeps to demonstrate consent — is now written from the real consent events for identified customers. When a signed-in customer saves their cookie preferences, each category (functional, analytics, marketing, preferences) is recorded as granted or withdrawn in the durable ledger, alongside the existing session-level cookie record. When a newsletter unsubscribe resolves to a customer account, a marketing-email withdrawal is recorded there too. Anonymous visitors and email-only subscribers with no account are unchanged — their cookie choice stays in the session-level store and their unsubscribe in the email-suppression list, neither of which can be customer-keyed. The ledger writes are best-effort and never block the banner save or the unsubscribe. No migration to apply. **Added:** *Cookie-banner choices recorded in the durable consent ledger for signed-in customers* — When an authenticated customer saves their cookie preferences, each of the four optional categories is now mirrored into the durable per-customer consent ledger as a granted or withdrawn decision (source: cookie banner), so a supervisory-authority audit shows the identified individual's choice and not only the session-keyed record. The durable record reflects the consent the storefront actually enforces: a browser-level opt-out signal (Global Privacy Control or Do Not Track) collapses the analytics and marketing categories to withdrawn even if their boxes were ticked, matching the runtime gate, so the record never claims consent the app refuses to honor. The customer is resolved from the existing signed-in session (a revoked session is treated as signed-out); anonymous visitors carry no account and are written only to the session-level cookie record as before. · *Newsletter unsubscribe records a marketing withdrawal for account holders* — A newsletter unsubscribe that resolves to a customer account now records a marketing-email withdrawal in the durable consent ledger. The unsubscribed address is matched to an account by its hashed form; an email-only subscriber with no account is handled by the existing email-suppression path only, since the durable ledger is keyed by customer. The existing unsubscribe behavior — the suppression entry and the one-click RFC 8058 flow — is unchanged.
 
 - v0.4.52 (2026-06-14) — **Consent records now carry the GDPR Article 6 lawful basis they rest on.** Each decision in the durable per-customer consent ledger now records the GDPR Article 6(1) lawful basis it is processed under — consent, contract, legal obligation, vital interests, public task, or legitimate interests — alongside what was decided and when. The basis defaults from the consent kind (cookie categories, marketing email/SMS, and data-sharing opt-ins are all consent-based), and a caller may pass an explicit, validated basis for a record that rests on another. The basis is surfaced in the subject-access and supervisory-authority exports, so a consent audit now shows not just the decision but the legal ground for it. A migration adds a nullable, constrained lawful_basis column; pre-existing rows keep a null basis rather than being assigned one retroactively. Apply the pending migration on upgrade. **Added:** *Lawful basis on consent-ledger records* — The consent ledger now stamps the GDPR Article 6(1) lawful basis on every recorded decision. The basis defaults from the consent kind — every category the ledger tracks (cookie functional/analytics/marketing/preferences, marketing email, marketing SMS, partner and analytics data-sharing, and general data processing) is consent-based — and an explicit basis can be supplied and is validated against the six Article 6(1) values. Withdrawal records carry the same basis as the grant they revoke. The basis is included in the subject-access export (CSV and JSON) and the jurisdiction bulk export, so a consent audit shows the legal ground each decision rests on. **Changed:** *Migration: lawful_basis column on consent_ledger* — A new migration adds a nullable lawful_basis column to consent_ledger, constrained to the six Article 6(1) bases. The column is nullable and the constraint applies only to rows written after the migration, so existing records keep a null basis (not retroactively assigned) while every new record carries one. Apply the pending migration on upgrade.

package/lib/admin.js

@@ -36,6 +36,7 @@ var collectionsModule = require("./collections");
 var quantityDiscountsModule = require("./quantity-discounts");
 var loyaltyEarnRulesModule = require("./loyalty-earn-rules");
 var loyaltyRedemptionModule = require("./loyalty-redemption");
+var tierBenefitsModule = require("./tier-benefits");
 var trustBadgesModule = require("./trust-badges");
 var cartModule = require("./cart");   // ABANDONED_* window/limit constants for the /admin/carts console
 var inventoryWriteoffsModule = require("./inventory-writeoffs");   // WRITEOFF_REASONS enum for the /admin/inventory/writeoffs console
@@ -13174,6 +13175,11 @@ function mount(router, deps) {
         try { rewards = await loyaltyRedemption.listRewards({ limit: 200 }); }
         catch (_e) { rewards = []; }
       }
+      var tierBenefitRows = null;
+      if (deps.tierBenefits) {
+        try { tierBenefitRows = await deps.tierBenefits.listBenefits({ limit: 200 }); }
+        catch (_e) { tierBenefitRows = []; }
+      }
       return Object.assign({
         shop_name:        deps.shop_name,
         nav_available:    navAvailable,
@@ -13185,8 +13191,10 @@ function mount(router, deps) {
         reward_kinds:     loyaltyRedemptionModule.KINDS,
         earn_rules:       earnRules,
         rewards:          rewards,
+        tier_benefits:    tierBenefitRows,
         can_manage_rules:   !!loyaltyEarnRules,
         can_manage_rewards: !!loyaltyRedemption,
+        can_manage_tier_benefits: !!deps.tierBenefits,
       }, flags);
     }
 
@@ -13609,6 +13617,136 @@ function mount(router, deps) {
         return patch;
       }
     }
+
+    // ---- tier benefits ------------------------------------------------
+    //
+    // The perks a loyalty tier INCLUDES — operator-authored rows the
+    // customer's /account/loyalty page surfaces under "what your tier
+    // includes". This screen is the authoring path so the customer
+    // display is non-empty end-to-end (no dormant-table display).
+    //
+    // HONESTY: these benefits are operator-defined inclusions. The
+    // framework does NOT auto-apply them at checkout / shipping / earn —
+    // the storefront frames them as perks the shop honours, and the
+    // create form tells the operator the same so they don't expect
+    // automatic enforcement.
+    //
+    // Authoring rather than seeding: the primitive already exposes
+    // defineBenefit / listBenefits / archiveBenefit, the loyalty admin
+    // screen is the natural home (the earn-rules / rewards screens are
+    // the reference CRUD shape), and seeding default rows would guess at
+    // the operator's tier ladder + thresholds. Cloning the earn-rule CRUD
+    // keeps the surface consistent.
+    if (deps.tierBenefits) {
+      var tierBenefits = deps.tierBenefits;
+
+      // The benefit's value_json shape depends on its kind. The console
+      // collects one or two typed fields and the create path assembles
+      // the per-kind payload the primitive validates. An unknown kind
+      // falls through to the primitive's refusal.
+      function _tierBenefitValue(kind, body) {
+        switch (kind) {
+          case "free_shipping": {
+            var minRaw = body.value_min_order_minor == null ? "" : String(body.value_min_order_minor).trim();
+            return minRaw !== ""
+              ? { min_order_minor: _strictMinorInt(minRaw, "admin", "min_order_minor") }
+              : {};
+          }
+          case "percent_off":
+            return { percent: _strictMinorInt(body.value_percent, "admin", "percent") };
+          case "early_access":
+            return { hours: _strictMinorInt(body.value_hours, "admin", "hours") };
+          case "priority_support":
+            return { sla_minutes: _strictMinorInt(body.value_sla_minutes, "admin", "sla_minutes") };
+          case "exclusive_access":
+            return { collection_slug: typeof body.value_collection_slug === "string" ? body.value_collection_slug.trim() : body.value_collection_slug };
+          case "birthday_bonus": {
+            var ptsRaw = body.value_points == null ? "" : String(body.value_points).trim();
+            var pctRaw = body.value_percent_off == null ? "" : String(body.value_percent_off).trim();
+            // Exactly one of points / percent_off — the primitive refuses
+            // both or neither. Forward what the operator filled in; if both
+            // are blank we send an empty object so the primitive's
+            // "exactly one" refusal surfaces as a clean 400 notice.
+            if (ptsRaw !== "") return { points: _strictMinorInt(ptsRaw, "admin", "points") };
+            if (pctRaw !== "") return { percent_off: _strictMinorInt(pctRaw, "admin", "percent_off") };
+            return {};
+          }
+          default:
+            return {};
+        }
+      }
+
+      function _tierBenefitDefineInput(body) {
+        var kind = typeof body.kind === "string" ? body.kind.trim() : body.kind;
+        return {
+          slug:  typeof body.slug === "string" ? body.slug.trim() : body.slug,
+          tier:  typeof body.tier === "string" ? body.tier.trim() : body.tier,
+          kind:  kind,
+          value: _tierBenefitValue(kind, body),
+        };
+      }
+
+      router.get("/admin/loyalty/tier-benefits", _pageOrApi(true,
+        R(async function (_req, res) {
+          _json(res, 200, { rows: await tierBenefits.listBenefits({ include_archived: true }) });
+        }),
+        async function (req, res) {
+          var url = req.url ? new URL(req.url, "http://localhost") : null;
+          _sendHtml(res, 200, renderAdminTierBenefits({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            kinds: tierBenefitsModule.KINDS,
+            tiers: loyalty.TIERS,
+            benefits: await tierBenefits.listBenefits({ include_archived: true }),
+            created:  url && url.searchParams.get("created"),
+            archived: url && url.searchParams.get("archived_ok"),
+            notice:   (url && url.searchParams.get("err")) ? "That action couldn't be completed for the benefit." : null,
+          }));
+        },
+      ));
+
+      router.post("/admin/loyalty/tier-benefits", _pageOrApi(false,
+        W("loyalty.tier_benefit.create", async function (req, res) {
+          var benefit;
+          try { benefit = await tierBenefits.defineBenefit(_tierBenefitDefineInput(req.body || {})); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 201, benefit);
+          return { id: benefit.slug };
+        }),
+        async function (req, res) {
+          try {
+            await tierBenefits.defineBenefit(_tierBenefitDefineInput(req.body || {}));
+          } catch (e) {
+            var n = _safeNotice(e, "loyalty.tier_benefit.create");
+            return _sendHtml(res, n.status, renderAdminTierBenefits({
+              shop_name: deps.shop_name, nav_available: navAvailable,
+              kinds: tierBenefitsModule.KINDS,
+              tiers: loyalty.TIERS,
+              benefits: await tierBenefits.listBenefits({ include_archived: true }),
+              notice: n.message.replace(/^tierBenefits[.:]\s*/, ""),
+            }));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.tier_benefit.create", outcome: "success" });
+          _redirect(res, "/admin/loyalty/tier-benefits?created=1");
+        },
+      ));
+
+      router.post("/admin/loyalty/tier-benefits/:slug/archive", _pageOrApi(false,
+        W("loyalty.tier_benefit.archive", async function (req, res) {
+          var benefit;
+          try { benefit = await tierBenefits.archiveBenefit(req.params.slug); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 200, benefit);
+          return { id: req.params.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          try { await tierBenefits.archiveBenefit(slug); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/loyalty/tier-benefits?err=1"); }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.tier_benefit.archive", outcome: "success", metadata: { slug: slug } });
+          _redirect(res, "/admin/loyalty/tier-benefits?archived_ok=1");
+        },
+      ));
+    }
   }
 
   // Patch builder for the loyalty earn-rule edit form. trigger is
@@ -22930,6 +23068,32 @@ function renderAdminLoyalty(opts) {
       "</div>";
   }
 
+  // Tier-benefits summary — the perks each tier includes, with a link to
+  // the authoring screen. The customer's /account/loyalty page surfaces
+  // these as "what your tier includes". They are operator-defined
+  // inclusions (not auto-applied at checkout), so the panel says so.
+  var tierBenefitSummary;
+  if (!opts.can_manage_tier_benefits) {
+    tierBenefitSummary = "";
+  } else {
+    var tbRows = opts.tier_benefits || [];
+    var tbBody = tbRows.map(function (ben) {
+      return "<tr>" +
+        "<td><strong>" + _htmlEscape(ben.slug) + "</strong></td>" +
+        "<td>" + _htmlEscape(String(ben.tier)) + "</td>" +
+        "<td>" + _htmlEscape(String(ben.kind)) + "</td>" +
+        "<td>" + _tierBenefitValueLabel(ben) + "</td>" +
+      "</tr>";
+    }).join("");
+    tierBenefitSummary = "<div class=\"panel\"><div class=\"actions-row\"><h3 class=\"subhead\">Tier benefits</h3>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/loyalty/tier-benefits\">Manage tier benefits</a></div>" +
+      "<p class=\"meta\">The perks a tier includes — shown to customers on their rewards page as what their tier includes. The shop honours them; they aren't applied automatically at checkout.</p>" +
+      (tbRows.length
+        ? _tableWrap("<table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Tier</th><th scope=\"col\">Kind</th><th scope=\"col\">Value</th></tr></thead><tbody>" + tbBody + "</tbody></table>")
+        : "<p class=\"empty\">No tier benefits yet. Customers see a perk list only once you add benefits.</p>") +
+      "</div>";
+  }
+
   // Points-adjustment form. The customer id is pasted (the customers
   // roster shows each customer's id); the amount is a positive integer; a
   // grant / deduct radio sets the sign; the reason is required and lands
@@ -22957,7 +23121,7 @@ function renderAdminLoyalty(opts) {
     "</div>";
 
   var bodyHtml = "<section><h2>Loyalty</h2>" + adjusted + notice +
-    tierTable + earnSummary + rewardSummary + adjustForm + "</section>";
+    tierTable + earnSummary + rewardSummary + tierBenefitSummary + adjustForm + "</section>";
   return _renderAdminShell(opts.shop_name, "Loyalty", bodyHtml, "loyalty", opts.nav_available);
 }
 
@@ -23183,6 +23347,96 @@ function renderAdminLoyaltyReward(opts) {
   return _renderAdminShell(opts.shop_name, "Reward", body, "loyalty", opts.nav_available);
 }
 
+// A tier benefit's value rendered for the admin list — the typed
+// value_json per kind, kept terse. Escaped (operator-authored fields).
+function _tierBenefitValueLabel(benefit) {
+  var v = benefit && benefit.value ? benefit.value : {};
+  switch (benefit && benefit.kind) {
+    case "free_shipping":
+      return v.min_order_minor != null
+        ? _htmlEscape("min order " + String(v.min_order_minor) + " minor")
+        : _htmlEscape("any order");
+    case "percent_off":      return _htmlEscape(String(v.percent || 0) + "%");
+    case "early_access":     return _htmlEscape(String(v.hours || 0) + "h early");
+    case "priority_support": return _htmlEscape(String(v.sla_minutes || 0) + " min SLA");
+    case "exclusive_access": return _htmlEscape(String(v.collection_slug || ""));
+    case "birthday_bonus":
+      if (v.points != null)      return _htmlEscape(String(v.points) + " pts");
+      if (v.percent_off != null) return _htmlEscape(String(v.percent_off) + "% off");
+      return _htmlEscape("—");
+    default: return _htmlEscape("—");
+  }
+}
+
+// Tier-benefits list + create form. A benefit is a (tier, kind) pair plus
+// a typed value — the perks the customer's /account/loyalty page surfaces
+// as "what your tier includes". These are operator-defined inclusions: the
+// framework does NOT auto-apply them at checkout / shipping / earn, so the
+// create-form copy says so (and the customer page frames them the same).
+function renderAdminTierBenefits(opts) {
+  opts = opts || {};
+  var benefits = opts.benefits || [];
+  var kinds = opts.kinds || tierBenefitsModule.KINDS;
+  var tiers = opts.tiers || [];
+  var created  = opts.created  ? "<div class=\"banner banner--ok\">Benefit saved.</div>" : "";
+  var archived = opts.archived ? "<div class=\"banner banner--ok\">Benefit archived.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var bodyRows = benefits.map(function (ben) {
+    var enc = encodeURIComponent(ben.slug);
+    return "<tr>" +
+      "<td><strong>" + _htmlEscape(ben.slug) + "</strong></td>" +
+      "<td>" + _htmlEscape(String(ben.tier)) + "</td>" +
+      "<td>" + _htmlEscape(String(ben.kind)) + "</td>" +
+      "<td>" + _tierBenefitValueLabel(ben) + "</td>" +
+      "<td>" + (ben.archived_at == null
+        ? "<span class=\"status-pill paid\">active</span>"
+        : "<span class=\"status-pill\">archived</span>") + "</td>" +
+      "<td><div class=\"actions-row\">" +
+        (ben.archived_at == null
+          ? "<form method=\"post\" action=\"/admin/loyalty/tier-benefits/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+              "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>"
+          : "") +
+      "</div></td>" +
+    "</tr>";
+  }).join("");
+  var table = benefits.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Tier</th><th scope=\"col\">Kind</th><th scope=\"col\">Value</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No tier benefits yet. Add one below so customers see what their tier includes.</p>";
+
+  var kindOpts = kinds.map(function (k) {
+    return "<option value=\"" + _htmlEscape(k) + "\">" + _htmlEscape(k) + "</option>";
+  }).join("");
+  var tierField = tiers.length
+    ? "<label class=\"form-field\"><span>Tier</span><select name=\"tier\">" +
+        tiers.map(function (t) { return "<option value=\"" + _htmlEscape(t) + "\">" + _htmlEscape(t) + "</option>"; }).join("") +
+      "</select><small>The tier this perk is included with.</small></label>"
+    : _setupField("Tier", "tier", "", "text", "The tier this perk is included with (e.g. gold).", " maxlength=\"32\" required");
+
+  var createForm =
+    "<div class=\"panel mt mw-40\"><h3 class=\"subhead\">Add a tier benefit</h3>" +
+      "<p class=\"meta\">A benefit is a perk a tier includes. Fill only the value fields that match the kind: free_shipping → optional minimum order (minor units, blank for any); percent_off → percent (1–100); early_access → hours; priority_support → SLA minutes; exclusive_access → a collection slug; birthday_bonus → either points or a percent off (exactly one). These perks are shown to customers as what their tier includes — the shop honours them; they are not applied automatically at checkout.</p>" +
+      "<form method=\"post\" action=\"/admin/loyalty/tier-benefits\">" +
+        _setupField("Slug", "slug", "", "text", "Letters, digits, dashes, dots, underscores (e.g. platinum-free-ship).", " maxlength=\"80\" required") +
+        tierField +
+        "<label class=\"form-field\"><span>Kind</span><select name=\"kind\">" + kindOpts + "</select></label>" +
+        _setupField("Free shipping: min order (minor)", "value_min_order_minor", "", "number", "free_shipping only — minimum order in minor units. Blank for any order.", " min=\"0\" step=\"1\" class=\"input-code\"") +
+        _setupField("Percent off", "value_percent", "", "number", "percent_off only — 1 to 100.", " min=\"1\" max=\"100\" step=\"1\" class=\"input-code\"") +
+        _setupField("Early access (hours)", "value_hours", "", "number", "early_access only — 1 to 720.", " min=\"1\" max=\"720\" step=\"1\" class=\"input-code\"") +
+        _setupField("Priority support (SLA minutes)", "value_sla_minutes", "", "number", "priority_support only — 1 to 10080.", " min=\"1\" max=\"10080\" step=\"1\" class=\"input-code\"") +
+        _setupField("Exclusive collection slug", "value_collection_slug", "", "text", "exclusive_access only — the collection slug.", " maxlength=\"80\"") +
+        _setupField("Birthday bonus: points", "value_points", "", "number", "birthday_bonus only — points granted on the birthday (set this OR percent off).", " min=\"1\" step=\"1\" class=\"input-code\"") +
+        _setupField("Birthday bonus: percent off", "value_percent_off", "", "number", "birthday_bonus only — percent off on the birthday (set this OR points).", " min=\"1\" max=\"100\" step=\"1\" class=\"input-code\"") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Add benefit</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Tier benefits</h2>" +
+    "<p class=\"meta\"><a href=\"/admin/loyalty\">&larr; Loyalty</a></p>" +
+    created + archived + notice + table + createForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Tier benefits", bodyHtml, "loyalty", opts.nav_available);
+}
+
 // Product detail / management screen — the console's full editor for a
 // single catalog product: its fields (slug / title / description /
 // status), its variants (create / edit / delete), each variant's price

package/lib/asset-manifest.json

@@ -1,13 +1,13 @@
 {
-  "version": "0.4.53",
+  "version": "0.4.54",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",
       "fingerprinted": "css/admin.6941d5151488a7c1.css"
     },
     "css/main.css": {
-      "integrity": "sha384-z6x2cNhNfsxxs7OZi3ZIg84HAcsJIUyhH4RjZwuHCdf03Rr68dm9zxciLgThkGLh",
-      "fingerprinted": "css/main.cf0a6763075ece73.css"
+      "integrity": "sha384-wm9Kgl9osJlGxNW9swpY/yaFoS07Sw6ek5e9sce9RLd5W5BPwz9DcXs0wxym4oAn",
+      "fingerprinted": "css/main.9f60d689ff4715d7.css"
     },
     "js/announcement.js": {
       "integrity": "sha384-z4zcEMn+tScoVnYRE4nEf8N/oyvpxdpaxTNrT4QO/jURChid4+qjAvWkzatCaAPq",

package/lib/storefront.js

@@ -5586,6 +5586,74 @@ function _loyaltyRewardValue(reward) {
   return reward.kind;
 }
 
+// A tier benefit's customer-facing label + value description, keyed by
+// the benefit `kind`. These are the operator-authored perks a tier
+// INCLUDES — not auto-applied guarantees (checkout/shipping/earn do not
+// consume tier-benefits), so the copy describes the inclusion in plain
+// language and the rendered page frames the whole set as "what your tier
+// includes". Falls back to the raw kind so a future kind still renders a
+// row. Returns plain strings — the caller esc()'s every field before it
+// reaches HTML.
+function _loyaltyTierBenefitLabel(benefit) {
+  var v = benefit && benefit.value ? benefit.value : {};
+  switch (benefit && benefit.kind) {
+    case "free_shipping":
+      return v.min_order_minor != null
+        ? "Free shipping on orders over " + pricing.format(Number(v.min_order_minor) || 0, "USD")
+        : "Free shipping";
+    case "percent_off":
+      return (Number(v.percent) || 0) + "% off your order";
+    case "early_access":
+      return "Early access — shop new drops " + (Number(v.hours) || 0) + " hours before everyone else";
+    case "priority_support":
+      return "Priority support" + (v.sla_minutes != null
+        ? " — a reply within " + (Number(v.sla_minutes) || 0) + " minutes"
+        : "");
+    case "exclusive_access":
+      return "Exclusive access to the " + String(v.collection_slug || "") + " collection";
+    case "birthday_bonus":
+      if (v.points != null)      return "Birthday bonus — " + (Number(v.points) || 0) + " points on your birthday";
+      if (v.percent_off != null) return "Birthday bonus — " + (Number(v.percent_off) || 0) + "% off on your birthday";
+      return "Birthday bonus";
+    default:
+      return benefit && benefit.kind ? String(benefit.kind) : "Tier perk";
+  }
+}
+
+// Progress toward the next tier for a balance + the operator's tier
+// ladder. Returns the current tier, the next tier (or null at the top),
+// the lifetime points still needed, and a 0-100 percent for the bar.
+// Defensive read — a missing/garbage balance or threshold map degrades to
+// a sane "bronze, no progress" rather than throwing on the customer page.
+function _loyaltyTierProgress(tiers, thresholds, lifetime) {
+  var ladder = Array.isArray(tiers) && tiers.length ? tiers : ["bronze"];
+  var th = thresholds && typeof thresholds === "object" ? thresholds : {};
+  var lp = Number(lifetime);
+  if (!isFinite(lp) || lp < 0) lp = 0;
+  // Walk the ladder from the top down; the current tier is the highest
+  // whose threshold the lifetime total has reached. Mirrors
+  // loyalty.computeTier's inclusive-on-upgrade ordering.
+  var curIdx = 0;
+  for (var i = ladder.length - 1; i >= 0; i -= 1) {
+    var t = th[ladder[i]];
+    if (typeof t === "number" && lp >= t) { curIdx = i; break; }
+  }
+  var current = ladder[curIdx];
+  var nextTier = curIdx + 1 < ladder.length ? ladder[curIdx + 1] : null;
+  if (nextTier == null) {
+    return { current: current, next: null, remaining: 0, percent: 100 };
+  }
+  var curFloor  = typeof th[current]  === "number" ? th[current]  : 0;
+  var nextFloor = typeof th[nextTier] === "number" ? th[nextTier] : curFloor;
+  var span = nextFloor - curFloor;
+  var remaining = nextFloor - lp;
+  if (remaining < 0) remaining = 0;
+  var percent = span > 0 ? Math.floor(((lp - curFloor) / span) * 100) : 100;
+  if (percent < 0) percent = 0;
+  if (percent > 100) percent = 100;
+  return { current: current, next: nextTier, remaining: remaining, percent: percent };
+}
+
 // Earn-rule trigger → customer-facing phrase. Operators see slugs;
 // customers see plain language. Unknown triggers fall back to the raw
 // trigger so a future enum addition still renders something.
@@ -5625,6 +5693,54 @@ function renderLoyalty(opts) {
       "<div><dt>Worth</dt><dd>" + esc(spendableValue) + "</dd></div>" +
     "</dl>";
 
+  // Progress toward the next tier — the points the customer still needs
+  // and a labelled progress bar. At the top tier there's no "next", so we
+  // congratulate instead of rendering a stalled bar.
+  var prog = _loyaltyTierProgress(opts.tiers, opts.tier_thresholds, bal.lifetime);
+  var progressSection;
+  if (prog.next) {
+    progressSection =
+      "<h2 class=\"pdp__variants-title\">Your tier progress</h2>" +
+      "<p class=\"return-card__meta\">You're <strong>" + esc(String(prog.current)) + "</strong>. " +
+        "Earn <strong>" + esc(String(prog.remaining)) + "</strong> more lifetime points to reach <strong>" +
+        esc(String(prog.next)) + "</strong>.</p>" +
+      "<div class=\"loyalty-progress\" role=\"progressbar\" aria-valuenow=\"" + esc(String(prog.percent)) +
+        "\" aria-valuemin=\"0\" aria-valuemax=\"100\" aria-label=\"Progress to " + esc(String(prog.next)) + " tier\">" +
+        "<span class=\"loyalty-progress__bar\" style=\"width:" + esc(String(prog.percent)) + "%\"></span>" +
+      "</div>";
+  } else {
+    progressSection =
+      "<h2 class=\"pdp__variants-title\">Your tier progress</h2>" +
+      "<p class=\"return-card__meta\">You've reached <strong>" + esc(String(prog.current)) +
+        "</strong> — the top tier. Thanks for being a loyal customer.</p>";
+  }
+
+  // Tier benefits — the perks the current tier INCLUDES. These are
+  // operator-defined inclusions; the framework does not auto-apply them at
+  // checkout, so the copy says "includes" and the footnote tells the
+  // customer perks are applied by the shop, not automatically. Every
+  // operator-authored field is esc()'d (manual HTML concat — a forgotten
+  // esc is stored XSS).
+  var benefits = opts.tier_benefits || [];
+  var benefitsSection;
+  if (benefits.length) {
+    var benefitItems = "";
+    for (var bi = 0; bi < benefits.length; bi += 1) {
+      var ben = benefits[bi];
+      benefitItems +=
+        "<li class=\"return-card\"><div class=\"return-card__head\">" +
+          "<span class=\"return-card__rma\">" + esc(_loyaltyTierBenefitLabel(ben)) + "</span>" +
+          "<span class=\"pdp__badge\">" + esc(String(ben.tier || "")) + "</span>" +
+        "</div></li>";
+    }
+    benefitsSection =
+      "<h2 class=\"pdp__variants-title\">What your " + esc(String(bal.tier || "bronze")) + " tier includes</h2>" +
+      "<ul class=\"return-list\">" + benefitItems + "</ul>" +
+      "<p class=\"return-card__meta\">These perks come with your tier. Ask at checkout or contact support to have a perk applied to an order.</p>";
+  } else {
+    benefitsSection = "";
+  }
+
   // How points are earned.
   var rules = opts.earn_rules || [];
   var earnInner = "";
@@ -5732,6 +5848,8 @@ function renderLoyalty(opts) {
       "<h1 class=\"account-returns__title\">Rewards</h1>" +
       notice +
       stats +
+      progressSection +
+      benefitsSection +
       rewardSection +
       earnSection +
       redSection +
@@ -19890,6 +20008,21 @@ function mount(router, deps) {
             redemptions = rpage.rows;
           } catch (_e) { redemptions = []; }
         }
+        // Tier benefits — the perks the customer's current tier includes.
+        // Best-effort: a not-wired / not-migrated table degrades this panel
+        // rather than the page. benefitsForCustomer resolves the tier off
+        // the SAME loyalty handle (balance().tier), so it's the signed-in
+        // customer's own tier — no IDOR surface (the id comes from auth,
+        // never from a path/query param). No context envelope is passed:
+        // the conditional gates (min order, currency, region, time window)
+        // can't be evaluated on a static account page, so an
+        // unconditional perk shows and a gated one is suppressed until
+        // checkout — see _loyaltyTierBenefitLabel's framing.
+        var tierBenefits = [];
+        if (deps.tierBenefits) {
+          try { tierBenefits = await deps.tierBenefits.benefitsForCustomer(auth.customer_id); }
+          catch (_e) { tierBenefits = []; }
+        }
         var cartCount = await _cartCountForReq(req);
         return {
           balance:        bal,
@@ -19901,6 +20034,7 @@ function mount(router, deps) {
           earn_rules:     rules,
           rewards:        rewards,
           redemptions:    redemptions,
+          tier_benefits:  tierBenefits,
           can_redeem:     !!deps.loyaltyRedemption,
           notice:         opts2.notice || null,
           notice_kind:    opts2.notice_kind || null,
@@ -21819,6 +21953,7 @@ module.exports = {
   renderAccountPickups:  renderAccountPickups,
   renderProfile:         renderProfile,
   renderAccountSubscriptions: renderAccountSubscriptions,
+  renderLoyalty:         renderLoyalty,
   renderCookiePreferences: renderCookiePreferences,
   renderSurveyPage:      renderSurveyPage,
   renderSuggestionsPage: renderSuggestionsPage,

package/package.json

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