@blamejs/blamejs-shop 0.1.26 → 0.1.28

package/lib/storefront.js

@@ -1413,6 +1413,319 @@ function renderReturns(opts) {
   });
 }
 
+// Loyalty transaction-type pill — reuses the `pdp__badge` class the
+// theme already styles. The type is one of the ledger's closed enum
+// (earn / redeem / expire / adjust / tier-bonus).
+function _loyaltyTxBadge(type) {
+  var esc = b.template.escapeHtml;
+  return "<span class=\"pdp__badge loyalty-tx--" + esc(String(type)) + "\">" + esc(String(type)) + "</span>";
+}
+
+// Human label for a reward `kind` + its value payload. Keeps the
+// catalog row readable without leaking the raw value_json shape.
+function _loyaltyRewardValue(reward) {
+  var v = reward.value_json || {};
+  if (reward.kind === "discount_percent") return (Number(v.percent) || 0) + "% off";
+  if (reward.kind === "discount_amount")  return pricing.format(Number(v.amount_minor) || 0, "USD") + " off";
+  if (reward.kind === "free_shipping")    return "Free shipping";
+  if (reward.kind === "free_product")     return "Free product";
+  return reward.kind;
+}
+
+// Earn-rule trigger → customer-facing phrase. Operators see slugs;
+// customers see plain language. Unknown triggers fall back to the raw
+// trigger so a future enum addition still renders something.
+var LOYALTY_TRIGGER_LABELS = {
+  per_dollar_spent:         "per $1 spent",
+  per_purchase:             "per order",
+  per_review:               "per review you write",
+  per_referral_redeemed:    "per friend you refer",
+  birthday:                 "on your birthday",
+  signup_bonus:             "when you sign up",
+  first_purchase:           "on your first order",
+  abandoned_cart_recovered: "when you complete a saved cart",
+};
+
+// The signed-in customer's loyalty surface: balance + tier, how points
+// are earned (active earn rules), the reward catalog (redeem control
+// when wired), the earn/redeem ledger (paginated), and past
+// redemptions. Reuses the account/returns layout classes — no new CSS.
+function renderLoyalty(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+  var bal = opts.balance || { balance: 0, lifetime: 0, tier: "bronze" };
+  var ratio = Number(opts.redemption_points_per_usd) || 100;
+
+  var notice = opts.notice
+    ? "<p class=\"form-notice" + (opts.notice_kind === "error" ? " form-notice--error" : "") + "\" role=\"alert\">" +
+        esc(String(opts.notice)) + "</p>"
+    : "";
+
+  // Stats strip — balance / tier / lifetime / spendable value.
+  var spendableValue = pricing.format(Math.floor((Number(bal.balance) || 0) * 100 / ratio), "USD");
+  var stats =
+    "<dl class=\"account-dash__stats\">" +
+      "<div><dt>Points balance</dt><dd>" + esc(String(Number(bal.balance) || 0)) + "</dd></div>" +
+      "<div><dt>Tier</dt><dd>" + esc(String(bal.tier || "bronze")) + "</dd></div>" +
+      "<div><dt>Lifetime points</dt><dd>" + esc(String(Number(bal.lifetime) || 0)) + "</dd></div>" +
+      "<div><dt>Worth</dt><dd>" + esc(spendableValue) + "</dd></div>" +
+    "</dl>";
+
+  // How points are earned.
+  var rules = opts.earn_rules || [];
+  var earnInner = "";
+  for (var i = 0; i < rules.length; i += 1) {
+    var rule = rules[i];
+    var label = LOYALTY_TRIGGER_LABELS[rule.trigger] || rule.trigger;
+    earnInner +=
+      "<li class=\"return-card\"><div class=\"return-card__head\">" +
+        "<span>" + esc(String(rule.points_per_unit)) + " points " + esc(label) + "</span>" +
+      "</div></li>";
+  }
+  var earnSection = earnInner
+    ? "<h2 class=\"pdp__variants-title\">How you earn points</h2><ul class=\"return-list\">" + earnInner + "</ul>"
+    : "<h2 class=\"pdp__variants-title\">How you earn points</h2>" +
+      "<p class=\"return-empty\">Earn points on every order — your balance grows as you shop.</p>";
+
+  // Reward catalog + redeem control.
+  var rewards = opts.rewards || [];
+  var rewardSection = "";
+  if (rewards.length) {
+    var rewardItems = "";
+    for (var r = 0; r < rewards.length; r += 1) {
+      var rw = rewards[r];
+      var affordable = (Number(bal.balance) || 0) >= Number(rw.point_cost);
+      var action;
+      if (opts.can_redeem) {
+        action = "<form method=\"post\" action=\"/account/loyalty/redeem\">" +
+          "<input type=\"hidden\" name=\"reward_slug\" value=\"" + esc(rw.slug) + "\">" +
+          "<button type=\"submit\" class=\"btn-primary\"" + (affordable ? "" : " disabled") + ">" +
+          (affordable ? "Redeem" : "Not enough points") + "</button></form>";
+      } else {
+        action = "";
+      }
+      rewardItems +=
+        "<li class=\"return-card\"><div class=\"return-card__head\">" +
+          "<span class=\"return-card__rma\">" + esc(rw.title) + "</span>" +
+          "<span class=\"pdp__badge\">" + esc(_loyaltyRewardValue(rw)) + "</span>" +
+        "</div>" +
+        "<p class=\"return-card__meta\">" + esc(String(rw.point_cost)) + " points</p>" +
+        action +
+        "</li>";
+    }
+    rewardSection =
+      "<h2 class=\"pdp__variants-title\">Redeem your points</h2>" +
+      "<ul class=\"return-list\">" + rewardItems + "</ul>";
+  }
+
+  // Past redemptions.
+  var reds = opts.redemptions || [];
+  var redSection = "";
+  if (reds.length) {
+    var redItems = "";
+    for (var d = 0; d < reds.length; d += 1) {
+      var red = reds[d];
+      var rdate = red.redeemed_at ? new Date(Number(red.redeemed_at)).toISOString().slice(0, 10) : "";
+      redItems +=
+        "<li class=\"return-card\"><div class=\"return-card__head\">" +
+          "<span class=\"return-card__rma\">" + esc(red.reward_slug) + "</span>" +
+          "<span class=\"pdp__badge loyalty-tx--" + esc(String(red.status)) + "\">" + esc(String(red.status)) + "</span>" +
+        "</div>" +
+        "<p class=\"return-card__meta\">" + esc(String(red.points_debited)) + " points" +
+          (rdate ? " &middot; <time datetime=\"" + esc(rdate) + "\">" + esc(rdate) + "</time>" : "") +
+          (red.coupon_code ? " &middot; code <code>" + esc(red.coupon_code) + "</code>" : "") +
+        "</p></li>";
+    }
+    redSection = "<h2 class=\"pdp__variants-title\">Your redemptions</h2><ul class=\"return-list\">" + redItems + "</ul>";
+  }
+
+  // Earn/redeem ledger (paginated).
+  var hist = opts.history || [];
+  var histInner = "";
+  for (var h = 0; h < hist.length; h += 1) {
+    var tx = hist[h];
+    var tdate = tx.occurred_at ? new Date(Number(tx.occurred_at)).toISOString().slice(0, 10) : "";
+    var pts = Number(tx.points) || 0;
+    var ptsStr = (pts > 0 ? "+" : "") + pts;
+    histInner +=
+      "<li class=\"return-card\"><div class=\"return-card__head\">" +
+        _loyaltyTxBadge(tx.transaction_type) +
+        "<span class=\"return-card__rma\">" + esc(ptsStr) + " points</span>" +
+      "</div>" +
+      "<p class=\"return-card__meta\">" + esc(String(tx.source || "")) +
+        (tdate ? " &middot; <time datetime=\"" + esc(tdate) + "\">" + esc(tdate) + "</time>" : "") +
+        (tx.notes ? " &middot; " + esc(String(tx.notes)) : "") +
+      "</p></li>";
+  }
+  var historySection;
+  if (histInner) {
+    var more = opts.history_next_cursor != null
+      ? "<p class=\"loyalty-more\"><a class=\"btn-secondary\" href=\"/account/loyalty?cursor=" +
+          esc(String(opts.history_next_cursor)) + "\">Older activity</a></p>"
+      : "";
+    historySection = "<h2 class=\"pdp__variants-title\">Activity</h2><ul class=\"return-list\">" + histInner + "</ul>" + more;
+  } else {
+    historySection = "<h2 class=\"pdp__variants-title\">Activity</h2>" +
+      "<p class=\"return-empty\">No points activity yet. Place an order to start earning.</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\">Rewards</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-returns__title\">Rewards</h1>" +
+      notice +
+      stats +
+      rewardSection +
+      earnSection +
+      redSection +
+      historySection +
+    "</section>";
+
+  return _wrap({
+    title:      "Rewards",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
+// Human-readable funnel stage for a referred friend. The referred
+// email is stored hash-only, so a row never carries an address — the
+// surface shows the stage + dates only.
+var REFERRAL_STAGE_LABELS = {
+  pending:     "Invited",
+  visited:     "Visited",
+  "signed-up": "Joined",
+  converted:   "Converted",
+};
+
+// Initials for a leaderboard row — first letter of each whitespace-
+// separated word in the display name, up to two, uppercased. Falls back
+// to a neutral glyph when the name is empty / whitespace. NEVER renders
+// the full name, the email (which is hash-only anyway), or the customer
+// id — the public-ish leaderboard surface exposes rank + initials only.
+function _referralInitials(displayName) {
+  var s = String(displayName == null ? "" : displayName).trim();
+  if (!s) return "–";
+  var words = s.split(/\s+/);
+  var out = "";
+  for (var i = 0; i < words.length && out.length < 2; i += 1) {
+    var w = words[i];
+    if (w.length) out += w.charAt(0);
+  }
+  return out.toUpperCase() || "–";
+}
+
+// The signed-in customer's referral surface: their personal code +
+// shareable link, the friends they've referred (funnel stage + dates,
+// no PII), the reward funnel summary, and an in-account top-referrer
+// leaderboard (rank + initials only — never names/emails/ids). Reuses
+// the account/returns layout classes — no new CSS.
+function renderReferrals(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+
+  var notice = opts.notice
+    ? "<p class=\"form-notice" + (opts.notice_kind === "error" ? " form-notice--error" : "") + "\" role=\"alert\">" +
+        esc(String(opts.notice)) + "</p>"
+    : "";
+
+  // Code + shareable link. `code`/`link` are null until the customer
+  // mints one (the empty state offers a Create-code button).
+  var code = opts.code || null;
+  var link = opts.link || null;
+  var codeSection;
+  if (code && link) {
+    codeSection =
+      "<dl class=\"account-dash__stats\">" +
+        "<div><dt>Your referral code</dt><dd><code>" + esc(String(code)) + "</code></dd></div>" +
+        "<div><dt>Friends converted</dt><dd>" + esc(String(Number(opts.completed_referrals) || 0)) + "</dd></div>" +
+        "<div><dt>Friends joined</dt><dd>" + esc(String(Number(opts.invitations_signed_up) || 0)) + "</dd></div>" +
+        "<div><dt>Friends invited</dt><dd>" + esc(String(Number(opts.invitations_total) || 0)) + "</dd></div>" +
+      "</dl>" +
+      "<h2 class=\"pdp__variants-title\">Share your link</h2>" +
+      "<p class=\"return-card__meta\">Share this link with friends. Anyone who signs up through it and places their first order is counted here as your referral.</p>" +
+      "<p><a class=\"btn-secondary\" href=\"" + esc(String(link)) + "\">" + esc(String(link)) + "</a></p>";
+  } else {
+    codeSection =
+      "<p class=\"return-empty\">You don't have a referral code yet. Create one to start inviting friends.</p>" +
+      "<form method=\"post\" action=\"/account/referrals/code\">" +
+        "<div class=\"form-actions\"><button type=\"submit\" class=\"btn-primary\">Create my referral code</button></div>" +
+      "</form>";
+  }
+
+  // Friends referred — funnel stage + dates, no identity.
+  var friends = opts.invitations || [];
+  var friendsSection;
+  if (friends.length) {
+    var items = "";
+    for (var i = 0; i < friends.length; i += 1) {
+      var f = friends[i];
+      var stageLabel = REFERRAL_STAGE_LABELS[f.stage] || f.stage || "Invited";
+      var when = f.invited_at ? new Date(Number(f.invited_at)).toISOString().slice(0, 10) : "";
+      var converted = f.first_purchase_at
+        ? new Date(Number(f.first_purchase_at)).toISOString().slice(0, 10)
+        : "";
+      items +=
+        "<li class=\"return-card\"><div class=\"return-card__head\">" +
+          "<span class=\"return-card__rma\">Friend " + esc(String(i + 1)) + "</span>" +
+          "<span class=\"pdp__badge referral-stage--" + esc(String(f.stage || "pending")) + "\">" + esc(stageLabel) + "</span>" +
+        "</div>" +
+        "<p class=\"return-card__meta\">" +
+          (when ? "Invited <time datetime=\"" + esc(when) + "\">" + esc(when) + "</time>" : "") +
+          (converted ? " &middot; converted <time datetime=\"" + esc(converted) + "\">" + esc(converted) + "</time>" : "") +
+        "</p></li>";
+    }
+    friendsSection = "<h2 class=\"pdp__variants-title\">Friends you've referred</h2><ul class=\"return-list\">" + items + "</ul>";
+  } else {
+    friendsSection = "<h2 class=\"pdp__variants-title\">Friends you've referred</h2>" +
+      "<p class=\"return-empty\">No referrals yet. Share your link above to get started.</p>";
+  }
+
+  // In-account leaderboard — rank + initials only. The signed-in
+  // customer's own row is marked "You".
+  var board = opts.leaderboard || [];
+  var boardSection = "";
+  if (board.length) {
+    var rows = "";
+    for (var j = 0; j < board.length; j += 1) {
+      var entry = board[j];
+      var who = entry.is_you ? "You" : _referralInitials(entry.display_name);
+      rows +=
+        "<li class=\"return-card\"><div class=\"return-card__head\">" +
+          "<span class=\"return-card__rma\">#" + esc(String(j + 1)) + " " + esc(who) + "</span>" +
+          "<span class=\"pdp__badge\">" + esc(String(Number(entry.completed_referrals) || 0)) + " referred</span>" +
+        "</div></li>";
+    }
+    boardSection = "<h2 class=\"pdp__variants-title\">Top referrers</h2><ul class=\"return-list\">" + rows + "</ul>";
+  }
+
+  var body =
+    "<section class=\"account-returns\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" +
+        "<li><a href=\"/account\">Account</a></li>" +
+        "<li aria-current=\"page\">Refer a friend</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-returns__title\">Refer a friend</h1>" +
+      notice +
+      codeSection +
+      friendsSection +
+      boardSection +
+    "</section>";
+
+  return _wrap({
+    title:      "Refer a friend",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Subscription status pill — mirrors `_returnStatusBadge`. The status
 // string is one of Stripe's enum values (active, trialing, past_due,
 // canceled, …), surfaced as a CSS-classed badge the theme can style.
@@ -1748,6 +2061,28 @@ var CHECKOUT_PAGE =
   "  </form>\n" +
   "</section>\n";
 
+// Redeem-points-at-checkout field — appended to the checkout form for a
+// signed-in customer with a spendable balance. The customer types how
+// many points to spend; the server caps the credit at the order total
+// and at the balance (the `loyalty_redeem_points` field rides the same
+// POST as the gift-card code). The max attribute is advisory client-
+// side polish; the backend is authoritative.
+function _loyaltyCheckoutField(bal, perUsd) {
+  var esc = b.template.escapeHtml;
+  var points = Number(bal.balance) || 0;
+  var ratio = Number(perUsd) || 100;
+  // Minor-unit value of the full balance (points / ratio dollars), for
+  // the helper line. Floored to a whole point's worth.
+  var worth = pricing.format(Math.floor((points * 100) / ratio), "USD");
+  return "<div class=\"form-row\"><label class=\"form-field\">" +
+    "<span class=\"form-field__label\">Redeem loyalty points <span class=\"small\">(optional)</span></span>" +
+    "<input type=\"number\" name=\"loyalty_redeem_points\" min=\"0\" step=\"1\" max=\"" + points + "\" " +
+    "inputmode=\"numeric\" autocomplete=\"off\" placeholder=\"0\">" +
+    "<span class=\"form-field__req\">You have " + esc(String(points)) + " points (worth " + esc(worth) +
+    ") &middot; " + esc(String(ratio)) + " points = $1</span>" +
+    "</label></div>";
+}
+
 function renderCheckoutForm(opts) {
   if (!opts) throw new TypeError("storefront.renderCheckoutForm: opts required");
   var lines  = opts.lines  || [];
@@ -1764,6 +2099,19 @@ function renderCheckoutForm(opts) {
     });
   }
   var body = _render(CHECKOUT_PAGE, { subtotal: subtotal });
+  // Signed-in customer with a spendable points balance — surface a
+  // redeem-at-checkout field. The block is appended as raw HTML (the
+  // balance + value are numbers we control, the conversion ratio is the
+  // ledger's own constant) so it slots into the existing form via a
+  // small client island that copies the field into the POST. Rendered
+  // only when there's a balance to spend; absent that the checkout is
+  // unchanged for guests + zero-balance customers.
+  if (opts.loyalty_balance && opts.loyalty_balance.balance > 0) {
+    body = body.replace(
+      "</form>",
+      _loyaltyCheckoutField(opts.loyalty_balance, opts.loyalty_points_per_usd) + "</form>",
+    );
+  }
   // When PayPal is configured, append its button below the card form. The
   // block is built as raw HTML (appended after the strict render) so the SDK
   // script + handlers survive; the client-id is the only interpolation and is
@@ -2402,6 +2750,14 @@ var PAY_COOKIE_NAME = "shop_pay";
 // SameSite=Lax so it survives the provider's top-level GET redirect back.
 var OAUTH_COOKIE_NAME = "shop_oauth";
 
+// Short-lived sealed cookie naming the referral code an inbound visitor
+// arrived through (set by the /r/:code landing). Read at account-creation
+// to attribute the new customer to the referrer. Path "/" so it survives
+// the visitor's navigation from the landing to the register / sign-in
+// flow; SameSite=Lax so a top-level GET from a shared link carries it.
+// Sealed so it can't be forged to mis-attribute a signup.
+var REFERRAL_COOKIE_NAME = "shop_ref";
+
 // Shape of a valid session id — mirrors cart.js's SESSION_ID_RE.
 var SID_SHAPE_RE = /^[A-Za-z0-9_-]{16,64}$/;
 
@@ -2471,6 +2827,22 @@ function _readChallengeEnv(req) {
   try { return JSON.parse(raw); } catch (_e) { return null; }
 }
 
+// Referral-attribution cookie. Carries the code the visitor arrived
+// through + when it was set, sealed so it can't be forged. Path "/" so
+// it survives navigation from the landing through register / sign-in.
+function _setReferralCookie(res, env) {
+  var T = b.constants.TIME;
+  _cookieJar().writeSealed(res, REFERRAL_COOKIE_NAME, JSON.stringify(env), { expires: new Date(Date.now() + T.days(30)) });
+}
+function _clearReferralCookie(res) {
+  _cookieJar().clear(res, REFERRAL_COOKIE_NAME);
+}
+function _readReferralEnv(req) {
+  var raw = _cookieJar().readSealed(req, REFERRAL_COOKIE_NAME);
+  if (raw === null) return null;
+  try { return JSON.parse(raw); } catch (_e) { return null; }
+}
+
 // ---- account-page renderers --------------------------------------------
 
 var ACCOUNT_LOGIN_PAGE =
@@ -2569,6 +2941,8 @@ 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/loyalty\">Rewards</a>\n" +
+  "      <a class=\"btn-secondary\" href=\"/account/referrals\">Refer a friend</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/subscriptions\">Subscriptions</a>\n" +
   "      <form method=\"post\" action=\"/account/logout\"><button type=\"submit\" class=\"btn-ghost\">Sign out</button></form>\n" +
   "    </div>\n" +
@@ -2694,6 +3068,20 @@ function mount(router, deps) {
     res.end ? res.end(html) : res.send(html);
   }
 
+  // Defensive request-shape reader for the optional loyalty-points
+  // redeem field on the checkout form. Returns undefined for missing /
+  // empty / zero / non-numeric input (checkout treats undefined as "no
+  // redemption"); a positive integer otherwise. The backend's
+  // _resolveLoyaltyCredit is authoritative on balance + cap — this only
+  // shapes the wire value so a blank field doesn't become a "0 points"
+  // validation error.
+  function _parseRedeemPoints(raw) {
+    if (raw == null || raw === "") return undefined;
+    var n = parseInt(String(raw), 10);
+    if (!Number.isFinite(n) || n <= 0) return undefined;
+    return n;
+  }
+
   // Cart-count read shared across every handler that wraps a page in
   // the layout — the header's cart pill renders the count. Returns 0
   // for visitors with no session cookie. Defined at the top of mount
@@ -2708,6 +3096,23 @@ function mount(router, deps) {
     return lines.length;
   }
 
+  // Absolute shareable referral link for a code. Prefers the operator's
+  // configured origin (deps.shop_origin / SHOP_ORIGIN) so the link is
+  // stable across the edge/container split; falls back to the request's
+  // Host header when no origin is configured (dev / single-host deploys).
+  // The /r/<code> landing is container-served (not an edge route), so it
+  // always reaches this primitive's attribution handler.
+  function _referralLink(req, code) {
+    var origin = deps.shop_origin
+      ? String(deps.shop_origin).replace(/\/$/, "")
+      : null;
+    if (!origin) {
+      var host = (req && req.headers && (req.headers.host || req.headers.Host)) || "";
+      origin = host ? ("https://" + host) : "";
+    }
+    return origin + "/r/" + encodeURIComponent(code);
+  }
+
   // The signed-in customer's sealed-cookie envelope, or null. Shared by
   // the PDP view recorder (mounted outside the `if (deps.customers)`
   // block) and the account routes inside it, so there's one auth-cookie
@@ -3021,7 +3426,23 @@ function mount(router, deps) {
         return res.end ? res.end() : res.send("");
       }
       var totals = pricing.totals(c, lines, {});
-      _send(res, 200, renderCheckoutForm({ lines: lines, totals: totals, shop_name: shopName, theme: theme, paypal_client_id: deps.paypal ? deps.paypal_client_id : null }));
+      // Loyalty balance — only for a signed-in customer with loyalty
+      // wired. A read failure (table not migrated) degrades to no
+      // redeem field rather than 500-ing checkout.
+      var loyaltyBalance = null;
+      if (deps.loyalty) {
+        var loyAuth = _currentCustomerEnv(req);
+        if (loyAuth) {
+          try { loyaltyBalance = await deps.loyalty.balance(loyAuth.customer_id); }
+          catch (_e) { loyaltyBalance = null; }
+        }
+      }
+      _send(res, 200, renderCheckoutForm({
+        lines: lines, totals: totals, shop_name: shopName, theme: theme,
+        paypal_client_id: deps.paypal ? deps.paypal_client_id : null,
+        loyalty_balance: loyaltyBalance,
+        loyalty_points_per_usd: deps.loyalty ? deps.loyalty.REDEMPTION_POINTS_PER_USD : null,
+      }));
     });
 
     router.post("/checkout", async function (req, res) {
@@ -3063,6 +3484,7 @@ function mount(router, deps) {
           selected_shipping_id: defaultShipId || "std",
           customer:             { email: body.email, name: body.name },
           gift_card_code:       body.gift_card_code || undefined,
+          loyalty_redeem_points: _parseRedeemPoints(body.loyalty_redeem_points),
           idempotency_key:      "checkout:" + c.id + ":" + b.uuid.v7(),
         });
         // When a gift card fully covered the order there's no Stripe
@@ -3083,11 +3505,13 @@ function mount(router, deps) {
         res.setHeader && res.setHeader("location", "/pay/" + result.order.id);
         return res.end ? res.end() : res.send("");
       } catch (e) {
-        // A bad customer input (malformed shape OR a gift-card code the
-        // customer typed that can't be applied) is a 400, not a 500 —
-        // the gift-card errors carry a GIFTCARD_* code so a fat-fingered
-        // code re-prompts rather than 500-ing the checkout.
-        var clientErr = (e instanceof TypeError) || (e && typeof e.code === "string" && e.code.indexOf("GIFTCARD_") === 0);
+        // A bad customer input (malformed shape, a gift-card code, or a
+        // loyalty-points request the customer entered that can't be
+        // applied) is a 400, not a 500 — the gift-card errors carry a
+        // GIFTCARD_* code and the loyalty errors a LOYALTY_* code so a
+        // fat-fingered value re-prompts rather than 500-ing checkout.
+        var code = (e && typeof e.code === "string") ? e.code : "";
+        var clientErr = (e instanceof TypeError) || code.indexOf("GIFTCARD_") === 0 || code.indexOf("LOYALTY_") === 0;
         res.status(clientErr ? 400 : 500);
         var msg = (e && e.message) || "checkout failed";
         return res.end ? res.end(msg) : res.send(msg);
@@ -3382,6 +3806,33 @@ function mount(router, deps) {
       return res.end ? res.end(msg) : res.send(msg);
     }
 
+    // Attribute a freshly-created customer to the referrer named in the
+    // sealed referral cookie, then clear the cookie so it can't attribute
+    // a later signup. Guards:
+    //   * no cookie / unknown / disabled code → no-op (silent)
+    //   * self-referral (the code belongs to this customer) → no-op
+    //   * already-attributed (trackSignup pins to the oldest pending
+    //     invitation; a customer with one already pinned won't get a
+    //     second) → no-op
+    // Best-effort: a referrals failure never blocks the signup. Mounts
+    // only when the referrals primitive is wired. The cookie is always
+    // cleared (even on a guarded no-op) so a stale code doesn't linger.
+    async function _attributeReferral(req, res, newCustomerId) {
+      if (!deps.referrals) return;
+      var env = null;
+      try { env = _readReferralEnv(req); } catch (_e) { env = null; }
+      // Clear regardless — one shot per signup.
+      try { _clearReferralCookie(res); } catch (_e) { /* best-effort */ }
+      if (!env || !env.code) return;
+      try {
+        var row = await deps.referrals.byCode(env.code);
+        if (!row || row.status !== "active") return;
+        // Self-referral guard — a customer can't refer themselves.
+        if (row.referrer_customer_id === newCustomerId) return;
+        await deps.referrals.trackSignup({ code: env.code, customer_id: newCustomerId });
+      } catch (_e) { /* drop-silent — attribution is best-effort, signup wins */ }
+    }
+
     function _readJsonBody(req) {
       // b.middleware.bodyParser leaves JSON in req.body when the
       // request's content-type is application/json. Some test
@@ -3444,6 +3895,12 @@ function mount(router, deps) {
           customer_id:    customer.id,
           challenge:      startOpts.challenge,
           created_at:     Date.now(),
+          // Whether THIS begin created the customer (vs reused an existing
+          // row for a known email). register-finish gates referral
+          // attribution on it — an existing customer re-enrolling a passkey
+          // through a referral link must not be attributed to a referrer
+          // (it isn't a new signup), mirroring the OIDC `rv.created` gate.
+          is_new:         !existing,
         });
         res.status(200);
         res.setHeader && res.setHeader("content-type", "application/json");
@@ -3492,6 +3949,18 @@ function mount(router, deps) {
           customer_id: env.customer_id,
           exp:         Date.now() + b.constants.TIME.days(14),
         });
+        // Attribute this signup to a referrer if the visitor arrived
+        // through a /r/<code> link — ONLY for a genuinely new account
+        // (env.is_new, stamped in register-begin). An existing customer
+        // re-enrolling a passkey is not a new signup and must never be
+        // attributed (that would let an existing user mint referral
+        // credit by following their own/a friend's link), matching the
+        // OIDC `rv.created` gate. Best-effort; never blocks the ceremony.
+        if (env.is_new === true) {
+          await _attributeReferral(req, res, env.customer_id);
+        } else {
+          try { _clearReferralCookie(res); } catch (_e) { /* best-effort */ }
+        }
         res.status(200);
         return res.end ? res.end("ok") : res.send("ok");
       } catch (e) {
@@ -3767,6 +4236,14 @@ function mount(router, deps) {
             await deps.order.linkGuestOrdersByEmailHash(rv.customer.id, deps.customers.hashEmail(claims.email));
           } catch (_e) { /* best-effort reconciliation; sign-in succeeds regardless */ }
         }
+        // Attribute a referral ONLY on a genuinely new account
+        // (rv.created) — an existing customer signing in through Google
+        // is not a new signup and must not be attributed to a referrer.
+        if (rv.created === true) {
+          await _attributeReferral(req, res, rv.customer.id);
+        } else {
+          try { _clearReferralCookie(res); } catch (_e) { /* best-effort */ }
+        }
         _setAuthCookie(res, { customer_id: rv.customer.id, exp: Date.now() + b.constants.TIME.days(14) });
         res.status(303); res.setHeader && res.setHeader("location", "/account");
         return res.end ? res.end() : res.send("");
@@ -3873,6 +4350,13 @@ function mount(router, deps) {
             await deps.order.linkGuestOrdersByEmailHash(rv.customer.id, deps.customers.hashEmail(claims.email));
           } catch (_e) { /* best-effort reconciliation; sign-in succeeds regardless */ }
         }
+        // Attribute a referral ONLY on a genuinely new account (rv.created)
+        // — mirrors the Google path.
+        if (rv.created === true) {
+          await _attributeReferral(req, res, rv.customer.id);
+        } else {
+          try { _clearReferralCookie(res); } catch (_e) { /* best-effort */ }
+        }
         _setAuthCookie(res, { customer_id: rv.customer.id, exp: Date.now() + b.constants.TIME.days(14) });
         res.status(303); res.setHeader && res.setHeader("location", "/account");
         return res.end ? res.end() : res.send("");
@@ -4414,6 +4898,285 @@ function mount(router, deps) {
       });
     }
 
+    // Loyalty — the signed-in customer's points balance + tier, the
+    // earn/redeem ledger, how points are earned, and (when a reward
+    // catalog + redemption primitive are wired) a redeem-a-reward
+    // control. Login-gated; a read failure on any optional sub-read
+    // degrades that section to empty rather than 500-ing the page.
+    if (deps.loyalty) {
+      function _loyaltyAuth(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;
+      }
+
+      // Build the full /account/loyalty render context for a customer.
+      // `opts2.cursor` is the optional history-page cursor (epoch-ms).
+      // Each optional read (earn rules, reward catalog, redemptions) is
+      // best-effort so a not-migrated table degrades that panel rather
+      // than the page.
+      async function _loyaltyView(req, auth, opts2) {
+        opts2 = opts2 || {};
+        var bal = await deps.loyalty.balance(auth.customer_id);
+        var hist = await deps.loyalty.history(auth.customer_id, { limit: 20, cursor: opts2.cursor });
+        var rules = [];
+        if (deps.loyaltyEarnRules) {
+          try { rules = await deps.loyaltyEarnRules.listRules({ active_only: true, limit: 50 }); }
+          catch (_e) { rules = []; }
+        }
+        var rewards = [];
+        var redemptions = [];
+        if (deps.loyaltyRedemption) {
+          try { rewards = await deps.loyaltyRedemption.listRewards({ active_only: true, limit: 50 }); }
+          catch (_e) { rewards = []; }
+          try {
+            var rpage = await deps.loyaltyRedemption.redemptionsForCustomer(auth.customer_id, { limit: 20 });
+            redemptions = rpage.rows;
+          } catch (_e) { redemptions = []; }
+        }
+        var cartCount = await _cartCountForReq(req);
+        return {
+          balance:        bal,
+          tiers:          deps.loyalty.TIERS,
+          tier_thresholds: deps.loyalty.TIER_THRESHOLDS,
+          redemption_points_per_usd: deps.loyalty.REDEMPTION_POINTS_PER_USD,
+          history:        hist.rows,
+          history_next_cursor: hist.next_cursor,
+          earn_rules:     rules,
+          rewards:        rewards,
+          redemptions:    redemptions,
+          can_redeem:     !!deps.loyaltyRedemption,
+          notice:         opts2.notice || null,
+          notice_kind:    opts2.notice_kind || null,
+          shop_name:      shopName,
+          cart_count:     cartCount,
+        };
+      }
+
+      router.get("/account/loyalty", async function (req, res) {
+        var auth = _loyaltyAuth(req, res); if (!auth) return;
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var cursorRaw = url && url.searchParams.get("cursor");
+        var cursor;
+        if (cursorRaw != null && cursorRaw !== "") {
+          var n = parseInt(cursorRaw, 10);
+          // A malformed cursor degrades to the first page (the lib
+          // would TypeError on a non-integer) — never 500 the page.
+          cursor = Number.isFinite(n) && n >= 0 ? n : undefined;
+        }
+        var view = await _loyaltyView(req, auth, { cursor: cursor });
+        _send(res, 200, renderLoyalty(view));
+      });
+
+      // Redeem a reward from the catalog. Mounts only when the
+      // redemption primitive is wired. The reward debits points via the
+      // composed loyalty ledger; insufficient balance / cap reached /
+      // not-redeemable surface as a 400 re-render, never a 500.
+      if (deps.loyaltyRedemption) {
+        router.post("/account/loyalty/redeem", async function (req, res) {
+          var auth = _loyaltyAuth(req, res); if (!auth) return;
+          var body = req.body || {};
+          var rewardSlug = body.reward_slug;
+          try {
+            await deps.loyaltyRedemption.redeemForCustomer({
+              customer_id: auth.customer_id,
+              reward_slug: rewardSlug,
+            });
+          } catch (e) {
+            // Customer-facing refusals (TypeError on a bad slug,
+            // LOYALTY_INSUFFICIENT_BALANCE, REWARD_NOT_REDEEMABLE,
+            // REDEMPTION_CAP_REACHED) re-render the page with the
+            // reason; anything else propagates as a 500.
+            var code = (e && typeof e.code === "string") ? e.code : "";
+            var clientErr = (e instanceof TypeError)
+              || code === "LOYALTY_INSUFFICIENT_BALANCE"
+              || code === "REWARD_NOT_REDEEMABLE"
+              || code === "REDEMPTION_CAP_REACHED";
+            if (!clientErr) throw e;
+            var msg;
+            if (code === "LOYALTY_INSUFFICIENT_BALANCE") msg = "You don't have enough points for that reward yet.";
+            else if (code === "REWARD_NOT_REDEEMABLE")   msg = "That reward isn't available right now.";
+            else if (code === "REDEMPTION_CAP_REACHED")  msg = "You've reached the redemption limit for that reward.";
+            else                                          msg = "We couldn't redeem that reward — please pick one from the list.";
+            var failView = await _loyaltyView(req, auth, { notice: msg, notice_kind: "error" });
+            return _send(res, 400, renderLoyalty(failView));
+          }
+          res.status(303); res.setHeader && res.setHeader("location", "/account/loyalty");
+          return res.end ? res.end() : res.send("");
+        });
+      }
+    }
+
+    // Referrals — refer-a-friend. Three surfaces:
+    //   * GET  /r/:code            — the attribution landing. Sets a
+    //     short-lived sealed first-party cookie naming the code, records
+    //     the visit, then 303s home. An unknown / malformed / disabled
+    //     code is silently ignored (no cookie, no error to the visitor).
+    //     Public — no sign-in. The cookie is read at account-creation to
+    //     attribute the new customer to the referrer.
+    //   * GET  /account/referrals — the signed-in customer's own code +
+    //     shareable link, the friends they've referred (funnel stage,
+    //     no PII), and the in-account top-referrer leaderboard.
+    //   * POST /account/referrals/code — mint the customer's code (one
+    //     active code per customer; idempotent on an existing one).
+    // Attribution is FIRST-TOUCH: trackSignup pins the signup to the
+    // oldest pending invitation under the code, and the landing only
+    // overwrites the cookie when none is already set (below), so the
+    // first referral link a visitor follows wins.
+    if (deps.referrals) {
+      function _referralsAuth(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;
+      }
+
+      // The attribution landing. The cookie is path "/" so it survives
+      // the visitor's navigation to the register page, sealed so it
+      // can't be forged to mis-attribute a signup, and short-lived
+      // (30 days) so a stale link doesn't attribute a much-later signup.
+      router.get("/r/:code", async function (req, res) {
+        function _goHome() {
+          res.status(303); res.setHeader && res.setHeader("location", "/");
+          return res.end ? res.end() : res.send("");
+        }
+        var raw = req.params && req.params.code;
+        // Resolve the code to a live row. A bad shape throws TypeError
+        // inside byCode (canonicalization) — swallow it; the visitor
+        // sees a clean redirect home, never an error tied to a guessed
+        // code (no code-existence oracle).
+        var row;
+        try { row = await deps.referrals.byCode(raw); }
+        catch (_e) { row = null; }
+        if (!row || row.status !== "active") return _goHome();
+        // First-touch: don't overwrite an existing referral cookie — the
+        // first link the visitor followed keeps the attribution.
+        var existing = null;
+        try { existing = _readReferralEnv(req); } catch (_e) { existing = null; }
+        if (!existing || !existing.code) {
+          _setReferralCookie(res, { code: row.code, set_at: Date.now() });
+        }
+        // Record the visit on the funnel (best-effort — a tracking
+        // failure must not block the redirect).
+        try { await deps.referrals.trackVisit({ code: row.code }); }
+        catch (_e) { /* drop-silent — the visit stat is non-critical */ }
+        return _goHome();
+      });
+
+      // Build the /account/referrals render context. Each read is
+      // best-effort so a not-migrated dependency degrades that panel
+      // rather than 500-ing the page.
+      async function _referralsView(req, auth, opts2) {
+        opts2 = opts2 || {};
+        var code = null, link = null;
+        var stats = null;
+        try { stats = await deps.referrals.statsForReferrer(auth.customer_id); }
+        catch (_e) { stats = null; }
+        if (stats && stats.codes && stats.codes.length) {
+          // Surface ONLY an active code — the one /r/<code> will honor.
+          // If every code is disabled, leave code/link null so the page
+          // shows the "create a code" state rather than prompting the
+          // customer to share a dead link they can't replace.
+          var active = null;
+          for (var i = 0; i < stats.codes.length; i += 1) {
+            if (stats.codes[i].status === "active") { active = stats.codes[i]; break; }
+          }
+          if (active) {
+            code = active.code;
+            link = _referralLink(req, active.code);
+          }
+        }
+        var invitations = [];
+        try { invitations = await deps.referrals.invitationsForReferrer(auth.customer_id); }
+        catch (_e) { invitations = []; }
+        var leaderboard = [];
+        if (deps.referralLeaderboard) {
+          try {
+            // Lifetime top referrers. The referrals primitive's own
+            // leaderboard returns { referrer_customer_id, completed }; we
+            // resolve each to initials for display (rank + initials only,
+            // never names/emails/ids), and mark the signed-in customer.
+            var top = await deps.referrals.leaderboard({ limit: 10 });
+            for (var k = 0; k < top.length; k += 1) {
+              var rid = top[k].referrer_customer_id;
+              var dn = "";
+              try {
+                var cust = await deps.customers.get(rid);
+                dn = (cust && cust.display_name) || "";
+              } catch (_e) { dn = ""; }
+              leaderboard.push({
+                completed_referrals: top[k].completed_referrals,
+                display_name:        dn,
+                is_you:              rid === auth.customer_id,
+              });
+            }
+          } catch (_e) { leaderboard = []; }
+        }
+        var cartCount = await _cartCountForReq(req);
+        return {
+          code:                  code,
+          link:                  link,
+          invitations:           invitations,
+          leaderboard:           leaderboard,
+          completed_referrals:   stats ? stats.completed_referrals : 0,
+          invitations_total:     stats ? stats.invitations_total : 0,
+          invitations_signed_up: stats ? stats.invitations_signed_up : 0,
+          notice:                opts2.notice || null,
+          notice_kind:           opts2.notice_kind || null,
+          shop_name:             shopName,
+          cart_count:            cartCount,
+        };
+      }
+
+      router.get("/account/referrals", async function (req, res) {
+        var auth = _referralsAuth(req, res); if (!auth) return;
+        var view = await _referralsView(req, auth, {});
+        _send(res, 200, renderReferrals(view));
+      });
+
+      router.post("/account/referrals/code", async function (req, res) {
+        var auth = _referralsAuth(req, res); if (!auth) return;
+        try {
+          await deps.referrals.issueCode({ referrer_customer_id: auth.customer_id });
+        } catch (e) {
+          // An existing active code is the idempotent happy path — the
+          // customer already has one, so just show the page. Any other
+          // refusal re-renders with a generic notice; never a 500 for a
+          // TypeError on the (cookie-derived) customer id.
+          var code = (e && typeof e.code === "string") ? e.code : "";
+          if (code !== "REFERRAL_CODE_ALREADY_ACTIVE" && !(e instanceof TypeError)) {
+            throw e;
+          }
+          if (code !== "REFERRAL_CODE_ALREADY_ACTIVE") {
+            var failView = await _referralsView(req, auth, {
+              notice: "We couldn't create your referral code — please try again.",
+              notice_kind: "error",
+            });
+            return _send(res, 400, renderReferrals(failView));
+          }
+        }
+        res.status(303); res.setHeader && res.setHeader("location", "/account/referrals");
+        return res.end ? res.end() : res.send("");
+      });
+    }
+
     // Recently viewed — the signed-in customer's newest-first browse
     // history. Views are recorded server-side on the (container-rendered)
     // PDP; this surface lets the customer review + clear that history.