@blamejs/blamejs-shop 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- v0.1.9 (2026-05-25) — **Admin console — a returns moderation screen.** Returns join the admin console. `/admin/returns` is the RMA moderation queue: filter by status (pending, approved, received, refunded, rejected), and open a request to see its items, reason, customer notes, and linked order. From the detail page an operator works the return through its lifecycle — approve with a refund amount, mark the goods received, record the refund, or reject with a reason shown to the customer — with only the moves legal from the current status offered. An illegal move or a bad id is refused with a notice rather than an error. As with Products and Orders, every path content-negotiates: a bearer-token client gets the JSON API unchanged, a signed-in browser gets the HTML console. **Added:** *Returns moderation screen* — `/admin/returns` renders the RMA queue as a table (RMA code, order, reason, status, item count, refund amount, requested date) with status-filter chips, when opened in a signed-in browser; the same path serves the existing JSON list to a bearer-token client. Each return links to a detail page showing its line items, reason and customer notes, linked order, and refund details, with the legal next actions as forms — Approve takes a refund amount and currency, Reject takes a reason, Mark received and Refund are single-click. Each posts to its own endpoint and redirects (PRG); an unknown id renders a 404 page and an illegal or refused action redirects back with a notice, never a 500. · *returns.transitionsFrom* — `returns.transitionsFrom(status)` returns the moderation events legal from a given status as `{ on, to }`, derived from the same transition table the setters use — so the console's action buttons stay in lockstep with the return state machine. **Changed:** *Console nav gains Returns; the returns API content-negotiates* — The signed-in admin nav now includes Returns alongside Home, Dashboard, Products, Orders, Integrations, and Setup — shown only when the returns primitive is wired, so the link never points at an unmounted route. The `/admin/returns` list, detail, and approve / received / refund / reject endpoints now serve the HTML console to a signed-in browser while continuing to serve the JSON API to a bearer-token client unchanged. A request without the bearer token is no longer answered with a 401 on these paths — a browser GET receives the sign-in form and a write redirects to the console, matching the other console screens.
+
 - v0.1.8 (2026-05-25) — **Admin console — an orders screen with full lifecycle control.** Orders join the admin console. `/admin/orders` lists recent orders newest-first with one-click status filters, and each order opens to its line items, totals, shipping address, and payment reference. From the detail page an operator drives the order through its lifecycle — mark paid, start fulfilment, mark shipped, mark delivered, cancel, refund — with only the moves that are legal from the current status offered as buttons; an illegal move is refused with a notice rather than an error. Refund moves money, so the console Refund button issues a real payment-provider refund (and only appears when a provider is wired and the order has a captured intent) before the order advances to refunded. As with Products, every path content-negotiates: a bearer-token client gets the JSON API unchanged, a signed-in browser gets the HTML console. **Added:** *Orders management screen* — `/admin/orders` renders recent orders as a table (order, status, item count, total, placed date) with status-filter chips, when opened in a signed-in browser; the same path serves a new JSON list to a bearer-token client. Each order links to a detail page showing its line items, subtotal / tax / shipping / total, shipping address, and linked payment intent, with the order's legal next transitions as action buttons that post back and redirect (PRG). The Refund button posts to the payment-refund flow — it issues the provider refund and then advances the order, so a console refund never marks an order refunded without moving the money; it appears only when a payment provider is wired and the order has a captured intent (partial refunds remain on the JSON API). A bad or unknown order id renders a 404 page, never a 500; an illegal or failed action redirects back with a notice and leaves the order unchanged. · *order.listRecent + order.transitionsFrom* — `order.listRecent({ limit, status })` returns recent orders across all customers (guest orders included), newest-first, optionally filtered to one status, with line items and shipping hydrated. `order.transitionsFrom(status)` returns the lifecycle moves legal from a given status as `{ on, to, label }` — both derived from a single order-FSM edge list, so the console actions stay in lockstep with the state machine. **Changed:** *Console nav gains Orders; dashboard orders link through* — The signed-in admin nav now includes Orders alongside Home, Dashboard, Products, Integrations, and Setup. The dashboard's recent-orders list links each row to its order detail.
 
 - v0.1.7 (2026-05-25) — **Admin console — persistent navigation and a products screen.** The admin is now a cohesive, navigable web console rather than a set of disconnected pages. A persistent nav (Home, Dashboard, Products, Integrations, Setup) runs across every signed-in page, and Products is the first full management screen: browse the catalog, create a product, and archive or restore one — all from the browser. The JSON API is unchanged: an endpoint serves the HTML console to a signed-in browser and JSON to a bearer-token client, so tooling keeps working exactly as before. **Added:** *Console navigation* — Every signed-in admin page shares a top nav with the current section highlighted, so the dashboard, products, integrations, and setup wizard are one console. The shell is the same brand-matched layout as the dashboard. · *Products management screen* — `/admin/products` renders the catalog as a table (title, slug, status) with Archive / Restore actions and a New-product form, when opened in a signed-in browser. The same path returns the existing JSON list to a bearer-token client; create, archive, and restore content-negotiate the same way (browser form → redirect; bad input re-renders with a notice, never a 500). The product create / archive / restore JSON API is unchanged.

