@blamejs/blamejs-shop 0.3.39 → 0.3.41

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.41 (2026-05-31) — **The public product API no longer leaks internal error details, and bad order links return Not Found.** A server-side error on the public product API could include the raw internal error message — potentially database or query details — in its 500 response to anonymous callers. Those responses now return a generic message, with the real error recorded server-side only, matching how the admin side already behaves. Separately, opening an order or payment page with a malformed link now returns a clean Not Found instead of a server error. This release also updates the vendored blamejs runtime to v0.14.15. **Changed:** *Vendored blamejs runtime updated to v0.14.15* — The bundled blamejs runtime is updated to v0.14.15, which adds a recognized-purpose vocabulary to its consent ledger (with lawful-basis enforcement for regulated purposes) and a new privacy namespace for periodic third-party vendor-review attestations. These are additive, opt-in capabilities; existing behavior is unchanged and no operator action is required. **Fixed:** *Public product API hides internal error details* — When the public product API (the catalog endpoints) hit a server-side error, its 500 response could carry the raw internal error message — including database or constraint text — to any caller. It now returns a generic "something went wrong" message and records the real error server-side only, the same way the admin console already scrubs its errors. Validation errors still return their helpful 400 message unchanged. · *Malformed order and payment links return Not Found* — Opening an order confirmation or payment page with a malformed (non-identifier) link returned a server error instead of a Not Found. Both pages now return a clean 404 for a malformed or unknown link, matching the order reorder and cancel pages.
+
+- 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.41",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",