@blamejs/blamejs-shop 0.3.32 → 0.3.34

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.34 (2026-05-31) — **Edit, pin, and archive the internal notes on a customer.** Internal notes on a customer could only be added — a note with a typo or one that was no longer true could not be corrected or removed, which is a liability for notes like "do not ship to this address" or "allergic to X". The customer detail screen now lets you edit a note's text, pin important notes to the top, and archive notes that no longer apply (and restore them). Each action is limited to notes that belong to the customer being viewed. **Added:** *Edit, pin, and archive customer notes* — The notes panel on a customer's detail screen now supports the full lifecycle: edit a note's text to fix or update it, pin the notes that matter so they sort to the top, and archive notes that no longer apply, with a toggle to show archived notes and restore them. Previously notes were append-only, so a wrong or stale note could not be corrected or retired. Every edit, pin, and archive action is scoped to the customer being viewed, so a note can only be changed from the record it belongs to.
+
+- v0.3.33 (2026-05-31) — **Create and manage customer segments from the admin console.** Customer segments could be shown on a customer's profile but there was no way to define or manage them, so the feature could not actually be used. A new Segments screen in the admin console creates rule-based segments from recency, frequency, lifetime-order, spend, average-order-value, and refund-rate criteria, edits their rules, archives and restores them, and recomputes membership on demand — showing how many customers each segment now contains. Segment membership stays rule-derived: it is recalculated from order history, not assigned by hand. **Added:** *Customer segments administration* — A Segments screen in the admin console manages rule-based customer segments. Each segment is defined by RFM-style criteria — how recently and how often a customer orders, their lifetime order count and spend, average order value, and refund rate — and a list shows every segment with its rules, current member count, and status, filterable by active or archived. You can create and edit segments, archive and restore them, and recompute membership on demand, which re-evaluates the rules against order history and reports how many customers match. Membership is always derived from the rules, never assigned per customer.
+
 - v0.3.32 (2026-05-31) — **Collection pages now page through every product instead of stopping at 24.** A collection page showed only its first 24 products and provided no way to reach the rest, so any product past the 24th in a collection was silently unreachable. Collection pages now have previous/next pagination, matching the search results, so a collection of any size can be browsed in full. A shared link to a specific page keeps its position, while the page's canonical URL stays the plain collection address. **Fixed:** *Collection pages paginate* — A collection with more than 24 products was truncated at the first 24 with no way to see the others. Collection pages now carry previous/next pagination — the same control used on search results — so every product in a collection is reachable. The canonical URL remains the bare collection address on every page (so search engines see one collection page, not duplicates), while a shared link to a deeper page preserves its position.
 
 - v0.3.31 (2026-05-31) — **A public help center, authored from the admin console.** The knowledge-base backend was built but had no pages, so there was no way to publish help content or for a shopper to read it. There is now a Help center at /help: a browsable index of published articles grouped by category, and an article page that renders the article, shows a breadcrumb trail in search results, and lets a reader mark whether it was helpful. Operators get a Help center screen in the admin console to write articles, save them as drafts, publish them, and archive them. Article text is written in a small Markdown subset and is fully escaped on the page, and only published, non-archived articles are publicly reachable. **Added:** *Help center for shoppers* — A new /help section lists published articles by category and renders each article at /help/:slug with a breadcrumb (carried into search results as BreadcrumbList structured data) and a "Was this helpful?" control. Article bodies are written in a Markdown subset and escaped on output, and a draft, archived, or unknown article returns a clean 404 — only published articles are ever publicly reachable. · *Help center authoring in the admin console* — A Help center screen lets operators write articles (slug, title, category, body), keep them as drafts, publish or unpublish them, and archive ones that should no longer appear. The list filters by all/published/drafts and shows each article's view count and helpfulness tally, so the team can see what readers are using and which articles need work.

package/lib/admin.js

@@ -516,7 +516,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, knowledgeBase: !!deps.knowledgeBase, 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, supportTickets: !!supportTickets };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, 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, supportTickets: !!supportTickets };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -2674,8 +2674,13 @@ function mount(router, deps) {
       }
 
       var notes = [];
+      var showArchivedNotes = flags.show_archived_notes === true;
       if (customerNotes) {
-        try { notes = (await customerNotes.notesForCustomer({ customer_id: customer.id, limit: 20 })).rows || []; }
+        try {
+          notes = (await customerNotes.notesForCustomer({
+            customer_id: customer.id, limit: 50, include_archived: showArchivedNotes,
+          })).rows || [];
+        }
         catch (_e) { notes = []; }
       }
 
@@ -2698,6 +2703,7 @@ function mount(router, deps) {
         loyalty_link:   !!deps.loyalty,
         can_notes:      !!customerNotes,
         notes:          notes,
+        show_archived_notes: showArchivedNotes,
         can_segments:   !!customerSegments,
         segments:       segments,
       }, flags);
@@ -2716,8 +2722,13 @@ function mount(router, deps) {
       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, {});
