@blamejs/blamejs-shop 0.1.7 → 0.1.9

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 }));
     },
   ));
 
@@ -599,50 +604,153 @@ function mount(router, deps) {
 
   // ---- orders ---------------------------------------------------------
 
-  router.get("/admin/orders/:id", R(async function (req, res) {
-    var o = await order.get(req.params.id);
-    if (!o) return _problem(res, 404, "order-not-found");
-    _json(res, 200, o);
-  }));
-
-  router.post("/admin/orders/:id/transition", W("order.transition", async function (req, res) {
-    var body = req.body || {};
-    if (!body.event) throw new TypeError("admin.order.transition: body.event required");
-    var o = await order.transition(req.params.id, body.event, { reason: body.reason, metadata: body.metadata });
-    _json(res, 200, o);
-    return o;
-  }));
-
-  // ---- refunds --------------------------------------------------------
+  // Recent orders across all customers. Bearer → no list endpoint existed
+  // before, so this adds one (JSON); a signed-in browser gets the console.
+  router.get("/admin/orders", _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");
+      var limitS = url && url.searchParams.get("limit");
+      var limit  = limitS == null ? 50 : parseInt(limitS, 10);
+      var list = await order.listRecent({ status: status || undefined, limit: limit });
+      _json(res, 200, list);
+    }),
+    async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var statusRaw = url && url.searchParams.get("status");
+      // A bad ?status= filter falls back to "all" rather than erroring the
+      // page — the operator just sees everything, which is a safe default.
+      var status = null, notice = null;
+      if (statusRaw) {
+        try { await order.listRecent({ status: statusRaw, limit: 1 }); status = statusRaw; }
+        catch (_e) { notice = "Unknown status filter — showing all orders."; }
+      }
+      var list = await order.listRecent({ status: status || undefined, limit: 100 });
+      _sendHtml(res, 200, renderAdminOrders({
+        shop_name: deps.shop_name, nav_available: navAvailable, orders: list.rows || [],
+        status: status, notice: notice,
+      }));
+    },
+  ));
 
