@blamejs/blamejs-shop 0.3.24 → 0.3.25

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.25 (2026-05-30) — **Open an individual customer to see their orders and manage store credit, notes, and loyalty.** The customers list was view-only — there was no way to open a single customer. Each customer now has a detail screen showing their identity, recent orders (linked), store-credit balance with a grant/deduct control, loyalty balance and tier (with a link to adjust points), internal operator notes, and the segments they belong to. A store-credit grant or deduction requires a reason and is written to the store-credit ledger, an over-deduction is refused, and segment membership is shown read-only because it is computed from purchase behavior rather than set by hand. **Added:** *Customer detail screen* — Opening a customer from the roster now shows their record, recent orders, store-credit balance with a reason-gated grant/deduct (recorded in the store-credit ledger; an over-deduction is refused), their loyalty balance and tier with a link to adjust points, and an internal notes log you can add to. The segments a customer belongs to are listed read-only, since membership is derived from their behavior. Customer identity fields remain read-only by design.
+
 - 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.

package/lib/admin.js

@@ -497,6 +497,9 @@ function mount(router, deps) {
   var productQa     = deps.productQa     || null;   // Q&A moderation endpoints disabled when absent
   var returns       = deps.returns       || null;   // RMA moderation endpoints disabled when absent
   var customers     = deps.customers     || null;   // read-only customers console disabled when absent
+  var storeCredit      = deps.storeCredit      || null;  // per-customer store-credit panel + grant/deduct disabled when absent
+  var customerNotes    = deps.customerNotes    || null;  // per-customer CRM notes panel disabled when absent
+  var customerSegments = deps.customerSegments || null;  // per-customer segment-membership panel disabled when absent
   var orderTracking = deps.orderTracking || null;   // shipment/tracking panel disabled when absent
   var salesReports  = deps.salesReports  || null;   // /admin/reports degrades to an unconfigured notice when absent
   var printReceipts = deps.printReceipts || null;   // order receipt document disabled when absent
@@ -2597,6 +2600,276 @@ function mount(router, deps) {
         }));
       },
     ));