package/README.md

@@ -72,7 +72,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/collections.js`** | Curated + smart product groupings. `GET /collections` lists the shop's active collections; `GET /collections/:slug` renders the grid — manual collections list hand-picked members, smart collections evaluate stored rules against the active catalog and apply the collection's sort strategy. Each product resolves fresh, so archived products drop out. Public, no sign-in; a bad or unknown slug is a 404 (never a 500). Linked from the footer on every page. |
 | **`lib/subscriptions.js`** | Stripe-backed recurring billing — `subscription_plans` (interval / amount / trial) + `subscriptions` (mirrors Stripe's object byte-for-byte). `subscriptions.create` POSTs to Stripe via the payment dep, then persists the returned object locally. `handleStripeEvent` replays `customer.subscription.*` events into the local row so the shop has an authoritative view without round-tripping. |
 | **`lib/newsletter.js`** | Operator-collected email broadcast list — `signup({ email, source })` composes `b.guardEmail` for shape validation, `b.crypto.namespaceHash` for the dedup key, and `INSERT OR IGNORE` for idempotency. Storefront POST `/newsletter` route renders a designed thank-you card with separate copy for the `new` vs `dedup` branches. |
-| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel, refund) through the order FSM. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. |
+| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM; **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. |
 | **`lib/catalog-import.js`** | Bulk CSV import — `POST /admin/catalog/import` accepts a `text/csv` body, parses via `b.csv`, content-safety-filters every cell through `b.guardCsv` (formula-injection / bidi / control / dangerous-function denylist), validates exact header order, de-dupes rows by `product_slug`, returns per-row errors without aborting. Default 1 MiB / 10000 rows caps. |
 | **`lib/theme.js`** | File-backed templates with fallback chain. Operators register a named theme under `<themesDir>/<name>/*.html` and the storefront dispatches every renderer through it. `assetUrl(path)` resolves to `/assets/themes/<name>/<path>`. The shipped `default` theme is the fallback. |
 

package/lib/admin.js

@@ -226,6 +226,11 @@ function mount(router, deps) {
   var reviews       = deps.reviews       || null;   // moderation endpoints disabled when absent
   var returns       = deps.returns       || null;   // RMA moderation endpoints disabled when absent
 
+  // Which optional console sections are wired — gates their nav links so a
+  // signed-in admin is never sent to a route that wasn't mounted. Passed
+  // into every authed render call as `nav_available`.
+  var navAvailable = { returns: !!returns, reviews: !!reviews };
+
   try { _b().audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
   var W = function (auditAction, h) {
@@ -277,7 +282,7 @@ function mount(router, deps) {
         if (e instanceof TypeError || e.code === "CATALOG_DUPLICATE" || /slug|exists|duplicate/i.test(e.message || "")) {
           var page = await catalog.products.list({ limit: 100 });
           return _sendHtml(res, 400, renderAdminProducts({
-            shop_name: deps.shop_name, products: page.rows || [],
+            shop_name: deps.shop_name, nav_available: navAvailable, products: page.rows || [],
             notice: (e && e.message) || "Couldn't create that product.",
           }));
         }
@@ -321,7 +326,7 @@ function mount(router, deps) {
       var url = req.url ? new URL(req.url, "http://localhost") : null;
       var created = !!(url && url.searchParams.get("created"));
       var page = await catalog.products.list({ limit: 100 });
-      _sendHtml(res, 200, renderAdminProducts({ shop_name: deps.shop_name, products: page.rows || [], created: created }));
+      _sendHtml(res, 200, renderAdminProducts({ shop_name: deps.shop_name, nav_available: navAvailable, products: page.rows || [], created: created }));
     },
   ));
 
@@ -622,7 +627,7 @@ function mount(router, deps) {
       }
       var list = await order.listRecent({ status: status || undefined, limit: 100 });
       _sendHtml(res, 200, renderAdminOrders({
-        shop_name: deps.shop_name, orders: list.rows || [],
+        shop_name: deps.shop_name, nav_available: navAvailable, orders: list.rows || [],
         status: status, notice: notice,
       }));
     },
@@ -640,11 +645,12 @@ function mount(router, deps) {
       try { o = await order.get(req.params.id); }
       catch (e) { if (!(e instanceof TypeError)) throw e; o = null; }
       if (!o) return _sendHtml(res, 404, renderAdminOrders({
-        shop_name: deps.shop_name, orders: [], notice: "Order not found.",
+        shop_name: deps.shop_name, nav_available: navAvailable, orders: [], notice: "Order not found.",
       }));
       var url = req.url ? new URL(req.url, "http://localhost") : null;
       _sendHtml(res, 200, renderAdminOrder({
         shop_name:   deps.shop_name,
+        nav_available: navAvailable,
         order:       o,
         transitions: order.transitionsFrom(o.status),
         // Refund moves money, so the console only offers it when a payment
@@ -819,94 +825,182 @@ function mount(router, deps) {
       return null;
     }
 
-    router.get("/admin/returns", R(async function (req, res) {
-      var url = req.url ? new URL(req.url, "http://localhost") : null;
-      var status = (url && url.searchParams.get("status")) || "pending";
-      var cursor = url && url.searchParams.get("cursor");
-      var limitS = url && url.searchParams.get("limit");
-      var limit  = limitS == null ? undefined : parseInt(limitS, 10);
-      var page = await returns.listByStatus(status, { cursor: cursor || undefined, limit: limit });
-      _json(res, 200, page);
-    }));
+    router.get("/admin/returns", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var status = (url && url.searchParams.get("status")) || "pending";
+        var cursor = url && url.searchParams.get("cursor");
+        var limitS = url && url.searchParams.get("limit");
+        var limit  = limitS == null ? undefined : parseInt(limitS, 10);
+        var page = await returns.listByStatus(status, { cursor: cursor || undefined, limit: limit });
+        _json(res, 200, page);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var status = (url && url.searchParams.get("status")) || "pending";
+        var notice = null, rows = [];
+        // A bad ?status= (not one of the RMA states) raises a TypeError
+        // from listByStatus — fall back to pending with a notice rather
+        // than erroring the page.
+        try {
+          var page = await returns.listByStatus(status, { limit: 100 });
+          rows = page.rows || [];
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          status = "pending"; notice = "Unknown status filter — showing pending returns.";
+          rows = (await returns.listByStatus("pending", { limit: 100 })).rows || [];
+        }
+        _sendHtml(res, 200, renderAdminReturns({
+          shop_name: deps.shop_name, nav_available: navAvailable, returns: rows, status: status, notice: notice,
+        }));
+      },
+    ));
 
-    router.get("/admin/returns/:id", R(async function (req, res) {
-      var rma;
-      try {
-        rma = await returns.get(req.params.id);
-      } catch (e) {
-        // A non-UUID :id raises a guardUuid TypeError — surface it as a
-        // 404 (the route is a defensive request-shape reader, never a
-        // 500). Re-raise anything that isn't the bad-id shape so the
-        // wrapper's generic handling applies.
-        if (e instanceof TypeError) return _problem(res, 404, "return-not-found");
-        throw e;
-      }
-      if (!rma) return _problem(res, 404, "return-not-found");
-      _json(res, 200, rma);
-    }));
+    router.get("/admin/returns/:id", _pageOrApi(true,
+      R(async function (req, res) {
+        var rma;
+        try {
+          rma = await returns.get(req.params.id);
+        } catch (e) {
+          // A non-UUID :id raises a guardUuid TypeError — surface it as a
+          // 404 (the route is a defensive request-shape reader, never a
+          // 500). Re-raise anything that isn't the bad-id shape so the
+          // wrapper's generic handling applies.
+          if (e instanceof TypeError) return _problem(res, 404, "return-not-found");
+          throw e;
+        }
+        if (!rma) return _problem(res, 404, "return-not-found");
+        _json(res, 200, rma);
+      }),
+      async function (req, res) {
+        var rma;
+        try { rma = await returns.get(req.params.id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; rma = null; }
+        if (!rma) return _sendHtml(res, 404, renderAdminReturns({
+          shop_name: deps.shop_name, nav_available: navAvailable, returns: [], status: "pending", notice: "Return not found.",
+        }));
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _sendHtml(res, 200, renderAdminReturn({
+          shop_name:   deps.shop_name,
+          nav_available: navAvailable,
+          rma:         rma,
+          transitions: returns.transitionsFrom(rma.status),
+          moved:       url && url.searchParams.get("moved"),
+          notice:      url && url.searchParams.get("err") ? "That action couldn't be completed for this return." : null,
+        }));
+      },
+    ));
 
-    router.post("/admin/returns/:id/approve", W("return.approve", async function (req, res) {
-      var body = req.body || {};
-      var rma;
-      try {
-        rma = await returns.approve(req.params.id, {
-          refund_amount_minor: body.refund_amount_minor,
-          refund_currency:     body.refund_currency,
-          operator_notes:      body.operator_notes,
+    // The browser side of an RMA action: run `opFn(id, body)`, then PRG
+    // back to the detail. A bad id / shape (TypeError) or an FSM refusal /
+    // not-found (mapped by _returnsClientError) becomes a notice on the
+    // detail, never a 500; anything else propagates.
+    function _returnAction(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 (e instanceof TypeError || _returnsClientError(e)) {
+            return _redirect(res, "/admin/returns/" + encodeURIComponent(id) + "?err=1");
+          }
+          throw e;
+        }
+        _b().audit.safeEmit({ action: AUDIT_NAMESPACE + "." + auditEvent, outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/returns/" + encodeURIComponent(id) + "?moved=1");
+      });
+    }
+
+    router.post("/admin/returns/:id/approve", _returnAction(
+      W("return.approve", async function (req, res) {
+        var body = req.body || {};
+        var rma;
+        try {
+          rma = await returns.approve(req.params.id, {
+            refund_amount_minor: body.refund_amount_minor,
+            refund_currency:     body.refund_currency,
+            operator_notes:      body.operator_notes,
+          });
+        } catch (e) {
+          var ce = _returnsClientError(e);
+          if (ce) return _problem(res, ce.status, ce.slug, e.message);
+          throw e;
+        }
+        _json(res, 200, rma);
+        return rma;
+      }),
+      "return.approve",
+      function (id, body) {
+        // Browser form fields arrive as strings. Convert ONLY a clean
+        // non-negative integer to a number; anything else (e.g. "4999usd",
+        // "1e3", "") passes through unchanged so returns.approve's
+        // _nonNegInt rejects it (→ notice via _returnAction) instead of
+        // parseInt silently truncating garbage onto a money field.
+        var raw = body.refund_amount_minor;
+        var amount = (typeof raw === "string" && /^\d+$/.test(raw.trim())) ? Number(raw.trim()) : raw;
+        return returns.approve(id, {
+          refund_amount_minor: amount,
+          refund_currency:     body.refund_currency || undefined,
+          operator_notes:      body.operator_notes || undefined,
         });
-      } catch (e) {
-        var ce = _returnsClientError(e);
-        if (ce) return _problem(res, ce.status, ce.slug, e.message);
-        throw e;
-      }
-      _json(res, 200, rma);
-      return rma;
-    }));
+      },
+    ));
 
-    router.post("/admin/returns/:id/received", W("return.received", async function (req, res) {
-      var body = req.body || {};
-      var rma;
-      try {
-        rma = await returns.markReceived(req.params.id, { operator_notes: body.operator_notes });
-      } catch (e) {
-        var ce = _returnsClientError(e);
-        if (ce) return _problem(res, ce.status, ce.slug, e.message);
-        throw e;
-      }
-      _json(res, 200, rma);
-      return rma;
-    }));
+    router.post("/admin/returns/:id/received", _returnAction(
+      W("return.received", async function (req, res) {
+        var body = req.body || {};
+        var rma;
+        try {
+          rma = await returns.markReceived(req.params.id, { operator_notes: body.operator_notes });
+        } catch (e) {
+          var ce = _returnsClientError(e);
+          if (ce) return _problem(res, ce.status, ce.slug, e.message);
+          throw e;
+        }
+        _json(res, 200, rma);
+        return rma;
+      }),
+      "return.received",
+      function (id, body) { return returns.markReceived(id, { operator_notes: body.operator_notes || undefined }); },
+    ));
 
-    router.post("/admin/returns/:id/refund", W("return.refund", async function (req, res) {
-      var body = req.body || {};
-      var rma;
-      try {
-        rma = await returns.refund(req.params.id, { operator_notes: body.operator_notes });
-      } catch (e) {
-        var ce = _returnsClientError(e);
-        if (ce) return _problem(res, ce.status, ce.slug, e.message);
-        throw e;
-      }
-      _json(res, 200, rma);
-      return rma;
-    }));
+    router.post("/admin/returns/:id/refund", _returnAction(
+      W("return.refund", async function (req, res) {
+        var body = req.body || {};
+        var rma;
+        try {
+          rma = await returns.refund(req.params.id, { operator_notes: body.operator_notes });
+        } catch (e) {
+          var ce = _returnsClientError(e);
+          if (ce) return _problem(res, ce.status, ce.slug, e.message);
+          throw e;
+        }
+        _json(res, 200, rma);
+        return rma;
+      }),
+      "return.refund",
+      function (id, body) { return returns.refund(id, { operator_notes: body.operator_notes || undefined }); },
+    ));
 
-    router.post("/admin/returns/:id/reject", W("return.reject", async function (req, res) {
-      var body = req.body || {};
-      var rma;
-      try {
-        rma = await returns.reject(req.params.id, {
-          rejected_reason: body.rejected_reason,
-          operator_notes:  body.operator_notes,
-        });
-      } catch (e) {
-        var ce = _returnsClientError(e);
-        if (ce) return _problem(res, ce.status, ce.slug, e.message);
-        throw e;
-      }
-      _json(res, 200, rma);
-      return rma;
-    }));
+    router.post("/admin/returns/:id/reject", _returnAction(
+      W("return.reject", async function (req, res) {
+        var body = req.body || {};
+        var rma;
+        try {
+          rma = await returns.reject(req.params.id, {
+            rejected_reason: body.rejected_reason,
+            operator_notes:  body.operator_notes,
+          });
+        } catch (e) {
+          var ce = _returnsClientError(e);
+          if (ce) return _problem(res, ce.status, ce.slug, e.message);
+          throw e;
+        }
+        _json(res, 200, rma);
+        return rma;
+      }),
+      "return.reject",
+      function (id, body) { return returns.reject(id, { rejected_reason: body.rejected_reason, operator_notes: body.operator_notes || undefined }); },
+    ));
   }
 
   // ---- config ---------------------------------------------------------
@@ -1073,6 +1167,7 @@ function mount(router, deps) {
         top_skus:   top,
         recent:     recent,
         shop_name:  (deps.shop_name || "blamejs.shop"),
+        nav_available: navAvailable,
       }));
     });
   }
@@ -1166,6 +1261,7 @@ function mount(router, deps) {
     _sendHtml(res, 200, renderAdminLanding({
       shop_name:      deps.shop_name,
       setup_complete: await _setupComplete(),
+      nav_available:  navAvailable,
     }));
   });
 
@@ -1202,6 +1298,7 @@ function mount(router, deps) {
     _sendHtml(res, 200, renderAdminIntegrations({
       shop_name: deps.shop_name,
       status:    deps.integrations || {},
+      nav_available: navAvailable,
     }));
   });
 
@@ -1217,7 +1314,7 @@ function mount(router, deps) {
         values.currency      = await config.get("shop.currency", "");
         values.support_url   = await config.get("shop.support_url", "");
       } catch (_e) { /* unconfigured — render an empty form */ }
