@blamejs/blamejs-shop 0.3.34 → 0.3.36

package/lib/storefront.js

@@ -2488,6 +2488,12 @@ function renderWishlist(opts) {
   var notice = okMsg
     ? "<p class=\"form-notice form-notice--ok\" role=\"status\">" + esc(okMsg) + "</p>"
     : "";
+  // The owner's share panel — a "Share this wishlist" control plus the
+  // list of active share links each with a Revoke action. The route
+  // builds the panel HTML (it owns the share-link reads); absent it (the
+  // sharing primitive isn't wired, or a unit test calling the renderer
+  // directly) the panel is empty so the page renders unchanged.
+  var sharePanel = opts.share_panel || "";
   var body =
     "<section class=\"account-wishlist\">" +
       "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
@@ -2496,6 +2502,7 @@ function renderWishlist(opts) {
       "</ol></nav>" +
       "<h1 class=\"account-wishlist__title\">Saved items</h1>" +
       notice +
+      sharePanel +
       inner +
     "</section>";
   return _wrap({
@@ -2507,6 +2514,136 @@ function renderWishlist(opts) {
   });
 }
 
+// The owner-side wishlist share panel (mounts on /account/wishlist). It
+// renders a "Create a share link" control plus the owner's active share
+// links, each with a status + view count and a Revoke form. `opts.shares`
+// is the owner's links from `listSharesForOwner` (already scoped to the
+// session customer by the route). A revoked / expired link still appears
+// (greyed, no Revoke) so the owner sees the history; only an active link
+// carries a Revoke control.
+//
+// The plaintext share token is surfaced EXACTLY ONCE — at create time, via
+// `opts.fresh_url` (the full public URL of the just-minted link). The list
+// rows never carry the URL because the token isn't persisted; the owner
+// copies the link from this one-time confirmation. `opts.notice` surfaces a
+// created/revoked confirmation via role="status".
+var WISHLIST_SHARE_NOTICES = {
+  created: "Share link created. Copy it below — it's shown only once.",
+  revoked: "Share link revoked. The link no longer works.",
+};
+function _wishlistSharePanel(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+  var shares = opts.shares || [];
+  var nowTs = Date.now();
+  var rows = "";
+  for (var i = 0; i < shares.length; i += 1) {
+    var s = shares[i];
+    var revoked = s.revoked_at != null;
+    var expired = !revoked && s.expires_at != null && Number(s.expires_at) < nowTs;
+    var inactive = revoked || expired;
+    var statusLabel = revoked ? "Revoked" : (expired ? "Expired" : "Active");
+    var statusCls = revoked ? "wishlist-share__status--revoked"
+                  : (expired ? "wishlist-share__status--expired" : "wishlist-share__status--active");
+    var revokeForm = inactive
+      ? ""
+      : "<form class=\"wishlist-share__revoke\" method=\"post\" action=\"/wishlist/share/" + esc(s.id) + "/revoke\">" +
+          "<button type=\"submit\" class=\"btn-ghost btn-ghost--sm\">Revoke</button>" +
+        "</form>";
+    var viewN = Number(s.view_count) || 0;
+    rows +=
+      "<li class=\"wishlist-share" + (inactive ? " wishlist-share--inactive" : "") + "\">" +
+        "<div class=\"wishlist-share__head\">" +
+          "<span class=\"wishlist-share__status " + statusCls + "\">" + esc(statusLabel) + "</span>" +
+          "<span class=\"wishlist-share__views\">" + esc(String(viewN)) + " view" + (viewN === 1 ? "" : "s") + "</span>" +
+        "</div>" +
+        revokeForm +
+      "</li>";
+  }
+  var list = rows ? "<ul class=\"wishlist-share__list\">" + rows + "</ul>" : "";
+  var noticeMsg = WISHLIST_SHARE_NOTICES[opts.notice];
+  var notice = noticeMsg
+    ? "<p class=\"form-notice form-notice--ok\" role=\"status\">" + esc(noticeMsg) + "</p>"
+    : "";
+  // The one-time URL block — present only on the create confirmation. A
+  // read-only text field the owner can copy; it never re-renders after the
+  // owner navigates away (the token isn't persisted).
+  var freshUrl = opts.fresh_url
+    ? "<div class=\"wishlist-share__fresh\">" +
+        "<label class=\"wishlist-share__fresh-label\" for=\"wishlist-share-url\">Your share link</label>" +
+        "<input id=\"wishlist-share-url\" class=\"wishlist-share__url\" type=\"text\" readonly value=\"" + esc(opts.fresh_url) + "\" " +
+          "aria-label=\"Shareable wishlist link\" onfocus=\"this.select()\">" +
+      "</div>"
+    : "";
+  return "<section class=\"wishlist-share-panel\" aria-labelledby=\"wishlist-share-heading\">" +
+           "<h2 id=\"wishlist-share-heading\" class=\"wishlist-share-panel__title\">Share this wishlist</h2>" +
+           "<p class=\"wishlist-share-panel__lede\">Create a link so friends and family can see what you're hoping for. The link shows your saved products only — it never reveals your account.</p>" +
+           notice +
+           freshUrl +
+           "<form class=\"wishlist-share-panel__create\" method=\"post\" action=\"/wishlist/share\">" +
+             "<button type=\"submit\" class=\"btn-secondary\">Create a share link</button>" +
+           "</form>" +
+           list +
+         "</section>";
+}
+
+// Public, no-auth shared-wishlist page (`GET /wishlist/shared/:token`). It
+// renders ONLY the shared product cards (title, image, link to each PDP) —
+// the owner's identity, the per-entry private notes, and the owner customer
+// id are NEVER emitted, mirroring what the primitive's `viewShared` is
+// trusted to surface to a giver. `opts.entries` is the `viewShared` entry
+// list resolved to products; `opts.title` is the share's display title.
+// Carries a noindex robots directive — a personal shared wishlist is not a
+// page search engines should index. An unknown / revoked / expired token
+// never reaches this renderer (the route 404s first via renderNotFound).
+function renderSharedWishlist(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+  var items = opts.items || [];
+  var prefix = opts.asset_prefix || "/assets/";
+  var heading = (opts.title && String(opts.title).length) ? opts.title : "A shared wishlist";
+  var rowsHtml = "";
+  for (var i = 0; i < items.length; i += 1) {
+    var it = items[i];
+    if (!it.product) continue;   // archived/deleted product → drop the card (no owner data to leak)
+    var slug = esc(it.product.slug);
+    var thumb = it.hero_media
+      ? "<img src=\"" + esc(prefix + it.hero_media.r2_key) + "\" alt=\"" + esc(it.hero_media.alt_text || it.product.title) + "\" loading=\"lazy\">"
+      : "<span class=\"wishlist-item__mark\" aria-hidden=\"true\">" + esc((it.product.title || "?").trim().charAt(0).toUpperCase() || "?") + "</span>";
+    rowsHtml +=
+      "<li class=\"wishlist-item\">" +
+        "<a class=\"wishlist-item__media\" href=\"/products/" + slug + "\">" + thumb + "</a>" +
+        "<div class=\"wishlist-item__body\">" +
+          "<a class=\"wishlist-item__title\" href=\"/products/" + slug + "\">" + esc(it.product.title) + "</a>" +
+          "<a class=\"wishlist-item__view card-link\" href=\"/products/" + slug + "\">View product →</a>" +
+        "</div>" +
+      "</li>";
+  }
+  var inner = rowsHtml
+    ? "<ul class=\"wishlist-list\">" + rowsHtml + "</ul>"
+    : "<div class=\"account-empty\">" +
+        "<p class=\"account-empty__lede\">This wishlist is empty right now — nothing's been saved yet.</p>" +
+        "<a class=\"btn-secondary\" href=\"/\">Browse the shop →</a>" +
+      "</div>";
+  var body =
+    "<section class=\"account-wishlist\">" +
+      "<p class=\"eyebrow\">Shared with you</p>" +
+      "<h1 class=\"account-wishlist__title\">" + esc(heading) + "</h1>" +
+      inner +
+    "</section>";
+  return _wrap({
+    title:      heading,
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    // A personal shared wishlist is not search-index material — keep it
+    // out of the index. `noindex` maps to noindex,nofollow in _wrap; the
+    // page needs no canonical (a crawler won't index it to dedupe).
+    robots:     "noindex",
+    body:       body,
+  });
+}
+
 // Compare page notice banner — surfaced after a toggle / a full-basket
 // refusal. The route passes a short message key; unknown keys render
 // nothing so a forged `?notice=` query can't inject arbitrary copy.
@@ -3325,6 +3462,206 @@ function renderReturns(opts) {
   });
 }
 