+        // Bearer JSON: the customer record + its satellites (no HTML). A
+        // tooling client can opt into the archived notes via
+        // ?notes_archived=1, matching the browser detail-screen toggle.
+        var apiUrl = req.url ? new URL(req.url, "http://localhost") : null;
+        var model = await _customerDetailModel(c, {
+          show_archived_notes: !!(apiUrl && apiUrl.searchParams.get("notes_archived") === "1"),
+        });
         _json(res, 200, {
           customer:             c,
           recent_orders:        model.recent_orders,
@@ -2738,6 +2749,7 @@ function mount(router, deps) {
           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,
+          show_archived_notes: !!(url && url.searchParams.get("notes_archived") === "1"),
         };
         _sendHtml(res, 200, renderAdminCustomerDetail(await _customerDetailModel(c, flags)));
       },
@@ -2870,6 +2882,104 @@ function mount(router, deps) {
           _redirect(res, "/admin/customers/" + encodeURIComponent(c.id) + "?saved=1");
         },
       ));
+
+      // ---- customer notes (edit / pin / archive lifecycle) ---------------
+      // A note belongs to a customer. customerNotes' update / pin / archive
+      // methods move a row by note id alone — they carry no notion of which
+      // customer the operator is acting on — so every per-note write route
+      // under :id MUST first assert the note belongs to THAT customer before
+      // mutating it, or an operator on customer A's screen could edit / pin /
+      // retire customer B's note by guessing its id (an IDOR). This mirrors
+      // the media setPrimary (_mediaBelongsToProduct) + support thread
+      // (_ownedTicket) scoping: load the note, refuse it unless its
+      // customer_id matches the path id. A malformed note id throws a
+      // TypeError inside getNote's UUID guard → a clean 400; a well-formed
+      // unknown id (or one owned by a different customer) returns null /
+      // false → a clean 404, with nothing written either way.
+      async function _noteBelongsToCustomer(noteId, customerId) {
+        var note;
+        try { note = await customerNotes.getNote(noteId); }
+        catch (e) { if (e instanceof TypeError) throw e; return false; }
+        return (note && note.customer_id === customerId) ? note : false;
+      }
+
+      // Map a per-note write to a content-negotiated outcome. `mutate(note)`
+      // performs the customerNotes call (already ownership-checked); on the
+      // bearer path it returns the updated note as JSON, on the browser path
+      // it PRGs back to the detail screen with a saved / note_err banner.
+      // A malformed note id is a clean 400 (bearer) / note_err redirect
+      // (browser); a missing / cross-customer note is a clean 404 (bearer) /
+      // note_err redirect (browser). Nothing is mutated on any refusal.
+      function _noteWriteRoute(routePath, audit, mutate) {
+        router.post(routePath, _pageOrApi(false,
+          W(audit, async function (req, res) {
+            var c = await _resolveCustomer(req.params.id);
+            if (!c) return _problem(res, 404, "customer-not-found");
+            var owned;
+            try { owned = await _noteBelongsToCustomer(req.params.noteId, c.id); }
+            catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+            if (!owned) return _problem(res, 404, "note-not-found");
+            var updated;
+            try { updated = await mutate(owned, req.body || {}); }
+            catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+            _json(res, 200, updated);
+            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 enc = encodeURIComponent(c.id);
+            var owned;
+            try { owned = await _noteBelongsToCustomer(req.params.noteId, c.id); }
+            catch (e) {
+              var nm = _safeNotice(e, audit);
+              return _redirect(res, "/admin/customers/" + enc +
+                "?note_err=" + encodeURIComponent(nm.message.replace(/^(?:admin|customerNotes)[.:]\s*/, "")));
+            }
+            if (!owned) {
+              return _redirect(res, "/admin/customers/" + enc +
+                "?note_err=" + encodeURIComponent("That note was not found on this customer."));
+            }
+            try { await mutate(owned, req.body || {}); }
+            catch (e) {
+              var n = _safeNotice(e, audit);
+              return _redirect(res, "/admin/customers/" + enc +
+                "?note_err=" + encodeURIComponent(n.message.replace(/^(?:admin|customerNotes)[.:]\s*/, "")));
+            }
+            b.audit.safeEmit({ action: AUDIT_NAMESPACE + "." + audit, outcome: "success", metadata: { id: c.id } });
+            _redirect(res, "/admin/customers/" + enc + "?saved=1");
+          },
+        ));
+      }
+
+      // Edit the note body / kind. The new text is required + length-capped by
+      // the primitive's validator (empty / over-long body, bad kind → a clean
+      // 4xx with nothing written); the kind is left unchanged when the form
+      // omits it.
+      _noteWriteRoute("/admin/customers/:id/notes/:noteId/edit", "customer.note.edit",
+        function (owned, body) {
+          var patch = { body: body.body };
+          if (body.kind != null && body.kind !== "") patch.kind = body.kind;
+          return customerNotes.updateNote(owned.id, patch);
+        });
+
+      // Pin / unpin — a pinned note floats to the top of the customer's note
+      // list (notesForCustomer orders pinned DESC). Idempotent at the
+      // primitive.
+      _noteWriteRoute("/admin/customers/:id/notes/:noteId/pin", "customer.note.pin",
+        function (owned) { return customerNotes.pinNote(owned.id); });
+      _noteWriteRoute("/admin/customers/:id/notes/:noteId/unpin", "customer.note.unpin",
+        function (owned) { return customerNotes.unpinNote(owned.id); });
+
+      // Archive / unarchive — a soft-retire that drops the note from the
+      // default (active) listing; unarchive brings it back. Both idempotent at
+      // the primitive.
+      _noteWriteRoute("/admin/customers/:id/notes/:noteId/archive", "customer.note.archive",
+        function (owned) { return customerNotes.archiveNote(owned.id); });
+      _noteWriteRoute("/admin/customers/:id/notes/:noteId/unarchive", "customer.note.unarchive",
+        function (owned) { return customerNotes.unarchiveNote(owned.id); });
     }
   }
 
