@blamejs/blamejs-shop 0.3.43 → 0.3.44

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.44 (2026-05-31) — **Customers can rate a delivered order, and the admin console moderates and replies.** There was no way for a customer to give feedback on how an order was fulfilled, and no way for an operator to act on it. Customers can now rate one of their own delivered orders on shipping, packaging, and how likely they are to recommend you, with an optional comment. The admin console gets a Ratings screen with a moderation queue of every flagged comment plus the most recent ratings, where an operator can flag a comment or post one public reply that the customer then sees on their order page. A customer can only rate an order they own, and every comment and reply is HTML-escaped wherever it is shown, so feedback text can't inject markup into another shopper's or an operator's page. **Added:** *Order ratings* — A customer viewing one of their own orders can rate it on three axes — shipping, packaging, and likelihood to recommend (1 to 5) — and optionally leave a comment. Each order can be rated once. The rating, and any public reply from the store, appear on the customer's order page. A customer can only rate an order tied to their own account; the rating is always recorded against the signed-in customer, never a value taken from the request. · *Ratings moderation in the admin console* — A new Ratings screen lists recent ratings with their scores and comments, alongside a moderation queue that surfaces every flagged comment regardless of its score, so a flagged comment on an otherwise high rating is never hidden. An operator can flag a comment for moderation and post a single public reply to a rating, which is then shown to the customer. Comments and replies are HTML-escaped everywhere they are rendered.
+
 - v0.3.43 (2026-05-31) — **Export orders for a date range as CSV or NDJSON, with scheduled exports.** There was no way to pull a bulk export of orders over a date range. A new Exports screen in the admin console previews how many orders and how much revenue a date range covers, then downloads them as a CSV or NDJSON file. The export can also be scheduled and managed as a queued job. Customer email addresses are exported only as a hash, never in the clear, and any field that could be interpreted as a spreadsheet formula is neutralized so an exported file can't run code when opened. This release also updates the vendored blamejs runtime to v0.14.16. **Added:** *Order export* — An Exports screen in the admin console exports orders over a chosen date range. It first shows a preview — the order count, revenue, and average order value for the range — then downloads the orders as a CSV or NDJSON file with a standard set of columns. Exports can also be queued as scheduled jobs and cancelled before they run. Customer email is exported as a hash rather than in the clear, and any cell that begins with a character a spreadsheet would treat as a formula is escaped, so an exported file can't execute anything when opened in Excel or Sheets. **Changed:** *Vendored blamejs runtime updated to v0.14.16* — The bundled blamejs runtime is updated to v0.14.16, which validates connection ports at configuration time — a malformed port (a non-integer or out-of-range value) is now rejected with a clear error at startup instead of silently falling back to a default. No operator action is required.
 
 - v0.3.42 (2026-05-31) — **The blog now pages through every post, and the byline shows the shop name.** The blog index showed only the 12 most recent posts with no way to reach the rest, so older posts were a dead end for anyone browsing — even though they stayed in the sitemap. The index now has previous/next pagination, so every published post is reachable. The post byline and the article's structured data now show the shop name instead of an internal author identifier, and a missing blog post or product page no longer returns a body on a HEAD request. **Fixed:** *Blog index pagination* — The blog index listed only the 12 most recent posts and offered no way to reach older ones from /blog. It now has previous/next pagination — the same control used on collection and search pages — so every published post is reachable, with the next link appearing only when there is genuinely another page. · *Blog byline shows the shop name, not an internal id* — The blog post byline and the article's structured data displayed the raw internal author identifier. They now show the shop name, so the public byline and the author Google reads from the structured data are meaningful rather than an internal id. · *Missing pages don't return a body on HEAD* — A missing blog post or product page returned a full page body even for a HEAD request. Those 404 responses now omit the body on HEAD, matching the other pages and the HTTP spec.

package/lib/admin.js