+// 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
+// there. (No-longer-needed isn't an exchange reason — that's a return.)
+var EXCHANGE_REASONS = [
+  ["defective", "Defective / doesn't work"],
+  ["wrong-item", "Wrong item received"],
+  ["wrong-size", "Wrong size"],
+  ["wrong-colour", "Wrong colour"],
+  ["damaged-in-transit", "Damaged in transit"],
+  ["not-as-described", "Not as described"],
+  ["other", "Other"],
+];
+
+// Customer-facing phrasing for an exchange's FSM status. The module's
+// enum (pending / approved / shipped / delivered / received / closed /
+// rejected) is operator vocabulary; these read for the shopper.
+var EXCHANGE_STATUS_LABELS = {
+  pending:   "Requested",
+  approved:  "Approved",
+  shipped:   "Replacement shipped",
+  delivered: "Replacement delivered",
+  received:  "Return received",
+  closed:    "Completed",
+  rejected:  "Declined",
+};
+
+function _exchangeStatusBadge(status) {
+  var esc = b.template.escapeHtml;
+  var label = EXCHANGE_STATUS_LABELS[status] || status;
+  return "<span class=\"return-status return-status--" + esc(String(status)) + "\">" +
+    esc(String(label)) + "</span>";
+}
+
+// Customer-facing exchange-request form for one owned order. `opts.lines`
+// is the order's order_lines, each decorated with `replacement_options`
+// (the sibling variants of that line's product the shopper can swap to).
+// `opts.notice` is an optional error bounced back from a failed POST.
+// Reuses the returns-form layout classes — no new CSS.
+function renderExchangeForm(opts) {
+  var esc = b.template.escapeHtml;
+  var order = opts.order;
+  var lines = opts.lines || [];
+  var lineRows = "";
+  for (var i = 0; i < lines.length; i += 1) {
+    var l = lines[i];
+    var maxQty = Number(l.qty) || 1;
+    var replOpts = (l.replacement_options || []).map(function (o) {
+      return "<option value=\"" + esc(String(o.id)) + "\">" + esc(String(o.label)) + "</option>";
+    }).join("");
+    // A line with no resolvable sibling variants can't be exchanged for a
+    // different option — offer a same-SKU swap (replace a defective unit)
+    // so the line is never silently undisplayable.
+    var replaceField = replOpts
+      ? "<label class=\"return-line__qty\">Swap for " +
+          "<select name=\"replacement_" + esc(l.id) + "\">" + replOpts + "</select>" +
+        "</label>"
+      : "<p class=\"return-line__of\">Same item, replacement unit.</p>";
+    lineRows +=
+      "<li class=\"return-line\">" +
+        "<label class=\"return-line__pick\">" +
+          "<input type=\"radio\" name=\"line_id\" value=\"" + esc(l.id) + "\"" + (i === 0 ? " checked" : "") + ">" +
+          "<span class=\"return-line__sku\"><code>" + esc(l.sku) + "</code></span>" +
+        "</label>" +
+        "<label class=\"return-line__qty\">Qty to exchange " +
+          "<input type=\"number\" name=\"qty_" + esc(l.id) + "\" value=\"1\" min=\"1\" max=\"" + maxQty + "\">" +
+          " <span class=\"return-line__of\">of " + maxQty + "</span>" +
+        "</label>" +
+        replaceField +
+      "</li>";
+  }
+  var reasonOpts = EXCHANGE_REASONS.map(function (r) {
+    return "<option value=\"" + esc(r[0]) + "\">" + esc(r[1]) + "</option>";
+  }).join("");
+  var notice = opts.notice
+    ? "<p class=\"form-notice form-notice--error\" role=\"alert\">" + esc(String(opts.notice)) + "</p>"
+    : "";
+  var body =
+    "<section class=\"return-form-page\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/exchanges\">Exchanges</a></li>" +
+        "<li aria-current=\"page\">Request an exchange</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"return-form-page__title\">Request an exchange</h1>" +
+      "<p class=\"return-form-page__order\">Order <code>" + esc(order.id) + "</code></p>" +
+      notice +
+      "<form class=\"return-form form-stack\" method=\"post\" action=\"/account/orders/" + esc(order.id) + "/exchange\">" +
+        "<fieldset class=\"return-form__lines\"><legend>Which item?</legend>" +
+          "<ul class=\"return-line-list\">" + lineRows + "</ul>" +
+        "</fieldset>" +
+        "<label class=\"form-field\"><span class=\"form-field__label\">Reason</span>" +
+          "<select name=\"reason\" required>" + reasonOpts + "</select></label>" +
+        "<button type=\"submit\" class=\"btn-primary\">Request exchange</button>" +
+      "</form>" +
+    "</section>";
+  return _wrap({
+    title:      "Request an exchange",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// The signed-in customer's exchange list. `opts.exchanges` is the
+// ownership-scoped set (already filtered to this customer's orders); each
+// links to its status detail.
+function renderExchanges(opts) {
+  var esc = b.template.escapeHtml;
+  var exchanges = opts.exchanges || [];
+  var rowsHtml = "";
+  for (var i = 0; i < exchanges.length; i += 1) {
+    var x = exchanges[i];
+    var date = x.created_at ? new Date(Number(x.created_at)).toISOString().slice(0, 10) : "";
+    rowsHtml +=
+      "<li class=\"return-card\">" +
+        "<div class=\"return-card__head\">" +
+          "<a class=\"return-card__rma\" href=\"/account/exchanges/" + esc(String(x.id)) + "\"><code>" + esc(String(x.id).slice(0, 8)) + "</code></a>" +
+          _exchangeStatusBadge(x.status) +
+        "</div>" +
+        "<p class=\"return-card__meta\">" +
+          esc(String(x.return_sku || "")) + " &rarr; " + esc(String(x.replacement_sku || "")) +
+          (date ? " &middot; <time datetime=\"" + esc(date) + "\">" + esc(date) + "</time>" : "") +
+        "</p>" +
+        (x.status === "rejected" && x.reject_reason ? "<p class=\"return-card__reject\">" + esc(String(x.reject_reason)) + "</p>" : "") +
+      "</li>";
+  }
+  var inner = rowsHtml
+    ? "<ul class=\"return-list\">" + rowsHtml + "</ul>"
+    : "<div class=\"account-empty\">" +
+        "<p class=\"account-empty__lede\">No exchanges yet. Start one from an order in your account.</p>" +
+        "<a class=\"btn-secondary\" href=\"/account/orders\">View your orders &rarr;</a>" +
+      "</div>";
+  var notice = opts.requested
+    ? "<p class=\"form-notice form-notice--ok\" role=\"status\">Exchange request received — we'll review it and email you next steps.</p>"
+    : "";
+  var body =
+    "<section class=\"account-returns\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li aria-current=\"page\">Exchanges</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-returns__title\">Exchanges</h1>" +
+      notice +
+      inner +
+    "</section>";
+  return _wrap({
+    title:      "Exchanges",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// One exchange's status detail. Ownership-scoped (the route only renders
+// this for an exchange whose parent order belongs to the session
+// customer). Surfaces the swap, the reason, the live status, the
+// rejection reason (if declined), and the outbound tracking number once
+// the replacement has shipped.
+function renderExchangeDetail(opts) {
+  var esc = b.template.escapeHtml;
+  var x = opts.exchange;
+  var date = x.created_at ? new Date(Number(x.created_at)).toISOString().slice(0, 10) : "";
+  var rows = "";
+  function _row(label, value) {
+    return "<p class=\"return-card__meta\"><span class=\"form-field__label\">" + esc(label) + "</span> " +
+      (value ? esc(String(value)) : "&mdash;") + "</p>";
+  }
+  rows += _row("Item returned", x.return_sku + " ×" + x.return_qty);
+  rows += _row("Replacement", x.replacement_sku + " ×" + x.replacement_qty);
+  rows += _row("Reason", x.reason);
+  if (date) rows += _row("Requested", date);
+  if (x.status === "rejected" && x.reject_reason) rows += _row("Why it was declined", x.reject_reason);
+  if (x.tracking_number) {
+    rows += _row("Replacement tracking", x.carrier ? (x.carrier + " · " + x.tracking_number) : x.tracking_number);
+  }
+  var body =
+    "<section class=\"account-returns\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li><a href=\"/account/exchanges\">Exchanges</a></li>" +
+        "<li aria-current=\"page\">" + esc(String(x.id).slice(0, 8)) + "</li>" +
+      "</ol></nav>" +
+      "<div class=\"return-card__head\">" +
+        "<h1 class=\"account-returns__title\">Exchange <code>" + esc(String(x.id).slice(0, 8)) + "</code></h1>" +
+        _exchangeStatusBadge(x.status) +
+      "</div>" +
+      "<div class=\"return-card\">" + rows + "</div>" +
+    "</section>";
+  return _wrap({
+    title:      "Exchange " + String(x.id).slice(0, 8),
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Support ticket — the categories a shopper can pick when raising one,
 // and the human label for each. The values mirror the support-tickets
 // module's ALLOWED_CATEGORIES; the backend validates the submitted value
@@ -5118,6 +5455,17 @@ function _orderEligibleForReturn(status) {
     status === "shipped" || status === "delivered";
 }
 
+// An exchange (swap the item for a different size / colour / unit at the
+// same value) is offered on the same window as a return: a paid (or
+// further-along) order, never a still-pending (unpaid) one nor the
+// terminal off-ramps (cancelled / refunded). The customer ships the
+// original back AND receives a replacement — no refund — so the window
+// matches the goods being in the customer's hands.
+function _orderEligibleForExchange(status) {
+  return status === "paid" || status === "fulfilling" ||
+    status === "shipped" || status === "delivered";
+}
+
 // Reorder is offered for any order that represents a real purchase the
 // customer might want to repeat — paid through delivered, plus the
 // terminal refunded/cancelled states (a cancelled or refunded order is a
@@ -5241,6 +5589,10 @@ function _orderActionsBlock(o) {
     btns.push(
       "<a class=\"btn-secondary order-action\" href=\"/account/orders/" + esc(String(o.id)) + "/return\">Request a return</a>");
   }
+  if (_orderEligibleForExchange(o.status)) {
+    btns.push(
+      "<a class=\"btn-secondary order-action\" href=\"/account/orders/" + esc(String(o.id)) + "/exchange\">Request an exchange</a>");
+  }
   if (_orderEligibleForCancel(o.status)) {
     btns.push(
       "<form class=\"order-action\" method=\"post\" action=\"/orders/" + esc(String(o.id)) + "/cancel\">" +
@@ -6504,6 +6856,7 @@ var ACCOUNT_DASH_PAGE =
   "      <a class=\"btn-secondary\" href=\"/account/recently-viewed\">Recently viewed</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/addresses\">Addresses</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/returns\">Returns</a>\n" +
+  "      <a class=\"btn-secondary\" href=\"/account/exchanges\">Exchanges</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/support\">Support</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/loyalty\">Rewards</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/credit\">Store credit</a>\n" +
@@ -10695,9 +11048,29 @@ function mount(router, deps) {
         }
         var cartCount = await _cartCountForReq(req);
         var wlUrl = req.url ? new URL(req.url, "http://localhost") : null;
+        // Owner share panel — only when the sharing primitive is wired.
+        // The share-link list read is SCOPED to the session customer's id,
+        // so the owner only ever sees their own links. A reads failure
+        // (missing table on a fresh deploy) degrades to no panel rather
+        // than 500-ing the page.
+        var sharePanel = "";
+        if (deps.wishlistSharing) {
+          // Scoped to the session customer — the panel read keys on the
+          // signed-in customer's id, so the owner only ever sees their own
+          // links (this list surface carries no path id, so no IDOR).
+          var sessionOwnerId = auth.customer_id;
+          var ownShares = [];
+          try { ownShares = await deps.wishlistSharing.listSharesForOwner(sessionOwnerId); }
+          catch (_e) { ownShares = []; }
+          sharePanel = _wishlistSharePanel({
+            shares: ownShares,
+            notice: wlUrl ? wlUrl.searchParams.get("share") : null,
+          });
+        }
         _send(res, 200, renderWishlist({
           items:        items,
           notice:       wlUrl ? wlUrl.searchParams.get("ok") : null,
+          share_panel:  sharePanel,
           shop_name:    shopName,
           cart_count:   cartCount,
           asset_prefix: deps.asset_prefix || "/assets/",
@@ -10705,6 +11078,194 @@ function mount(router, deps) {
       });
     }
 
+    // ---- wishlist sharing -----------------------------------------------
+    //
+    // Owner-scoped share links on the customer's own wishlist, plus the
+    // public, no-auth shared view a giver opens. Mounts only when the
+    // sharing primitive is wired (it composes the wishlist primitive, so a
+    // store with sharing also has the solo wishlist above).
+    //
+    // Owner side (gated on the session customer, CSRF-protected by the
+    // container form chokepoint): create a share link, see active links,
+    // revoke a link. Every owner action is scoped to the session customer —
+    // the create keys on the signed-in customer's id; the revoke loads the
+    // session customer's links by their id and refuses a link that isn't
+    // the session customer's (clean 404, no IDOR).
+    //
+    // Public side (NO auth): `GET /wishlist/shared/:token` resolves the
+    // wishlist ONLY through `viewShared(token)` — never by a guessable
+    // wishlist/customer id — renders the saved products (redacting the
+    // owner's identity + private notes), records the view, and 404s an
+    // unknown / revoked / expired token. noindex (a personal wishlist isn't
+    // index material).
+    if (deps.wishlistSharing) {
+      // Build the owner's share panel from links scoped to the session
+      // customer. `opts.fresh_url` (the one-time URL of a just-created link)
+      // and `opts.notice` (created / revoked) thread through to the panel.
+      // A reads failure (missing table on a fresh deploy) degrades to a
+      // panel with no list rather than throwing.
+      async function _buildSharePanel(customerId, opts) {
+        opts = opts || {};
+        var shareRows = [];
+        try { shareRows = await deps.wishlistSharing.listSharesForOwner(customerId); }
+        catch (_e) { shareRows = []; }
+        return _wishlistSharePanel({
+          shares:    shareRows,
+          notice:    opts.notice || null,
+          fresh_url: opts.fresh_url || null,
+        });
+      }
+
+      // Re-render the /account/wishlist page (used by the create POST so the
+      // one-time share URL is shown inline, and on a revoke). Resolves the
+      // same saved-items list the GET route renders.
+      async function _renderWishlistWithPanel(req, res, customerId, panelOpts) {
+        var page = await deps.wishlist.listForCustomer(customerId, { limit: 50 });
+        var items = [];
+        for (var i = 0; i < page.rows.length; i += 1) {
+          var entry = page.rows[i];
+          var product = null;
+          try { product = await deps.catalog.products.get(entry.product_id); } catch (_e) { product = null; }
+          if (!product) { items.push({ product: null, product_id: entry.product_id }); continue; }
+          var media = await deps.catalog.media.listForProduct(product.id);
+          items.push({ product: product, hero_media: media.length ? media[0] : null });
+        }
+        var cartCount = await _cartCountForReq(req);
+        var panel = await _buildSharePanel(customerId, panelOpts || {});
+        _send(res, 200, renderWishlist({
+          items:        items,
+          share_panel:  panel,
+          shop_name:    shopName,
+          cart_count:   cartCount,
+          asset_prefix: deps.asset_prefix || "/assets/",
+        }));
+      }
+
+      // POST /wishlist/share — mint a share link for the SESSION customer's
+      // wishlist. The link is owner-scoped (keyed on `auth.customer_id`);
+      // the plaintext token is returned once and surfaced inline as the
+      // public URL the owner copies (never persisted). `unlisted` is the
+      // default privacy: link-bearer access, no friends-graph requirement,
+      // not advertised. The page re-renders directly (200) rather than a
+      // redirect so the one-time URL is shown.
+      router.post("/wishlist/share", async function (req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") return _serviceUnavailable(res, "auth not configured");
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          return res.end ? res.end() : res.send("");
+        }
+        var created;
+        try {
+          created = await deps.wishlistSharing.createShareLink({
+            owner_customer_id: auth.customer_id,
+            privacy:           "unlisted",
+          });
+        } catch (e) {
+          res.status(e instanceof TypeError ? 400 : 500);
+          return res.end ? res.end((e && e.message) || "Error") : res.send((e && e.message) || "Error");
+        }
+        // The full public URL the giver opens. Built from this request's
+        // ORIGIN (scheme + host) so the one-time link is a correct absolute
+        // URL — this POST lands on /wishlist/share, so trimming a path off
+        // the canonical URL would mangle the link (and the token shows once).
+        var shareOrigin = "";
+        try { shareOrigin = new URL(_requestUrls(req).canonical_url).origin; }
+        catch (_e) { shareOrigin = ""; /* unparseable — fall back to a host-relative link */ }
+        var freshUrl = shareOrigin + "/wishlist/shared/" + encodeURIComponent(created.plaintext_token);
+        await _renderWishlistWithPanel(req, res, auth.customer_id, { notice: "created", fresh_url: freshUrl });
+      });
+
+      // POST /wishlist/share/:share_id/revoke — revoke one of the SESSION
+      // customer's share links. The primitive's revokeShareLink moves a link
+      // by id alone (no owner notion), so the route owns the ownership
+      // decision: it loads the session customer's own links and refuses a
+      // share_id that isn't among them (clean 404). Without that scope, any
+      // signed-in shopper could revoke another customer's link by guessing
+      // its id (IDOR).
+      router.post("/wishlist/share/:share_id/revoke", async function (req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") return _serviceUnavailable(res, "auth not configured");
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          return res.end ? res.end() : res.send("");
+        }
+        var shareId = (req.params && req.params.share_id) || "";
+        // Ownership scope: the link must belong to the session customer.
+        var owned = [];
+        try { owned = await deps.wishlistSharing.listSharesForOwner(auth.customer_id); }
+        catch (_e) { owned = []; }
+        var match = null;
+        for (var i = 0; i < owned.length; i += 1) {
+          if (owned[i].id === shareId) { match = owned[i]; break; }
+        }
+        if (!match) {
+          // Unknown id, malformed id, or a link owned by someone else all
+          // resolve the same way — a clean 404, no act, no leak.
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        try {
+          await deps.wishlistSharing.revokeShareLink({ link_id: shareId, reason: "owner revoked from account" });
+        } catch (e) {
+          res.status(e instanceof TypeError ? 400 : 500);
+          return res.end ? res.end((e && e.message) || "Error") : res.send((e && e.message) || "Error");
+        }
+        res.status(303); res.setHeader && res.setHeader("location", "/account/wishlist?share=revoked");
+        return res.end ? res.end() : res.send("");
+      });
+
+      // GET /wishlist/shared/:token — the public, no-auth shared view. The
+      // wishlist is resolved ONLY via viewShared(token); a giver with the
+      // link sees the saved products (with the owner identity + private
+      // notes redacted — the renderer emits product cards only). An unknown
+      // / revoked / expired token 404s exactly like an unknown route. The
+      // view is recorded best-effort (analytics for the owner) and never
+      // blocks the render. noindex.
+      router.get("/wishlist/shared/:token", async function (req, res) {
+        var token = (req.params && req.params.token) || "";
+        var view = null;
+        try {
+          view = await deps.wishlistSharing.viewShared({ token: token });
+        } catch (_e) {
+          // A malformed token (TypeError) and a not-found / revoked / expired
+          // token (coded errors) all render the same 404 — no oracle on why.
+          return _send(res, 404, renderNotFound({ shop_name: shopName, cart_count: await _cartCountForReq(req) }));
+        }
+        // Record the open for the owner's view counter. Best-effort: a
+        // record failure never breaks the giver's page.
+        try { await deps.wishlistSharing.recordView({ token: token }); }
+        catch (_e) { /* drop-silent — analytics, not the render path */ }
+        // Resolve each shared entry to its product + hero image. The entry's
+        // owner customer_id + private notes are NOT carried into the view
+        // (the renderer emits product cards only) so the giver never sees
+        // the owner's identity.
+        var items = [];
+        var entries = (view && view.entries) || [];
+        for (var i = 0; i < entries.length; i += 1) {
+          var product = null;
+          try { product = await deps.catalog.products.get(entries[i].product_id); } catch (_e) { product = null; }
+          if (!product) continue;
+          var media = await deps.catalog.media.listForProduct(product.id);
+          items.push({ product: product, hero_media: media.length ? media[0] : null });
+        }
+        _send(res, 200, renderSharedWishlist({
+          items:        items,
+          title:        (view && view.share && view.share.title) || "A shared wishlist",
+          shop_name:    shopName,
+          cart_count:   await _cartCountForReq(req),
+          asset_prefix: deps.asset_prefix || "/assets/",
+        }));
+      });
+    }
+
     // Save for later — move a cart line into a per-customer holding
     // list and back. Login required (the list is per-customer).
     if (deps.saveForLater) {
@@ -11424,6 +11985,240 @@ function mount(router, deps) {
       });
     }
 
+    // Self-serve exchanges — a customer requests a same-value item SWAP
+    // (different size / colour / unit) against one of their own orders and
+    // tracks its status; operators action it via the admin /admin/exchanges
+    // queue. Distinct from returns (which end in a refund): an exchange
+    // ships the original back AND a replacement out, no money refunded.
+    //
+    // Ownership / IDOR: an order_exchanges row carries `order_id` but NOT
+    // `customer_id` — the customer→order linkage lives on the order. So
+    // every per-exchange / per-order route here loads the parent order and
+    // refuses (clean 404) unless `order.customer_id === auth.customer_id`,
+    // exactly like the returns + support gates. The exchange primitive
+    // moves a row by id alone, so the route owns the ownership decision.
+    if (deps.orderExchanges && deps.order) {
+      function _exchangeAuth(req, res) {
+        var auth;
+        try { auth = _currentCustomer(req); }
+        catch (e) {
+          if (e && e.code === "vault/not-initialized") { _serviceUnavailable(res, "auth not configured"); return null; }
+          throw e;
+        }
+        if (!auth) {
+          res.status(303); res.setHeader && res.setHeader("location", "/account/login");
+          res.end ? res.end() : res.send("");
+          return null;
+        }
+        return auth;
+      }
+
+      // Load the order named in :order_id and confirm it belongs to the
+      // signed-in customer. A malformed id (guardUuid TypeError), a missing
+      // order, or someone else's order all return 404 — never a 500, never
+      // a leak. This is the ownership gate the request form + POST funnel
+      // through.
+      async function _ownedOrderForExchange(req, res, auth) {
+        var order;
+        try { order = await deps.order.get(req.params && req.params.order_id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!order || order.customer_id !== auth.customer_id) {
+          _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+          return null;
+        }
+        return order;
+      }
+
+      // Load the exchange named in :id, then load its parent order and
+      // confirm THAT order belongs to the signed-in customer. The exchange
+      // row has no customer_id, so ownership is asserted transitively
+      // through the order. A malformed id (TypeError), an unknown exchange,
+      // an exchange whose order is gone, or an exchange owned by someone
+      // else ALL return 404 — never a 500, never a cross-customer reveal.
+      async function _ownedExchange(req, res, auth) {
+        var exchange;
+        try { exchange = await deps.orderExchanges.getExchange(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 (!exchange) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+        var order;
+        try { order = await deps.order.get(exchange.order_id); }
+        catch (e) {
+          if (e instanceof TypeError) { _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme })); return null; }
+          throw e;
+        }
+        if (!order || order.customer_id !== auth.customer_id) {
+          _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
+          return null;
+        }
+        return exchange;
+      }
+
+      // Resolve the sibling variants a line's product can be swapped to:
+      // every active variant of the same product, labelled by its option
+      // values (falling back to the SKU). Best-effort — absent the catalog
+      // handle (or a read failure) the line offers a same-SKU swap.
+      async function _replacementOptions(line) {
+        if (!deps.catalog || !line || !line.variant_id) return [];
+        try {
+          var v = await deps.catalog.variants.get(line.variant_id);
+          if (!v) return [];
+          var siblings = await deps.catalog.variants.listForProduct(v.product_id);
+          return (siblings || []).map(function (s) {
+            var optLabel = s.options
+              ? Object.keys(s.options).map(function (k) { return s.options[k]; }).join(" / ")
+              : "";
+            var label = (optLabel ? optLabel + " — " : "") + s.sku;
+            return { id: s.id, sku: s.sku, label: label };
+          });
+        } catch (_e) { return []; }
+      }
+
+      // The customer's own exchange list, scoped to their orders. The
+      // primitive resolves the customer→order linkage through the injected
+      // order handle, so a foreign order's exchange never appears here.
+      router.get("/account/exchanges", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var exchanges = [];
+        try { exchanges = await deps.orderExchanges.exchangesForCustomer(auth.customer_id, { limit: 100 }); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; exchanges = []; }
+        var cartCount = await _cartCountForReq(req);
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _send(res, 200, renderExchanges({
+          exchanges:  exchanges,
+          requested:  url && url.searchParams.get("ok") === "1",
+          shop_name:  shopName,
+          cart_count: cartCount,
+        }));
+      });
+
+      // One exchange's status detail. Ownership-scoped through the parent
+      // order (foreign / unknown → 404).
+      router.get("/account/exchanges/:id", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var exchange = await _ownedExchange(req, res, auth); if (!exchange) return;
+        var cartCount = await _cartCountForReq(req);
+        _send(res, 200, renderExchangeDetail({ exchange: exchange, shop_name: shopName, cart_count: cartCount }));
+      });
+
+      // The exchange-request form for one of the customer's own orders,
+      // gated on the same eligibility window as a return.
+      router.get("/account/orders/:order_id/exchange", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var order = await _ownedOrderForExchange(req, res, auth); if (!order) return;
+        var cartCount = await _cartCountForReq(req);
+        if (!_orderEligibleForExchange(order.status)) {
+          return _send(res, 400, renderExchangeForm({
+            order: order, lines: [], notice: "This order isn't eligible for an exchange.",
+            shop_name: shopName, cart_count: cartCount,
+          }));
+        }
+        var lines = [];
+        var orderLines = order.lines || [];
+        for (var i = 0; i < orderLines.length; i += 1) {
+          var ol = orderLines[i];
+          lines.push(Object.assign({}, ol, { replacement_options: await _replacementOptions(ol) }));
+        }
+        _send(res, 200, renderExchangeForm({ order: order, lines: lines, shop_name: shopName, cart_count: cartCount }));
+      });
+
+      router.post("/account/orders/:order_id/exchange", async function (req, res) {
+        var auth = _exchangeAuth(req, res); if (!auth) return;
+        var order = await _ownedOrderForExchange(req, res, auth); if (!order) return;
+        var body = req.body || {};
+        var cartCount = await _cartCountForReq(req);
+
+        // Re-decorate the lines so a failed POST re-renders the same form
+        // (with the replacement pickers intact) rather than a bare page.
+        async function _decoratedLines() {
+          var out = [];
+          var ols = order.lines || [];
+          for (var i = 0; i < ols.length; i += 1) {
+            out.push(Object.assign({}, ols[i], { replacement_options: await _replacementOptions(ols[i]) }));
+          }
+          return out;
+        }
+        function _badForm(notice, status) {
+          return _decoratedLines().then(function (lines) {
+            return _send(res, status || 400, renderExchangeForm({
+              order: order, lines: lines, notice: notice,
+              shop_name: shopName, cart_count: cartCount,
+            }));
+          });
+        }
+
+        if (!_orderEligibleForExchange(order.status)) {
+          return _badForm("This order isn't eligible for an exchange.");
+        }
+
+        // Resolve the picked line from the order's OWN lines (authoritative
+        // sku/qty) — never trust a client-supplied sku. The radio carries
+        // the order_line id.
+        var orderLines = order.lines || [];
+        var picked = null;
+        for (var i = 0; i < orderLines.length; i += 1) {
+          if (orderLines[i].id === body.line_id) { picked = orderLines[i]; break; }
+        }
+        if (!picked) return _badForm("Pick the item you'd like to exchange.");
+
+        var wantedQty = parseInt(body["qty_" + picked.id], 10);
+        var maxQty = Number(picked.qty) || 1;
+        var qty = Number.isFinite(wantedQty) && wantedQty >= 1 && wantedQty <= maxQty ? wantedQty : maxQty;
+
+        // The replacement variant: the chosen sibling variant of the same
+        // product. The select carries the variant id; resolve it back to a
+        // sku through the catalog (never trust a client sku). Absent a
+        // selection (a same-SKU swap — replace a defective unit) the
+        // replacement defaults to the line's own sku/variant.
+        var replacementSku = picked.sku;
+        var replacementVariantId = picked.variant_id;
+        var chosen = body["replacement_" + picked.id];
+        if (chosen && deps.catalog) {
+          // The replacement MUST be one of the sibling variants offered for
+          // the purchased line's product. Validate the chosen id against the
+          // same option set the form was built from (_replacementOptions) —
+          // resolving it through a bare variants.get would accept ANY catalog
+          // variant, letting a forged replacement_<id> swap a cheap item for
+          // any variant in the catalog. The option carries the catalog-
+          // resolved sku/id, so a client sku is never trusted.
+          var options = await _replacementOptions(picked);
+          var match = null;
+          for (var oi = 0; oi < options.length; oi += 1) {
+            if (options[oi].id === chosen) { match = options[oi]; break; }
+          }
+          if (!match) return _badForm("That replacement variant isn't available — pick another.");
+          replacementSku = match.sku;
+          replacementVariantId = match.id;
+        }
+
+        try {
+          await deps.orderExchanges.requestExchange({
+            order_id:               order.id,
+            line_id:                picked.id,
+            return_sku:             picked.sku,
+            return_qty:             qty,
+            replacement_sku:        replacementSku,
+            replacement_variant_id: replacementVariantId,
+            replacement_qty:        qty,
+            reason:                 body.reason,
+          });
+        } catch (e) {
+          if (e instanceof TypeError) {
+            return _badForm((e && e.message || "").replace(/^order-exchanges[.:]\s*/, "") || "Please check your exchange request.");
+          }
+          throw e;
+        }
+        res.status(303);
+        res.setHeader && res.setHeader("location", "/account/exchanges?ok=1");
+        return res.end ? res.end() : res.send("");
+      });
+    }
+
     // Support tickets — the signed-in customer raises a ticket, lists
     // their own, reads a thread, and replies. EVERY route is login-gated
     // AND scoped to the session customer's id: the support primitive