+
+    // ---- customer detail ----------------------------------------------
+    // The per-customer operator screen. The roster (above) is read-only by
+    // design — the storefront owns account mutation via the passkey / OIDC
+    // ceremonies — so this screen READS the customer's identity fields +
+    // recent orders, and WRITES only the operator-managed satellites:
+    // store-credit (an audited wallet), CRM notes, and (read-only) segment
+    // membership. It does NOT edit the customer profile: the only mutable
+    // identity field is display_name, and the roster's stated design intent
+    // is read-only identity, so the operator-managed satellites are the
+    // write surface here. Each satellite panel renders only when its
+    // primitive is wired; an unwired one degrades to a "not wired" notice
+    // rather than vanishing.
+
+    // Free-text reason gate for a store-credit adjustment. A store-credit
+    // grant / deduct is a money-adjacent action, so the reason is MANDATORY
+    // — it rides into the ledger row's source_ref (grant) / reason (deduct)
+    // column so every balance change is attributed. Throws a TypeError
+    // (→ 400) on a missing / blank / over-long / control-byte reason so the
+    // form surfaces a clean notice and writes nothing. 128 chars matches the
+    // primitive's source_ref cap (storeCredit MAX_SOURCE_REF_LEN); the
+    // primitive re-validates, so this gate fails fast with operator-facing
+    // text rather than relying on the deeper throw.
+    var STORE_CREDIT_REASON_MAX = 128;
+    function _storeCreditReason(raw) {
+      if (raw == null) throw new TypeError("admin: a reason is required for a store-credit adjustment");
+      var s = String(raw).trim();
+      if (!s.length) throw new TypeError("admin: a reason is required for a store-credit adjustment");
+      if (s.length > STORE_CREDIT_REASON_MAX) throw new TypeError("admin: reason must be <= " + STORE_CREDIT_REASON_MAX + " chars");
+      if (/[\x00-\x1f\x7f]/.test(s)) throw new TypeError("admin: reason must not contain control bytes");
+      return s;
+    }
+    // Coerce the grant/deduct form into a positive minor-unit amount + a
+    // direction. `direction` is "grant" or "deduct"; `amount_minor` is a
+    // positive integer (the strict reader refuses "", floats, "12abc").
+    function _storeCreditDirection(body) {
+      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;
+    }
+
+    // Best-effort hydrate of a customer's satellites for the detail render.
+    // A satellite whose primitive isn't wired (or whose table isn't migrated
+    // on a given deploy) degrades that panel to a notice rather than 500-ing
+    // the page — same discipline as the order-detail tracking panel.
+    async function _customerDetailModel(customer, flags) {
+      flags = flags || {};
+      var currency = await _defaultCurrency();
+
+      var recentOrders = [];
+      try {
+        var ordersPage = await order.listForCustomer(customer.id, { limit: 10 });
+        recentOrders = ordersPage.rows || [];
+      } catch (_e) { recentOrders = []; }
+
+      var creditBalanceMinor = null;
+      var creditHistory = [];
+      if (storeCredit) {
+        try { creditBalanceMinor = (await storeCredit.balance(customer.id)).balance_minor; }
+        catch (_e) { creditBalanceMinor = null; }
+        try { creditHistory = (await storeCredit.history({ customer_id: customer.id, limit: 10 })).rows || []; }
+        catch (_e) { creditHistory = []; }
+      }
+
+      var loyaltyInfo = null;
+      if (deps.loyalty) {
+        try { loyaltyInfo = await deps.loyalty.balance(customer.id); }
+        catch (_e) { loyaltyInfo = null; }
+      }
+
+      var notes = [];
+      if (customerNotes) {
+        try { notes = (await customerNotes.notesForCustomer({ customer_id: customer.id, limit: 20 })).rows || []; }
+        catch (_e) { notes = []; }
+      }
+
+      var segments = null;
+      if (customerSegments) {
+        try { segments = await customerSegments.segmentsForCustomer(customer.id); }
+        catch (_e) { segments = []; }
+      }
+
+      return Object.assign({
+        shop_name:      deps.shop_name,
+        nav_available:  navAvailable,
+        customer:       customer,
+        currency:       currency,
+        recent_orders:  recentOrders,
+        can_store_credit:    !!storeCredit,
+        store_credit_minor:  creditBalanceMinor,
+        store_credit_history: creditHistory,
+        loyalty:        loyaltyInfo,
+        loyalty_link:   !!deps.loyalty,
+        can_notes:      !!customerNotes,
+        notes:          notes,
+        can_segments:   !!customerSegments,
+        segments:       segments,
+      }, flags);
+    }
+
+    // Resolve the :id to a customer record. A malformed id throws inside the
+    // defensive id reader (customers.get) — caught and treated as "no such
+    // customer" so the route renders a clean 404, never a 500. An unknown
+    // (well-formed) id returns null → the same 404.
+    async function _resolveCustomer(id) {
+      try { return await customers.get(id); }
+      catch (e) { if (e instanceof TypeError) return null; throw e; }
+    }
+
+    router.get("/admin/customers/:id", _pageOrApi(true,
+      R(async function (req, res) {
+        var c = await _resolveCustomer(req.params.id);
+        if (!c) return _problem(res, 404, "customer-not-found");
+        // Bearer JSON: the customer record + its satellites (no HTML).
+        var model = await _customerDetailModel(c, {});
+        _json(res, 200, {
+          customer:             c,
+          recent_orders:        model.recent_orders,
+          store_credit_minor:   model.store_credit_minor,
+          store_credit_history: model.store_credit_history,
+          loyalty:              model.loyalty,
+          notes:                model.notes,
+          segments:             model.segments,
+        });
+      }),
+      async function (req, res) {
+        var c = await _resolveCustomer(req.params.id);
+        if (!c) return _sendHtml(res, 404, renderAdminCustomers({
+          shop_name: deps.shop_name, nav_available: navAvailable, customers: [], notice: "Customer not found.",
+        }));
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var flags = {
+          saved:        url && url.searchParams.get("saved"),
+          credit_notice: url && url.searchParams.get("credit_err") ? url.searchParams.get("credit_err") : null,
+          note_notice:   url && url.searchParams.get("note_err") ? url.searchParams.get("note_err") : null,
+        };
+        _sendHtml(res, 200, renderAdminCustomerDetail(await _customerDetailModel(c, flags)));
+      },
+    ));
+
+    // ---- store-credit adjustment (grant / deduct) ----------------------
+    // Scoped to the :id customer — the customer the adjustment targets is the
+    // path id, never a form field, so an operator can't grant credit to a
+    // different customer than the screen they're on. A grant composes
+    // storeCredit.credit (source goodwill / source_ref reason); a deduct
+    // composes storeCredit.expire (the operator-initiated burn that carries a
+    // required reason). Over-deduction is refused at the route as a clean 409
+    // BEFORE any write — the expire primitive caps silently at the balance,
+    // so the route enforces the no-overdraft contract by reading the balance
+    // first (nothing is written when the deduction exceeds the balance).
+    if (storeCredit) {
+      router.post("/admin/customers/:id/store-credit", _pageOrApi(false,
+        W("customer.store_credit.adjust", async function (req, res) {
+          var c = await _resolveCustomer(req.params.id);
+          if (!c) return _problem(res, 404, "customer-not-found");
+          var body = req.body || {};
+          var dir, amount, reason;
+          try {
+            dir    = _storeCreditDirection(body);
+            amount = _strictMinorInt(body.amount_minor, "admin", "amount_minor");
+            if (amount <= 0) throw new TypeError("admin: amount_minor must be a positive integer (minor units)");
+            reason = _storeCreditReason(body.reason);
+          } catch (e) {
+            if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+            throw e;
+          }
+          var result;
+          if (dir === "grant") {
+            result = await storeCredit.credit({
+              customer_id: c.id, amount_minor: amount, source: "goodwill", source_ref: reason,
+            });
+          } else {
+            var bal = (await storeCredit.balance(c.id)).balance_minor;
+            if (amount > bal) {
+              return _problem(res, 409, "insufficient-balance", "Deduction exceeds the available store-credit balance.");
+            }
+            result = await storeCredit.expire({ customer_id: c.id, amount_minor: amount, reason: reason });
+          }
+          _json(res, 200, result);
+          return { id: c.id };
+        }),
+        async function (req, res) {
+          var c = await _resolveCustomer(req.params.id);
+          if (!c) return _sendHtml(res, 404, renderAdminCustomers({
+            shop_name: deps.shop_name, nav_available: navAvailable, customers: [], notice: "Customer not found.",
+          }));
+          var body = req.body || {};
+          var dir, amount, reason;
+          try {
+            dir    = _storeCreditDirection(body);
+            amount = _strictMinorInt(body.amount_minor, "admin", "amount_minor");
+            if (amount <= 0) throw new TypeError("admin: amount_minor must be a positive integer (minor units)");
+            reason = _storeCreditReason(body.reason);
+          } catch (e) {
+            var n = _safeNotice(e, "customer.store_credit.adjust");
+            return _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) +
+              "?credit_err=" + encodeURIComponent(n.message.replace(/^admin[.:]\s*/, "")));
+          }
+          if (dir === "deduct") {
+            var bal = (await storeCredit.balance(c.id)).balance_minor;
+            if (amount > bal) {
+              return _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) +
+                "?credit_err=" + encodeURIComponent("That deduction exceeds the available balance."));
+            }
+          }
+          try {
+            if (dir === "grant") {
+              await storeCredit.credit({ customer_id: c.id, amount_minor: amount, source: "goodwill", source_ref: reason });
+            } else {
+              await storeCredit.expire({ customer_id: c.id, amount_minor: amount, reason: reason });
+            }
+          } catch (e) {
+            var n2 = _safeNotice(e, "customer.store_credit.adjust");
+            return _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) +
+              "?credit_err=" + encodeURIComponent(n2.message.replace(/^(?:admin|storeCredit)[.:]\s*/, "")));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer.store_credit.adjust", outcome: "success", metadata: { id: c.id, direction: dir } });
+          _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) + "?saved=1");
+        },
+      ));
+    }
+
+    // ---- customer notes (add) ------------------------------------------
+    // Scoped to the :id customer — the note attaches to the path customer.
+    // Composes customerNotes.addNote (the body is required + length-capped by
+    // the primitive). The author is stamped "operator" — the console never
+    // adds a system note. Bad input (empty / over-long body, bad kind) is a
+    // clean 4xx with nothing written.
+    if (customerNotes) {
+      router.post("/admin/customers/:id/notes", _pageOrApi(false,
+        W("customer.note.add", async function (req, res) {
+          var c = await _resolveCustomer(req.params.id);
+          if (!c) return _problem(res, 404, "customer-not-found");
+          var body = req.body || {};
+          var note;
+          try {
+            note = await customerNotes.addNote({
+              customer_id: c.id, author: "operator",
+              body: body.body, kind: (body.kind != null && body.kind !== "") ? body.kind : undefined,
+            });
+          } catch (e) {
+            if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+            throw e;
+          }
+          _json(res, 201, note);
+          return { id: c.id };
+        }),
+        async function (req, res) {
+          var c = await _resolveCustomer(req.params.id);
+          if (!c) return _sendHtml(res, 404, renderAdminCustomers({
+            shop_name: deps.shop_name, nav_available: navAvailable, customers: [], notice: "Customer not found.",
+          }));
+          var body = req.body || {};
+          try {
+            await customerNotes.addNote({
+              customer_id: c.id, author: "operator",
+              body: body.body, kind: (body.kind != null && body.kind !== "") ? body.kind : undefined,
+            });
+          } catch (e) {
+            var n = _safeNotice(e, "customer.note.add");
+            return _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) +
+              "?note_err=" + encodeURIComponent(n.message.replace(/^(?:admin|customerNotes)[.:]\s*/, "")));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer.note.add", outcome: "success", metadata: { id: c.id } });
+          _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) + "?saved=1");
+        },
+      ));
+    }
   }
 
   // ---- refunds --------------------------------------------------------