@@ -512,6 +512,7 @@ function mount(router, deps) {
   var salesTaxFilings = deps.salesTaxFilings || null; // sales-tax-filing remittance console disabled when absent
   var supportTickets  = deps.supportTickets  || null; // support-ticket queue + thread console disabled when absent
   var orderExchanges  = deps.orderExchanges  || null; // exchange queue + FSM-action console disabled when absent
+  var orderRatings    = deps.orderRatings    || null; // per-order rating moderation queue (flag/clear + public reply) disabled when absent
   var preorder        = deps.preorder        || null; // pre-order campaign console (define/launch/close) disabled when absent
 
   // Which optional console sections are wired — gates their nav links so a
@@ -520,7 +521,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, preorder: !!deps.preorder, 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, orderExchanges: !!orderExchanges, orderExport: !!orderExport };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, 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, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, orderExport: !!orderExport };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -6710,6 +6711,142 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- order ratings (moderation) -------------------------------------
+  //
+  // Surfaces (mounted only when the orderRatings primitive is wired):
+  //   GET  /admin/ratings[?flagged=1]  — screen: the flagged-comment
+  //         moderation queue first, then a list of recent ratings with
+  //         their scores + (escaped) comment. Bearer JSON returns both lists.
+  //   POST /admin/ratings/:id/flag     — flag a comment for moderation.
+  //   POST /admin/ratings/:id/respond  — post the operator's one public reply.
+  //
+  // Coded-error mapping mirrors the exchanges console: the primitive throws
+  // plain Errors carrying `.code` (ORDER_RATING_NOT_FOUND / _ALREADY_FLAGGED
+  // / _ALREADY_RESPONDED / _NO_COMMENT) AND TypeErrors for bad input, so the
+  // `.code` checks MUST run before the generic `instanceof TypeError → 400`,
+  // else a not-found / already-acted error would wrongly return 400.
+  if (orderRatings) {
+    // The operator-facing window for the recent-ratings list + the flagged
+    // queue. A wide span (the primitive's read paths are date-windowed); the
+    // list methods cap their own rows so this never streams unbounded.
+    var RATINGS_WINDOW_MS = b.constants.TIME.days(365);
+    function _ratingsWindow() {
+      var to = Date.now();
+      return { from: to - RATINGS_WINDOW_MS, to: to };
+    }
+
+    // Map a thrown rating error to a problem-details status for the bearer
+    // JSON path: missing row → 404, already-flagged / already-responded /
+    // no-comment-to-flag → 409, bad shape → 400. The coded checks run BEFORE
+    // the `instanceof TypeError` branch (the primitive's _NOT_FOUND etc. are
+    // plain Errors with a .code; a malformed UUID is a TypeError).
+    function _ratingApiError(res, e) {
+      if (!e) return null;
+      if (e.code === "ORDER_RATING_NOT_FOUND") return _problem(res, 404, "rating-not-found");
+      if (e.code === "ORDER_RATING_ALREADY_FLAGGED" ||
+          e.code === "ORDER_RATING_ALREADY_RESPONDED" ||
+          e.code === "ORDER_RATING_NO_COMMENT") {
+        return _problem(res, 409, "conflict", e.message);
+      }
+      if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+      return null;
+    }
+    // The same classes for the browser path: a coded refusal / bad shape is a
+    // correction notice (?err redirect), never a 500. Anything else propagates.
+    function _ratingClientError(e) {
+      if (!e) return false;
+      if (e instanceof TypeError) return true;
+      return e.code === "ORDER_RATING_NOT_FOUND" ||
+             e.code === "ORDER_RATING_ALREADY_FLAGGED" ||
+             e.code === "ORDER_RATING_ALREADY_RESPONDED" ||
+             e.code === "ORDER_RATING_NO_COMMENT";
+    }
+
+    // Resolve the flagged queue + the recent-ratings list for the screen /
+    // the JSON API. The flagged queue comes from listFlagged (every flagged
+    // comment in the window, most-recent-first, regardless of score) so a
+    // flagged comment on an otherwise high rating is never hidden behind the
+    // recent list's score cap; the recent list is the lowest-scored ratings
+    // in the window (the moderation-priority view). Each read is best-effort
+    // against an unmigrated table (degrades to an empty list, never a 500).
+    async function _ratingsLists() {
+      var win = _ratingsWindow();
+      var recent = [], flagged = [];
+      try { recent = await orderRatings.topNegativeRatings({ from: win.from, to: win.to, limit: 100 }); }
+      catch (_e) { recent = []; }
+      try { flagged = await orderRatings.listFlagged({ from: win.from, to: win.to }); }
+      catch (_e2) { flagged = []; }
+      return { recent: recent, flagged: flagged };
+    }
+
+    router.get("/admin/ratings", _pageOrApi(true,
+      R(async function (req, res) {
+        var lists = await _ratingsLists();
+        _json(res, 200, { flagged: lists.flagged, ratings: lists.recent });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var onlyFlagged = !!(url && url.searchParams.get("flagged"));
+        var lists = await _ratingsLists();
+        _sendHtml(res, 200, renderAdminRatings({
+          shop_name:     deps.shop_name,
+          nav_available: navAvailable,
+          ratings:       lists.recent,
+          flagged:       lists.flagged,
+          only_flagged:  onlyFlagged,
+          moved:         url && url.searchParams.get("moved"),
+          notice:        url && url.searchParams.get("err") ? "That action couldn't be completed for this rating." : null,
+        }));
+      },
+    ));
+
+    // The browser side of a rating action: run opFn(id, body), then PRG back
+    // to the queue. A bad shape / coded refusal / not-found becomes an ?err
+    // notice, never a 500; anything else propagates.
+    function _ratingAction(jsonHandler, auditEvent, opFn) {
+      return _pageOrApi(false, jsonHandler, async function (req, res) {
+        var id = req.params.id;
+        try { await opFn(id, req.body || {}); }
+        catch (e) {
+          if (_ratingClientError(e)) return _redirect(res, "/admin/ratings?err=1");
+          throw e;
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + "." + auditEvent, outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/ratings?moved=1");
+      });
+    }
+
+    // Flag a comment for moderation. The operator supplies a reason + their
+    // own UUID (the single-bearer admin model has no per-operator session).
+    router.post("/admin/ratings/:id/flag", _ratingAction(
+      W("rating.flag", async function (req, res) {
+        var body = req.body || {};
+        var row;
+        try { row = await orderRatings.flagComment({ rating_id: req.params.id, reason: body.reason, flagged_by: body.flagged_by }); }
+        catch (e) { var mapped = _ratingApiError(res, e); if (mapped !== null) return mapped; throw e; }
+        _json(res, 200, row);
+        return { id: row.id };
+      }),
+      "rating.flag",
+      function (id, body) { return orderRatings.flagComment({ rating_id: id, reason: body.reason, flagged_by: body.flagged_by }); },
+    ));
+
+    // Post the operator's one public reply to a rating. The primitive
+    // refuses a second reply (409 ORDER_RATING_ALREADY_RESPONDED).
+    router.post("/admin/ratings/:id/respond", _ratingAction(
+      W("rating.respond", async function (req, res) {
+        var body = req.body || {};
+        var row;
+        try { row = await orderRatings.responseToCustomer({ rating_id: req.params.id, response: body.response, responded_by: body.responded_by }); }
+        catch (e) { var mapped = _ratingApiError(res, e); if (mapped !== null) return mapped; throw e; }
+        _json(res, 200, row);
+        return { id: row.id };
+      }),
+      "rating.respond",
+      function (id, body) { return orderRatings.responseToCustomer({ rating_id: id, response: body.response, responded_by: body.responded_by }); },
+    ));
+  }
+
   // ---- analytics ------------------------------------------------------
 
   var analytics = deps.analytics || null;
@@ -9564,6 +9701,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "returns",      href: "/admin/returns",      label: "Returns",      requires: "returns" },
   { key: "support",      href: "/admin/support",      label: "Support",      requires: "supportTickets" },
   { key: "exchanges",    href: "/admin/exchanges",    label: "Exchanges",    requires: "orderExchanges" },
+  { key: "ratings",      href: "/admin/ratings",      label: "Ratings",      requires: "orderRatings" },
   { key: "reviews",      href: "/admin/reviews",      label: "Reviews",      requires: "reviews" },
   { key: "questions",    href: "/admin/questions",    label: "Q&A",          requires: "productQa" },
   { key: "subscriptions", href: "/admin/subscription-plans", label: "Subscriptions", requires: "subscriptions" },
@@ -11637,6 +11775,117 @@ function renderAdminExchange(opts) {
   return _renderAdminShell(opts.shop_name, "Exchange " + String(x.id).slice(0, 8), body, "exchanges", opts.nav_available);
 }
 
+// One rating card for the moderation queue / recent list. Shows the three
+// scores, the (escaped) comment, the flag state + reason, and the operator
+// reply — plus the flag / reply action forms.
+//
+// ESCAPE-BY-DEFAULT: the customer comment is rendered from the primitive's
+// pre-escaped `comment_html`, and the operator reply from `response_html`
+// — both already run through b.template.escapeHtml by the primitive's
+// render layer. They are spliced as-is, NEVER re-built from the raw
+// `comment` / `response_text`, so a `<script>`/`onerror` payload a customer
+// typed is inert on this screen. (`_htmlEscape` is NOT applied to the _html
+// fields — that would double-escape; it IS applied to every other field.)
+function _ratingCard(rt) {
+  var shortId  = _htmlEscape(String(rt.id).slice(0, 8));
+  var shortOrd = _htmlEscape(String(rt.order_id).slice(0, 8));
+  var scores =
+    "<span class=\"meta\">Shipping " + _htmlEscape(String(rt.shipping_rating)) + "/5</span> · " +
+    "<span class=\"meta\">Packaging " + _htmlEscape(String(rt.packaging_rating)) + "/5</span> · " +
+    "<span class=\"meta\">Recommend " + _htmlEscape(String(rt.recommend_rating)) + "/5</span>";
+  // comment_html / response_html are already escaped by the primitive —
+  // splice them, never rt.comment / rt.response_text.
+  var commentBlock = rt.comment_html
+    ? "<p class=\"review-card__body\">" + rt.comment_html + "</p>"
+    : "<p class=\"meta\">No comment.</p>";
+  var flagState = rt.comment_flagged
+    ? "<span class=\"status-pill cancelled\">Flagged</span>" +
+        (rt.flag_reason ? " <span class=\"meta\">" + _htmlEscape(rt.flag_reason) + "</span>" : "")
+    : "";
+  var replyBlock = rt.response_html
+    ? "<div class=\"panel\"><h4 class=\"subhead\">Operator reply</h4>" +
+        "<p class=\"review-card__body\">" + rt.response_html + "</p></div>"
+    : "";
+
+  // Flag form — only when there is a comment AND it isn't already flagged
+  // (the primitive refuses both no-comment and already-flagged with a 409;
+  // gating the form keeps the console from offering a doomed action).
+  var flagForm = (rt.comment_html && !rt.comment_flagged)
+    ? "<form method=\"post\" action=\"/admin/ratings/" + _htmlEscape(rt.id) + "/flag\" class=\"return-action\">" +
+        "<h4>Flag comment</h4>" +
+        _setupField("Reason", "reason", "", "text", "Why this comment is being flagged (shown in the audit log).", " maxlength=\"500\" required") +
+        _setupField("Operator id (UUID)", "flagged_by", "", "text", "The operator placing the flag.", " required") +
+        "<button class=\"btn btn--danger\" type=\"submit\">Flag</button>" +
+      "</form>"
+    : "";
+  // Reply form — only when no reply exists yet (one reply per rating; the
+  // primitive refuses a second with a 409).
+  var replyForm = !rt.response_html
+    ? "<form method=\"post\" action=\"/admin/ratings/" + _htmlEscape(rt.id) + "/respond\" class=\"return-action\">" +
+        "<h4>Public reply</h4>" +
+        _setupField("Reply", "response", "", "text", "Shown to the customer on their order page.", " maxlength=\"2000\" required") +
+        _setupField("Operator id (UUID)", "responded_by", "", "text", "The operator authoring the reply.", " required") +
+        "<button class=\"btn\" type=\"submit\">Post reply</button>" +
+      "</form>"
+    : "";
+  var actions = (flagForm || replyForm)
+    ? "<div class=\"return-actions\">" + flagForm + replyForm + "</div>"
+    : "";
+
+  return "<div class=\"panel review-card\">" +
+    "<div class=\"review-card__head\">" +
+      "<code class=\"order-id\">" + shortId + "</code> " +
+      "<span class=\"meta\">order <a class=\"order-id\" href=\"/admin/orders/" + _htmlEscape(rt.order_id) + "\">" + shortOrd + "</a></span> " +
+      flagState +
+    "</div>" +
+    "<p>" + scores + "</p>" +
+    commentBlock +
+    replyBlock +
+    actions +
+  "</div>";
+}
+
+// Order-ratings moderation console: the flagged-comment queue first, then a
+// list of recent ratings (lowest-scored first — the ones most likely to
+// need a reply). Each card carries the flag + public-reply forms.
+function renderAdminRatings(opts) {
+  opts = opts || {};
+  var recent  = opts.ratings || [];
+  var flagged = opts.flagged || [];
+  var onlyFlagged = !!opts.only_flagged;
+  var moved  = opts.moved  ? "<div class=\"banner banner--ok\">Rating updated.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var chips = "<div class=\"order-filters\">" +
+    "<a class=\"chip" + (!onlyFlagged ? " chip--on" : "") + "\" href=\"/admin/ratings\">all recent</a>" +
+    "<a class=\"chip" + (onlyFlagged ? " chip--on" : "") + "\" href=\"/admin/ratings?flagged=1\">flagged</a>" +
+    "</div>";
+
+  var flaggedCards = flagged.map(_ratingCard).join("");
+  var flaggedSection =
+    "<section><h2>Flagged comments</h2>" +
+      (flagged.length ? flaggedCards : "<p class=\"empty\">No flagged comments.</p>") +
+    "</section>";
+
+  // The recent list excludes the ones already in the flagged queue above so
+  // a flagged card isn't rendered twice on the default (unfiltered) view.
+  var recentList = recent.filter(function (r) { return !r.comment_flagged; });
+  var recentCards = recentList.map(_ratingCard).join("");
+  var recentSection = onlyFlagged ? "" :
+    "<section><h2>Recent ratings</h2>" +
+      (recentList.length ? recentCards : "<p class=\"empty\">No ratings yet.</p>") +
+    "</section>";
+
+  var body =
+    "<section><h2>Ratings</h2>" + moved + notice +
+      "<p class=\"meta\">Per-order shipping / packaging / recommend feedback. Flag a comment to suppress it on the storefront, or post one public reply the customer sees on their order page.</p>" +
+      chips +
+    "</section>" +
+    flaggedSection +
+    recentSection;
+  return _renderAdminShell(opts.shop_name, "Ratings", body, "ratings", opts.nav_available);
+}
+
 // The review states an operator can filter the moderation queue by.
 var REVIEW_STATUS_FILTERS = ["pending", "published", "rejected"];
 
@@ -15311,6 +15560,7 @@ module.exports = {
   renderAdminReturns:      renderAdminReturns,
   renderAdminReturn:       renderAdminReturn,
   renderAdminReviews:      renderAdminReviews,
+  renderAdminRatings:      renderAdminRatings,
   renderAdminQuestions:    renderAdminQuestions,
   renderAdminQuestion:     renderAdminQuestion,
   renderAdminCollections:  renderAdminCollections,

package/lib/asset-manifest.json

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

package/lib/order-ratings.js

@@ -455,6 +455,41 @@ function create(opts) {
     return _topRatings(input, "topNegativeRatings", "negative");
   }
 
+  // ---- listFlagged -----------------------------------------------------
+
+  // The moderation queue: every rating whose comment an operator has
+  // flagged, most-recent-first, backed by the (comment_flagged,
+  // occurred_at) index. Unlike topNegativeRatings (score-ordered, capped
+  // at MAX_TOP_LIMIT), this surfaces ALL flagged comments regardless of
+  // their score — so a flagged comment on an otherwise high rating is
+  // never hidden behind the score cap. The from/to window is optional and
+  // applied only when supplied; the row count is capped by `limit`.
+  async function listFlagged(input) {
+    input = (input && typeof input === "object") ? input : {};
+    var limit = _limit(input.limit, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, "limit");
+
+    var sql = "SELECT * FROM order_ratings WHERE comment_flagged = 1";
+    var params = [];
+    if (input.from != null || input.to != null) {
+      var from = _epoch(input.from, "from");
+      var to   = _epoch(input.to,   "to");
+      if (from > to) {
+        throw new TypeError("orderRatings.listFlagged: from must be <= to");
+      }
+      params.push(from);
+      sql += " AND occurred_at >= ?" + params.length;
+      params.push(to);
+      sql += " AND occurred_at <= ?" + params.length;
+    }
+    params.push(limit);
+    sql += " ORDER BY occurred_at DESC, id DESC LIMIT ?" + params.length;
+
+    var r = await query(sql, params);
+    var out = [];
+    for (var i = 0; i < r.rows.length; i += 1) out.push(_decode(r.rows[i]));
+    return out;
+  }
+
   return {
     RATING_AXES:           RATING_AXES.slice(),
     MIN_RATING:            MIN_RATING,
@@ -471,6 +506,7 @@ function create(opts) {
     responseToCustomer:    responseToCustomer,
     topPositiveRatings:    topPositiveRatings,
     topNegativeRatings:    topNegativeRatings,
+    listFlagged:           listFlagged,
   };
 }
 

package/lib/storefront.js

@@ -6128,6 +6128,7 @@ var ORDER_PAGE =
   "        </table>\n" +
   "      </div>\n" +
   "      RAW_ORDER_ACTIONS" +
+  "      RAW_ORDER_RATING" +
   "    </div>\n" +
   "    <aside class=\"order-page__totals\">\n" +
   "      RAW_ORDER_TIMELINE" +
@@ -6335,6 +6336,134 @@ function _orderActionsBlock(o) {
   return "<div class=\"order-page__actions\">" + btns.join("") + "</div>";
 }
 
+// A post-purchase rating is offered on the same window a return is: a paid
+// (or further-along) order, never a still-pending (unpaid) one nor the
+// terminal off-ramps (cancelled / refunded). The order FSM has no
+// `fulfilled` status — the post-payment states are paid / fulfilling /
+// shipped / delivered — so the rating window mirrors _orderEligibleForReturn
+// rather than gating on a status the primitive doesn't expose.
+function _orderEligibleForRating(status) {
+  return status === "paid" || status === "fulfilling" ||
+    status === "shipped" || status === "delivered";
+}
+
+// The three rating axes the customer scores, in display order. Labels are
+// static framework copy; the axis key matches the submitRating field name.
+var ORDER_RATING_AXES = [
+  { key: "shipping",  label: "Shipping",         field: "shipping_rating" },
+  { key: "packaging", label: "Packaging",        field: "packaging_rating" },
+  { key: "recommend", label: "Recommend us",     field: "recommend_rating" },
+];
+
+// 1–5 selector for one rating axis. Rendered as native radio buttons so the
+// form works with no JavaScript and a screen reader announces each option.
+// `field` is the submitRating field name; nothing here is operator/customer
+// input, but the labels are escaped at the sink for consistency.
+function _ratingAxisField(axis) {
+  var esc = b.template.escapeHtml;
+  var opts = "";
+  for (var v = 1; v <= 5; v += 1) {
+    opts +=
+      "<label class=\"order-rating__option\">" +
+        "<input type=\"radio\" name=\"" + esc(axis.field) + "\" value=\"" + v + "\" required>" +
+        "<span>" + v + "</span>" +
+      "</label>";
+  }
+  return "<fieldset class=\"order-rating__axis\">" +
+    "<legend>" + esc(axis.label) + "</legend>" +
+    "<div class=\"order-rating__scale\">" + opts + "</div>" +
+    "</fieldset>";
+}
+
+// The rating form (eligible, not-yet-rated order). Posts to
+// /orders/:id/rate; the container CSRF injection tokens it automatically
+// (the action is not an EDGE_POST_PATHS prefix). A correction notice from a
+// rejected submit (bad value / over-length comment / duplicate) renders
+// above the form.
+function _orderRatingForm(o, notice) {
+  var esc = b.template.escapeHtml;
+  var noticeHtml = notice
+    ? "<p class=\"form-notice form-notice--err\" role=\"alert\">" + esc(String(notice)) + "</p>"
+    : "";
+  var axes = ORDER_RATING_AXES.map(_ratingAxisField).join("");
+  return "<section class=\"order-rating order-rating--form\">" +
+    "<h2 class=\"pdp__variants-title\">Rate this order</h2>" +
+    "<p class=\"order-rating__lede\">How did the delivery go? Your feedback helps us improve.</p>" +
+    noticeHtml +
+    "<form class=\"form-stack\" method=\"post\" action=\"/orders/" + esc(String(o.id)) + "/rate\">" +
+      axes +
+      "<label class=\"form-field\"><span>Comment <small>(optional)</small></span>" +
+        "<textarea name=\"comment\" rows=\"3\" maxlength=\"2000\" " +
+          "placeholder=\"Tell us about your delivery experience\"></textarea></label>" +
+      "<div class=\"order-page__actions\">" +
+        "<button type=\"submit\" class=\"btn-primary\">Submit rating</button>" +
+      "</div>" +
+    "</form>" +
+    "</section>";
+}
+
+// The submitted rating (the three scores) plus, when present, the
+// customer's own comment and the operator's public reply. ESCAPE-BY-DEFAULT:
+// the comment and the reply are spliced from the primitive's pre-escaped
+// `comment_html` / `response_html` fields (escaped via b.template.escapeHtml
+// at the primitive's render layer), NEVER the raw `comment` / `response_text`
+// — so a `<script>`/`onerror` payload a customer typed is inert here. A
+// flagged comment is suppressed (operators moderate via the admin queue).
+function _orderRatingDisplay(rating) {
+  var esc = b.template.escapeHtml;
+  var scoreRows = ORDER_RATING_AXES.map(function (axis) {
+    return "<div><dt>" + esc(axis.label) + "</dt>" +
+      "<dd>" + esc(String(rating[axis.field])) + " / 5</dd></div>";
+  }).join("");
+  // comment_html is already escaped by the primitive — splice it, do not
+  // re-escape (double-escaping would render visible entities) and never
+  // reach for rating.comment (the raw, un-escaped string).
+  var commentHtml = (rating.comment_html && !rating.comment_flagged)
+    ? "<div class=\"order-rating__comment\"><h3>Your comment</h3>" +
+        "<p>" + rating.comment_html + "</p></div>"
+    : "";
+  // response_html is the operator's public reply, also pre-escaped — splice
+  // it, never rating.response_text.
+  var responseHtml = rating.response_html
+    ? "<div class=\"order-rating__response\"><h3>Our reply</h3>" +
+        "<p>" + rating.response_html + "</p></div>"
+    : "";
+  return "<section class=\"order-rating order-rating--done\">" +
+    "<h2 class=\"pdp__variants-title\">Your rating</h2>" +
+    "<dl class=\"order-rating__scores\">" + scoreRows + "</dl>" +
+    commentHtml +
+    responseHtml +
+    "</section>";
+}
+
+// Resolve the rating panel for the order page: the submitted rating (read-
+// only display) when one exists, the submission form when the order is
+// eligible and unrated, and nothing otherwise (a pending / cancelled /
+// refunded order, or a renderer reached without the ratings primitive
+// wired). `opts.rating` is the getRating row (or null); `opts.rating_notice`
+// is a correction message echoed back onto a rejected submit.
+function _orderRatingBlock(opts) {
+  var o = opts.order;
+  if (opts.rating) return _orderRatingDisplay(opts.rating);
+  if (opts.rating_eligible && _orderEligibleForRating(o.status)) {
+    return _orderRatingForm(o, opts.rating_notice || null);
+  }
+  return "";
+}
+
+// Map a ?rate_err= code (set by a rejected rating POST on its PRG redirect)
+// to a clean, operator-safe correction message rendered above the rating
+// form. Defensive request reader — an unknown / absent code yields no
+// notice, never a raw error or a leak. The duplicate / value / length codes
+// mirror the primitive's refusal classes without echoing its raw message.
+function _ratingNoticeFor(code) {
+  if (code === "dupe")    return "You've already rated this order.";
+  if (code === "value")   return "Please give each rating a score from 1 to 5.";
+  if (code === "comment") return "Your comment couldn't be saved — please shorten it and try again.";
+  if (code === "input")   return "Please check your rating and try again.";
+  return null;
+}
+
 function renderOrder(opts) {
   if (!opts || !opts.order) throw new TypeError("storefront.renderOrder: opts.order required");
   var o = opts.order;
@@ -6376,6 +6505,10 @@ function renderOrder(opts) {
   var timelineHtml = _orderTimelineBlock(o.status);
   var trackingHtml = _orderTrackingBlock(shipments);
   var actionsHtml  = _orderActionsBlock(o);
+  // Post-purchase rating panel — container-only (session-gated). The route
+  // passes the resolved getRating row (rating) + the eligibility/notice
+  // flags; the edge render never does, so the panel is empty at the edge.
+  var ratingHtml   = _orderRatingBlock(opts);
   if (opts.theme) {
     return opts.theme.render("order", {
       title:               "Order " + o.id,
@@ -6393,6 +6526,7 @@ function renderOrder(opts) {
       timeline_html:       timelineHtml,
       tracking_html:       trackingHtml,
       actions_html:        actionsHtml,
+      rating_html:         ratingHtml,
       can_return:          _orderEligibleForReturn(o.status),
       can_reorder:         _orderEligibleForReorder(o.status),
       can_cancel:          _orderEligibleForCancel(o.status),
@@ -6444,6 +6578,11 @@ function renderOrder(opts) {
     .replace("RAW_ORDER_TRACKING", trackingHtml)
     .replace("RAW_ORDER_ACTIONS", actionsHtml)
     .replace("RAW_SHIP_TO", _shipToAddressBlock(o.ship_to));
+  // The rating panel carries customer/operator free text (already escaped
+  // into comment_html / response_html, but a `$` in that text would still
+  // trip String.replace's dollar substitution) — splice it via the
+  // replacer-function helper, never a replacement-string .replace.
+  body = _spliceRaw(body, "RAW_ORDER_RATING", ratingHtml);
   // Post-purchase cross-sell rail — reuses the catalog grid + product-card
   // markup (so it inherits the storefront's card styling), rendered only
   // when the picker returned something.
@@ -10738,12 +10877,35 @@ function mount(router, deps) {
           }
         } catch (_e) { shipments = []; }
       }
+      // Post-purchase fulfillment rating. Surfaced only on a signed-in
+      // customer's OWN order (the IDOR gate above already proved
+      // o.customer_id === orderAuth.customer_id when set) — a guest order
+      // carries no owner, so the rating form/display is suppressed there.
+      // Best-effort: an absent ratings primitive (or its table unmigrated)
+      // degrades to "no rating panel" rather than 500-ing the order page.
+      var ratingRow = null;
+      var ratingEligible = false;
+      if (deps.orderRatings && o.customer_id && orderAuth && o.customer_id === orderAuth.customer_id) {
+        // Offer the rating surface only AFTER a successful read: an absent /
+        // unmigrated ratings table degrades to "no rating panel" rather than
+        // rendering a form whose POST would then 500 against the same missing
+        // table. Eligibility also tracks the order-status window so the form
+        // shows only when a submit would actually be accepted (the POST gates
+        // on the same _orderEligibleForRating check).
+        try {
+          ratingRow = await deps.orderRatings.getRating({ order_id: o.id });
+          ratingEligible = _orderEligibleForRating(o.status);
+        } catch (_e) { ratingRow = null; ratingEligible = false; }
+      }
       var ordUrl = req.url ? new URL(req.url, "http://localhost") : null;
       _send(res, 200, renderOrder({
         order:           o,
         product_lookup:  productLookup,
         recommendations: recommendations,
         shipments:       shipments,
+        rating:          ratingRow,
+        rating_eligible: ratingEligible,
+        rating_notice:   ordUrl ? _ratingNoticeFor(ordUrl.searchParams.get("rate_err")) : null,
         reordered:       ordUrl ? ordUrl.searchParams.get("reordered") === "1" : false,
         cancelled:       ordUrl ? ordUrl.searchParams.get("cancelled") === "1" : false,
         shop_name:       shopName,
@@ -14661,6 +14823,97 @@ function mount(router, deps) {
       res.setHeader && res.setHeader("location", "/orders/" + encodeURIComponent(o.id) + "?cancelled=1");
       return res.end ? res.end() : res.send("");
     });
+
+    // POST /orders/:id/rate — a customer rates one of their OWN orders
+    // (shipping / packaging / recommend, plus an optional comment). The
+    // rating's customer_id is pinned to the SESSION customer — never a
+    // form/query field — and the order_id is verified to belong to that
+    // session before submitRating runs. Two refusals guard against IDOR: an
+    // unauthenticated POST goes to login (never near an order), and a
+    // foreign / guest-owned / unknown / malformed order is a clean 404
+    // (never rated, never leaked). Bad input (rating out of [1,5], over-
+    // length comment) and a duplicate submission map to a clean correction
+    // redirect, never a 500 or a raw-error leak. Mounts only when the
+    // ratings primitive is wired.
+    if (deps.orderRatings) {
+      router.post("/orders/:order_id/rate", async function (req, res) {
+        var orderId = req.params && req.params.order_id;
+        // Rating is a logged-in-customer action — resolve the session first
+        // so an unauthenticated POST goes to login, never near the order.
+        var rateAuth = _currentCustomerEnv(req);
+        if (!rateAuth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          return res.end ? res.end() : res.send("");
+        }
+        var o;
+        try { o = orderId ? await deps.order.get(orderId) : null; }
+        catch (e) { if (e instanceof TypeError) { o = null; } else throw e; }
+        // Ownership gate against IDOR: a missing order, a malformed id, an
+        // order owned by another customer, OR a guest order with no owner
+        // all 404 — the rating never touches an order the caller doesn't own.
+        if (!o || !o.customer_id || o.customer_id !== rateAuth.customer_id) {
+          return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+        }
+        // Eligibility gate mirrors the rating window (paid → delivered). A
+        // pending / cancelled / refunded order bounces back unchanged.
+        if (!_orderEligibleForRating(o.status)) {
+          res.status(303);
+          res.setHeader && res.setHeader("location", "/orders/" + encodeURIComponent(o.id));
+          return res.end ? res.end() : res.send("");
+        }
+        var body = req.body || {};
+        // Defensive request-shape readers: the rating axes arrive as form
+        // strings — coerce to integers so the primitive's strict [1,5]
+        // integer validator sees a number (a blank / garbage field becomes
+        // NaN, which the primitive refuses as a clean TypeError → "value").
+        function _scoreField(raw) {
+          // Whole-string integer only. parseInt would silently accept a
+          // crafted "5abc" (→5) or "1.9" (→1) and persist a value the
+          // shopper never chose; require the entire field to be digits so
+          // anything else becomes NaN, which the primitive's strict [1,5]
+          // validator refuses as a clean "value" correction.
+          var s = String(raw == null ? "" : raw).trim();
+          if (!/^-?\d+$/.test(s)) return NaN;
+          var n = Number(s);
+          return Number.isInteger(n) ? n : NaN;
+        }
+        function _rateRedirect(code) {
+          res.status(303);
+          res.setHeader && res.setHeader("location",
+            "/orders/" + encodeURIComponent(o.id) + (code ? "?rate_err=" + code : ""));
+          return res.end ? res.end() : res.send("");
+        }
+        var comment = typeof body.comment === "string" && body.comment.length ? body.comment : undefined;
+        try {
+          await deps.orderRatings.submitRating({
+            order_id:         o.id,
+            customer_id:      rateAuth.customer_id,   // session-pinned, never from the form
+            shipping_rating:  _scoreField(body.shipping_rating),
+            packaging_rating: _scoreField(body.packaging_rating),
+            recommend_rating: _scoreField(body.recommend_rating),
+            comment:          comment,
+          });
+        } catch (e) {
+          // Coded errors first (a plain Error with .code), then the
+          // primitive's TypeErrors — so a duplicate surfaces its own notice
+          // rather than the generic bad-input one. Any of these is a clean
+          // correction redirect, never a 500.
+          if (e && e.code === "ORDER_RATING_ALREADY_EXISTS") return _rateRedirect("dupe");
+          if (e instanceof TypeError) {
+            // The comment validator's message names "comment"; everything
+            // else is a rating-value problem. Either way, no raw leak.
+            var isComment = /comment/.test(String(e.message || ""));
+            return _rateRedirect(isComment ? "comment" : "value");
+          }
+          throw e;
+        }
+        // PRG back to the order page — the submitted rating now renders in
+        // place of the form (a refresh doesn't re-submit).
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/orders/" + encodeURIComponent(o.id));
+        return res.end ? res.end() : res.send("");
+      });
+    }
   }
 
   // POST /cart/lines — add a line. Reads variant_id + qty from the

package/package.json

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