@blamejs/blamejs-shop 0.3.23 → 0.3.24

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.24 (2026-05-30) — **Manage the loyalty program from the admin console.** The loyalty program was visible to customers at /account/loyalty — their points balance, tier, the ways to earn, and the rewards — but there was no way to configure it from the console, so it could not actually be run. A new Loyalty admin screen now manages the whole program: create and edit the rules that award points (and archive ones that should no longer apply), build and edit the rewards catalog (a reward must be active to appear to customers), and grant or deduct a specific customer's points balance. A points adjustment requires a reason and is written to the loyalty ledger, so every manual change is recorded. **Added:** *Loyalty program administration* — A Loyalty screen in the admin console manages earn rules (the events that award points and how many), the rewards catalog (what points can be redeemed for, with per-kind values), and per-customer point adjustments. Only active, non-archived rules and rewards appear to customers. A manual grant or deduction requires a reason and is recorded in the loyalty ledger alongside automatic earn and redeem activity, and an over-deduction or invalid adjustment is rejected without changing the balance. This completes a program that previously could be shown to shoppers but not configured.
+
 - v0.3.23 (2026-05-30) — **Fix page corruption from a dollar sign in content, keep search pages out of the index, and add a working unsubscribe link.** Three storefront fixes. First, a content-corruption bug: a dollar sign in any page's dynamic content — a product description, a blog post, a content page, a cart or admin page — could mangle the rendered HTML, and a dollar immediately followed by a backtick could splice the page's head markup into the body. Every page assembled its body in a way that gave dollar sequences special meaning; all of them now insert content verbatim. Second, internal search result pages are now marked noindex so the many query and filter URLs are not indexed as thin, duplicate pages (their product links are still followed). Third, the unsubscribe link that marketing emails point to now has a route behind it, so a recipient can actually unsubscribe (and resubscribe) instead of hitting a missing page. **Added:** *Newsletter unsubscribe link works* — A /unsubscribe route now backs the one-click unsubscribe link in marketing emails: opening the link shows a confirmation page, confirming removes the address, and a resubscribe option is offered. Invalid, expired, and already-used links each show a clear page rather than an error. The backend for this already existed; it simply had no route. **Fixed:** *A dollar sign in content no longer corrupts the page* — Pages were assembled by substituting the body into a template in a way that treated dollar sequences (such as a dollar followed by a backtick) as special, so content containing them could corrupt the output or pull head markup into the body. Every render path now inserts dynamic content literally, so any text — prices, code samples, anything with a dollar sign — renders exactly as written. · *Search result pages are no longer indexed* — Internal search result pages now carry a noindex robots tag so the large number of query and facet URL combinations aren't indexed as thin or duplicate content; the product links on those pages are still followed.
 
 - v0.3.22 (2026-05-30) — **Create and publish content pages (About, Shipping, Returns, and the like) from the admin console.** The shop now has editable content pages. An admin Pages screen lets an operator create a page with a slug, title, Markdown body, layout, and meta fields, then publish, unpublish, archive, or restore it — and the storefront serves each published page at /pages/<slug>. Previously the content-page backend existed but had no admin screen and the storefront did not serve it, so it could not be used; a page is created as a draft and is not visible on the storefront until it is published. **Added:** *Content pages: author in the console, serve on the storefront* — A new Pages admin screen manages content pages through their full lifecycle (draft, published, archived, with restore). Published pages are served at /pages/<slug> with the page's chosen layout; a draft or archived slug returns not-found. The Markdown body is rendered with the same escaping and safe-link handling as the rest of the storefront. This makes a standard set of pages — about, shipping, returns, and similar — editable instead of requiring a code change.

package/lib/admin.js

@@ -33,6 +33,8 @@
 var pricing = require("./pricing");
 var collectionsModule = require("./collections");
 var quantityDiscountsModule = require("./quantity-discounts");
+var loyaltyEarnRulesModule = require("./loyalty-earn-rules");
+var loyaltyRedemptionModule = require("./loyalty-redemption");
 var textGuard = require("./text-guard");
 var { AsyncLocalStorage } = require("node:async_hooks");   // allow:non-shop-require — Node-core per-request context (no npm dep); the framework itself composes it in db-role-context / log. No b.* request-context primitive exists to wrap it.
 
