@blamejs/blamejs-shop 0.3.39 → 0.3.40

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.40 (2026-05-31) — **Return shipping labels — operators issue one, customers download and track it.** After a return was approved there was no way to give the customer a shipping label or for them to follow the parcel back. Operators can now issue a return label on an approved return from the admin console — entering the carrier, tracking number, and the label link generated in their carrier account — and post tracking updates as the parcel moves. The customer sees the label on their return: they can open or print it, see the carrier and tracking number, and follow the scan history, with the return marked received once it arrives back. A customer can only see and download the label for their own return. **Added:** *Return shipping labels and tracking* — Opening a return in the account area now shows its detail, and once a label has been issued the customer can open or print the return label, see the carrier and tracking number, and follow the parcel's scan history — all scoped so a customer only ever sees their own return. On the operator side, an approved return gains an Issue return label form (carrier, service level, weight, the carrier label link, tracking number, and cost) and controls to mark the parcel shipped, in transit, delivered, or held with an exception; marking it delivered records the return as received. The label link is required to be a secure URL, and the customer download is served without exposing that link in the page.
+
 - v0.3.39 (2026-05-31) — **Paginated lists no longer show an empty extra page at exact page boundaries.** Several paginated lists offered a next page even when the current page was the last one, if the list's length happened to be an exact multiple of the page size — following that next link landed on an empty page. This affected a customer's order history, loyalty history, and store-credit history, and the admin customer list. Each now checks whether a further item actually exists before offering a next page, so the next link appears only when there is genuinely more to show. **Fixed:** *No phantom next page on exactly-full lists* — A customer's order history, loyalty history, and store-credit history, and the admin customer list, offered a next page whenever the current page was full — so a list whose total was an exact multiple of the page size showed a next link that led to an empty page. These lists now look one item past the page before offering a next link, so it appears only when a further item exists. This matches the fix already in place for collection pages.
 
 - v0.3.38 (2026-05-31) — **Pre-order campaigns — reserve a product before it is released.** Products that are not yet released could not be sold or reserved. Operators can now run a pre-order campaign for a product from the admin console — setting its release date, price, and an optional reservation cap. While the campaign is open, the product page shows a Pre-order control with the release date and how many reservations remain, and a signed-in customer can reserve their quantity without paying upfront. Customers see and can cancel their reservations from their account, and when the operator launches the campaign on its release date, each reservation is turned into a pending order the customer pays for through normal checkout. **Added:** *Pre-order campaigns* — A Pre-orders screen in the admin console runs a campaign for a product's SKU — release date, price, an optional deposit, and a reservation cap — with launch and close controls (launch is available once the release date arrives). While a campaign is open, the product page shows a Pre-order control with the release date and remaining availability instead of the usual add-to-cart, and a signed-in customer can reserve their quantity (no charge at reservation time; reserving past the cap or on a closed campaign is refused). Customers manage their reservations under Pre-orders in their account and can cancel one, which frees that capacity. Launching the campaign converts each open reservation into a pending order the customer completes through normal checkout. A customer can only see and cancel their own reservations.

package/lib/admin.js

@@ -496,6 +496,7 @@ function mount(router, deps) {
   var reviews       = deps.reviews       || null;   // moderation endpoints disabled when absent
   var productQa     = deps.productQa     || null;   // Q&A moderation endpoints disabled when absent
   var returns       = deps.returns       || null;   // RMA moderation endpoints disabled when absent
+  var returnLabels  = deps.returnLabels  || null;   // return-label issuance + tracking-update endpoints disabled when absent
   var customers     = deps.customers     || null;   // read-only customers console disabled when absent
   var storeCredit      = deps.storeCredit      || null;  // per-customer store-credit panel + grant/deduct disabled when absent
   var customerNotes    = deps.customerNotes    || null;  // per-customer CRM notes panel disabled when absent
@@ -3447,6 +3448,7 @@ function mount(router, deps) {
         }));
         var url = req.url ? new URL(req.url, "http://localhost") : null;
         var rmaCtx = await _rmaProviderContext(rma);