-  if (payment) {
-    router.post("/admin/orders/:id/refund", W("order.refund", async function (req, res) {
+  router.get("/admin/orders/:id", _pageOrApi(true,
+    R(async function (req, res) {
       var o = await order.get(req.params.id);
       if (!o) return _problem(res, 404, "order-not-found");
-      if (!o.payment_intent_id) return _problem(res, 422, "no-payment-intent", "Order has no linked payment intent");
+      _json(res, 200, o);
+    }),
+    async function (req, res) {
+      var o;
+      // A malformed id throws (defensive id reader) — render 404, not 500.
+      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, 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
+        // provider is wired AND the order has a captured intent to refund.
+        can_refund:  !!(payment && o.payment_intent_id),
+        moved:       url && url.searchParams.get("moved"),
+        notice:      url && url.searchParams.get("err") ? "That action couldn't be completed for this order." : null,
+      }));
+    },
+  ));
+
+  router.post("/admin/orders/:id/transition", _pageOrApi(false,
+    W("order.transition", async function (req, res) {
       var body = req.body || {};
-      var refundIdempotencyKey = "refund:" + o.id + ":" + (body.idempotency_suffix || _b().uuid.v7());
-      var refund;
+      if (!body.event) throw new TypeError("admin.order.transition: body.event required");
+      var o = await order.transition(req.params.id, body.event, { reason: body.reason, metadata: body.metadata });
+      _json(res, 200, o);
+      return o;
+    }),
+    async function (req, res) {
+      // Browser form → run the transition, then redirect back to the
+      // detail (PRG). A bad id (TypeError) or an FSM refusal (the move
+      // isn't legal from this status) surfaces as a notice, not a 500;
+      // any other failure propagates.
+      var id = req.params.id;
+      var event = (req.body || {}).event;
+      if (!event) return _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?err=1");
       try {
-        refund = await payment.refund({
-          payment_intent: o.payment_intent_id,
-          amount_minor:   body.amount_minor || undefined,
-          reason:         body.reason || undefined,
-          metadata:       { order_id: o.id },
-        }, refundIdempotencyKey);
+        await order.transition(id, event, { reason: "admin:console" });
       } catch (e) {
-        return _problem(res, 502, "stripe-refund-failed", (e && e.message) || String(e));
+        if (e instanceof TypeError || (e && e.code && /FSM|TRANSITION|GUARD/i.test(e.code))) {
+          return _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?err=1");
+        }
+        throw e;
       }
+      _b().audit.safeEmit({ action: AUDIT_NAMESPACE + ".order.transition", outcome: "success", metadata: { id: id, event: event } });
+      _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?moved=1");
+    },
+  ));
+
+  // ---- refunds --------------------------------------------------------
+
+  if (payment) {
+    // Issue the actual payment-provider refund, then advance the order
+    // FSM. Shared by the JSON API and the browser console so a console
+    // "Refund" moves the money first (never a bare state change — that
+    // would mark an order refunded with the customer never paid back).
+    async function _refundOrder(o, body) {
+      var refundIdempotencyKey = "refund:" + o.id + ":" + (body.idempotency_suffix || _b().uuid.v7());
+      var refund = await payment.refund({
+        payment_intent: o.payment_intent_id,
+        amount_minor:   body.amount_minor || undefined,
+        reason:         body.reason || undefined,
+        metadata:       { order_id: o.id },
+      }, refundIdempotencyKey);
       try {
         await order.transition(o.id, "refund", {
           reason:   "admin:refund:" + (body.reason || "requested_by_customer"),
           metadata: { stripe_refund_id: refund.id, amount_minor: refund.amount },
         });
-      } catch (_e) { /* refund succeeded at Stripe; transition refusal logged, surface to operator via re-fetch */ }
-      var updated = await order.get(o.id);
-      _json(res, 200, { refund: refund, order: updated });
-      return { id: o.id };
-    }));
+      } catch (_e) { /* refund succeeded at the provider; transition refusal logged, surfaced via re-fetch */ }
+      return { refund: refund, order: await order.get(o.id) };
+    }
+
+    router.post("/admin/orders/:id/refund", _pageOrApi(false,
+      W("order.refund", async function (req, res) {
+        var o = await order.get(req.params.id);
+        if (!o) return _problem(res, 404, "order-not-found");
+        if (!o.payment_intent_id) return _problem(res, 422, "no-payment-intent", "Order has no linked payment intent");
+        var result;
+        try {
+          result = await _refundOrder(o, req.body || {});
+        } catch (e) {
+          return _problem(res, 502, "stripe-refund-failed", (e && e.message) || String(e));
+        }
+        _json(res, 200, result);
+        return { id: o.id };
+      }),
+      async function (req, res) {
+        // Browser console: full refund (partial refunds stay on the JSON
+        // API via amount_minor), then PRG back to the detail. A bad id or
+        // missing payment intent surfaces as a notice, never a 500.
+        var id = req.params.id;
+        var o;
+        try { o = await order.get(id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; o = null; }
+        if (!o || !o.payment_intent_id) {
+          return _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?err=1");
+        }
+        try {
+          await _refundOrder(o, { reason: "requested_by_customer" });
+        } catch (_e) {
+          // Provider refund failed — the order is untouched (the FSM
+          // transition only runs after a successful refund).
+          return _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?err=1");
+        }
+        _b().audit.safeEmit({ action: AUDIT_NAMESPACE + ".order.refund", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?moved=1");
+      },
+    ));
   }
 
   // ---- reviews (moderation) -------------------------------------------
@@ -717,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/: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.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,
-        });
-      } 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/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.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", _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,
+        }));
+      },
+    ));
+
+    // 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/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,
+    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", _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", _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", _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 ---------------------------------------------------------
@@ -971,6 +1167,7 @@ function mount(router, deps) {
         top_skus:   top,
         recent:     recent,
         shop_name:  (deps.shop_name || "blamejs.shop"),
+        nav_available: navAvailable,
       }));
     });
   }
@@ -1064,6 +1261,7 @@ function mount(router, deps) {
     _sendHtml(res, 200, renderAdminLanding({
       shop_name:      deps.shop_name,
       setup_complete: await _setupComplete(),
+      nav_available:  navAvailable,
     }));
   });
 
@@ -1100,6 +1298,7 @@ function mount(router, deps) {
     _sendHtml(res, 200, renderAdminIntegrations({
       shop_name: deps.shop_name,
       status:    deps.integrations || {},
+      nav_available: navAvailable,
     }));
   });
 
@@ -1115,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) {
@@ -1142,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);
@@ -1152,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."),
         }));
       }
@@ -1232,6 +1431,18 @@ var DASHBOARD_LAYOUT =
   "    .btn:hover { background:var(--accent-d); border-color:var(--accent-d); }\n" +
   "    .btn--ghost { background:transparent; color:var(--ink); border-color:var(--ink); }\n" +
   "    .btn--ghost:hover { background:var(--ink); color:var(--paper); }\n" +