@@ -510,7 +512,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, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -6628,6 +6630,535 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- loyalty --------------------------------------------------------
+  // Manage the loyalty program from the console: the earn rules that mint
+  // points, the rewards catalog customers redeem against, and a direct
+  // per-customer points adjustment (grant / deduct with a required reason,
+  // recorded in the loyalty ledger). The customer-facing /account/loyalty
+  // page shows ONLY active earn rules + active rewards, so the console
+  // flags inactive rows and an archive removes them from the storefront.
+  //
+  // `loyalty` (the points ledger) is the core dep — the overview + the
+  // adjustment action mount on it. Earn rules + the rewards catalog mount
+  // additionally on their own primitives, so a deployment that wired only
+  // the ledger still gets the adjustment surface (and the nav link).
+  if (deps.loyalty) {
+    var loyalty = deps.loyalty;
+    var loyaltyEarnRules  = deps.loyaltyEarnRules  || null;
+    var loyaltyRedemption = deps.loyaltyRedemption || null;
+
+    // Validate the operator's free-text adjustment reason at the route.
+    // A points adjustment is a money-adjacent action, so the reason is
+    // MANDATORY — it rides into the ledger row's `notes` column. Throws a
+    // TypeError (→ 400) on a missing / blank / over-long / control-byte
+    // reason so the browser form surfaces a clean notice and writes
+    // nothing. The amount goes through the strict signed-integer reader
+    // (refuses "", floats, "12abc") and must be non-zero.
+    var LOYALTY_REASON_MAX = 256;
+    function _loyaltyReason(raw) {
+      if (raw == null) throw new TypeError("admin: a reason is required for a points adjustment");
+      var s = String(raw).trim();
+      if (!s.length) throw new TypeError("admin: a reason is required for a points adjustment");
+      if (s.length > LOYALTY_REASON_MAX) throw new TypeError("admin: reason must be <= " + LOYALTY_REASON_MAX + " chars");
+      if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(s)) throw new TypeError("admin: reason must not contain control bytes");
+      return s;
+    }
+    // Coerce the grant/deduct form into a signed delta. `direction` is
+    // "grant" (positive) or "deduct" (negative); `amount` is a positive
+    // integer count of points. The two compose into the non-zero signed
+    // delta loyalty.adjust expects, so the operator never types a sign.
+    function _loyaltyDelta(body) {
+      var amount = _strictMinorInt(body.amount, "admin", "amount");
+      if (amount <= 0) throw new TypeError("admin: amount must be a positive integer");
+      var dir = typeof body.direction === "string" ? body.direction.trim() : "";
+      if (dir !== "grant" && dir !== "deduct") {
+        throw new TypeError("admin: direction must be 'grant' or 'deduct'");
+      }
+      return dir === "deduct" ? -amount : amount;
+    }
+
+    // Build the overview model: thresholds + ratios from the ledger, plus
+    // (best-effort) the earn-rule + reward lists. A not-wired or
+    // not-migrated sub-primitive degrades that panel rather than the page.
+    async function _loyaltyOverview(flags) {
+      flags = flags || {};
+      var earnRules = null;
+      if (loyaltyEarnRules) {
+        try { earnRules = await loyaltyEarnRules.listRules({ limit: 200 }); }
+        catch (_e) { earnRules = []; }
+      }
+      var rewards = null;
+      if (loyaltyRedemption) {
+        try { rewards = await loyaltyRedemption.listRewards({ limit: 200 }); }
+        catch (_e) { rewards = []; }
+      }
+      return Object.assign({
+        shop_name:        deps.shop_name,
+        nav_available:    navAvailable,
+        tiers:            loyalty.TIERS,
+        tier_thresholds:  loyalty.TIER_THRESHOLDS,
+        points_per_usd:   loyalty.POINTS_PER_USD,
+        redemption_points_per_usd: loyalty.REDEMPTION_POINTS_PER_USD,
+        earn_triggers:    loyaltyEarnRulesModule.TRIGGERS,
+        reward_kinds:     loyaltyRedemptionModule.KINDS,
+        earn_rules:       earnRules,
+        rewards:          rewards,
+        can_manage_rules:   !!loyaltyEarnRules,
+        can_manage_rewards: !!loyaltyRedemption,
+      }, flags);
+    }
+
+    router.get("/admin/loyalty", _pageOrApi(true,
+      R(async function (_req, res) {
+        // Bearer JSON: the program's configuration snapshot.
+        _json(res, 200, {
+          tiers:            loyalty.TIERS,
+          tier_thresholds:  loyalty.TIER_THRESHOLDS,
+          points_per_usd:   loyalty.POINTS_PER_USD,
+          redemption_points_per_usd: loyalty.REDEMPTION_POINTS_PER_USD,
+          earn_rules:       loyaltyEarnRules  ? await loyaltyEarnRules.listRules({ limit: 200 }) : null,
+          rewards:          loyaltyRedemption ? await loyaltyRedemption.listRewards({ limit: 200 }) : null,
+        });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var flags = {
+          adjusted: url && url.searchParams.get("adjusted"),
+          notice:   (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+        };
+        // A failed adjustment round-trips its message through a one-shot
+        // query flag set on the redirect (kept short + already escaped on
+        // render) so the operator sees WHY without a 5xx.
+        if (url && url.searchParams.get("adjust_err")) {
+          flags.adjust_notice = url.searchParams.get("adjust_err");
+        }
+        _sendHtml(res, 200, renderAdminLoyalty(await _loyaltyOverview(flags)));
+      },
+    ));
+
+    // Points adjustment — grant or deduct a specific customer's balance
+    // with a required reason. Composes loyalty.adjust, which writes the
+    // signed delta to loyalty_transactions (the audited ledger) and
+    // recomputes the tier. A bad customer id / amount / missing reason is
+    // a clean 4xx with nothing written; an underflowing deduction surfaces
+    // the primitive's LOYALTY_INSUFFICIENT_BALANCE as a notice.
+    router.post("/admin/loyalty/adjust", _pageOrApi(false,
+      W("loyalty.adjust", async function (req, res) {
+        var body = req.body || {};
+        var customerId = body.customer_id;
+        var delta;
+        var reason;
+        try {
+          delta  = _loyaltyDelta(body);
+          reason = _loyaltyReason(body.reason);
+        } catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          throw e;
+        }
+        var result;
+        try {
+          result = await loyalty.adjust({
+            customer_id: customerId,
+            points:      delta,
+            source:      "admin-adjustment",
+            notes:       reason,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          if (e && e.code === "LOYALTY_INSUFFICIENT_BALANCE") {
+            return _problem(res, 409, "insufficient-balance", "Adjustment would drop the balance below zero.");
+          }
+          throw e;
+        }
+        _json(res, 200, result);
+        return { id: customerId };
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var customerId = body.customer_id;
+        var cidPrefill = typeof customerId === "string" ? customerId : "";
+        // Re-render the overview with the adjustment form's error notice.
+        // The message is classified by the shared _safeNotice funnel (so
+        // the cookie/HTML path can never reveal more than the bearer JSON
+        // path); the `admin:`/`loyalty:` namespace prefix is stripped for
+        // the operator. An insufficient-balance refusal is the one
+        // primitive code _safeNotice would otherwise genericize to a 500,
+        // so it's mapped to a clean 4xx notice ahead of the funnel.
+        async function _adjustFail(e) {
+          if (e && e.code === "LOYALTY_INSUFFICIENT_BALANCE") {
+            return _sendHtml(res, 409, renderAdminLoyalty(await _loyaltyOverview({
+              adjust_notice: "That deduction would drop the balance below zero.",
+              adjust_customer_id: cidPrefill,
+            })));
+          }
+          var n = _safeNotice(e, "loyalty.adjust");
+          return _sendHtml(res, n.status, renderAdminLoyalty(await _loyaltyOverview({
+            adjust_notice: n.message.replace(/^(?:admin|loyalty)[.:]\s*/, ""),
+            adjust_customer_id: cidPrefill,
+          })));
+        }
+        var delta;
+        var reason;
+        try {
+          delta  = _loyaltyDelta(body);
+          reason = _loyaltyReason(body.reason);
+        } catch (e) {
+          return _adjustFail(e);
+        }
+        try {
+          await loyalty.adjust({
+            customer_id: customerId,
+            points:      delta,
+            source:      "admin-adjustment",
+            notes:       reason,
+          });
+        } catch (e) {
+          return _adjustFail(e);
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.adjust", outcome: "success" });
+        _redirect(res, "/admin/loyalty?adjusted=1");
+      },
+    ));
+
+    // ---- earn rules ---------------------------------------------------
+    if (loyaltyEarnRules) {
+      // Translate the create / edit form into a defineRule / updateRule
+      // input. The status list is a comma-separated free-text field
+      // (e.g. "active, vip"); a blank field means no restriction (null).
+      function _loyaltyStatusList(raw) {
+        if (raw == null) return null;
+        var s = String(raw).trim();
+        if (!s.length) return null;
+        return s.split(",").map(function (x) { return x.trim(); }).filter(Boolean);
+      }
+      function _earnDefineInput(body) {
+        var input = {
+          slug:            typeof body.slug === "string" ? body.slug.trim() : body.slug,
+          trigger:         typeof body.trigger === "string" ? body.trigger.trim() : body.trigger,
+          points_per_unit: _strictMinorInt(body.points_per_unit, "admin", "points_per_unit"),
+          active:          (body.active === "on" || body.active === "1" || body.active === true),
+        };
+        var maxRaw = body.max_per_event == null ? "" : String(body.max_per_event).trim();
+        if (maxRaw !== "") input.max_per_event = _strictMinorInt(maxRaw, "admin", "max_per_event");
+        var statusList = _loyaltyStatusList(body.customer_status_in);
+        if (statusList) input.customer_status_in = statusList;
+        return input;
+      }
+
+      router.get("/admin/loyalty/earn-rules", _pageOrApi(true,
+        R(async function (_req, res) {
+          _json(res, 200, { rows: await loyaltyEarnRules.listRules({ limit: 200 }) });
+        }),
+        async function (req, res) {
+          var url = req.url ? new URL(req.url, "http://localhost") : null;
+          _sendHtml(res, 200, renderAdminLoyaltyEarnRules({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            triggers: loyaltyEarnRulesModule.TRIGGERS,
+            rules: await loyaltyEarnRules.listRules({ limit: 200 }),
+            created: url && url.searchParams.get("created"),
+            saved:   url && url.searchParams.get("saved"),
+            archived: url && url.searchParams.get("archived_ok"),
+            notice:  (url && url.searchParams.get("err")) ? "That action couldn't be completed for the rule." : null,
+          }));
+        },
+      ));
+
+      router.post("/admin/loyalty/earn-rules", _pageOrApi(false,
+        W("loyalty.earn_rule.create", async function (req, res) {
+          var rule;
+          try { rule = await loyaltyEarnRules.defineRule(_earnDefineInput(req.body || {})); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 201, rule);
+          return { id: rule.slug };
+        }),
+        async function (req, res) {
+          try {
+            await loyaltyEarnRules.defineRule(_earnDefineInput(req.body || {}));
+          } catch (e) {
+            var n = _safeNotice(e, "loyalty.earn_rule.create");
+            return _sendHtml(res, n.status, renderAdminLoyaltyEarnRules({
+              shop_name: deps.shop_name, nav_available: navAvailable,
+              triggers: loyaltyEarnRulesModule.TRIGGERS,
+              rules: await loyaltyEarnRules.listRules({ limit: 200 }),
+              notice: n.message.replace(/^loyaltyEarnRules[.:]\s*/, ""),
+            }));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.earn_rule.create", outcome: "success" });
+          _redirect(res, "/admin/loyalty/earn-rules?created=1");
+        },
+      ));
+
+      router.get("/admin/loyalty/earn-rules/:slug", _pageOrApi(true,
+        R(async function (req, res) {
+          var rule;
+          try { rule = await loyaltyEarnRules.getRule(req.params.slug); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!rule) return _problem(res, 404, "loyalty-earn-rule-not-found");
+          _json(res, 200, rule);
+        }),
+        async function (req, res) {
+          var url = req.url ? new URL(req.url, "http://localhost") : null;
+          var rule;
+          try { rule = await loyaltyEarnRules.getRule(req.params.slug); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; rule = null; }
+          if (!rule) return _sendHtml(res, 404, renderAdminLoyaltyEarnRule({
+            shop_name: deps.shop_name, nav_available: navAvailable, rule: null,
+          }));
+          _sendHtml(res, 200, renderAdminLoyaltyEarnRule({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            triggers: loyaltyEarnRulesModule.TRIGGERS, rule: rule,
+            saved:  url && url.searchParams.get("saved"),
+            notice: (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+          }));
+        },
+      ));
+
+      router.post("/admin/loyalty/earn-rules/:slug/edit", _pageOrApi(false,
+        W("loyalty.earn_rule.update", async function (req, res) {
+          var patch = _earnPatchFromForm(req.body || {});
+          var rule;
+          try { rule = await loyaltyEarnRules.updateRule(req.params.slug, patch); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!rule) return _problem(res, 404, "loyalty-earn-rule-not-found");
+          _json(res, 200, rule);
+          return { id: rule.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          var enc = encodeURIComponent(slug);
+          try {
+            var rule = await loyaltyEarnRules.updateRule(slug, _earnPatchFromForm(req.body || {}));
+            if (!rule) return _redirect(res, "/admin/loyalty/earn-rules?err=1");
+          } catch (e) {
+            if (!(e instanceof TypeError)) throw e;
+            return _redirect(res, "/admin/loyalty/earn-rules/" + enc + "?err=1");
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.earn_rule.update", outcome: "success", metadata: { slug: slug } });
+          _redirect(res, "/admin/loyalty/earn-rules/" + enc + "?saved=1");
+        },
+      ));
+
+      router.post("/admin/loyalty/earn-rules/:slug/archive", _pageOrApi(false,
+        W("loyalty.earn_rule.archive", async function (req, res) {
+          var rule;
+          try { rule = await loyaltyEarnRules.archiveRule(req.params.slug); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!rule) return _problem(res, 404, "loyalty-earn-rule-not-found");
+          _json(res, 200, rule);
+          return { id: req.params.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          try { await loyaltyEarnRules.archiveRule(slug); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/loyalty/earn-rules?err=1"); }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.earn_rule.archive", outcome: "success", metadata: { slug: slug } });
+          _redirect(res, "/admin/loyalty/earn-rules?archived_ok=1");
+        },
+      ));
+    }
+
+    // ---- rewards catalog ----------------------------------------------
+    if (loyaltyRedemption) {
+      // The reward's value_json shape depends on its kind. The console
+      // collects one numeric field (percent / amount_minor / product_id)
+      // and the create path assembles the per-kind payload the primitive
+      // validates. free_shipping carries an empty object.
+      function _rewardValueJson(kind, body) {
+        if (kind === "discount_percent") {
+          return { percent: _strictMinorInt(body.value_number, "admin", "percent") };
+        }
+        if (kind === "discount_amount") {
+          return { amount_minor: _strictMinorInt(body.value_number, "admin", "amount_minor") };
+        }
+        if (kind === "free_product") {
+          var pid = typeof body.value_text === "string" ? body.value_text.trim() : "";
+          return { product_id: pid };
+        }
+        // free_shipping (or an unknown kind the primitive will reject).
+        return {};
+      }
+      function _rewardDefineInput(body) {
+        var kind = typeof body.kind === "string" ? body.kind.trim() : body.kind;
+        var input = {
+          slug:       typeof body.slug === "string" ? body.slug.trim() : body.slug,
+          kind:       kind,
+          title:      typeof body.title === "string" ? body.title : body.title,
+          point_cost: _strictMinorInt(body.point_cost, "admin", "point_cost"),
+          value_json: _rewardValueJson(kind, body),
+          active:     (body.active === "on" || body.active === "1" || body.active === true),
+        };
+        var maxRaw = body.max_per_customer == null ? "" : String(body.max_per_customer).trim();
+        if (maxRaw !== "") input.max_per_customer = _strictMinorInt(maxRaw, "admin", "max_per_customer");
+        var expRaw = body.expires_days_after_redemption == null ? "" : String(body.expires_days_after_redemption).trim();
+        if (expRaw !== "") input.expires_days_after_redemption = _strictMinorInt(expRaw, "admin", "expires_days_after_redemption");
+        return input;
+      }
+
+      router.get("/admin/loyalty/rewards", _pageOrApi(true,
+        R(async function (_req, res) {
+          _json(res, 200, { rows: await loyaltyRedemption.listRewards({ limit: 200 }) });
+        }),
+        async function (req, res) {
+          var url = req.url ? new URL(req.url, "http://localhost") : null;
+          _sendHtml(res, 200, renderAdminLoyaltyRewards({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            kinds: loyaltyRedemptionModule.KINDS,
+            rewards: await loyaltyRedemption.listRewards({ limit: 200 }),
+            created: url && url.searchParams.get("created"),
+            saved:   url && url.searchParams.get("saved"),
+            archived: url && url.searchParams.get("archived_ok"),
+            notice:  (url && url.searchParams.get("err")) ? "That action couldn't be completed for the reward." : null,
+          }));
+        },
+      ));
+
+      router.post("/admin/loyalty/rewards", _pageOrApi(false,
+        W("loyalty.reward.create", async function (req, res) {
+          var reward;
+          try { reward = await loyaltyRedemption.defineReward(_rewardDefineInput(req.body || {})); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 201, reward);
+          return { id: reward.slug };
+        }),
+        async function (req, res) {
+          try {
+            await loyaltyRedemption.defineReward(_rewardDefineInput(req.body || {}));
+          } catch (e) {
+            var n = _safeNotice(e, "loyalty.reward.create");
+            return _sendHtml(res, n.status, renderAdminLoyaltyRewards({
+              shop_name: deps.shop_name, nav_available: navAvailable,
+              kinds: loyaltyRedemptionModule.KINDS,
+              rewards: await loyaltyRedemption.listRewards({ limit: 200 }),
+              notice: n.message.replace(/^loyaltyRedemption[.:]\s*/, ""),
+            }));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.reward.create", outcome: "success" });
+          _redirect(res, "/admin/loyalty/rewards?created=1");
+        },
+      ));
+
+      router.get("/admin/loyalty/rewards/:slug", _pageOrApi(true,
+        R(async function (req, res) {
+          var reward;
+          try { reward = await loyaltyRedemption.getReward(req.params.slug); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          if (!reward) return _problem(res, 404, "loyalty-reward-not-found");
+          _json(res, 200, reward);
+        }),
+        async function (req, res) {
+          var url = req.url ? new URL(req.url, "http://localhost") : null;
+          var reward;
+          try { reward = await loyaltyRedemption.getReward(req.params.slug); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; reward = null; }
+          if (!reward) return _sendHtml(res, 404, renderAdminLoyaltyReward({
+            shop_name: deps.shop_name, nav_available: navAvailable, reward: null,
+          }));
+          _sendHtml(res, 200, renderAdminLoyaltyReward({
+            shop_name: deps.shop_name, nav_available: navAvailable, reward: reward,
+            saved:  url && url.searchParams.get("saved"),
+            notice: (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+          }));
+        },
+      ));
+
+      router.post("/admin/loyalty/rewards/:slug/edit", _pageOrApi(false,
+        W("loyalty.reward.update", async function (req, res) {
+          var reward;
+          try { reward = await loyaltyRedemption.updateReward(req.params.slug, await _rewardPatchFromForm(req.params.slug, req.body || {})); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 200, reward);
+          return { id: reward.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          var enc = encodeURIComponent(slug);
+          try {
+            await loyaltyRedemption.updateReward(slug, await _rewardPatchFromForm(slug, req.body || {}));
+          } catch (e) {
+            if (!(e instanceof TypeError)) throw e;
+            return _redirect(res, "/admin/loyalty/rewards/" + enc + "?err=1");
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.reward.update", outcome: "success", metadata: { slug: slug } });
+          _redirect(res, "/admin/loyalty/rewards/" + enc + "?saved=1");
+        },
+      ));
+
+      router.post("/admin/loyalty/rewards/:slug/archive", _pageOrApi(false,
+        W("loyalty.reward.archive", async function (req, res) {
+          var reward;
+          try { reward = await loyaltyRedemption.archiveReward(req.params.slug); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          _json(res, 200, reward);
+          return { id: req.params.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          try { await loyaltyRedemption.archiveReward(slug); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/loyalty/rewards?err=1"); }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".loyalty.reward.archive", outcome: "success", metadata: { slug: slug } });
+          _redirect(res, "/admin/loyalty/rewards?archived_ok=1");
+        },
+      ));
+
+      // Build the updateReward patch from the edit form. Only the columns
+      // the operator changed are forwarded; value_json is re-validated
+      // against the reward's STORED kind (kind is immutable on update), so
+      // the helper reads the current reward to resolve it.
+      async function _rewardPatchFromForm(slug, body) {
+        var patch = {};
+        if (typeof body.title === "string" && body.title.length) patch.title = body.title;
+        if (body.point_cost != null && String(body.point_cost).trim() !== "") {
+          patch.point_cost = _strictMinorInt(body.point_cost, "admin", "point_cost");
+        }
+        if (body.active_present === "1") {
+          patch.active = (body.active === "on" || body.active === "1");
+        }
+        var maxRaw = body.max_per_customer == null ? "" : String(body.max_per_customer).trim();
+        if (maxRaw !== "") patch.max_per_customer = _strictMinorInt(maxRaw, "admin", "max_per_customer");
+        var expRaw = body.expires_days_after_redemption == null ? "" : String(body.expires_days_after_redemption).trim();
+        if (expRaw !== "") patch.expires_days_after_redemption = _strictMinorInt(expRaw, "admin", "expires_days_after_redemption");
+        // A supplied value field rewrites value_json against the stored
+        // kind. Absent it, value_json is left untouched.
+        if ((body.value_number != null && String(body.value_number).trim() !== "") ||
+            (typeof body.value_text === "string" && body.value_text.trim() !== "")) {
+          var current = await loyaltyRedemption.getReward(slug);
+          if (current) patch.value_json = _rewardValueJson(current.kind, body);
+        }
+        return patch;
+      }
+    }
+  }
+
+  // Patch builder for the loyalty earn-rule edit form. trigger is
+  // immutable on update (the primitive refuses a change), so the form
+  // never sends it; only points_per_unit / max_per_event /
+  // customer_status_in / active are editable. Hoisted above the rewards
+  // block's IIFE-free scope so both the bearer + browser edit paths share
+  // it. Defined as a closure inside mount() so it can stay near its
+  // callers without polluting the module surface.
+  function _earnPatchFromForm(body) {
+    var patch = {};
+    if (body.points_per_unit != null && String(body.points_per_unit).trim() !== "") {
+      patch.points_per_unit = _strictMinorInt(body.points_per_unit, "admin", "points_per_unit");
+    }
+    if (body.max_per_event != null) {
+      var maxRaw = String(body.max_per_event).trim();
+      // An explicit "0" / "" clears the cap (null); a positive value sets it.
+      if (maxRaw === "" || maxRaw === "0") patch.max_per_event = null;
+      else patch.max_per_event = _strictMinorInt(maxRaw, "admin", "max_per_event");
+    }
+    if (body.customer_status_in != null) {
+      var s = String(body.customer_status_in).trim();
+      patch.customer_status_in = s.length
+        ? s.split(",").map(function (x) { return x.trim(); }).filter(Boolean)
+        : null;
+    }
+    if (body.active_present === "1") {
+      patch.active = (body.active === "on" || body.active === "1");
+    }
+    return patch;
+  }
+
   // Render the discounts screen — gathers rules + (optional) stacking
   // policies, then hands them to the renderer with whatever banner flags
   // the caller passed.
@@ -7084,6 +7615,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "discounts",    href: "/admin/discounts",    label: "Discounts",    requires: "autoDiscount" },
   { key: "discount-allocation", href: "/admin/discount-allocation", label: "Discount splits", requires: "discountAllocation" },
   { key: "quantity-discounts", href: "/admin/quantity-discounts", label: "Quantity breaks", requires: "quantityDiscounts" },
+  { key: "loyalty",      href: "/admin/loyalty",      label: "Loyalty",      requires: "loyalty" },
   { key: "tax",          href: "/admin/tax-rates",    label: "Tax",          requires: "taxRates" },
   { key: "tax-filings",  href: "/admin/tax-filings",  label: "Tax filings",  requires: "salesTaxFilings" },
   { key: "shipping",     href: "/admin/shipping",     label: "Shipping",     requires: "shippingZones" },
@@ -10960,6 +11492,354 @@ function renderAdminQuantityDiscount(opts) {
   return _renderAdminShell(opts.shop_name, "Quantity break", body, "quantity-discounts", opts.nav_available);
 }
 
+// ---- loyalty render functions ------------------------------------------
+
+// Status pill for an active / inactive / archived loyalty row — shared by
+// the earn-rule + reward lists.
+function _loyaltyStatusPill(active, archivedAt) {
+  if (archivedAt != null) return "<span class=\"status-pill cancelled\">archived</span>";
+  return active
+    ? "<span class=\"status-pill paid\">active</span>"
+    : "<span class=\"status-pill pending\">inactive</span>";
+}
+
+// Render a reward's value_json as a short human label per kind.
+function _loyaltyRewardValueLabel(reward) {
+  var v = reward.value_json || {};
+  if (reward.kind === "discount_percent") return _htmlEscape(String(v.percent)) + "% off";
+  if (reward.kind === "discount_amount")  return _htmlEscape(String(v.amount_minor)) + " minor off";
+  if (reward.kind === "free_product")     return "free product " + _htmlEscape(String(v.product_id || ""));
+  if (reward.kind === "free_shipping")    return "free shipping";
+  return _htmlEscape(reward.kind);
+}
+
+// Loyalty overview / settings — the program's tiers + conversion ratios,
+// a summary of earn rules + rewards (with links to manage each), and the
+// per-customer points-adjustment form (grant / deduct with a required
+// reason, recorded in the loyalty ledger). The customer's /account/loyalty
+// page shows only ACTIVE earn rules + ACTIVE rewards, so the summary flags
+// inactive rows.
+function renderAdminLoyalty(opts) {
+  opts = opts || {};
+  var adjusted = opts.adjusted ? "<div class=\"banner banner--ok\">Points adjusted. The ledger recorded the change.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var adjustNotice = opts.adjust_notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.adjust_notice) + "</div>" : "";
+
+  var thresholds = opts.tier_thresholds || {};
+  var tiers = opts.tiers || [];
+  var tierRows = tiers.map(function (t) {
+    return "<tr><td><strong>" + _htmlEscape(t) + "</strong></td>" +
+      "<td class=\"num\">" + _htmlEscape(String(thresholds[t] == null ? "—" : thresholds[t])) + "</td></tr>";
+  }).join("");
+  var tierTable =
+    "<div class=\"panel\"><h3 class=\"subhead\">Tiers</h3>" +
+      "<p class=\"meta\">Lifetime points (never decremented) place a customer in a tier. " +
+        "Earning $1 grants " + _htmlEscape(String(opts.points_per_usd)) + " points; " +
+        _htmlEscape(String(opts.redemption_points_per_usd)) + " points redeem for $1 of value.</p>" +
+      "<table><thead><tr><th scope=\"col\">Tier</th><th scope=\"col\" class=\"num\">Lifetime points to reach</th></tr></thead>" +
+      "<tbody>" + tierRows + "</tbody></table></div>";
+
+  // Earn-rule summary.
+  var earnSummary;
+  if (!opts.can_manage_rules) {
+    earnSummary = "<div class=\"panel\"><h3 class=\"subhead\">Earn rules</h3>" +
+      "<p class=\"empty\">Earn-rule management isn't wired in this deployment.</p></div>";
+  } else {
+    var earnRules = opts.earn_rules || [];
+    var earnRows = earnRules.map(function (r) {
+      var enc = encodeURIComponent(r.slug);
+      return "<tr>" +
+        "<td><a href=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(r.slug) + "</strong></a></td>" +
+        "<td>" + _htmlEscape(r.trigger) + "</td>" +
+        "<td class=\"num\">" + _htmlEscape(String(r.points_per_unit)) + "</td>" +
+        "<td>" + _loyaltyStatusPill(r.active, r.archived_at) + "</td>" +
+      "</tr>";
+    }).join("");
+    earnSummary = "<div class=\"panel\"><div class=\"actions-row\"><h3 class=\"subhead\">Earn rules</h3>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/loyalty/earn-rules\">Manage earn rules</a></div>" +
+      (earnRules.length
+        ? "<table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Trigger</th><th scope=\"col\" class=\"num\">Points/unit</th><th scope=\"col\">Status</th></tr></thead><tbody>" + earnRows + "</tbody></table>"
+        : "<p class=\"empty\">No earn rules yet. Customers only earn points from active rules.</p>") +
+      "</div>";
+  }
+
+  // Reward summary.
+  var rewardSummary;
+  if (!opts.can_manage_rewards) {
+    rewardSummary = "<div class=\"panel\"><h3 class=\"subhead\">Rewards catalog</h3>" +
+      "<p class=\"empty\">Rewards-catalog management isn't wired in this deployment.</p></div>";
+  } else {
+    var rewards = opts.rewards || [];
+    var rewardRows = rewards.map(function (rw) {
+      var enc = encodeURIComponent(rw.slug);
+      return "<tr>" +
+        "<td><a href=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(rw.slug) + "</strong></a></td>" +
+        "<td>" + _htmlEscape(rw.title) + "</td>" +
+        "<td class=\"num\">" + _htmlEscape(String(rw.point_cost)) + "</td>" +
+        "<td>" + _loyaltyStatusPill(rw.active, rw.archived_at) + "</td>" +
+      "</tr>";
+    }).join("");
+    rewardSummary = "<div class=\"panel\"><div class=\"actions-row\"><h3 class=\"subhead\">Rewards catalog</h3>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/loyalty/rewards\">Manage rewards</a></div>" +
+      (rewards.length
+        ? "<table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Title</th><th scope=\"col\" class=\"num\">Point cost</th><th scope=\"col\">Status</th></tr></thead><tbody>" + rewardRows + "</tbody></table>"
+        : "<p class=\"empty\">No rewards yet. Customers only see active rewards in their catalog.</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
+  // in the ledger row.
+  var prefillCid = opts.adjust_customer_id ? _htmlEscape(opts.adjust_customer_id) : "";
+  var adjustForm =
+    "<div class=\"panel mw-40\"><h3 class=\"subhead\">Adjust a customer's points</h3>" +
+      "<p class=\"meta\">Grant or deduct points for one customer. Every adjustment is recorded in the loyalty ledger with the reason you give. A grant also counts toward the customer's lifetime tier.</p>" +
+      adjustNotice +
+      "<form method=\"post\" action=\"/admin/loyalty/adjust\">" +
+        "<label class=\"form-field\"><span>Customer id</span>" +
+          "<input type=\"text\" name=\"customer_id\" value=\"" + prefillCid + "\" required maxlength=\"64\" class=\"input-code\" placeholder=\"customer UUID\">" +
+          "<small>From the Customers roster — each row's id column.</small></label>" +
+        "<fieldset class=\"box\"><legend class=\"legend-sm\">Direction</legend>" +
+          "<label class=\"kv\"><input type=\"radio\" name=\"direction\" value=\"grant\" checked> Grant (add points)</label>" +
+          "<label class=\"kv\"><input type=\"radio\" name=\"direction\" value=\"deduct\"> Deduct (remove points)</label>" +
+        "</fieldset>" +
+        "<label class=\"form-field\"><span>Amount (points)</span>" +
+          "<input type=\"number\" name=\"amount\" min=\"1\" step=\"1\" required class=\"input-code\"></label>" +
+        "<label class=\"form-field\"><span>Reason</span>" +
+          "<input type=\"text\" name=\"reason\" required maxlength=\"256\" placeholder=\"e.g. service recovery for order #1234\">" +
+          "<small>Required. Recorded with the adjustment in the ledger.</small></label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Apply adjustment</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Loyalty</h2>" + adjusted + notice +
+    tierTable + earnSummary + rewardSummary + adjustForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Loyalty", bodyHtml, "loyalty", opts.nav_available);
+}
+
+// Earn-rules list + create form. Customers earn points only from ACTIVE
+// rules, so the create form defaults `active` on and the list flags
+// inactive / archived rows.
+function renderAdminLoyaltyEarnRules(opts) {
+  opts = opts || {};
+  var rules = opts.rules || [];
+  var triggers = opts.triggers || loyaltyEarnRulesModule.TRIGGERS;
+  var created  = opts.created  ? "<div class=\"banner banner--ok\">Earn rule saved.</div>" : "";
+  var saved    = opts.saved    ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var archived = opts.archived ? "<div class=\"banner banner--ok\">Earn rule archived.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var bodyRows = rules.map(function (r) {
+    var enc = encodeURIComponent(r.slug);
+    var statusList = (r.customer_status_in && r.customer_status_in.length) ? r.customer_status_in.join(", ") : "all";
+    return "<tr>" +
+      "<td><a href=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(r.slug) + "</strong></a></td>" +
+      "<td>" + _htmlEscape(r.trigger) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(r.points_per_unit)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(r.max_per_event == null ? "—" : String(r.max_per_event)) + "</td>" +
+      "<td>" + _htmlEscape(statusList) + "</td>" +
+      "<td>" + _loyaltyStatusPill(r.active, r.archived_at) + "</td>" +
+      "<td><div class=\"actions-row\">" +
+        "<a class=\"btn btn--ghost\" href=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "\">Manage</a>" +
+        (r.archived_at == null
+          ? "<form method=\"post\" action=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+              "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>"
+          : "") +
+      "</div></td>" +
+    "</tr>";
+  }).join("");
+  var table = rules.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Trigger</th><th scope=\"col\" class=\"num\">Points/unit</th><th scope=\"col\" class=\"num\">Max/event</th><th scope=\"col\">Statuses</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No earn rules yet.</p>";
+
+  var triggerOpts = triggers.map(function (t) {
+    return "<option value=\"" + _htmlEscape(t) + "\">" + _htmlEscape(t) + "</option>";
+  }).join("");
+
+  var createForm =
+    "<div class=\"panel mt mw-40\"><h3 class=\"subhead\">Create an earn rule</h3>" +
+      "<p class=\"meta\">An earn rule grants points when a trigger fires. points/unit is the multiplier for per_dollar_spent / per_purchase and the flat amount for the bonus triggers. Customers earn only from active rules.</p>" +
+      "<form method=\"post\" action=\"/admin/loyalty/earn-rules\">" +
+        _setupField("Slug", "slug", "", "text", "Lowercase letters, digits, dashes (e.g. spend-1pt-per-dollar).", " maxlength=\"100\" required") +
+        "<label class=\"form-field\"><span>Trigger</span><select name=\"trigger\">" + triggerOpts + "</select></label>" +
+        _setupField("Points per unit", "points_per_unit", "", "number", "Positive integer.", " min=\"1\" step=\"1\" required class=\"input-code\"") +
+        _setupField("Max per event", "max_per_event", "", "number", "Optional cap so a huge order doesn't mint a giant balance. Leave blank for uncapped.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+        _setupField("Customer statuses", "customer_status_in", "", "text", "Optional comma-separated list (e.g. active, vip). Blank means every customer is eligible.", " maxlength=\"256\"") +
+        "<label class=\"kv\"><input type=\"checkbox\" name=\"active\" value=\"on\" checked> Active — show this rule to customers and award on its trigger.</label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create earn rule</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Earn rules</h2>" +
+    "<p class=\"meta\"><a href=\"/admin/loyalty\">&larr; Loyalty</a></p>" +
+    created + saved + archived + notice + table + createForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Earn rules", bodyHtml, "loyalty", opts.nav_available);
+}
+
+// Earn-rule detail — the rule's stored fields and an edit form. trigger
+// is immutable on update (the primitive refuses a change), so the form
+// shows it read-only.
+function renderAdminLoyaltyEarnRule(opts) {
+  opts = opts || {};
+  var r = opts.rule;
+  if (!r) {
+    var nf = "<section><h2>Earn rule</h2><p class=\"empty\">Earn rule not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/loyalty/earn-rules\">Back to earn rules</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Earn rule", nf, "loyalty", opts.nav_available);
+  }
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var enc = encodeURIComponent(r.slug);
+  var statusList = (r.customer_status_in && r.customer_status_in.length) ? r.customer_status_in.join(", ") : "";
+  var isArchived = r.archived_at != null;
+
+  var editForm = isArchived
+    ? "<div class=\"panel mw-40\"><p class=\"empty\">This rule is archived and can no longer be edited. Archived rules don't award points or show to customers.</p></div>"
+    : "<div class=\"panel mw-40\"><h3 class=\"subhead\">Edit</h3>" +
+        "<form method=\"post\" action=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "/edit\">" +
+          _setupField("Points per unit", "points_per_unit", String(r.points_per_unit), "number", "Positive integer.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+          _setupField("Max per event", "max_per_event", r.max_per_event == null ? "" : String(r.max_per_event), "number", "Blank or 0 clears the cap.", " min=\"0\" step=\"1\" class=\"input-code\"") +
+          _setupField("Customer statuses", "customer_status_in", statusList, "text", "Comma-separated; blank means all customers.", " maxlength=\"256\"") +
+          "<input type=\"hidden\" name=\"active_present\" value=\"1\">" +
+          "<label class=\"kv\"><input type=\"checkbox\" name=\"active\" value=\"on\"" + (r.active ? " checked" : "") + "> Active</label>" +
+          "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save rule</button></div>" +
+        "</form>" +
+      "</div>";
+
+  var archiveBlock = isArchived ? "" :
+    "<div class=\"actions-row mt-1\">" +
+      "<form method=\"post\" action=\"/admin/loyalty/earn-rules/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+        "<button class=\"btn btn--danger\" type=\"submit\">Archive rule</button></form>" +
+    "</div>";
+
+  var head =
+    "<p class=\"meta\"><a href=\"/admin/loyalty/earn-rules\">&larr; Earn rules</a> · " +
+      "<span class=\"status-pill paid\">" + _htmlEscape(r.trigger) + "</span> · " +
+      _loyaltyStatusPill(r.active, r.archived_at) + "</p>";
+
+  var body = "<section><h2>" + _htmlEscape(r.slug) + "</h2>" + saved + notice + head + editForm + archiveBlock + "</section>";
+  return _renderAdminShell(opts.shop_name, "Earn rule", body, "loyalty", opts.nav_available);
+}
+
+// Rewards-catalog list + create form. A reward must be active (and not
+// archived) to appear in the customer's redemption catalog, so the create
+// form defaults active on and the list flags inactive / archived rows.
+function renderAdminLoyaltyRewards(opts) {
+  opts = opts || {};
+  var rewards = opts.rewards || [];
+  var kinds = opts.kinds || loyaltyRedemptionModule.KINDS;
+  var created  = opts.created  ? "<div class=\"banner banner--ok\">Reward saved.</div>" : "";
+  var saved    = opts.saved    ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var archived = opts.archived ? "<div class=\"banner banner--ok\">Reward archived.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var bodyRows = rewards.map(function (rw) {
+    var enc = encodeURIComponent(rw.slug);
+    return "<tr>" +
+      "<td><a href=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(rw.slug) + "</strong></a></td>" +
+      "<td>" + _htmlEscape(rw.title) + "</td>" +
+      "<td>" + _htmlEscape(rw.kind) + "</td>" +
+      "<td>" + _loyaltyRewardValueLabel(rw) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(rw.point_cost)) + "</td>" +
+      "<td>" + _loyaltyStatusPill(rw.active, rw.archived_at) + "</td>" +
+      "<td><div class=\"actions-row\">" +
+        "<a class=\"btn btn--ghost\" href=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "\">Manage</a>" +
+        (rw.archived_at == null
+          ? "<form method=\"post\" action=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+              "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>"
+          : "") +
+      "</div></td>" +
+    "</tr>";
+  }).join("");
+  var table = rewards.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Slug</th><th scope=\"col\">Title</th><th scope=\"col\">Kind</th><th scope=\"col\">Value</th><th scope=\"col\" class=\"num\">Point cost</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No rewards yet.</p>";
+
+  var kindOpts = kinds.map(function (k) {
+    return "<option value=\"" + _htmlEscape(k) + "\">" + _htmlEscape(k) + "</option>";
+  }).join("");
+
+  var createForm =
+    "<div class=\"panel mt mw-40\"><h3 class=\"subhead\">Create a reward</h3>" +
+      "<p class=\"meta\">A reward debits points at redemption. The value field's meaning depends on the kind: discount_percent → a whole-number percent (1–100); discount_amount → minor units off; free_product → a product id; free_shipping → leave it blank. A reward must be active to appear to customers.</p>" +
+      "<form method=\"post\" action=\"/admin/loyalty/rewards\">" +
+        _setupField("Slug", "slug", "", "text", "Letters, digits, dashes, dots, underscores.", " maxlength=\"80\" required") +
+        "<label class=\"form-field\"><span>Kind</span><select name=\"kind\">" + kindOpts + "</select></label>" +
+        _setupField("Title", "title", "", "text", "Shown to customers in the catalog.", " maxlength=\"200\" required") +
+        _setupField("Point cost", "point_cost", "", "number", "Positive integer — points spent to redeem.", " min=\"1\" step=\"1\" required class=\"input-code\"") +
+        _setupField("Value (number)", "value_number", "", "number", "percent (1–100) or amount in minor units. Leave blank for free_product / free_shipping.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+        _setupField("Value (product id)", "value_text", "", "text", "Only for free_product — the product id the reward grants.", " maxlength=\"128\"") +
+        _setupField("Max per customer", "max_per_customer", "", "number", "Optional lifetime cap per customer. Blank for unlimited.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+        _setupField("Expires (days)", "expires_days_after_redemption", "", "number", "Optional — an unconsumed redemption expires after N days. Blank never expires.", " min=\"1\" step=\"1\" class=\"input-code\"") +
+        "<label class=\"kv\"><input type=\"checkbox\" name=\"active\" value=\"on\" checked> Active — show this reward in the customer catalog.</label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create reward</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Rewards catalog</h2>" +
+    "<p class=\"meta\"><a href=\"/admin/loyalty\">&larr; Loyalty</a></p>" +
+    created + saved + archived + notice + table + createForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Rewards catalog", bodyHtml, "loyalty", opts.nav_available);
+}
+
+// Reward detail — the reward's stored fields and an edit form. kind is
+// immutable on update (the primitive validates value_json against the
+// stored kind), so the form shows it read-only and re-validates value on
+// change.
+function renderAdminLoyaltyReward(opts) {
+  opts = opts || {};
+  var rw = opts.reward;
+  if (!rw) {
+    var nf = "<section><h2>Reward</h2><p class=\"empty\">Reward not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/loyalty/rewards\">Back to rewards</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Reward", nf, "loyalty", opts.nav_available);
+  }
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var enc = encodeURIComponent(rw.slug);
+  var isArchived = rw.archived_at != null;
+  var v = rw.value_json || {};
+  var valueNumber = rw.kind === "discount_percent" ? (v.percent == null ? "" : String(v.percent))
+                  : rw.kind === "discount_amount"  ? (v.amount_minor == null ? "" : String(v.amount_minor))
+                  : "";
+  var valueText = rw.kind === "free_product" ? String(v.product_id || "") : "";
+
+  var editForm = isArchived
+    ? "<div class=\"panel mw-40\"><p class=\"empty\">This reward is archived. Archived rewards stay readable for past redemptions but never show to customers.</p></div>"
+    : "<div class=\"panel mw-40\"><h3 class=\"subhead\">Edit</h3>" +
+        "<form method=\"post\" action=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "/edit\">" +
+          _setupField("Title", "title", rw.title, "text", "", " maxlength=\"200\"") +
+          _setupField("Point cost", "point_cost", String(rw.point_cost), "number", "", " min=\"1\" step=\"1\" class=\"input-code\"") +
+          (rw.kind === "free_product"
+            ? _setupField("Value (product id)", "value_text", valueText, "text", "Leave unchanged to keep the current product.", " maxlength=\"128\"")
+            : rw.kind === "free_shipping"
+              ? "<p class=\"meta\">free_shipping carries no value field.</p>"
+              : _setupField("Value (number)", "value_number", valueNumber, "number", "percent (1–100) or amount in minor units.", " min=\"1\" step=\"1\" class=\"input-code\"")) +
+          _setupField("Max per customer", "max_per_customer", rw.max_per_customer == null ? "" : String(rw.max_per_customer), "number", "", " min=\"1\" step=\"1\" class=\"input-code\"") +
+          _setupField("Expires (days)", "expires_days_after_redemption", rw.expires_days_after_redemption == null ? "" : String(rw.expires_days_after_redemption), "number", "", " min=\"1\" step=\"1\" class=\"input-code\"") +
+          "<input type=\"hidden\" name=\"active_present\" value=\"1\">" +
+          "<label class=\"kv\"><input type=\"checkbox\" name=\"active\" value=\"on\"" + (rw.active ? " checked" : "") + "> Active — show in the customer catalog.</label>" +
+          "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save reward</button></div>" +
+        "</form>" +
+      "</div>";
+
+  var archiveBlock = isArchived ? "" :
+    "<div class=\"actions-row mt-1\">" +
+      "<form method=\"post\" action=\"/admin/loyalty/rewards/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+        "<button class=\"btn btn--danger\" type=\"submit\">Archive reward</button></form>" +
+    "</div>";
+
+  var head =
+    "<p class=\"meta\"><a href=\"/admin/loyalty/rewards\">&larr; Rewards catalog</a> · " +
+      "<span class=\"status-pill paid\">" + _htmlEscape(rw.kind) + "</span> · " +
+      _loyaltyStatusPill(rw.active, rw.archived_at) + " · " +
+      "<code class=\"order-id\">" + _htmlEscape(String(rw.point_cost)) + " pts</code></p>";
+
+  var body = "<section><h2>" + _htmlEscape(rw.title) + "</h2>" + saved + notice + head + editForm + archiveBlock + "</section>";
+  return _renderAdminShell(opts.shop_name, "Reward", body, "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
@@ -11239,5 +12119,10 @@ module.exports = {
   renderAdminDiscountAllocation: renderAdminDiscountAllocation,
   renderAdminQuantityDiscounts: renderAdminQuantityDiscounts,
   renderAdminQuantityDiscount:  renderAdminQuantityDiscount,
+  renderAdminLoyalty:           renderAdminLoyalty,
+  renderAdminLoyaltyEarnRules:  renderAdminLoyaltyEarnRules,
+  renderAdminLoyaltyEarnRule:   renderAdminLoyaltyEarnRule,
+  renderAdminLoyaltyRewards:    renderAdminLoyaltyRewards,
+  renderAdminLoyaltyReward:     renderAdminLoyaltyReward,
   renderAdminConfirm:      renderAdminConfirm,
 };

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.23",
+  "version": "0.3.24",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",

package/package.json

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