+        var labelCtx = await _returnLabelContext(rma);
         _sendHtml(res, 200, renderAdminReturn({
           shop_name:   deps.shop_name,
           nav_available: navAvailable,
@@ -3457,6 +3459,15 @@ function mount(router, deps) {
           // provider via a confirm interstitial. Absent either, it stays
           // record-only with a pointer to the order page for the money side.
           can_provider_refund: rmaCtx.canProviderRefund,
+          // The return-shipping label surface: the issue-label form mounts on
+          // an approved return with no label; once a label is issued, the
+          // label + its carrier-scan timeline + the legal tracking-update
+          // actions take its place. Absent the returnLabels dep this whole
+          // panel is suppressed.
+          labels_available: !!returnLabels,
+          label:       labelCtx.label,
+          label_events: labelCtx.events,
+          label_currency: rmaCtx.order ? rmaCtx.order.currency : (rma.refund_currency || "USD"),
           moved:       url && url.searchParams.get("moved"),
           notice:      url && url.searchParams.get("err") ? "That action couldn't be completed for this return." : null,
         }));
@@ -3477,6 +3488,190 @@ function mount(router, deps) {
       return ctx;
     }
 
+    // Resolve the return's current (most-recently-issued) shipping label plus
+    // its ordered carrier-scan timeline for the detail screen. Best-effort —
+    // the labels primitive may be unwired, the tables may not be migrated, or
+    // a legacy return id may not parse; any of those degrades to "no label"
+    // rather than throwing, so the detail never 500s on the label read.
+    async function _returnLabelContext(rma) {
+      var ctx = { label: null, events: [] };
+      if (!returnLabels || !rma || !rma.id) return ctx;
+      try { ctx.label = await returnLabels.labelForReturn(rma.id); }
+      catch (e) { if (!(e instanceof TypeError)) throw e; ctx.label = null; }
+      if (ctx.label) {
+        try { ctx.events = await returnLabels.eventsForLabel(ctx.label.id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; ctx.events = []; }
+      }
+      return ctx;
+    }
+
+    // Single classifier for a thrown return-label error → an operator-safe
+    // status, shared by the bearer-JSON path and the cookie/HTML form path.
+    // This MUST run BEFORE a generic `instanceof TypeError → 400` branch: the
+    // labels primitive raises its not-found misses as *coded TypeErrors*
+    // (issueLabel's RETURN_NOT_FOUND, _currentStatus's RETURN_LABEL_NOT_FOUND),
+    // so checking `instanceof TypeError` first would map a genuine 404 to a
+    // 400. Order is: coded-error map (by `.code`) first, then the generic
+    // bad-shape TypeError fall-through the caller applies.
+    //   - a missing return / a missing label    → 404 (the id named nothing)
+    //   - an issue refused (RMA not approved)    → 409 (state conflict)
+    //   - a transition refused (illegal FSM hop) → 409 (state conflict)
+    //   - anything else                          → null (caller's default map)
+    function _returnLabelsClientError(e) {
+      if (!e) return null;
+      if (e.code === "RETURN_NOT_FOUND" || e.code === "RETURN_LABEL_NOT_FOUND") {
+        return { status: 404, slug: "return-label-not-found" };
+      }
+      if (e.code === "RETURN_LABEL_ISSUE_REFUSED" || e.code === "RETURN_LABEL_TRANSITION_REFUSED") {
+        return { status: 409, slug: "return-label-action-refused" };
+      }
+      return null;
+    }
+
+    // Coerce a browser form's string fields to the numeric shapes
+    // returnLabels.issueLabel demands. ONLY a clean unsigned-integer string
+    // becomes a number; anything else (e.g. "340g", "", "12.5") passes through
+    // unchanged so the primitive's _positiveInt / _nonNegInt rejects it as a
+    // clean 400, never silently truncated by parseInt.
+    function _intField(raw) {
+      return (typeof raw === "string" && /^\d+$/.test(raw.trim())) ? Number(raw.trim()) : raw;
+    }
+
+    // The return-label issuance + tracking-update routes mount only when the
+    // returnLabels primitive is wired — without it the customer download
+    // surface has nothing to show, and these operator routes have no backing
+    // store.
+    if (returnLabels) {
+
+    // POST /admin/returns/:id/label — issue an operator-funded return label.
+    // The route forwards the form/JSON straight to returnLabels.issueLabel,
+    // which owns ALL validation: the carrier / service_level / tracking
+    // bounds, the weight + cost integer shapes, the currency ISO check, the
+    // HTTPS-only label_url (b.safeUrl), and the refusal unless the RMA is
+    // `approved`. The route never hand-rolls an INSERT — composing the
+    // primitive keeps the label_url SSRF/scheme gate and the approved-only
+    // rule in one place. Coded errors map via _returnLabelsClientError BEFORE
+    // the generic TypeError→400, so a missing return 404s (not 400).
+    router.post("/admin/returns/:id/label", _pageOrApi(false,
+      W("return.label.issue", async function (req, res) {
+        var body = req.body || {};
+        var label;
+        try {
+          label = await returnLabels.issueLabel({
+            return_id:       req.params.id,
+            carrier:         body.carrier,
+            service_level:   body.service_level,
+            weight_grams:    _intField(body.weight_grams),
+            label_url:       body.label_url,
+            tracking_number: body.tracking_number,
+            cost_minor:      _intField(body.cost_minor),
+            currency:        body.currency,
+          });
+        } catch (e) {
+          var ce = _returnLabelsClientError(e);
+          if (ce) return _problem(res, ce.status, ce.slug, e.message);
+          throw e;   // bad-shape TypeError → _wrap maps to a clean 400
+        }
+        _json(res, 200, label);
+        return label;
+      }),
+      async function (req, res) {
+        var id  = req.params.id;
+        var enc = encodeURIComponent(id);
+        var body = req.body || {};
+        try {
+          await returnLabels.issueLabel({
+            return_id:       id,
+            carrier:         body.carrier,
+            service_level:   body.service_level,
+            weight_grams:    _intField(body.weight_grams),
+            label_url:       body.label_url,
+            tracking_number: body.tracking_number,
+            cost_minor:      _intField(body.cost_minor),
+            currency:        body.currency,
+          });
+        } catch (e) {
+          // A coded miss/refusal OR a bad-shape TypeError both become a notice
+          // on the detail (PRG), never a 500; anything else propagates.
+          if (_returnLabelsClientError(e) || e instanceof TypeError) {
+            return _redirect(res, "/admin/returns/" + enc + "?err=1");
+          }
+          throw e;
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".return.label.issue", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/returns/" + enc + "?moved=1");
+      },
+    ));
+
+    // The four tracking-update actions on a return that HAS a label. Each
+    // appends one carrier-scan event via the matching mark-* primitive (which
+    // owns the FSM-legality check + the event write); mark-exception carries a
+    // short operator-supplied detail. The :id here is the RETURN id — the
+    // route resolves its current label first (labelForReturn), so a return
+    // with no label 404s before any mark-* call. `field` (when set) names the
+    // body key forwarded to the primitive.
+    function _returnLabelMark(auditEvent, markFn, field) {
+      return _pageOrApi(false,
+        W("return.label." + auditEvent, async function (req, res) {
+          var body = req.body || {};
+          var label;
+          try {
+            var rma = await returns.get(req.params.id);
+            if (!rma) return _problem(res, 404, "return-label-not-found");
+            label = await returnLabels.labelForReturn(rma.id);
+            if (!label) return _problem(res, 404, "return-label-not-found");
+            var updated = await markFn(label.id, body);
+            _json(res, 200, updated);
+            return updated;
+          } catch (e) {
+            var ce = _returnLabelsClientError(e);
+            if (ce) return _problem(res, ce.status, ce.slug, e.message);
+            throw e;
+          }
+        }),
+        async function (req, res) {
+          var id  = req.params.id;
+          var enc = encodeURIComponent(id);
+          try {
+            var rma = await returns.get(id);
+            if (!rma) return _redirect(res, "/admin/returns/" + enc + "?err=1");
+            var label = await returnLabels.labelForReturn(rma.id);
+            if (!label) return _redirect(res, "/admin/returns/" + enc + "?err=1");
+            await markFn(label.id, req.body || {});
+          } catch (e) {
+            if (_returnLabelsClientError(e) || e instanceof TypeError) {
+              return _redirect(res, "/admin/returns/" + enc + "?err=1");
+            }
+            throw e;
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".return.label." + auditEvent, outcome: "success", metadata: { id: id } });
+          _redirect(res, "/admin/returns/" + enc + "?moved=1");
+        },
+      );
+    }
+
+    router.post("/admin/returns/:id/label/shipped",
+      _returnLabelMark("shipped", function (labelId) {
+        return returnLabels.markShipped({ label_id: labelId });
+      }));
+    router.post("/admin/returns/:id/label/in-transit",
+      _returnLabelMark("in_transit", function (labelId, body) {
+        // location is optional — a bare scan with no place is legal.
+        return returnLabels.markInTransit({ label_id: labelId, location: body.location || undefined });
+      }));
+    router.post("/admin/returns/:id/label/delivered",
+      _returnLabelMark("delivered", function (labelId) {
+        return returnLabels.markDelivered({ label_id: labelId });
+      }));
+    router.post("/admin/returns/:id/label/exception",
+      _returnLabelMark("exception", function (labelId, body) {
+        // exception detail is REQUIRED by the primitive — a blank one throws a
+        // TypeError the wrapper maps to a clean 400.
+        return returnLabels.markException({ label_id: labelId, exception: body.exception });
+      }));
+
+    }   // end if (returnLabels)
+
     // 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
@@ -10458,6 +10653,141 @@ function _returnPillClass(status) {
   return "pending";
 }
 
+// Operator-facing phrasing for a return_labels FSM state + a label-event
+// row's event_type. The customer storefront has its own shopper-facing
+// phrasings; the console states it plainly for the operator.
+var RETURN_LABEL_STATUS_TEXT = {
+  issued:     "Issued",
+  shipped:    "Shipped",
+  in_transit: "In transit",
+  delivered:  "Delivered",
+  exception:  "Exception",
+};
+var RETURN_LABEL_EVENT_TEXT = {
+  issued:     "Label issued",
+  shipped:    "Marked shipped",
+  in_transit: "In transit",
+  delivered:  "Delivered to merchant",
+  exception:  "Exception",
+};
+function _returnLabelPillClass(status) {
+  if (status === "delivered") return "delivered";
+  if (status === "exception") return "cancelled";
+  if (status === "shipped" || status === "in_transit") return "shipped";
+  return "pending";   // issued
+}
+// The legal next tracking actions for a label in `status`, mirroring the
+// return-labels FSM transition graph. Each entry is the route suffix + the
+// button copy. Terminal states (delivered / exception) yield none.
+var RETURN_LABEL_NEXT_ACTIONS = {
+  issued:     [{ suffix: "shipped",    label: "Mark shipped" }, { suffix: "exception", label: "Flag exception" }],
+  shipped:    [{ suffix: "in-transit", label: "Add transit scan" }, { suffix: "delivered", label: "Mark delivered" }, { suffix: "exception", label: "Flag exception" }],
+  in_transit: [{ suffix: "in-transit", label: "Add transit scan" }, { suffix: "delivered", label: "Mark delivered" }, { suffix: "exception", label: "Flag exception" }],
+  delivered:  [],
+  exception:  [],
+};
+
+// The return-shipping-label panel on the return detail. Three states:
+//   - labels primitive unwired → suppressed entirely (empty string).
+//   - no label yet, return is `approved` → the issue-label form (the only
+//     status issueLabel accepts; on any other status we explain why).
+//   - a label exists → the label summary + carrier-scan timeline + the legal
+//     tracking-update actions.
+// Every form renders through _renderAdminShell, which injects the _csrf
+// field into each POST form, so no per-form token handling is needed here.
+function _returnLabelPanel(opts, r) {
+  if (!opts.labels_available) return "";
+  var label  = opts.label || null;
+  var events = opts.label_events || [];
+
+  if (!label) {
+    // No label issued yet. issueLabel accepts ONLY an `approved` return, so
+    // the form shows only there; on any other status we say why instead of
+    // offering a form that would 4xx.
+    if (r.status !== "approved") {
+      return "<div class=\"panel mt\"><h3 class=\"subhead\">Return shipping label</h3>" +
+        "<p class=\"meta\">A prepaid return label can be issued once this return is approved.</p></div>";
+    }
+    var ccy = opts.label_currency || r.refund_currency || "USD";
+    var form =
+      "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/label\" class=\"return-action\">" +
+        "<h4>Issue return label</h4>" +
+        "<p class=\"meta\">Generate the label in your carrier account, then record it here. The shopper downloads it from their return status page.</p>" +
+        _setupField("Carrier", "carrier", "", "text", "e.g. USPS, UPS, FedEx.", " maxlength=\"64\" required") +
+        _setupField("Service level", "service_level", "", "text", "e.g. Ground Advantage.", " maxlength=\"128\" required") +
+        _setupField("Weight (grams)", "weight_grams", "", "number", "Parcel weight in grams.", " min=\"1\" required") +
+        _setupField("Label URL", "label_url", "", "url", "The https:// link to the prepaid label PDF in your carrier account.", " maxlength=\"2048\" required") +
+        _setupField("Tracking number", "tracking_number", "", "text", "The carrier tracking number.", " maxlength=\"128\" required") +
+        _setupField("Cost (minor units)", "cost_minor", "", "number", "e.g. 795 for $7.95 of postage.", " min=\"0\" required") +
+        _setupField("Currency", "currency", ccy, "text", "3-letter ISO 4217.", " maxlength=\"3\" class=\"input-code\" required") +
+        "<button class=\"btn\" type=\"submit\">Issue return label</button>" +
+      "</form>";
+    return "<div class=\"panel mt\"><h3 class=\"subhead\">Return shipping label</h3>" + form + "</div>";
+  }
+
+  // A label exists — summary + timeline + the legal next actions.
+  var statusText = RETURN_LABEL_STATUS_TEXT[label.status] || label.status;
+  var costShown  = (label.cost_minor != null)
+    ? pricing.format(label.cost_minor, label.currency || "USD")
+    : null;
+  var summary =
+    "<p><span class=\"status-pill " + _returnLabelPillClass(label.status) + "\">" + _htmlEscape(statusText) + "</span></p>" +
+    "<p><span class=\"meta\">Carrier</span><br>" + _htmlEscape(label.carrier || "—") +
+      (label.service_level ? " · " + _htmlEscape(label.service_level) : "") + "</p>" +
+    "<p><span class=\"meta\">Tracking</span><br>" + _htmlEscape(label.tracking_number || "—") + "</p>" +
+    (costShown ? "<p><span class=\"meta\">Postage</span><br>" + _htmlEscape(costShown) + "</p>" : "") +
+    // The label_url is an https link the operator pasted — link it so they can
+    // re-open the label. rel=noopener noreferrer + a literal-text check keeps
+    // it inert beyond a navigation.
+    (label.label_url
+      ? "<p><a class=\"btn btn--ghost\" href=\"" + _htmlEscape(label.label_url) + "\" target=\"_blank\" rel=\"noopener noreferrer\">Open label</a></p>"
+      : "");
+
+  var timelineRows = events.map(function (ev) {
+    var evText = RETURN_LABEL_EVENT_TEXT[ev.event_type] || ev.event_type;
+    var detail = "";
+    try {
+      var d = ev.detail_json ? JSON.parse(ev.detail_json) : {};
+      if (d && d.location) detail = String(d.location);
+      else if (d && d.exception) detail = String(d.exception);
+    } catch (_e) { detail = ""; }
+    return "<li>" + _htmlEscape(String(evText)) +
+      (detail ? " — " + _htmlEscape(detail) : "") +
+      " <span class=\"meta\">" + _htmlEscape(_fmtDate(ev.occurred_at)) + "</span></li>";
+  }).join("");
+  var timeline = timelineRows
+    ? "<h4>Tracking timeline</h4><ul class=\"timeline\">" + timelineRows + "</ul>"
+    : "";
+
+  var nextActions = (RETURN_LABEL_NEXT_ACTIONS[label.status] || []).map(function (a) {
+    if (a.suffix === "exception") {
+      // The exception action takes a short required detail.
+      return "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/label/exception\" class=\"return-action\">" +
+        "<h4>" + _htmlEscape(a.label) + "</h4>" +
+        _setupField("What happened", "exception", "", "text", "Lost / damaged / refused — shown on the timeline.", " maxlength=\"256\" required") +
+        "<button class=\"btn btn--danger\" type=\"submit\">" + _htmlEscape(a.label) + "</button>" +
+      "</form>";
+    }
+    if (a.suffix === "in-transit") {
+      return "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/label/in-transit\" class=\"return-action\">" +
+        "<h4>" + _htmlEscape(a.label) + "</h4>" +
+        _setupField("Location (optional)", "location", "", "text", "e.g. LAX hub.", " maxlength=\"256\"") +
+        "<button class=\"btn\" type=\"submit\">" + _htmlEscape(a.label) + "</button>" +
+      "</form>";
+    }
+    return "<form method=\"post\" action=\"/admin/returns/" + _htmlEscape(r.id) + "/label/" + _htmlEscape(a.suffix) + "\" class=\"return-action\">" +
+      "<h4>" + _htmlEscape(a.label) + "</h4>" +
+      "<button class=\"btn\" type=\"submit\">" + _htmlEscape(a.label) + "</button>" +
+    "</form>";
+  }).join("");
+  var actionsBlock = nextActions
+    ? "<div class=\"return-actions\">" + nextActions + "</div>"
+    : "<p class=\"meta\">This label is in a final state — no further tracking updates.</p>";
+
+  return "<div class=\"panel mt\"><h3 class=\"subhead\">Return shipping label</h3>" +
+    summary + timeline + actionsBlock + "</div>";
+}
+
 function renderAdminReturns(opts) {
   opts = opts || {};
   var rmas = opts.returns || [];
@@ -10595,6 +10925,7 @@ function renderAdminReturn(opts) {
       "<div class=\"panel mt\"><h3 class=\"subhead\">Actions</h3>" +
         actions +
       "</div>" +
+      _returnLabelPanel(opts, r) +
     "</section>";
   return _renderAdminShell(opts.shop_name, "Return " + (r.rma_code || r.id.slice(0, 8)), body, "returns", opts.nav_available);
 }

package/lib/asset-manifest.json

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

package/lib/storefront.js

@@ -3916,7 +3916,7 @@ function renderReturns(opts) {
     rowsHtml +=
       "<li class=\"return-card\">" +
         "<div class=\"return-card__head\">" +
-          "<code class=\"return-card__rma\">" + esc(r.rma_code) + "</code>" +
+          "<a class=\"return-card__rma\" href=\"/account/returns/" + esc(String(r.id)) + "\"><code>" + esc(r.rma_code) + "</code></a>" +
           _returnStatusBadge(r.status) +
         "</div>" +
         "<p class=\"return-card__meta\">" + esc(String(r.reason || "")) +
@@ -3962,6 +3962,150 @@ function renderReturns(opts) {
   });
 }
 
+// Customer-facing phrasing for a return label's carrier-scan status. The
+// return-labels module's FSM enum (issued / shipped / in_transit /
+// delivered / exception) is operator/carrier vocabulary; these read for
+// the shopper following their parcel back to the merchant.
+var RETURN_LABEL_STATUS_LABELS = {
+  issued:     "Label ready",
+  shipped:    "Dropped off",
+  in_transit: "On its way back",
+  delivered:  "Delivered to us",
+  exception:  "Delivery issue",
+};
+
+function _returnLabelStatusBadge(status) {
+  var esc = b.template.escapeHtml;
+  var label = RETURN_LABEL_STATUS_LABELS[status] || status;
+  return "<span class=\"return-status return-status--" + esc(String(status)) + "\">" +
+    esc(String(label)) + "</span>";
+}
+
+// Human label for a return_label_events row. The event_type mirrors the
+// label FSM transitions (issued / shipped / in_transit / delivered /
+// exception); these are the shopper-facing phrasings on the timeline.
+var RETURN_LABEL_EVENT_LABELS = {
+  issued:     "Label issued",
+  shipped:    "Parcel dropped off",
+  in_transit: "In transit",
+  delivered:  "Delivered to the merchant",
+  exception:  "Delivery exception",
+};
+
+// One return's status detail, including its return-shipping label (if one
+// has been issued) and the carrier-scan timeline. Ownership-scoped: the
+// route only renders this for a return whose customer_id matches the
+// session customer, so the label + tracking reads are already gated.
+//
+// `opts.rma` is the return_authorizations row. `opts.label` is the most
+// recent return_labels row (or null — a return with no label yet shows a
+// neutral "no label" state, never an error). `opts.events` is the label's
+// ordered return_label_events timeline (empty when there's no label).
+// Reuses the account/returns layout classes — no new CSS.
+function renderReturnDetail(opts) {
+  var esc = b.template.escapeHtml;
+  var rma = opts.rma;
+  var label = opts.label || null;
+  var events = opts.events || [];
+  var date = rma.created_at ? new Date(Number(rma.created_at)).toISOString().slice(0, 10) : "";
+
+  function _row(labelText, value) {
+    return "<p class=\"return-card__meta\"><span class=\"form-field__label\">" + esc(labelText) + "</span> " +
+      (value ? esc(String(value)) : "&mdash;") + "</p>";
+  }
+
+  var summaryRows = "";
+  summaryRows += _row("Reason", rma.reason);
+  if (date) summaryRows += _row("Requested", date);
+  if (rma.status === "rejected" && rma.rejected_reason) {
+    summaryRows += _row("Why it was declined", rma.rejected_reason);
+  }
+  if (Number(rma.refund_amount_minor) > 0) {
+    summaryRows += _row("Refund", pricing.format(Number(rma.refund_amount_minor), rma.refund_currency || "USD"));
+  }
+
+  // The return-label panel. A return with no issued label shows a neutral
+  // note (the label arrives once the operator approves + funds the return)
+  // — never an error. A return WITH a label surfaces the carrier + tracking
+  // number, a download/print affordance, the live status, and the timeline.
+  var labelPanel;
+  if (!label) {
+    labelPanel =
+      "<div class=\"return-card return-label-panel\">" +
+        "<h2 class=\"return-card__subhead\">Return shipping label</h2>" +
+        "<p class=\"return-card__meta return-label-panel__none\">No label yet. We'll add a prepaid return label here once your return is approved.</p>" +
+      "</div>";
+  } else {
+    var carrierLine = label.carrier
+      ? (esc(String(label.carrier)) + (label.service_level ? " &middot; " + esc(String(label.service_level)) : ""))
+      : "";
+    // The download is its own ownership-scoped route (GET
+    // /account/returns/:id/label), which loads the return, re-checks
+    // ownership, then redirects to the carrier label asset — the label_url
+    // is never emitted in the page by id, so the affordance is a link to
+    // the scoped route, not the raw carrier URL.
+    var downloadHref = "/account/returns/" + esc(String(rma.id)) + "/label";
+
+    var timelineRows = "";
+    for (var i = 0; i < events.length; i += 1) {
+      var ev = events[i];
+      var evLabel = RETURN_LABEL_EVENT_LABELS[ev.event_type] || ev.event_type;
+      var when = ev.occurred_at ? new Date(Number(ev.occurred_at)).toISOString().slice(0, 16).replace("T", " ") : "";
+      var detail = "";
+      try {
+        var d = ev.detail_json ? JSON.parse(ev.detail_json) : {};
+        if (d && d.location) detail = String(d.location);
+        else if (d && d.exception) detail = String(d.exception);
+      } catch (_e) { detail = ""; }
+      timelineRows +=
+        "<li class=\"return-timeline__event\">" +
+          "<span class=\"return-timeline__label\">" + esc(String(evLabel)) + "</span>" +
+          (detail ? " <span class=\"return-timeline__detail\">" + esc(detail) + "</span>" : "") +
+          (when ? " <time class=\"return-timeline__when\" datetime=\"" + esc(when) + "\">" + esc(when) + "</time>" : "") +
+        "</li>";
+    }
+    var timeline = timelineRows
+      ? "<ol class=\"return-timeline\">" + timelineRows + "</ol>"
+      : "";
+
+    labelPanel =
+      "<div class=\"return-card return-label-panel\">" +
+        "<div class=\"return-card__head\">" +
+          "<h2 class=\"return-card__subhead\">Return shipping label</h2>" +
+          _returnLabelStatusBadge(label.status) +
+        "</div>" +
+        (carrierLine ? "<p class=\"return-card__meta\"><span class=\"form-field__label\">Carrier</span> " + carrierLine + "</p>" : "") +
+        _row("Tracking number", label.tracking_number) +
+        "<p class=\"return-label-panel__actions\">" +
+          "<a class=\"btn-primary\" href=\"" + downloadHref + "\" rel=\"nofollow\">Download return label</a>" +
+        "</p>" +
+        (timeline ? "<h3 class=\"return-card__subhead\">Tracking</h3>" + timeline : "") +
+      "</div>";
+  }
+
+  var body =
+    "<section class=\"account-returns\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/returns\">Returns</a></li>" +
+        "<li aria-current=\"page\">" + esc(String(rma.rma_code || "")) + "</li>" +
+      "</ol></nav>" +
+      "<div class=\"return-card__head\">" +
+        "<h1 class=\"account-returns__title\">Return <code>" + esc(String(rma.rma_code || "")) + "</code></h1>" +
+        _returnStatusBadge(rma.status) +
+      "</div>" +
+      "<div class=\"return-card\">" + summaryRows + "</div>" +
+      labelPanel +
+    "</section>";
+  return _wrap({
+    title:      "Return " + String(rma.rma_code || ""),
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Customer-facing reasons for an exchange. The values mirror the
 // order-exchanges module's REASONS allow-list; the backend validates the
 // submitted value against its own list, so a forged value is refused
@@ -13227,6 +13371,39 @@ function mount(router, deps) {
         return order;
       }
 
+      // Load the return named in :id and confirm it belongs to the
+      // signed-in customer. The return_authorizations row carries
+      // `customer_id` directly, so ownership is a single comparison — no
+      // transitive lookup. A malformed id (guardUuid TypeError), an unknown
+      // return, or someone else's return ALL return 404 — never a 500,
+      // never a cross-customer reveal. This is the gate the return detail
+      // view + the label-download route funnel through, so a return label /
+      // its tracking is never reachable by a return/label id alone.
+      async function _ownedReturn(req, res, auth) {
+        var rma;
+        try { rma = await deps.returns.get(req.params && req.params.id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!rma || rma.customer_id !== auth.customer_id) {
+          _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+          return null;
+        }
+        return rma;
+      }
+
+      // The most-recent issued label for an owned return (or null). Returns
+      // null when the label primitive isn't wired or no label has been
+      // issued — the detail view renders the neutral "no label yet" state.
+      // Best-effort on a read failure (tables not migrated) so the return
+      // detail never 500s on a missing label table.
+      async function _labelForReturn(returnId) {
+        if (!deps.returnLabels) return null;
+        try { return await deps.returnLabels.labelForReturn(returnId); }
+        catch (e) { if (e instanceof TypeError) return null; throw e; }
+      }
+
       router.get("/account/returns", async function (req, res) {
         var auth = _returnsAuth(req, res); if (!auth) return;
         var page = await deps.returns.listForCustomer(auth.customer_id, { limit: 50 });
@@ -13240,6 +13417,58 @@ function mount(router, deps) {
         }));
       });
 
+      // One return's status detail, including its return-shipping label and
+      // carrier-scan timeline once a label has been issued. Ownership-scoped
+      // through _ownedReturn (foreign / unknown / malformed id → 404). A
+      // return with no issued label renders a neutral "no label yet" state.
+      router.get("/account/returns/:id", async function (req, res) {
+        var auth = _returnsAuth(req, res); if (!auth) return;
+        var rma = await _ownedReturn(req, res, auth); if (!rma) return;
+        var label = await _labelForReturn(rma.id);
+        var events = [];
+        if (label && deps.returnLabels) {
+          try { events = await deps.returnLabels.eventsForLabel(label.id); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; events = []; }
+        }
+        var cartCount = await _cartCountForReq(req);
+        _send(res, 200, renderReturnDetail({
+          rma:        rma,
+          label:      label,
+          events:     events,
+          shop_name:  shopName,
+          cart_count: cartCount,
+        }));
+      });
+
+      // Download / print the return label. Ownership-scoped: load + verify
+      // the return belongs to the session customer (via _ownedReturn — a
+      // foreign / unknown / malformed return id all 404 identically) BEFORE
+      // resolving its label, then redirect to the carrier label asset. The
+      // label_url is resolved server-side through the owning return, never
+      // exposed by a bare label id, and a return with no issued label 404s
+      // (there is nothing to download yet). Mounts only when the label
+      // primitive is wired.
+      if (deps.returnLabels) {
+        router.get("/account/returns/:id/label", async function (req, res) {
+          var auth = _returnsAuth(req, res); if (!auth) return;
+          var rma = await _ownedReturn(req, res, auth); if (!rma) return;
+          var label = await _labelForReturn(rma.id);
+          if (!label || !label.label_url) {
+            _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+            return;
+          }
+          // The carrier label asset is an already-validated HTTPS URL
+          // (return-labels runs label_url through b.safeUrl on issue), so a
+          // redirect can't smuggle a javascript:/credentialed target. The
+          // shopper reaches the printable label through the scoped route,
+          // never the raw URL by id.
+          res.status(302);
+          res.setHeader && res.setHeader("location", label.label_url);
+          res.setHeader && res.setHeader("cache-control", "private, no-store");
+          return res.end ? res.end() : res.send("");
+        });
+      }
+
       router.get("/account/orders/:order_id/return", async function (req, res) {
         var auth = _returnsAuth(req, res); if (!auth) return;
         var order = await _ownedOrder(req, res, auth); if (!order) return;

package/package.json

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