@blamejs/blamejs-shop 0.3.22 → 0.3.24

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.
@@ -6924,6 +7455,21 @@ function _renderTemplate(template, vars) {
   return out;
 }
 
+// Splice a fully-rendered HTML fragment into `html` at the first
+// occurrence of a literal `RAW_*` token, inserting the fragment LITERALLY.
+//
+// `String.prototype.replace(token, replacementString)` gives the
+// replacement string special meaning to `$` sequences — `$$`, `$&`,
+// `` $` `` (the text before the match), `$'` (the text after the match),
+// `$N`. An admin page body that contains a dollar followed by a backtick
+// would otherwise splice the page chrome into the body, and any other
+// dollar sequence corrupts the output. Passing a REPLACER FUNCTION makes
+// `String.replace` insert the return value verbatim, with no dollar
+// interpretation. Mirrors the storefront's `_spliceRaw`.
+function _spliceRaw(html, token, fragment) {
+  return html.replace(token, function () { return fragment == null ? "" : String(fragment); });
+}
+
 function _sparkSvg(byDay, currency) {
   // SVG sparkline rendered server-side from revenue-by-day rows of
   // the dashboard's primary currency. Returns an empty placeholder
@@ -7069,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" },
@@ -7106,8 +7653,10 @@ function _renderAdminShell(shopName, subtitle, bodyHtml, active, available) {
     nav:          "RAW_NAV",
     body:         "RAW_BODY",
   }).replace("RAW_ADMIN_CSS", _adminStylesheetLink())
-    .replace("RAW_NAV", _adminNav(active, available))
-    .replace("RAW_BODY", bodyHtml);
+    .replace("RAW_NAV", _adminNav(active, available));
+  // Splice the admin body literally so a `$`-bearing fragment can't trip
+  // `String.replace`'s dollar substitution. See `_spliceRaw`.
+  html = _spliceRaw(html, "RAW_BODY", bodyHtml);
   // Token every admin POST form with the per-request double-submit CSRF value
   // (seeded on the ALS by mount()'s sync middleware). Single funnel — every
   // authenticated admin page assembles here — so this is the one place the
@@ -10943,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
@@ -11222,5 +12119,10 @@ module.exports = {
   renderAdminDiscountAllocation: renderAdminDiscountAllocation,
   renderAdminQuantityDiscounts: renderAdminQuantityDiscounts,
   renderAdminQuantityDiscount:  renderAdminQuantityDiscount,
+  renderAdminLoyalty:           renderAdminLoyalty,
+  renderAdminLoyaltyEarnRules:  renderAdminLoyaltyEarnRules,
+  renderAdminLoyaltyEarnRule:   renderAdminLoyaltyEarnRule,
+  renderAdminLoyaltyRewards:    renderAdminLoyaltyRewards,
+  renderAdminLoyaltyReward:     renderAdminLoyaltyReward,
   renderAdminConfirm:      renderAdminConfirm,
 };