@blamejs/blamejs-shop 0.3.42 → 0.3.44

package/lib/admin.js

@@ -503,6 +503,7 @@ function mount(router, deps) {
   var customerSegments = deps.customerSegments || null;  // per-customer segment-membership panel disabled when absent
   var orderTracking = deps.orderTracking || null;   // shipment/tracking panel disabled when absent
   var salesReports  = deps.salesReports  || null;   // /admin/reports degrades to an unconfigured notice when absent
+  var orderExport   = deps.orderExport   || null;   // /admin/exports (date-range CSV/NDJSON dump + scheduled-export queue) disabled when absent
   var printReceipts = deps.printReceipts || null;   // order receipt document disabled when absent
   var packingSlips  = deps.packingSlips  || null;   // order packing-slip document disabled when absent
   var pickLists      = deps.pickLists      || null;  // warehouse pick-list console disabled when absent
@@ -511,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
@@ -519,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 };
+  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 */ }
 
@@ -6429,6 +6431,422 @@ function mount(router, deps) {
     });
   }
 
+  // ---- order export ---------------------------------------------------
+  //
+  // Bulk, date-range dump of the orders table to CSV / NDJSON, plus the
+  // queue of operator-filed scheduled-export jobs a background worker
+  // drains. Distinct from the per-order receipt CSV columns and the
+  // /admin/reports day-series ?format=csv (an aggregate, not the rows):
+  // this is the full row-level order set for offline analysis,
+  // accounting reconciliation, or a 3PL handoff.
+  //
+  // Surfaces (mounted only when the orderExport primitive is wired):
+  //   GET  /admin/exports                       — screen: range form +
+  //         summary preview (count + total) + the scheduled-export list +
+  //         a schedule-a-new-export form (bearer JSON returns the summary +
+  //         the export rows).
+  //   GET  /admin/exports/download?from=&to=&format=
+  //                                             — file response: streams
+  //         csvForRange / ndjsonForRange with the right content-type +
+  //         content-disposition. The primitive owns the CSV-injection
+  //         defense (a leading = / + / - / @ cell is prefixed with `'`),
+  //         so the route composes its output and never hand-rolls
+  //         serialization from raw order fields.
+  //   POST /admin/exports/schedule              — file a scheduled job.
+  //   POST /admin/exports/:id/cancel            — cancel a queued job.
+  //
+  // Range: from/to are calendar-date (YYYY-MM-DD) inputs from the browser,
+  // or raw epoch-ms for the JSON API. The window is half-open [from, to):
+  // the inclusive end day advances to the next UTC midnight so the chosen
+  // day is fully covered. An empty or inverted range is a config/entry-tier
+  // 400 (the operator corrects the typo), surfaced via _safeNotice.
+  if (orderExport) {
+    var EXPORT_FORMATS = orderExport.FORMATS || ["csv", "ndjson"];
+
+    // Resolve the export window from the query string into epoch-ms
+    // [from, to). Reuses the report screen's date helpers: the epoch-ms
+    // `from`/`to` pair wins for machine clients; the calendar-date
+    // `from-date`/`to-date` pair is what the browser date inputs submit
+    // (the `to-date` end day is inclusive, so step to the next UTC midnight).
+    // Both bounds are required — there is no implicit "last 30 days" default
+    // for a bulk dump, so a missing bound is a clean 400 rather than a
+    // surprise full-table export. Throws TypeError on a malformed/empty/
+    // inverted range; the orderExport primitive re-validates (non-negative
+    // integers, to >= from).
+    function _exportWindow(url) {
+      var from = _parseEpochMs(url && url.searchParams.get("from"), "from");
+      var to   = _parseEpochMs(url && url.searchParams.get("to"),   "to");
+      if (from == null) from = _parseDateParam(url && url.searchParams.get("from-date"), "from");
+      if (to == null) {
+        var toDate = _parseDateParam(url && url.searchParams.get("to-date"), "to");
+        if (toDate != null) to = toDate + b.constants.TIME.days(1);
+      }
+      if (from == null || to == null) {
+        throw new TypeError("admin: a from and a to date are both required for an export");
+      }
+      if (to <= from) {
+        throw new TypeError("admin: the to date must be after the from date");
+      }
+      return { from: from, to: to };
+    }
+
+    function _exportFormat(url) {
+      var f = (url && url.searchParams.get("format")) || "csv";
+      if (EXPORT_FORMATS.indexOf(f) === -1) {
+        throw new TypeError("admin: format must be one of " + EXPORT_FORMATS.join(", "));
+      }
+      return f;
+    }
+
+    // Stream the chosen format's async-iterable into the response body.
+    // csvForRange / ndjsonForRange yield the header (CSV) then one chunk
+    // per database batch; the route writes each batch to the socket as it
+    // is produced, so the process holds at most one batch in memory no
+    // matter how many orders the range covers (the resumable streamCursor
+    // / scheduled-export queue remains the path for an out-of-band dump).
+    // The primitive RFC-4180-quotes every CSV cell and neutralizes the
+    // spreadsheet-formula injection vector, so the route never touches the
+    // cell bytes.
+    async function _streamExport(res, win, format) {
+      var iter = format === "ndjson"
+        ? orderExport.ndjsonForRange({ from: win.from, to: win.to })
+        : orderExport.csvForRange({ from: win.from, to: win.to });
+      var contentType = format === "ndjson"
+        ? "application/x-ndjson; charset=utf-8"
+        : "text/csv; charset=utf-8";
+      var ext      = format === "ndjson" ? "ndjson" : "csv";
+      var fromDay  = _dateInputValue(win.from);
+      var toDay    = _dateInputValue(win.to - b.constants.TIME.days(1));
+      var filename = "orders-" + (fromDay || "start") + "-to-" + (toDay || "end") + "." + ext;
+      res.status(200);
+      if (res.setHeader) {
+        res.setHeader("content-type", contentType);
+        // The filename is built from validated epoch-ms date strings
+        // (digits + hyphens only), so it carries no quote/CRLF that could
+        // break out of the header — but keep it ASCII-safe regardless.
+        res.setHeader("content-disposition", "attachment; filename=\"" + filename.replace(/[^A-Za-z0-9._-]/g, "") + "\"");
+        res.setHeader("x-content-type-options", "nosniff");
+      }
+      // Write the header first, then one chunk per batch as the primitive
+      // yields it — bounded memory regardless of the order count. A
+      // response without an incremental write() (a JSON test stub) falls
+      // back to buffering the date-bounded window.
+      if (typeof res.write === "function" && typeof res.end === "function") {
+        for await (var chunk of iter) {
+          if (chunk) res.write(chunk);
+        }
+        res.end();
+      } else {
+        var body = "";
+        for await (var c2 of iter) body += c2;
+        if (res.end) res.end(body); else res.send(body);
+      }
+    }
+
+    router.get("/admin/exports", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        // A download link carries ?download=1 (+ from/to/format); the bearer
+        // API serves it as a file too so tooling can pull the dump directly.
+        if (url && url.searchParams.get("download")) {
+          var winD, fmtD;
+          try { winD = _exportWindow(url); fmtD = _exportFormat(url); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          return _streamExport(res, winD, fmtD);
+        }
+        // Summary preview for a chosen range (omitted when no range given).
+        var summary = null, win = null;
+        if ((url && url.searchParams.get("from")) || (url && url.searchParams.get("from-date"))) {
+          try { win = _exportWindow(url); }
+          catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+          summary = await orderExport.summaryForRange({ from: win.from, to: win.to });
+        }
+        var listing = await orderExport.listExports({ limit: 50 });
+        _json(res, 200, { summary: summary, range: win, exports: listing.rows || [] });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        // Download from the browser surface too (a link, not a fetch).
+        if (url && url.searchParams.get("download")) {
+          var win0, fmt0;
+          try { win0 = _exportWindow(url); fmt0 = _exportFormat(url); }
+          catch (e) {
+            var nd = _safeNotice(e, "export.download");
+            var rowsD = (await orderExport.listExports({ limit: 50 })).rows || [];
+            return _sendHtml(res, nd.status, renderAdminExports({
+              shop_name: deps.shop_name, nav_available: navAvailable, exports: rowsD,
+              formats: EXPORT_FORMATS, notice: nd.message.replace(/^admin:\s*/, ""),
+            }));
+          }
+          return _streamExport(res, win0, fmt0);
+        }
+        // Optional summary preview for a chosen range. A malformed/empty/
+        // inverted range re-renders the screen with a correction notice
+        // (config/entry tier) rather than 500-ing.
+        var summary = null, win = null, format = "csv", notice = null;
+        var hasRange = (url && url.searchParams.get("from-date")) || (url && url.searchParams.get("from"));
+        if (hasRange) {
+          try {
+            win = _exportWindow(url);
+            format = _exportFormat(url);
+            summary = await orderExport.summaryForRange({ from: win.from, to: win.to });
+          } catch (e) {
+            if (!(e instanceof TypeError)) throw e;
+            notice = _safeNotice(e, "export.summary").message.replace(/^admin:\s*/, "");
+            win = null; summary = null;
+          }
+        }
+        var rows = (await orderExport.listExports({ limit: 50 })).rows || [];
+        _sendHtml(res, 200, renderAdminExports({
+          shop_name: deps.shop_name, nav_available: navAvailable, exports: rows,
+          formats: EXPORT_FORMATS, summary: summary, range: win, format: format,
+          scheduled: url && url.searchParams.get("scheduled"),
+          cancelled: url && url.searchParams.get("cancelled"),
+          notice:    notice,
+        }));
+      },
+    ));
+
+    // The dedicated download route — a plain link target (and a bearer GET
+    // for tooling). Same file response on both surfaces.
+    router.get("/admin/exports/download", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var win, format;
+        try { win = _exportWindow(url); format = _exportFormat(url); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        return _streamExport(res, win, format);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var win, format;
+        try { win = _exportWindow(url); format = _exportFormat(url); }
+        catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          var n = _safeNotice(e, "export.download");
+          var rows = (await orderExport.listExports({ limit: 50 })).rows || [];
+          return _sendHtml(res, n.status, renderAdminExports({
+            shop_name: deps.shop_name, nav_available: navAvailable, exports: rows,
+            formats: EXPORT_FORMATS, notice: n.message.replace(/^admin:\s*/, ""),
+          }));
+        }
+        return _streamExport(res, win, format);
+      },
+    ));
+
+    // File a scheduled export job. Range + format are validated here (the
+    // same _exportWindow / _exportFormat shape the download uses); the
+    // primitive re-validates and persists a `queued` row a worker drains.
+    router.post("/admin/exports/schedule", _pageOrApi(false,
+      W("export.schedule", async function (req, res) {
+        var body = req.body || {};
+        var job = await orderExport.scheduleExport({
+          format: body.format,
+          from:   _strictNonNegIntField(body.from, "from"),
+          to:     _strictNonNegIntField(body.to,   "to"),
+        });
+        _json(res, 201, job);
+        return { id: job.id };
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        // The browser form submits calendar-date inputs; coerce to the
+        // epoch-ms [from, to) window the primitive expects.
+        try {
+          var win = _exportWindow(new URL("http://localhost/?" +
+            "from-date=" + encodeURIComponent(body["from-date"] || "") +
+            "&to-date=" + encodeURIComponent(body["to-date"] || "")));
+          var format = (body.format && EXPORT_FORMATS.indexOf(body.format) !== -1) ? body.format : null;
+          if (!format) throw new TypeError("admin: format must be one of " + EXPORT_FORMATS.join(", "));
+          await orderExport.scheduleExport({ format: format, from: win.from, to: win.to });
+        } catch (e) {
+          var n = _safeNotice(e, "export.schedule");
+          var rows = (await orderExport.listExports({ limit: 50 })).rows || [];
+          return _sendHtml(res, n.status, renderAdminExports({
+            shop_name: deps.shop_name, nav_available: navAvailable, exports: rows,
+            formats: EXPORT_FORMATS, notice: n.message.replace(/^admin:\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".export.schedule", outcome: "success" });
+        _redirect(res, "/admin/exports?scheduled=1");
+      },
+    ));
+
+    // Cancel a queued scheduled export. A malformed id is a 400; an unknown
+    // id (or a job past `queued`, which the FSM refuses) is surfaced as a
+    // correction notice on the browser path / a 4xx on the bearer path.
+    router.post("/admin/exports/:id/cancel", _pageOrApi(false,
+      W("export.cancel", async function (req, res) {
+        var row;
+        try { row = await orderExport.cancelExport(req.params.id); }
+        catch (e) {
+          // The FSM refuses a cancel once the job is running/terminal — a
+          // coded conflict (409), checked first. It is a plain Error with a
+          // .code, never a TypeError; the message is operator-safe (it names
+          // the refused transition, never storage internals).
+          if (e && e.code) return _problem(res, 409, "conflict", "That export can no longer be cancelled.");
+          // A syntactically valid id that names no job is a not-found
+          // TypeError — distinct from a malformed id — so map it to 404 (a
+          // malformed id stays a 400) and clients can tell the two apart.
+          if (e instanceof TypeError && / not found$/.test(String(e.message || ""))) {
+            return _problem(res, 404, "export-not-found");
+          }
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          throw e;
+        }
+        // cancelExport throws on a missing row, so a falsy return is purely
+        // defensive — keep the 404 in case the primitive ever returns null.
+        if (!row) return _problem(res, 404, "export-not-found");
+        _json(res, 200, row);
+        return { id: row.id };
+      }),
+      async function (req, res) {
+        var ok = false;
+        try { ok = !!(await orderExport.cancelExport(req.params.id)); }
+        catch (_e) { ok = false; }
+        if (!ok) return _redirect(res, "/admin/exports?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".export.cancel", outcome: "success", metadata: { id: req.params.id } });
+        _redirect(res, "/admin/exports?cancelled=1");
+      },
+    ));
+  }
+
+  // ---- 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;
@@ -9277,11 +9695,13 @@ var ADMIN_NAV_ITEMS = [
   { key: "inventory",    href: "/admin/inventory",    label: "Inventory" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
   { key: "reports",      href: "/admin/reports",      label: "Reports" },
+  { key: "exports",      href: "/admin/exports",      label: "Exports",      requires: "orderExport" },
   { 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: "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" },
@@ -9702,6 +10122,114 @@ function renderAdminReports(opts) {
   return _renderAdminShell(opts.shop_name, "Reports", body, "reports", opts.nav_available);
 }
 
+// Order-export screen. A date-range + format picker drives a summary
+// preview (order count + total for the chosen window) and the two download
+// links (CSV / NDJSON); below it the scheduled-export queue lists every
+// operator-filed job with a per-job cancel, and a schedule-a-new-export
+// form files one. `opts.summary` is null until the operator picks a range;
+// `opts.exports` is the scheduled-export rows.
+var EXPORT_STATUS_PILL = {
+  queued:    "pending",
+  running:   "fulfilling",
+  complete:  "paid",
+  failed:    "refunded",
+  cancelled: "cancelled",
+};
+function renderAdminExports(opts) {
+  opts = opts || {};
+  var exportsRows = opts.exports || [];
+  var formats     = opts.formats || ["csv", "ndjson"];
+  var summary     = opts.summary || null;
+  var range       = opts.range   || null;
+  var notice    = opts.notice    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var scheduled = opts.scheduled ? "<div class=\"banner banner--ok\">Export scheduled.</div>" : "";
+  var cancelled = opts.cancelled ? "<div class=\"banner banner--ok\">Export cancelled.</div>" : "";
+
+  // The range form prefills with the chosen window (or blank). It GETs back
+  // to /admin/exports so the window lives in the URL (bookmarkable) and the
+  // summary preview re-renders; the two download links carry the same window
+  // + the format as a ?download=1 query.
+  var fromVal = range ? _dateInputValue(range.from) : "";
+  var toVal   = range ? _dateInputValue(range.to - b.constants.TIME.days(1)) : "";
+
+  var rangeForm =
+    "<form method=\"get\" action=\"/admin/exports\" class=\"order-filters\">" +
+      "<label class=\"form-field\"><span>From</span><input type=\"date\" name=\"from-date\" value=\"" + _htmlEscape(fromVal) + "\" required></label>" +
+      "<label class=\"form-field\"><span>To</span><input type=\"date\" name=\"to-date\" value=\"" + _htmlEscape(toVal) + "\" required></label>" +
+      "<button class=\"btn\" type=\"submit\">Preview range</button>" +
+    "</form>";
+
+  // Summary preview + download links (only once a valid range is chosen).
+  var previewBlock = "";
+  if (summary && range) {
+    // Pick a headline currency from the by_currency map (the busiest
+    // bucket); fall back to USD when the window is empty.
+    var curBuckets = Object.keys(summary.by_currency || {});
+    var headlineCur = curBuckets.length ? curBuckets[0] : "USD";
+    var qWin = "from=" + encodeURIComponent(String(range.from)) + "&to=" + encodeURIComponent(String(range.to));
+    var dlLinks = formats.map(function (f) {
+      return "<a class=\"btn btn--ghost\" href=\"/admin/exports/download?" + qWin + "&format=" + encodeURIComponent(f) + "\">Download " + _htmlEscape(f.toUpperCase()) + "</a>";
+    }).join("");
+    previewBlock =
+      "<section><h2>Range preview</h2>" +
+        "<p class=\"meta\">Window: " + _htmlEscape(_fmtDate(range.from)) + " → " + _htmlEscape(_fmtDate(range.to - b.constants.TIME.days(1))) + " (inclusive)</p>" +
+        "<div class=\"stat-grid\">" +
+          _statCard("Orders in range", String(summary.order_count)) +
+          _statCard("Revenue", pricing.format(summary.revenue_minor, headlineCur)) +
+          _statCard("Avg order value", pricing.format(summary.average_order_minor, headlineCur)) +
+        "</div>" +
+        "<div class=\"actions-row mt\">" + dlLinks + "</div>" +
+      "</section>";
+  }
+
+  // Scheduled-export queue table.
+  var jobRows = exportsRows.map(function (j) {
+    var pill = EXPORT_STATUS_PILL[j.status] || "pending";
+    var from = j.from_ts != null ? _fmtDate(j.from_ts) : "—";
+    var to   = j.to_ts   != null ? _fmtDate(j.to_ts)   : "—";
+    var rowCount = (j.row_count != null) ? String(j.row_count) : "—";
+    var enc = _htmlEscape(encodeURIComponent(j.id));
+    var cancelCell = j.status === "queued"
+      ? "<form method=\"post\" action=\"/admin/exports/" + enc + "/cancel\" class=\"form-inline\">" +
+          "<button class=\"btn btn--danger\" type=\"submit\">Cancel</button></form>"
+      : "<span class=\"meta\">—</span>";
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(String(j.format || "")) + "</code></td>" +
+      "<td>" + _htmlEscape(from) + " → " + _htmlEscape(to) + "</td>" +
+      "<td><span class=\"status-pill " + pill + "\">" + _htmlEscape(String(j.status || "")) + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(rowCount) + "</td>" +
+      "<td>" + cancelCell + "</td>" +
+    "</tr>";
+  }).join("");
+  var jobTable = exportsRows.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Format</th><th scope=\"col\">Window</th><th scope=\"col\">Status</th><th scope=\"col\" class=\"num\">Rows</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + jobRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No scheduled exports yet.</p>";
+
+  var scheduleFmtOptions = formats.map(function (f) {
+    return "<option value=\"" + _htmlEscape(f) + "\">" + _htmlEscape(f.toUpperCase()) + "</option>";
+  }).join("");
+  var scheduleForm =
+    "<div class=\"panel mt mw-42\">" +
+      "<h3 class=\"subhead\">Schedule an export</h3>" +
+      "<p class=\"meta\">Queue a date-range dump for a background worker to produce. The job appears below as “queued” and can be cancelled until the worker claims it.</p>" +
+      "<form method=\"post\" action=\"/admin/exports/schedule\">" +
+        "<label class=\"form-field\"><span>From</span><input type=\"date\" name=\"from-date\" required></label>" +
+        "<label class=\"form-field\"><span>To</span><input type=\"date\" name=\"to-date\" required></label>" +
+        "<label class=\"form-field\"><span>Format</span><select name=\"format\">" + scheduleFmtOptions + "</select></label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Schedule export</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var body =
+    "<section><h2>Exports</h2>" + notice + scheduled + cancelled +
+      "<p class=\"meta\">Dump the full order set for a date range to CSV or NDJSON — for accounting, analysis, or a fulfilment-partner handoff. Customer email is pseudonymised in the output.</p>" +
+      rangeForm +
+    "</section>" +
+    previewBlock +
+    "<section><h2>Scheduled exports</h2>" + jobTable + scheduleForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Exports", body, "exports", opts.nav_available);
+}
+
 // A single shipping-label row for the standalone cross-order tables. Shows
 // carrier + service, tracking number, cost (via pricing.format from the
 // label's own minor units + currency), the broker it came from, its status
@@ -11247,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"];
 
@@ -14921,6 +15560,7 @@ module.exports = {
   renderAdminReturns:      renderAdminReturns,
   renderAdminReturn:       renderAdminReturn,
   renderAdminReviews:      renderAdminReviews,
+  renderAdminRatings:      renderAdminRatings,
   renderAdminQuestions:    renderAdminQuestions,
   renderAdminQuestion:     renderAdminQuestion,
   renderAdminCollections:  renderAdminCollections,