-      _sendHtml(res, 200, renderAdminSetup({ shop_name: deps.shop_name, values: values, saved: saved }));
+      _sendHtml(res, 200, renderAdminSetup({ shop_name: deps.shop_name, values: values, saved: saved, nav_available: navAvailable }));
     });
 
     router.post("/admin/setup", async function (req, res) {
@@ -1244,7 +1341,7 @@ function mount(router, deps) {
         if (!u || (u.protocol !== "https:" && u.protocol !== "http:")) notice = "Support URL must be a valid http(s) URL.";
       }
       if (notice) {
-        return _sendHtml(res, 400, renderAdminSetup({ shop_name: deps.shop_name, values: values, notice: notice }));
+        return _sendHtml(res, 400, renderAdminSetup({ shop_name: deps.shop_name, values: values, notice: notice, nav_available: navAvailable }));
       }
       try {
         await config.put("shop.name", values.shop_name);
@@ -1254,7 +1351,7 @@ function mount(router, deps) {
         await config.put("setup.completed", true);
       } catch (e) {
         return _sendHtml(res, 500, renderAdminSetup({
-          shop_name: deps.shop_name, values: values,
+          shop_name: deps.shop_name, values: values, nav_available: navAvailable,
           notice: "Couldn't save — " + ((e && e.message) || "please try again."),
         }));
       }
@@ -1343,6 +1440,9 @@ var DASHBOARD_LAYOUT =
   "    .order-totals { width:100%; }\n" +
   "    .order-totals td { padding:.3rem 0; }\n" +
   "    .order-actions { display:flex; flex-wrap:wrap; gap:.6rem; }\n" +
+  "    .return-actions { display:grid; grid-template-columns:repeat(auto-fit,minmax(16rem,1fr)); gap:1.25rem; }\n" +
+  "    .return-action { border:1px solid var(--hair); border-radius:8px; padding:1rem; }\n" +
+  "    .return-action h4 { margin:0 0 .6rem; font-size:.9rem; }\n" +
   "    .nav-cards { display:grid; grid-template-columns:repeat(auto-fit,minmax(14rem,1fr)); gap:1rem; }\n" +
   "    .nav-card { display:block; background:var(--paper); border:1px solid var(--hair); border-radius:8px; padding:1.4rem; text-decoration:none; color:var(--ink); }\n" +
   "    .nav-card:hover { border-color:var(--accent); box-shadow:0 8px 20px -12px rgba(0,0,0,.25); }\n" +
@@ -1501,6 +1601,7 @@ function renderDashboard(opts) {
     "Window: last 30 days (operator-tunable via ?since=&until=)",
     body,
     "dashboard",
+    opts.nav_available,
   );
 }
 
@@ -1514,30 +1615,40 @@ function _statCard(label, value, accent) {
 // Console nav — one entry per HTML console screen. `active` highlights
 // the current page; `null`/`false` (unauthenticated pages like the
 // sign-in form) renders no nav at all.
+// Items carrying `requires` map to an optional `deps.<key>` primitive —
+// their routes only mount when that dep is wired, so the nav link is shown
+// only when `available[key]` is truthy (otherwise it would point at an
+// unregistered route). Items without `requires` are always present.
 var ADMIN_NAV_ITEMS = [
   { key: "home",         href: "/admin",              label: "Home" },
   { key: "dashboard",    href: "/admin/dashboard",    label: "Dashboard" },
   { key: "products",     href: "/admin/products",     label: "Products" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
+  { key: "returns",      href: "/admin/returns",      label: "Returns",      requires: "returns" },
   { key: "integrations", href: "/admin/integrations", label: "Integrations" },
   { key: "setup",        href: "/admin/setup",        label: "Setup" },
 ];
-function _adminNav(active) {
+// `available` is a map of optional-section key → truthy when wired. When
+// omitted (a render fn called without it), optional items are shown — the
+// route handlers always pass it, so a real deployment gates correctly.
+function _adminNav(active, available) {
   if (active === null || active === undefined || active === false) return "";
-  var links = ADMIN_NAV_ITEMS.map(function (it) {
+  var links = ADMIN_NAV_ITEMS.filter(function (it) {
+    return !it.requires || !available || available[it.requires];
+  }).map(function (it) {
     return "<a href=\"" + it.href + "\"" + (it.key === active ? " class=\"active\"" : "") + ">" +
       _htmlEscape(it.label) + "</a>";
   }).join("");
   return "<nav class=\"admin-nav\"><div class=\"admin-nav__inner\">" + links + "</div></nav>";
 }
 
-function _renderAdminShell(shopName, subtitle, bodyHtml, active) {
+function _renderAdminShell(shopName, subtitle, bodyHtml, active, available) {
   return _renderTemplate(DASHBOARD_LAYOUT, {
     shop_name:    shopName || "blamejs.shop",
     window_label: subtitle || "",
     nav:          "RAW_NAV",
     body:         "RAW_BODY",
-  }).replace("RAW_NAV", _adminNav(active)).replace("RAW_BODY", bodyHtml);
+  }).replace("RAW_NAV", _adminNav(active, available)).replace("RAW_BODY", bodyHtml);
 }
 
 function renderAdminLogin(opts) {
@@ -1574,7 +1685,7 @@ function renderAdminLanding(opts) {
       "</div>" +
       "<div class=\"actions-row\"><form method=\"post\" action=\"/admin/logout\"><button type=\"submit\" class=\"btn btn--ghost\">Sign out</button></form></div>" +
     "</section>";
-  return _renderAdminShell(opts.shop_name, "", body, "home");
+  return _renderAdminShell(opts.shop_name, "", body, "home", opts.nav_available);
 }
 
 function _setupField(label, name, value, type, hint, extra) {
@@ -1603,7 +1714,7 @@ function renderAdminSetup(opts) {
           "<a class=\"btn btn--ghost\" href=\"/admin\">Back</a></div>" +
       "</form>" +
     "</section>";
-  return _renderAdminShell(opts.shop_name, "Setup", body, "setup");
+  return _renderAdminShell(opts.shop_name, "Setup", body, "setup", opts.nav_available);
 }
 
 // Each integration is off until the operator supplies its credentials.
@@ -1655,7 +1766,7 @@ function renderAdminIntegrations(opts) {
       "<p class=\"meta\" style=\"margin-top:1.25rem;\">Sign in with Apple and PayPal are planned. “Sign in with Shop” / Shop Pay isn't available to a self-hosted store. See the README “Optional integrations” section for full setup steps.</p>" +
       "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin\">Back</a></div>" +
     "</section>";
-  return _renderAdminShell(opts.shop_name, "Integrations", body, "integrations");
+  return _renderAdminShell(opts.shop_name, "Integrations", body, "integrations", opts.nav_available);
 }
 
 function renderAdminProducts(opts) {
@@ -1689,7 +1800,7 @@ function renderAdminProducts(opts) {
         "</form>" +
       "</div>" +
     "</section>";
-  return _renderAdminShell(opts.shop_name, "Products", body, "products");
+  return _renderAdminShell(opts.shop_name, "Products", body, "products", opts.nav_available);
 }
 
 // created_at / updated_at are epoch-ms numbers (order._now()); render a
@@ -1734,7 +1845,7 @@ function renderAdminOrders(opts) {
     : "<p class=\"empty\">No orders" + (active ? " with status “" + _htmlEscape(active) + "”" : " yet") + ".</p>";
 
   var body = "<section><h2>Orders</h2>" + notice + chips + table + "</section>";
-  return _renderAdminShell(opts.shop_name, "Orders", body, "orders");
+  return _renderAdminShell(opts.shop_name, "Orders", body, "orders", opts.nav_available);
 }
 
 function renderAdminOrder(opts) {
@@ -1814,7 +1925,145 @@ function renderAdminOrder(opts) {
         "<div class=\"order-actions\">" + actions + "</div>" +
       "</div>" +
     "</section>";
-  return _renderAdminShell(opts.shop_name, "Order " + o.id.slice(0, 8), body, "orders");
+  return _renderAdminShell(opts.shop_name, "Order " + o.id.slice(0, 8), body, "orders", opts.nav_available);
+}
+
+// The RMA states an operator can filter the returns queue by — drives the
+// filter chips, lifecycle order then terminal.
+var RETURN_STATUS_FILTERS = ["pending", "approved", "received", "refunded", "rejected"];
+
+// status → status-pill CSS class. The pill stylesheet has paid/fulfilling/
+// shipped/delivered (green), refunded, cancelled, pending — map the RMA
+// states onto the closest existing colour without new CSS.
+function _returnPillClass(status) {
+  if (status === "approved" || status === "received") return "shipped";  // in-progress green
+  if (status === "refunded") return "refunded";
+  if (status === "rejected") return "cancelled";
+  return "pending";
+}
+
+function renderAdminReturns(opts) {
+  opts = opts || {};
+  var rmas = opts.returns || [];
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var active = opts.status || "pending";
+
+  var chips = "<div class=\"order-filters\">" +
+    RETURN_STATUS_FILTERS.map(function (s) {
+      return "<a class=\"chip" + (active === s ? " chip--on" : "") + "\" href=\"/admin/returns?status=" + encodeURIComponent(s) + "\">" + _htmlEscape(s) + "</a>";
+    }).join("") +
+    "</div>";
+
+  var rows = rmas.map(function (r) {
+    var items = (r.lines || []).reduce(function (n, l) { return n + (l.qty || 0); }, 0);
+    var amount = r.refund_amount_minor != null ? pricing.format(r.refund_amount_minor, r.refund_currency || "USD") : "—";
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/returns/" + _htmlEscape(r.id) + "\">" + _htmlEscape(r.rma_code || r.id.slice(0, 8)) + "</a></td>" +
+      "<td><span class=\"order-id\">" + _htmlEscape(String(r.order_id).slice(0, 8)) + "</span></td>" +
+      "<td>" + _htmlEscape(r.reason) + "</td>" +
+      "<td><span class=\"status-pill " + _returnPillClass(r.status) + "\">" + _htmlEscape(r.status) + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(String(items)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(amount) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(r.created_at)) + "</td>" +
+      "</tr>";
+  }).join("");
+
+  var table = rmas.length
+    ? "<div class=\"panel\"><table><thead><tr><th>RMA</th><th>Order</th><th>Reason</th><th>Status</th><th class=\"num\">Items</th><th class=\"num\">Refund</th><th>Requested</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<p class=\"empty\">No “" + _htmlEscape(active) + "” returns.</p>";
+
+  var body = "<section><h2>Returns</h2>" + notice + chips + table + "</section>";
+  return _renderAdminShell(opts.shop_name, "Returns", body, "returns", opts.nav_available);
+}
+
+function renderAdminReturn(opts) {
+  opts = opts || {};
+  var r = opts.rma;
+  var transitions = opts.transitions || [];
+  var moved  = opts.moved  ? "<div class=\"banner banner--ok\">Return updated.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var has = function (on) { return transitions.some(function (t) { return t.on === on; }); };
+
+  var lineRows = (r.lines || []).map(function (l) {
+    return "<tr><td>" + _htmlEscape(l.sku) + "</td><td class=\"num\">" + _htmlEscape(String(l.qty)) + "</td>" +
+      "<td>" + _htmlEscape(l.reason || "—") + "</td></tr>";
+  }).join("");
+  var linesTable = (r.lines && r.lines.length)
+    ? "<table><thead><tr><th>SKU</th><th class=\"num\">Qty</th><th>Reason</th></tr></thead><tbody>" + lineRows + "</tbody></table>"
+    : "<p class=\"empty\">No line items recorded.</p>";
+
+  function _field(label, value) {
+    return "<p><span class=\"meta\">" + _htmlEscape(label) + "</span><br>" + (value ? _htmlEscape(String(value)) : "<span class=\"meta\">—</span>") + "</p>";
+  }
+  var refundShown = r.refund_amount_minor != null ? pricing.format(r.refund_amount_minor, r.refund_currency || "USD") : null;
+
+  // Action forms keyed to the legal transitions. Approve + reject need
+  // input (refund amount / rejection reason); mark-received + refund are
+  // single-click. Each posts to its own endpoint and redirects (PRG).
+  var actionBlocks = [];
+  if (has("approve")) {
+    actionBlocks.push(
+      "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/approve\" class=\"return-action\">" +
+        "<h4>Approve</h4>" +
+        _setupField("Refund amount (minor units)", "refund_amount_minor", "", "number", "e.g. 4999 for $49.99.", " min=\"0\" required") +
+        _setupField("Refund currency", "refund_currency", r.refund_currency || "USD", "text", "3-letter ISO 4217.", " maxlength=\"3\" style=\"text-transform:uppercase;max-width:8rem;\"") +
+        _setupField("Operator notes", "operator_notes", "", "text", "", " maxlength=\"500\"") +
+        "<button class=\"btn\" type=\"submit\">Approve return</button>" +
+      "</form>");
+  }
+  if (has("markReceived")) {
+    actionBlocks.push(
+      "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/received\" class=\"return-action\">" +
+        "<h4>Mark received</h4><p class=\"meta\">Confirm the returned goods arrived.</p>" +
+        _setupField("Operator notes", "operator_notes", "", "text", "", " maxlength=\"500\"") +
+        "<button class=\"btn\" type=\"submit\">Mark received</button>" +
+      "</form>");
+  }
+  if (has("refund")) {
+    actionBlocks.push(
+      "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/refund\" class=\"return-action\">" +
+        "<h4>Refund</h4><p class=\"meta\">Record the refund" + (refundShown ? " of " + _htmlEscape(refundShown) : "") + " for this return.</p>" +
+        _setupField("Operator notes", "operator_notes", "", "text", "", " maxlength=\"500\"") +
+        "<button class=\"btn\" type=\"submit\">Refund</button>" +
+      "</form>");
+  }
+  if (has("reject")) {
+    actionBlocks.push(
+      "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/reject\" class=\"return-action\">" +
+        "<h4>Reject</h4>" +
+        _setupField("Reason for rejection", "rejected_reason", "", "text", "Shown to the customer.", " maxlength=\"500\" required") +
+        _setupField("Operator notes", "operator_notes", "", "text", "", " maxlength=\"500\"") +
+        "<button class=\"btn btn--danger\" type=\"submit\">Reject return</button>" +
+      "</form>");
+  }
+  var actions = actionBlocks.length
+    ? "<div class=\"return-actions\">" + actionBlocks.join("") + "</div>"
+    : "<span class=\"meta\">This return is in a final state — no further changes.</span>";
+
+  var body =
+    "<section style=\"max-width:48rem;\">" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/returns\">&larr; Returns</a></div>" +
+      "<h2>Return <code class=\"order-id\">" + _htmlEscape(r.rma_code || r.id.slice(0, 8)) + "</code> " +
+        "<span class=\"status-pill " + _returnPillClass(r.status) + "\">" + _htmlEscape(r.status) + "</span></h2>" +
+      "<p class=\"meta\">Requested " + _htmlEscape(_fmtDate(r.created_at)) +
+        " · order <a class=\"order-id\" href=\"/admin/orders/" + _htmlEscape(r.order_id) + "\">" + _htmlEscape(String(r.order_id).slice(0, 8)) + "</a></p>" +
+      moved + notice +
+      "<div class=\"two-col\">" +
+        "<div class=\"panel\"><h3 style=\"font-size:.95rem; margin-bottom:.75rem;\">Items</h3>" + linesTable + "</div>" +
+        "<div class=\"panel\"><h3 style=\"font-size:.95rem; margin-bottom:.75rem;\">Details</h3>" +
+          _field("Reason", r.reason) +
+          _field("Customer detail", r.reason_detail) +
+          _field("Customer notes", r.customer_notes) +
+          (refundShown ? _field("Refund", refundShown) : "") +
+          (r.operator_notes ? _field("Operator notes", r.operator_notes) : "") +
+          (r.rejected_reason ? _field("Rejection reason", r.rejected_reason) : "") +
+        "</div>" +
+      "</div>" +
+      "<div class=\"panel\" style=\"margin-top:1.5rem;\"><h3 style=\"font-size:.95rem; margin-bottom:.75rem;\">Actions</h3>" +
+        actions +
+      "</div>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Return " + (r.rma_code || r.id.slice(0, 8)), body, "returns", opts.nav_available);
 }
 
 module.exports = {
@@ -1828,4 +2077,6 @@ module.exports = {
   renderAdminProducts:     renderAdminProducts,
   renderAdminOrders:       renderAdminOrders,
   renderAdminOrder:        renderAdminOrder,
+  renderAdminReturns:      renderAdminReturns,
+  renderAdminReturn:       renderAdminReturn,
 };

package/lib/returns.js

@@ -429,6 +429,16 @@ function create(opts) {
       return await _hydrate(r.rows[0] || null);
     },
 
+    // The moderation events legal from a given status, as {on, to} —
+    // drives the action buttons on the operator return-detail page. A
+    // terminal status returns []. Synchronous (pure lookup over the
+    // transition table). `on` is the API method name (approve / reject /
+    // markReceived / refund).
+    transitionsFrom: function (status) {
+      var edges = TRANSITIONS[status] || {};
+      return Object.keys(edges).map(function (on) { return { on: on, to: edges[on] }; });
+    },
+
     byCode: async function (rmaCode) {
       var canonical = _canonicalCode(rmaCode);
       var r = await query(

package/package.json

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