@@ -7113,6 +7223,305 @@ function mount(router, deps) {
     }
   }
 
+  // ---- customer segments ----------------------------------------------
+  //
+  // Operator-defined RFM-style groupings ("VIPs", "lapsed-90d",
+  // "high-refund-rate") used to target campaigns. A segment is a slug +
+  // title + a bag of rule predicates ANDed together; membership is
+  // RULE-DERIVED — the recompute action re-evaluates the rules against the
+  // live order history and rewrites the membership cache. This console
+  // manages the segment DEFINITIONS + triggers a recompute; it never
+  // hand-assigns individual customers (the customer-detail screen shows
+  // the segments a customer sits in, read-only). The structured create /
+  // edit form covers the numeric RFM predicates (recency / frequency /
+  // monetary / AOV / refund-rate); the list-valued predicates
+  // (last_order_status_in / country_in / currency_in) and any future rule
+  // keys pass through the bearer JSON surface untouched. Every rule is
+  // validated by composing defineSegment / update — the form translator
+  // never persists a rules_json blob straight from the body, so a bad /
+  // missing rule throws a TypeError the routes map to a clean 400.
+  if (customerSegments) {
+    // Translate the structured create form (or a bearer JSON body) into a
+    // defineSegment input. A body already carrying an object-shaped `rules`
+    // is a bearer client passing the full vocabulary — forward untouched so
+    // the primitive's validator owns it. Otherwise build `rules` from the
+    // numeric RFM fields the console exposes; an empty field is omitted (a
+    // segment needs at least one predicate, which defineSegment enforces).
+    function _segmentInput(body) {
+      if (body.rules && typeof body.rules === "object") {
+        return body; // full JSON shape from a bearer client
+      }
+      return {
+        slug:        typeof body.slug === "string" ? body.slug.trim() : body.slug,
+        title:       body.title,
+        description: body.description,
+        rules:       _segmentRules(body),
+      };
+    }
+
+    // Translate the edit form (or a bearer JSON patch) into an update patch.
+    // Title / description forward when present; the rules are re-collected
+    // from the same numeric RFM fields the create form uses, but only when
+    // the form declared it via the hidden `rules_present` marker — so a
+    // title-only edit doesn't wipe the rule set. A bearer client posting an
+    // object-shaped `rules` forwards it verbatim for the primitive to validate.
+    function _segmentPatch(body) {
+      var patch = {};
+      if (Object.prototype.hasOwnProperty.call(body, "title") && body.title !== "") patch.title = body.title;
+      if (Object.prototype.hasOwnProperty.call(body, "description")) patch.description = body.description;
+      if (body.rules && typeof body.rules === "object") {
+        patch.rules = body.rules;
+      } else if (body.rules_present === "1") {
+        patch.rules = _segmentRules(body);
+      }
+      return patch;
+    }
+
+    // Build the `rules` object from the structured form's numeric RFM
+    // fields. Each field is optional; a blank field is left out. The values
+    // pass into defineSegment / update verbatim, which validate every key
+    // (non-negative integers, bps caps, min ≤ max coherence) and throw a
+    // TypeError on a bad / empty rule set — surfaced as a clean 400. This
+    // translator never writes the rule itself; it only shapes the typed
+    // bag the primitive's validator owns.
+    function _segmentRules(body) {
+      var rules = {};
+      var NUMERIC = [
+        "recency_days_max", "recency_days_min",
+        "frequency_orders_min", "lifetime_orders_min", "lifetime_orders_max",
+        "monetary_minor_min", "monetary_minor_max", "aov_minor_min",
+        "refund_rate_bps_max", "refund_rate_bps_min",
+      ];
+      for (var i = 0; i < NUMERIC.length; i += 1) {
+        var k = NUMERIC[i];
+        if (body[k] != null && body[k] !== "") {
+          rules[k] = _strictMinorInt(body[k], "customerSegments", k);
+        }
+      }
+      return rules;
+    }
+
+    // One-line human summary of a segment's rules for the list/detail.
+    function _segmentSummary(seg) {
+      var rules = (seg && seg.rules) || {};
+      var keys = Object.keys(rules);
+      if (!keys.length) return "—";
+      return keys.map(function (k) {
+        var v = rules[k];
+        return k + " " + (Array.isArray(v) ? v.join("/") : String(v));
+      }).join(" · ");
+    }
+
+    async function _renderSegments(flags) {
+      flags = flags || {};
+      var url = flags.url || null;
+      var filter = url && url.searchParams.get("filter");
+      var includeArchived = filter === "all" || filter === "archived";
+      var all = await customerSegments.listSegments({ include_archived: includeArchived });
+      var segments = all;
+      if (filter === "archived") {
+        segments = all.filter(function (s) { return s.archived_at != null; });
+      } else if (filter !== "all") {
+        // default = active only (listSegments already excluded archived).
+        segments = all;
+      }
+      return renderAdminSegments(Object.assign({
+        shop_name: deps.shop_name, nav_available: navAvailable,
+        segments: segments, filter: filter || "active", summarize: _segmentSummary,
+      }, flags));
+    }
+
+    // List — every segment with its rule summary, member count, and archived
+    // state; an All/Active/Archived filter; a clean empty state. Content-
+    // negotiated: bearer → the JSON array; browser cookie → the rendered table.
+    router.get("/admin/segments", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var includeArchived = url && (url.searchParams.get("filter") === "all" || url.searchParams.get("filter") === "archived");
+        var segments = await customerSegments.listSegments({ include_archived: !!includeArchived });
+        _json(res, 200, { segments: segments });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _sendHtml(res, 200, await _renderSegments({
+          url:        url,
+          created:    url && url.searchParams.get("created"),
+          updated:    url && url.searchParams.get("updated"),
+          archived:   url && url.searchParams.get("archived"),
+          unarchived: url && url.searchParams.get("unarchived"),
+          recomputed: url && url.searchParams.get("recomputed"),
+          notice:     (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+        }));
+      },
+    ));
+
+    // New-segment form — its own GET so the create page survives a bad
+    // submit's err redirect with the operator's context intact.
+    router.get("/admin/segments/new", _pageOrApi(true,
+      R(async function (_req, res) {
+        // Bearer clients don't need a form; hand back the rule vocabulary so
+        // tooling knows what a valid create body accepts.
+        _json(res, 200, {
+          known_rule_keys:        customerSegments.KNOWN_RULE_KEYS,
+          allowed_order_statuses: customerSegments.ALLOWED_ORDER_STATUSES,
+        });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _sendHtml(res, 200, renderAdminSegmentNew({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          notice: (url && url.searchParams.get("err")) ? "Check the segment's slug and rules — at least one rule is required." : null,
+        }));
+      },
+    ));
+
+    // Create — composes defineSegment, which validates the slug + rules and
+    // throws a TypeError (→ 400) on a bad / missing rule. The bearer path
+    // returns 201 + the created segment; the browser path PRGs to the list.
+    router.post("/admin/segments", _pageOrApi(false,
+      W("customer_segment.create", async function (req, res) {
+        var seg = await customerSegments.defineSegment(_segmentInput(req.body || {}));
+        _json(res, 201, seg);
+        return { id: seg.slug };
+      }),
+      async function (req, res) {
+        try {
+          await customerSegments.defineSegment(_segmentInput(req.body || {}));
+        } catch (e) {
+          // A bad / missing rule (TypeError) or a duplicate slug
+          // (CUSTOMER_SEGMENT_SLUG_EXISTS) is operator input — bounce back to
+          // the create form's err state, never a 500. _safeNotice records an
+          // unknown failure server-side and yields a 5xx only for a genuine
+          // fault.
+          var n = _safeNotice(e, "customer_segment.create");
+          if (n.status >= 500) throw e;
+          return _redirect(res, "/admin/segments/new?err=1");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.create", outcome: "success" });
+        _redirect(res, "/admin/segments?created=1");
+      },
+    ));
+
+    // Resolve a :slug to its segment. A malformed slug throws inside
+    // listSegments' slug guard chain — but here we read via listSegments and
+    // match, so an unknown slug simply yields null → a clean 404.
+    async function _segmentBySlug(slug) {
+      // stats() is the cheapest single-segment read that also throws a
+      // TypeError on a malformed slug; pair it with the full hydrate via the
+      // list so the detail screen has the rules + archived state.
+      var all = await customerSegments.listSegments({ include_archived: true });
+      for (var i = 0; i < all.length; i += 1) {
+        if (all[i].slug === slug) return all[i];
+      }
+      return null;
+    }
+
+    // Detail — the single segment + its current member count + stats, and a
+    // full edit form (title / description / rules). Content-negotiated.
+    router.get("/admin/segments/:slug", _pageOrApi(true,
+      R(async function (req, res) {
+        var seg = await _segmentBySlug(req.params.slug);
+        if (!seg) return _problem(res, 404, "customer-segment-not-found");
+        var stats = await customerSegments.stats(seg.slug);
+        _json(res, 200, Object.assign({}, seg, { stats: stats }));
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var seg = await _segmentBySlug(req.params.slug);
+        if (!seg) return _sendHtml(res, 404, await _renderSegments({ url: url, notice: "Segment not found." }));
+        var stats = null;
+        try { stats = await customerSegments.stats(seg.slug); }
+        catch (_e) { stats = null; }
+        _sendHtml(res, 200, renderAdminSegment({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          segment: seg, stats: stats, summary: _segmentSummary(seg),
+          updated:    url && url.searchParams.get("updated"),
+          recomputed: url && url.searchParams.get("recomputed"),
+          recomputed_count: url && url.searchParams.get("members"),
+          notice:  (url && url.searchParams.get("err")) ? "That action couldn't be completed for the segment." : null,
+        }));
+      },
+    ));
+
+    // Edit — composes update, which re-validates the rules and throws on a
+    // bad set. A terms edit returns to the detail screen on error so the
+    // operator sees their input in context.
+    router.post("/admin/segments/:slug/edit", _pageOrApi(false,
+      W("customer_segment.update", async function (req, res) {
+        var seg;
+        try { seg = await customerSegments.update(req.params.slug, _segmentPatch(req.body || {})); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, seg);
+        return { id: seg.slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc = encodeURIComponent(slug);
+        try { await customerSegments.update(slug, _segmentPatch(req.body || {})); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/segments/" + enc + "?err=1"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.update", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/segments/" + enc + "?updated=1");
+      },
+    ));
+
+    // Recompute — re-evaluate this segment's rules against the live order
+    // history and rewrite its membership cache. Surfaces the resulting member
+    // count in the PRG banner (this is the action that populates a freshly
+    // defined or edited segment).
+    router.post("/admin/segments/:slug/recompute", _pageOrApi(false,
+      W("customer_segment.recompute", async function (req, res) {
+        var report;
+        try { report = await customerSegments.recompute({ slugs: [req.params.slug] }); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        var count = report.per_segment[req.params.slug];
+        _json(res, 200, { slug: req.params.slug, member_count: count == null ? 0 : count, report: report });
+        return { id: req.params.slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc = encodeURIComponent(slug);
+        var report;
+        try { report = await customerSegments.recompute({ slugs: [slug] }); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/segments/" + enc + "?err=1"); }
+        var count = report.per_segment[slug];
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.recompute", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/segments/" + enc + "?recomputed=1&members=" + encodeURIComponent(String(count == null ? 0 : count)));
+      },
+    ));
+
+    router.post("/admin/segments/:slug/archive", _pageOrApi(false,
+      W("customer_segment.archive", async function (req, res) {
+        var seg;
+        try { seg = await customerSegments.archive(req.params.slug); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, seg);
+        return { id: seg.slug };
+      }),
+      async function (req, res) {
+        try { await customerSegments.archive(req.params.slug); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/segments?err=1"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.archive", outcome: "success", metadata: { slug: req.params.slug } });
+        _redirect(res, "/admin/segments?archived=1");
+      },
+    ));
+
+    router.post("/admin/segments/:slug/unarchive", _pageOrApi(false,
+      W("customer_segment.unarchive", async function (req, res) {
+        var seg;
+        try { seg = await customerSegments.unarchive(req.params.slug); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, seg);
+        return { id: seg.slug };
+      }),
+      async function (req, res) {
+        try { await customerSegments.unarchive(req.params.slug); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/segments?err=1"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".customer_segment.unarchive", outcome: "success", metadata: { slug: req.params.slug } });
+        _redirect(res, "/admin/segments?unarchived=1");
+      },
+    ));
+  }
+
   // ---- quantity discounts ---------------------------------------------
   // Tier-set CRUD for automatic per-line quantity breaks ("buy 5, save
   // 10%"). The pricing engine already applies these at PDP / cart /
@@ -8347,6 +8756,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
   { key: "customers",    href: "/admin/customers",    label: "Customers",    requires: "customers" },
+  { key: "segments",     href: "/admin/segments",     label: "Segments",     requires: "customerSegments" },
   { key: "returns",      href: "/admin/returns",      label: "Returns",      requires: "returns" },
   { key: "support",      href: "/admin/support",      label: "Support",      requires: "supportTickets" },
   { key: "reviews",      href: "/admin/reviews",      label: "Reviews",      requires: "reviews" },
@@ -9625,25 +10035,56 @@ function renderAdminCustomerDetail(opts) {
       "<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 showArchived = opts.show_archived_notes === true;
+    // A <select name="kind"> with the active kind preselected. Reused by the
+    // add form and each note's inline edit form.
+    function _noteKindSelect(active) {
+      return ["general", "preference", "escalation", "warning", "billing"].map(function (k) {
+        return "<option value=\"" + k + "\"" + (k === active ? " selected" : "") + ">" + k + "</option>";
+      }).join("");
+    }
     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>";
+      var nenc = _htmlEscape(encodeURIComponent(n.id));
+      var base = "/admin/customers/" + _htmlEscape(enc) + "/notes/" + nenc;
+      var isPinned   = Number(n.pinned) === 1;
+      var isArchived = n.archived_at != null;
+      var pills =
+        (isPinned ? "<span class=\"status-pill paid\">Pinned</span>" : "") +
+        (isArchived ? "<span class=\"status-pill cancelled\">Archived</span>" : "");
+      // Inline edit form — kind + body, prefilled with the note's current
+      // values; the primitive re-validates an empty / over-long body.
+      var editForm = "<details class=\"note-edit\"><summary class=\"btn btn--ghost\">Edit</summary>" +
+        "<form method=\"post\" action=\"" + base + "/edit\">" +
+          "<label class=\"form-field\"><span>Kind</span>" +
+            "<select name=\"kind\">" + _noteKindSelect(n.kind) + "</select></label>" +
+          "<label class=\"form-field\"><span>Note</span>" +
+            "<textarea name=\"body\" required maxlength=\"8000\" rows=\"3\">" + _htmlEscape(n.body) + "</textarea></label>" +
+          "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save note</button></div>" +
+        "</form></details>";
+      var pinForm = "<form method=\"post\" action=\"" + base + (isPinned ? "/unpin" : "/pin") + "\">" +
+        "<button class=\"btn btn--ghost\" type=\"submit\">" + (isPinned ? "Unpin" : "Pin") + "</button></form>";
+      var archiveForm = "<form method=\"post\" action=\"" + base + (isArchived ? "/unarchive" : "/archive") + "\">" +
+        "<button class=\"btn btn--ghost\" type=\"submit\">" + (isArchived ? "Unarchive" : "Archive") + "</button></form>";
+      return "<li class=\"note-item\">" +
+        "<div class=\"note-meta\">" + _htmlEscape(n.kind) + " · " + _htmlEscape(_fmtDate(n.created_at)) +
+          (pills ? " " + pills : "") + "</div>" +
+        "<div class=\"note-body\">" + _htmlEscape(n.body) + "</div>" +
+        "<div class=\"actions-row\">" + editForm + pinForm + archiveForm + "</div>" +
+      "</li>";
     }).join("");
-    notesPanel = "<div class=\"panel\"><h3 class=\"subhead\">Notes</h3>" +
+    var archivedToggle = showArchived
+      ? "<a class=\"btn btn--ghost\" href=\"/admin/customers/" + _htmlEscape(enc) + "\">Hide archived</a>"
+      : "<a class=\"btn btn--ghost\" href=\"/admin/customers/" + _htmlEscape(enc) + "?notes_archived=1\">Show archived</a>";
+    notesPanel = "<div class=\"panel\"><div class=\"actions-row\"><h3 class=\"subhead\">Notes</h3>" + archivedToggle + "</div>" +
       noteNotice +
-      "<p class=\"meta\">Operator-only annotations on this customer. Never shown to the customer.</p>" +
+      "<p class=\"meta\">Operator-only annotations on this customer. Never shown to the customer. " +
+        "Pin the notes every shift should see first; archive a stale or wrong note to retire it from the active list.</p>" +
       ((opts.notes || []).length
         ? "<ul class=\"note-list\">" + noteRows + "</ul>"
-        : "<p class=\"empty\">No notes yet.</p>") +
+        : "<p class=\"empty\">" + (showArchived ? "No notes (including archived)." : "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>" +
+          "<select name=\"kind\">" + _noteKindSelect("general") + "</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>" +
@@ -11036,6 +11477,192 @@ function renderAdminDiscounts(opts) {
   return _renderAdminShell(opts.shop_name, "Discounts", body, "discounts", opts.nav_available);
 }
 
+// The numeric RFM rule fields the structured segment form collects. Each
+// maps 1:1 to a customer-segments rule key; a blank field is omitted from
+// the rules object, and the backend validates whatever's present (rejecting
+// an empty rule set, a bad integer, or an out-of-range basis-point value).
+var SEGMENT_RULE_FIELDS = [
+  { name: "frequency_orders_min", label: "Min lifetime orders (frequency)", hint: "Customer has placed at least this many paid orders.", extra: " min=\"0\"" },
+  { name: "lifetime_orders_max",  label: "Max lifetime orders",             hint: "At most this many orders — gate \"new\" buyers.", extra: " min=\"0\"" },
+  { name: "recency_days_max",     label: "Ordered within N days (recency)", hint: "Last order ≤ N days ago — recent buyers.", extra: " min=\"0\"" },
+  { name: "recency_days_min",     label: "Lapsed for N+ days",              hint: "Last order ≥ N days ago — the lapsed half of RFM.", extra: " min=\"0\"" },
+  { name: "monetary_minor_min",   label: "Min lifetime spend (minor)",      hint: "Lifetime gross ≥ N in the smallest currency unit.", extra: " min=\"0\"" },
+  { name: "monetary_minor_max",   label: "Max lifetime spend (minor)",      hint: "Lifetime gross ≤ N.", extra: " min=\"0\"" },
+  { name: "aov_minor_min",        label: "Min average order value (minor)", hint: "Average order value ≥ N.", extra: " min=\"0\"" },
+  { name: "refund_rate_bps_max",  label: "Max refund rate (bps)",           hint: "Refunds ÷ orders ≤ N basis points (10000 = 100%).", extra: " min=\"0\" max=\"10000\"" },
+  { name: "refund_rate_bps_min",  label: "Min refund rate (bps)",           hint: "Refunds ÷ orders ≥ N basis points — catch high-refund customers.", extra: " min=\"0\" max=\"10000\"" },
+];
+
+// Status pill for a segment's lifecycle: active = green (paid), archived =
+// neutral-off (cancelled). Reuses the shared order-pill classes.
+function _segmentPill(seg) {
+  var archived = seg && seg.archived_at != null;
+  return "<span class=\"status-pill " + (archived ? "cancelled" : "paid") + "\">" +
+    (archived ? "archived" : "active") + "</span>";
+}
+
+// Render the numeric RFM rule field set, each prefilled from the supplied
+// rules object (empty when creating). The list-valued predicates
+// (last_order_status_in / country_in / currency_in) and any future rule key
+// stay on the bearer JSON surface — documented in the form's help text.
+function _segmentRuleFields(rules) {
+  rules = rules || {};
+  return SEGMENT_RULE_FIELDS.map(function (f) {
+    var v = rules[f.name] != null ? String(rules[f.name]) : "";
+    return _setupField(f.label, f.name, v, "number", f.hint, f.extra);
+  }).join("");
+}
+
+function renderAdminSegments(opts) {
+  opts = opts || {};
+  var segments = opts.segments || [];
+  var summarize = typeof opts.summarize === "function" ? opts.summarize : function () { return "—"; };
+  var filter = opts.filter || "active";
+  var created    = opts.created    ? "<div class=\"banner banner--ok\">Segment created.</div>" : "";
+  var updated    = opts.updated    ? "<div class=\"banner banner--ok\">Segment updated.</div>" : "";
+  var archived   = opts.archived   ? "<div class=\"banner banner--ok\">Segment archived.</div>" : "";
+  var unarchived = opts.unarchived ? "<div class=\"banner banner--ok\">Segment unarchived.</div>" : "";
+  var recomputed = opts.recomputed ? "<div class=\"banner banner--ok\">Membership recomputed.</div>" : "";
+  var notice     = opts.notice     ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var FILTERS = [
+    { value: "active",   label: "Active" },
+    { value: "all",      label: "All" },
+    { value: "archived", label: "Archived" },
+  ];
+  var chips = "<div class=\"order-filters\">" + FILTERS.map(function (fl) {
+    var href = fl.value === "active" ? "/admin/segments" : "/admin/segments?filter=" + fl.value;
+    return "<a class=\"chip" + (filter === fl.value ? " chip--on" : "") + "\" href=\"" + href + "\">" + _htmlEscape(fl.label) + "</a>";
+  }).join("") + "</div>";
+
+  var rows = segments.map(function (s) {
+    var enc = encodeURIComponent(s.slug);
+    var isArchived = s.archived_at != null;
+    var actions =
+      "<a class=\"btn btn--ghost\" href=\"/admin/segments/" + _htmlEscape(enc) + "\">Manage</a> " +
+      (isArchived
+        ? "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/unarchive\" class=\"form-inline\">" +
+            "<button class=\"btn btn--ghost\" type=\"submit\">Unarchive</button></form>"
+        : "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/recompute\" class=\"form-inline\">" +
+            "<button class=\"btn btn--ghost\" type=\"submit\">Recompute</button></form> " +
+          "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+            "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>");
+    return "<tr>" +
+      "<td><a href=\"/admin/segments/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(s.title) + "</strong></a><br><code class=\"order-id\">" + _htmlEscape(s.slug) + "</code></td>" +
+      "<td>" + _htmlEscape(summarize(s)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(s.last_member_count == null ? 0 : s.last_member_count)) + "</td>" +
+      "<td>" + _segmentPill(s) + "</td>" +
+      "<td><div class=\"actions-row\">" + actions + "</div></td>" +
+    "</tr>";
+  }).join("");
+
+  var table = segments.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Segment</th><th scope=\"col\">Rules</th><th scope=\"col\" class=\"num\">Members</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<p class=\"empty\">No " + (filter === "archived" ? "archived " : (filter === "all" ? "" : "active ")) + "segments yet. Define one to start grouping customers for campaigns.</p>";
+
+  var body = "<section><h2>Customer segments</h2>" + created + updated + archived + unarchived + recomputed + notice +
+    "<p class=\"meta\">Rule-derived groupings for targeted campaigns. Membership is recomputed from order history — define a segment, then recompute to populate it.</p>" +
+    chips + table +
+    "<div class=\"actions-row mt\"><a class=\"btn\" href=\"/admin/segments/new\">Define a segment</a></div>" +
+  "</section>";
+  return _renderAdminShell(opts.shop_name, "Segments", body, "segments", opts.nav_available);
+}
+
+function renderAdminSegmentNew(opts) {
+  opts = opts || {};
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var form =
+    "<div class=\"panel mw-42\">" +
+      "<h3 class=\"subhead\">Define a segment</h3>" +
+      "<p class=\"meta\">Fill at least one rule — every rule must hold for a customer to land in the segment. Leave a rule blank to skip it. Members are populated by a recompute after the segment is saved.</p>" +
+      "<form method=\"post\" action=\"/admin/segments\">" +
+        _setupField("Slug", "slug", "", "text", "Stable handle, e.g. vip-buyers.", " maxlength=\"64\" required") +
+        _setupField("Title", "title", "", "text", "Operator-facing name, e.g. VIP buyers.", " maxlength=\"200\" required") +
+        _setupField("Description (optional)", "description", "", "text", "What this segment is for.", " maxlength=\"1000\"") +
+        "<h3 class=\"subhead subhead--sp-lg\">Rules (all must hold)</h3>" +
+        _segmentRuleFields({}) +
+        "<p class=\"meta\">List-valued rules (last order status / country / currency) are available through the JSON API.</p>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create segment</button>" +
+          "<a class=\"btn btn--ghost\" href=\"/admin/segments\">Cancel</a></div>" +
+      "</form>" +
+    "</div>";
+  var body = "<section><h2>Define a segment</h2>" + notice + form + "</section>";
+  return _renderAdminShell(opts.shop_name, "New segment", body, "segments", opts.nav_available);
+}
+
+function renderAdminSegment(opts) {
+  opts = opts || {};
+  var s = opts.segment;
+  if (!s) {
+    var nf = "<section><h2>Segment</h2><p class=\"empty\">Segment not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/segments\">Back to segments</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Segment", nf, "segments", opts.nav_available);
+  }
+  var stats = opts.stats || null;
+  var updated    = opts.updated    ? "<div class=\"banner banner--ok\">Segment updated.</div>" : "";
+  var recomputed = opts.recomputed
+    ? "<div class=\"banner banner--ok\">Membership recomputed — " + _htmlEscape(String(opts.recomputed_count == null ? 0 : opts.recomputed_count)) + " member(s).</div>"
+    : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var isArchived = s.archived_at != null;
+  var enc = encodeURIComponent(s.slug);
+
+  var memberCount = stats && stats.member_count != null ? stats.member_count : (s.last_member_count == null ? 0 : s.last_member_count);
+  var lastRecomputed = stats && stats.last_recomputed_at != null ? _fmtDate(stats.last_recomputed_at)
+                     : (s.last_recomputed_at != null ? _fmtDate(s.last_recomputed_at) : "never");
+
+  var statCards =
+    "<div class=\"stat-grid\">" +
+      _statCard("Members", String(memberCount)) +
+      _statCard("Avg lifetime (minor)", stats && stats.avg_lifetime_minor != null ? String(stats.avg_lifetime_minor) : "0") +
+      _statCard("Last recomputed", lastRecomputed) +
+    "</div>";
+
+  var head = "<div class=\"panel\"><dl class=\"detail-grid\">" +
+    "<div><dt>Segment</dt><dd><strong>" + _htmlEscape(s.title) + "</strong><br><code class=\"order-id\">" + _htmlEscape(s.slug) + "</code></dd></div>" +
+    "<div><dt>Rules</dt><dd>" + _htmlEscape(opts.summary || "—") + "</dd></div>" +
+    (s.description ? "<div><dt>Description</dt><dd>" + _htmlEscape(s.description) + "</dd></div>" : "") +
+    "<div><dt>Status</dt><dd>" + _segmentPill(s) + "</dd></div>" +
+  "</dl></div>";
+
+  // Recompute is the action that makes the rules actually populate the
+  // membership cache — surface it prominently for an active segment.
+  var recomputeForm = isArchived ? "" :
+    "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/recompute\" class=\"form-inline\">" +
+      "<button class=\"btn\" type=\"submit\">Recompute membership</button>" +
+    "</form>";
+
+  var editForm = isArchived
+    ? "<p class=\"empty\">This segment is archived. Unarchive it to edit or recompute.</p>" +
+        "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/unarchive\" class=\"form-inline\">" +
+          "<button class=\"btn\" type=\"submit\">Unarchive</button></form>"
+    : "<div class=\"panel mt mw-42\">" +
+        "<h3 class=\"subhead\">Edit segment</h3>" +
+        "<p class=\"meta\">Change the title, description, or rules. Editing the rules takes effect on the next recompute.</p>" +
+        "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/edit\">" +
+          "<input type=\"hidden\" name=\"rules_present\" value=\"1\">" +
+          _setupField("Title", "title", s.title, "text", "Operator-facing name.", " maxlength=\"200\"") +
+          _setupField("Description", "description", s.description || "", "text", "What this segment is for.", " maxlength=\"1000\"") +
+          "<h3 class=\"subhead subhead--sp-lg\">Rules (all must hold)</h3>" +
+          _segmentRuleFields(s.rules) +
+          "<p class=\"meta\">Leaving every rule blank is rejected — a segment needs at least one rule. List-valued rules stay on the JSON API.</p>" +
+          "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save changes</button></div>" +
+        "</form>" +
+      "</div>";
+
+  var archiveForm = isArchived ? "" :
+    "<form method=\"post\" action=\"/admin/segments/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+      "<button class=\"btn btn--danger\" type=\"submit\">Archive segment</button></form>";
+
+  var body = "<section><h2>" + _htmlEscape(s.title) + "</h2>" + updated + recomputed + notice +
+    head + statCards +
+    "<div class=\"actions-row mt\">" + recomputeForm + archiveForm + "</div>" +
+    editForm +
+    "<div class=\"actions-row mt\"><a class=\"btn btn--ghost\" href=\"/admin/segments\">Back to segments</a></div>" +
+  "</section>";
+  return _renderAdminShell(opts.shop_name, "Segment " + s.slug, body, "segments", opts.nav_available);
+}
+
 function renderAdminGiftCards(opts) {
   opts = opts || {};
   var rows = opts.cards || [];

package/lib/asset-manifest.json

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

package/package.json

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