+  "    .btn--danger { background:transparent; color:var(--accent-d); border-color:var(--accent-d); }\n" +
+  "    .btn--danger:hover { background:var(--accent-d); color:var(--paper); }\n" +
+  "    .order-filters { display:flex; flex-wrap:wrap; gap:.5rem; margin-bottom:1.25rem; }\n" +
+  "    .chip { display:inline-block; padding:.3rem .8rem; border-radius:999px; border:1px solid var(--hair); color:var(--ink-2); text-decoration:none; font-size:.78rem; text-transform:capitalize; }\n" +
+  "    .chip:hover { border-color:var(--accent); }\n" +
+  "    .chip--on { background:var(--ink); color:var(--paper); border-color:var(--ink); }\n" +
+  "    .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" +
@@ -1364,7 +1575,7 @@ function renderDashboard(opts) {
     ? recent.map(function (o) {
         var statusClass = _htmlEscape(o.status);
         return "<tr>" +
-          "<td><span class=\"order-id\">" + _htmlEscape(o.id.slice(0, 8)) + "</span></td>" +
+          "<td><a class=\"order-id\" href=\"/admin/orders/" + _htmlEscape(o.id) + "\">" + _htmlEscape(o.id.slice(0, 8)) + "</a></td>" +
           "<td><span class=\"status-pill " + statusClass + "\">" + _htmlEscape(o.status) + "</span></td>" +
           "<td class=\"num\">" + _htmlEscape(pricing.format(o.grand_total_minor, o.currency)) + "</td>" +
           "</tr>";
@@ -1390,6 +1601,7 @@ function renderDashboard(opts) {
     "Window: last 30 days (operator-tunable via ?since=&until=)",
     body,
     "dashboard",
+    opts.nav_available,
   );
 }
 
@@ -1403,29 +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) {
@@ -1462,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) {
@@ -1491,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.
@@ -1543,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) {
@@ -1577,7 +1800,270 @@ 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
+// short, locale-neutral date. Guards against a string or a bad value so a
+// malformed row never throws inside the template.
+function _fmtDate(v) {
+  var n = typeof v === "number" ? v : Date.parse(v);
+  if (!isFinite(n)) return "—";
+  return new Date(n).toISOString().slice(0, 10);
+}
+
+// The status values an operator can filter the orders list by — drives the
+// filter chips. Kept in render-layer order (lifecycle, then terminal).
+var ORDER_STATUS_FILTERS = ["pending", "paid", "fulfilling", "shipped", "delivered", "refunded", "cancelled"];
+
+function renderAdminOrders(opts) {
+  opts = opts || {};
+  var orders = opts.orders || [];
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var active = opts.status || null;
+
+  var chips = "<div class=\"order-filters\">" +
+    "<a class=\"chip" + (active ? "" : " chip--on") + "\" href=\"/admin/orders\">All</a>" +
+    ORDER_STATUS_FILTERS.map(function (s) {
+      return "<a class=\"chip" + (active === s ? " chip--on" : "") + "\" href=\"/admin/orders?status=" + encodeURIComponent(s) + "\">" + _htmlEscape(s) + "</a>";
+    }).join("") +
+    "</div>";
+
+  var rows = orders.map(function (o) {
+    var items = (o.lines || []).reduce(function (n, l) { return n + (l.qty || 0); }, 0);
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/orders/" + _htmlEscape(o.id) + "\">" + _htmlEscape(o.id.slice(0, 8)) + "</a></td>" +
+      "<td><span class=\"status-pill " + _htmlEscape(o.status) + "\">" + _htmlEscape(o.status) + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(String(items)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(pricing.format(o.grand_total_minor, o.currency)) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(o.created_at)) + "</td>" +
+      "</tr>";
+  }).join("");
+
+  var table = orders.length
+    ? "<div class=\"panel\"><table><thead><tr><th>Order</th><th>Status</th><th class=\"num\">Items</th><th class=\"num\">Total</th><th>Placed</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<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", opts.nav_available);
+}
+
+function renderAdminOrder(opts) {
+  opts = opts || {};
+  var o = opts.order;
+  var transitions = opts.transitions || [];
+  var moved  = opts.moved  ? "<div class=\"banner banner--ok\">Order updated.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var lineRows = (o.lines || []).map(function (l) {
+    return "<tr>" +
+      "<td>" + _htmlEscape(l.sku) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(l.qty)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(pricing.format(l.unit_amount_minor, l.unit_currency)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(pricing.format(l.line_total_minor, l.unit_currency)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var linesTable = (o.lines && o.lines.length)
+    ? "<table><thead><tr><th>SKU</th><th class=\"num\">Qty</th><th class=\"num\">Unit</th><th class=\"num\">Line</th></tr></thead><tbody>" + lineRows + "</tbody></table>"
+    : "<p class=\"empty\">No line items recorded.</p>";
+
+  function _total(label, minor, strong) {
+    return "<tr><td>" + _htmlEscape(label) + "</td><td class=\"num\">" +
+      (strong ? "<strong>" : "") + _htmlEscape(pricing.format(minor, o.currency)) + (strong ? "</strong>" : "") +
+      "</td></tr>";
+  }
+  var totals = "<table class=\"order-totals\"><tbody>" +
+    _total("Subtotal", o.subtotal_minor, false) +
+    (o.discount_minor ? _total("Discount", -o.discount_minor, false) : "") +
+    _total("Tax", o.tax_minor, false) +
+    _total("Shipping", o.shipping_minor, false) +
+    _total("Total", o.grand_total_minor, true) +
+    "</tbody></table>";
+
+  var ship = o.ship_to || {};
+  var shipLines = [ship.name, ship.line1, ship.line2,
+    [ship.city, ship.region, ship.postal_code].filter(Boolean).join(", "), ship.country]
+    .filter(Boolean).map(function (s) { return _htmlEscape(String(s)); }).join("<br>");
+
+  // One form per legal next transition. `refund` is special: it moves
+  // money, so it posts to the payment-refund endpoint (which issues the
+  // provider refund THEN advances the FSM) rather than the bare
+  // state-transition endpoint — and only when there's a captured payment
+  // to refund. Every other move posts to /transition. A terminal status
+  // (empty list) shows a note instead of buttons.
+  var actionForms = transitions.map(function (t) {
+    if (t.on === "refund") {
+      if (!opts.can_refund) return "";  // no payment intent — nothing to refund here
+      return "<form method=\"post\" action=\"/admin/orders/" + _htmlEscape(o.id) + "/refund\" style=\"display:inline;\">" +
+        "<button class=\"btn btn--danger\" type=\"submit\">" + _htmlEscape(t.label) + "</button>" +
+        "</form>";
+    }
+    var danger = (t.on === "cancel");
+    return "<form method=\"post\" action=\"/admin/orders/" + _htmlEscape(o.id) + "/transition\" style=\"display:inline;\">" +
+      "<input type=\"hidden\" name=\"event\" value=\"" + _htmlEscape(t.on) + "\">" +
+      "<button class=\"btn" + (danger ? " btn--danger" : "") + "\" type=\"submit\">" + _htmlEscape(t.label) + "</button>" +
+      "</form>";
+  }).filter(Boolean).join(" ");
+  var actions = actionForms || "<span class=\"meta\">This order 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/orders\">&larr; Orders</a></div>" +
+      "<h2>Order <code class=\"order-id\">" + _htmlEscape(o.id.slice(0, 8)) + "</code> " +
+        "<span class=\"status-pill " + _htmlEscape(o.status) + "\">" + _htmlEscape(o.status) + "</span></h2>" +
+      "<p class=\"meta\">Placed " + _htmlEscape(_fmtDate(o.created_at)) + " · last updated " + _htmlEscape(_fmtDate(o.updated_at)) +
+        (o.payment_intent_id ? " · payment <code class=\"order-id\">" + _htmlEscape(o.payment_intent_id) + "</code>" : "") + "</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;\">Ship to</h3>" +
+          (shipLines || "<span class=\"meta\">No shipping address.</span>") +
+          "<h3 style=\"font-size:.95rem; margin:1.25rem 0 .75rem;\">Totals</h3>" + totals +
+        "</div>" +
+      "</div>" +
+      "<div class=\"panel\" style=\"margin-top:1.5rem;\"><h3 style=\"font-size:.95rem; margin-bottom:.75rem;\">Actions</h3>" +
+        "<div class=\"order-actions\">" + actions + "</div>" +
+      "</div>" +
+    "</section>";
+  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 = {
@@ -1589,4 +2075,8 @@ module.exports = {
   renderAdminSetup:        renderAdminSetup,
   renderAdminIntegrations: renderAdminIntegrations,
   renderAdminProducts:     renderAdminProducts,
+  renderAdminOrders:       renderAdminOrders,
+  renderAdminOrder:        renderAdminOrder,
+  renderAdminReturns:      renderAdminReturns,
+  renderAdminReturn:       renderAdminReturn,
 };