@@ -8750,17 +9023,21 @@ function renderAdminCustomers(opts) {
     }
     var method = methodCells.length ? methodCells.join(" ") : "<span class=\"meta\">—</span>";
     var orders = orderCounts[c.id] || 0;
+    var enc = encodeURIComponent(c.id);
     return "<tr>" +
-      "<td><strong>" + _htmlEscape(c.display_name) + "</strong></td>" +
+      "<td><a href=\"/admin/customers/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(c.display_name) + "</strong></a></td>" +
       "<td><code class=\"order-id\">" + _htmlEscape(String(c.id).slice(0, 8)) + "</code></td>" +
       "<td>" + _htmlEscape(_fmtDate(c.created_at)) + "</td>" +
       "<td>" + method + "</td>" +
       "<td class=\"num\">" + _htmlEscape(String(orders)) + "</td>" +
+      "<td><a class=\"btn btn--ghost btn--sm\" href=\"/admin/customers/" + _htmlEscape(enc) + "\">Manage</a></td>" +
       "</tr>";
   }).join("");
 
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
   var table = customers.length
-    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Name</th><th scope=\"col\">ID</th><th scope=\"col\">Joined</th><th scope=\"col\">Sign-in method</th><th scope=\"col\" class=\"num\">Orders</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Name</th><th scope=\"col\">ID</th><th scope=\"col\">Joined</th><th scope=\"col\">Sign-in method</th><th scope=\"col\" class=\"num\">Orders</th><th scope=\"col\"><span class=\"sr-only\">Manage</span></th></tr></thead><tbody>" + rows + "</tbody></table></div>"
     : "<p class=\"empty\">No customers yet.</p>";
 
   // Cursor pager — a Next link when the page filled and more rows remain.
@@ -8769,12 +9046,165 @@ function renderAdminCustomers(opts) {
     ? "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/customers?cursor=" + _htmlEscape(encodeURIComponent(opts.next_cursor)) + "\">Next page <span aria-hidden=\"true\">→</span></a></div>"
     : "";
 
-  var body = "<section><h2>Customers</h2>" +
-    "<p class=\"meta\">Accounts are passwordless — customers enrol a passkey or sign in with a federated provider. Email addresses aren't stored in the clear, so they're not shown here.</p>" +
+  var body = "<section><h2>Customers</h2>" + notice +
+    "<p class=\"meta\">Accounts are passwordless — customers enrol a passkey or sign in with a federated provider. Email addresses aren't stored in the clear, so they're not shown here. Open a customer to manage their store credit, loyalty, notes, and segment membership.</p>" +
     table + pager + "</section>";
   return _renderAdminShell(opts.shop_name, "Customers", body, "customers", opts.nav_available);
 }
 
+// Per-customer operator detail screen. READS the customer's identity fields
+// + recent orders; WRITES only the operator-managed satellites (store-credit
+// + CRM notes). Segment membership is read-only — it is rule-derived (RFM
+// predicates recomputed by the scheduler), so there is no per-customer
+// manual assign / remove in the segments primitive; the panel shows the
+// segments the customer currently sits in and says so. Every panel renders
+// only when its primitive is wired.
+function renderAdminCustomerDetail(opts) {
+  opts = opts || {};
+  var c = opts.customer || {};
+  var currency = opts.currency || "USD";
+  var enc = encodeURIComponent(c.id);
+
+  var saved = opts.saved ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+
+  // ---- identity (read-only) -----------------------------------------
+  var identity = "<div class=\"panel\"><h3 class=\"subhead\">Customer</h3>" +
+    "<dl class=\"kv-list\">" +
+      "<div><dt>Name</dt><dd>" + _htmlEscape(c.display_name) + "</dd></div>" +
+      "<div><dt>Customer id</dt><dd><code class=\"order-id\">" + _htmlEscape(String(c.id)) + "</code></dd></div>" +
+      "<div><dt>Joined</dt><dd>" + _htmlEscape(_fmtDate(c.created_at)) + "</dd></div>" +
+    "</dl>" +
+    "<p class=\"meta\">Identity is read-only here — customers manage their own profile through the storefront (passkey / federated sign-in). Email addresses aren't stored in the clear.</p>" +
+  "</div>";
+
+  // ---- recent orders -------------------------------------------------
+  var orderRows = (opts.recent_orders || []).map(function (o) {
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/orders/" + _htmlEscape(encodeURIComponent(o.id)) + "\">" + _htmlEscape(String(o.id).slice(0, 8)) + "</a></td>" +
+      "<td><span class=\"status-pill " + _htmlEscape(o.status) + "\">" + _htmlEscape(o.status) + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(pricing.format(o.grand_total_minor, o.currency)) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(o.created_at)) + "</td>" +
+    "</tr>";
+  }).join("");
+  var ordersPanel = "<div class=\"panel\"><h3 class=\"subhead\">Recent orders</h3>" +
+    ((opts.recent_orders || []).length
+      ? "<table><thead><tr><th scope=\"col\">Order</th><th scope=\"col\">Status</th><th scope=\"col\" class=\"num\">Total</th><th scope=\"col\">Placed</th></tr></thead><tbody>" + orderRows + "</tbody></table>"
+      : "<p class=\"empty\">No orders yet.</p>") +
+  "</div>";
+
+  // ---- store credit --------------------------------------------------
+  var creditPanel;
+  if (!opts.can_store_credit) {
+    creditPanel = "<div class=\"panel\"><h3 class=\"subhead\">Store credit</h3>" +
+      "<p class=\"empty\">Store credit isn't wired in this deployment.</p></div>";
+  } else {
+    var bal = opts.store_credit_minor != null ? opts.store_credit_minor : 0;
+    var creditNotice = opts.credit_notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.credit_notice) + "</div>" : "";
+    var histRows = (opts.store_credit_history || []).map(function (h) {
+      var sign = h.kind === "credit" ? "+" : "−";
+      var note = h.source_ref != null ? h.source_ref : (h.source != null ? h.source : "");
+      return "<tr>" +
+        "<td>" + _htmlEscape(h.kind) + "</td>" +
+        "<td class=\"num\">" + _htmlEscape(sign + pricing.format(h.amount_minor, currency)) + "</td>" +
+        "<td class=\"num\">" + _htmlEscape(pricing.format(h.balance_after_minor, currency)) + "</td>" +
+        "<td>" + _htmlEscape(note) + "</td>" +
+        "<td>" + _htmlEscape(_fmtDate(h.occurred_at)) + "</td>" +
+      "</tr>";
+    }).join("");
+    var histTable = (opts.store_credit_history || []).length
+      ? "<table><thead><tr><th scope=\"col\">Kind</th><th scope=\"col\" class=\"num\">Amount</th><th scope=\"col\" class=\"num\">Balance after</th><th scope=\"col\">Reason</th><th scope=\"col\">When</th></tr></thead><tbody>" + histRows + "</tbody></table>"
+      : "<p class=\"empty\">No store-credit activity yet.</p>";
+    creditPanel = "<div class=\"panel\"><h3 class=\"subhead\">Store credit</h3>" +
+      creditNotice +
+      "<p class=\"stat-figure\">" + _htmlEscape(pricing.format(bal, currency)) + "</p>" +
+      "<p class=\"meta\">Account-bound balance — applied at checkout. Every grant or deduct is recorded with your reason in the ledger below.</p>" +
+      "<form method=\"post\" action=\"/admin/customers/" + _htmlEscape(enc) + "/store-credit\">" +
+        "<fieldset class=\"box\"><legend class=\"legend-sm\">Direction</legend>" +
+          "<label class=\"kv\"><input type=\"radio\" name=\"direction\" value=\"grant\" checked> Grant (add credit)</label>" +
+          "<label class=\"kv\"><input type=\"radio\" name=\"direction\" value=\"deduct\"> Deduct (remove credit)</label>" +
+        "</fieldset>" +
+        "<label class=\"form-field\"><span>Amount (" + _htmlEscape(currency) + " minor units)</span>" +
+          "<input type=\"number\" name=\"amount_minor\" min=\"1\" step=\"1\" required class=\"input-code\" placeholder=\"e.g. 500 = " + _htmlEscape(pricing.format(500, currency)) + "\"></label>" +
+        "<label class=\"form-field\"><span>Reason</span>" +
+          "<input type=\"text\" name=\"reason\" required maxlength=\"128\" placeholder=\"e.g. goodwill for the late delivery\">" +
+          "<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>" +
+      histTable +
+    "</div>";
+  }
+
+  // ---- loyalty -------------------------------------------------------
+  var loyaltyPanel = "";
+  if (opts.loyalty_link) {
+    var loy = opts.loyalty || { balance: 0, lifetime: 0, tier: "bronze" };
+    loyaltyPanel = "<div class=\"panel\"><div class=\"actions-row\"><h3 class=\"subhead\">Loyalty</h3>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/loyalty\">Adjust points</a></div>" +
+      "<dl class=\"kv-list\">" +
+        "<div><dt>Balance</dt><dd>" + _htmlEscape(String(loy.balance)) + " pts</dd></div>" +
+        "<div><dt>Lifetime</dt><dd>" + _htmlEscape(String(loy.lifetime)) + " pts</dd></div>" +
+        "<div><dt>Tier</dt><dd>" + _htmlEscape(String(loy.tier)) + "</dd></div>" +
+      "</dl>" +
+      "<p class=\"meta\">Grant or deduct points from the Loyalty screen — paste this customer's id (above) into the adjustment form.</p>" +
+    "</div>";
+  }
+
+  // ---- notes ---------------------------------------------------------
+  var notesPanel;
+  if (!opts.can_notes) {
+    notesPanel = "<div class=\"panel\"><h3 class=\"subhead\">Notes</h3>" +
+      "<p class=\"empty\">Customer notes aren't wired in this deployment.</p></div>";
+  } else {
+    var noteNotice = opts.note_notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.note_notice) + "</div>" : "";
+    var noteRows = (opts.notes || []).map(function (n) {
+      return "<li><div class=\"note-meta\">" + _htmlEscape(n.kind) + " · " + _htmlEscape(_fmtDate(n.created_at)) + "</div>" +
+        "<div class=\"note-body\">" + _htmlEscape(n.body) + "</div></li>";
+    }).join("");
+    notesPanel = "<div class=\"panel\"><h3 class=\"subhead\">Notes</h3>" +
+      noteNotice +
+      "<p class=\"meta\">Operator-only annotations on this customer. Never shown to the customer.</p>" +
+      ((opts.notes || []).length
+        ? "<ul class=\"note-list\">" + noteRows + "</ul>"
+        : "<p class=\"empty\">No notes yet.</p>") +
+      "<form method=\"post\" action=\"/admin/customers/" + _htmlEscape(enc) + "/notes\">" +
+        "<label class=\"form-field\"><span>Kind</span>" +
+          "<select name=\"kind\">" +
+            "<option value=\"general\">general</option>" +
+            "<option value=\"preference\">preference</option>" +
+            "<option value=\"escalation\">escalation</option>" +
+            "<option value=\"warning\">warning</option>" +
+            "<option value=\"billing\">billing</option>" +
+          "</select></label>" +
+        "<label class=\"form-field\"><span>Note</span>" +
+          "<textarea name=\"body\" required maxlength=\"8000\" rows=\"3\" placeholder=\"e.g. VIP — comp shipping where possible\"></textarea></label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Add note</button></div>" +
+      "</form>" +
+    "</div>";
+  }
+
+  // ---- segments (read-only) ------------------------------------------
+  var segmentsPanel = "";
+  if (opts.can_segments) {
+    var segChips = (opts.segments || []).map(function (s) {
+      return "<span class=\"chip\">" + _htmlEscape(s.title || s.slug) + "</span>";
+    }).join(" ");
+    segmentsPanel = "<div class=\"panel\"><h3 class=\"subhead\">Segments</h3>" +
+      ((opts.segments || []).length
+        ? "<div class=\"chip-row\">" + segChips + "</div>"
+        : "<p class=\"empty\">Not in any segment.</p>") +
+      "<p class=\"meta\">Segment membership is rule-derived — the scheduler recomputes it from each segment's RFM predicates, so there is no manual assign / remove per customer. Define or edit segments under their own console.</p>" +
+    "</div>";
+  }
+
+  var body = "<section>" +
+    "<div class=\"actions-row\"><h2>" + _htmlEscape(c.display_name) + "</h2>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/customers\"><span aria-hidden=\"true\">←</span> All customers</a></div>" +
+    saved +
+    identity + ordersPanel + creditPanel + loyaltyPanel + notesPanel + segmentsPanel +
+  "</section>";
+  return _renderAdminShell(opts.shop_name, c.display_name || "Customer", body, "customers", opts.nav_available);
+}
+
 // The RMA states an operator can filter the returns queue by — drives the
 // filter chips, lifecycle order then terminal.
 var RETURN_STATUS_FILTERS = ["pending", "approved", "received", "refunded", "rejected"];
@@ -12099,6 +12529,7 @@ module.exports = {
   renderAdminOrders:       renderAdminOrders,
   renderAdminOrder:        renderAdminOrder,
   renderAdminCustomers:    renderAdminCustomers,
+  renderAdminCustomerDetail: renderAdminCustomerDetail,
   renderAdminReturns:      renderAdminReturns,
   renderAdminReturn:       renderAdminReturn,
   renderAdminReviews:      renderAdminReviews,

package/lib/asset-manifest.json

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

package/package.json

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