@blamejs/blamejs-shop 0.1.27 → 0.1.28

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- v0.1.28 (2026-05-25) — **Refer-a-friend goes live — a shareable link, attributed signups, and conversions recorded when a referred friend's first order is paid.** The referrals ledger now has a customer-facing surface. A new /account/referrals page gives the signed-in customer a personal referral code, an absolute shareable link, the list of friends they've referred with each one's funnel stage, and an in-account top-referrer leaderboard. A new /r/<code> landing captures an inbound referral: it sets a short-lived sealed first-party cookie naming the code and sends the visitor home. When that visitor creates an account — by passkey, Google, or Apple — the new customer is attributed to the referrer, first-touch, with a self-referral guard so a code can never refer its own owner. When a referred customer's first order reaches paid, the order primitive marks that referral converted and bumps the referrer's count (the leaderboard key) — automatically, off the request path, and recorded once per order so a re-delivered payment webhook can't double-count. Issuing the actual reward (a gift card, store credit, or loyalty points — operator's choice) stays an explicit operator action through the referrals reward API, so the payout instrument and any fraud review are the operator's to control. **Added:** *Customer referrals page at /account/referrals* — A login-gated page showing the customer's referral code and an absolute shareable link (derived from the configured shop origin, falling back to the request host), the count of friends invited / joined / converted, the list of referred friends with each one's funnel stage (invited → visited → joined → converted) and dates, and an in-account top-referrer leaderboard. The friend list carries no personal data — referred emails are stored hash-only — and the leaderboard shows rank plus initials only, never names, emails, or account ids, with the signed-in customer's own row marked "You". Linked from the account dashboard as "Refer a friend". A customer with no code yet sees a one-click create control; a customer with one already gets the same page (creating is idempotent). · *Referral attribution landing at /r/<code>* — A public landing that captures an inbound referral: it sets a short-lived (30-day) sealed, first-party cookie naming the code, records the visit, and redirects the visitor to the home page. Attribution is first-touch — the first referral link a visitor follows wins, and a later link doesn't overwrite it. An unknown, malformed, or disabled code is silently ignored: the visitor still lands on the home page with no error and no cookie, so the route is never a code-existence oracle. · *Signups attributed to the referrer* — When a visitor who arrived through a referral link creates an account — passkey, Sign in with Google, or Sign in with Apple — the new customer is attributed to the referrer named in the referral cookie. A self-referral (the code belongs to the new account) is refused, a customer is attributed only once, and an existing customer signing in through Google or Apple is never attributed (only a genuinely new account is). Attribution is best-effort and never blocks account creation; the referral cookie is cleared after one signup so a stale link can't attribute a later one. · *Referral conversion recorded when a referred friend's first order is paid* — When a referred customer's first order reaches paid, the order primitive marks that referral converted and bumps the referrer's referral count (the leaderboard key). The update rides every paid path (card, wallet, PayPal, gift-card-covered), runs fire-and-forget off the request path, and is recorded once per order so a re-delivered payment webhook collapses onto a single conversion. Only orders carrying a customer account qualify; a guest order records nothing, and a customer's second and later orders don't re-trigger it. Issuing the payout itself — a gift card, store credit, or loyalty points — is a separate operator action through the referrals reward API, so the operator controls the reward instrument and can review before paying out.
+
 - v0.1.27 (2026-05-25) — **Loyalty rewards go live — points earned on purchase, viewed in the account, and redeemed at checkout.** The loyalty points ledger now has a customer-facing surface. A new /account/loyalty page shows the signed-in customer's balance, tier, and earn/redeem activity, explains how points are earned, and lists the reward catalog with a one-click redeem. Paid orders award points automatically: the order primitive fans its paid transition into the earn rules (per-dollar-spent + per-order), fire-and-forget and deduplicated so a re-delivered payment webhook never double-credits. At checkout, a signed-in customer can spend points for a storefront credit against the order total — capped at the order's value and the balance, recorded once, with the same atomic double-spend guard the gift-card credit uses. **Added:** *Customer rewards page at /account/loyalty* — A login-gated page showing the points balance, current tier, lifetime points, and the cash value of the balance; how points are earned (the active earn rules in plain language); the reward catalog with a Redeem control per reward (disabled when the balance is short); the customer's past redemptions; and the earn/redeem ledger, paginated newest-first. Linked from the account dashboard as "Rewards". A redeem that the customer can't complete (not enough points, reward unavailable, per-customer limit reached) re-renders the page with the reason rather than erroring; a malformed history cursor degrades to the first page. · *Points earned automatically on paid orders* — When an order reaches paid, the configured earn rules award points to the customer's balance — per dollar of order subtotal and a flat per-order bonus, whichever rules the operator has defined. The award rides the order's paid transition (so every paid path — card, PayPal, gift-card-covered, admin — earns), runs fire-and-forget off the request path, and is keyed to the order so a re-delivered payment webhook collapses onto a single award instead of double-crediting. Guest orders (no customer account) earn nothing, by design. · *Redeem points at checkout as a credit* — A signed-in customer with a balance sees a "Redeem loyalty points" field on the checkout form. The points are valued via the ledger's redemption ratio (100 points = $1 by default), capped at the order total so the credit never exceeds what the order is worth, and the credit reduces the amount due. The order still records the full grand total it owed; the points are debited once, after the order row exists, behind the same balance-guarded SQL decrement that prevents a double-spend. Points worth more than the order spend only what the granted credit is worth — the surplus stays in the balance. A request for more points than the balance, or from a guest cart, is refused with a clean re-prompt. A points credit stacks with a gift-card credit; together they can pay an order in full with no card charge.
 
 - v0.1.26 (2026-05-25) — **Fix the container build gate that rejected a manifest absent from the image.** The asset-integrity drift gate added last release checked both the container and edge copies of the manifest. The container image excludes the edge worker directory from its build context, so when the gate runs inside the image build it can't see the worker copy and read it as empty — failing the build. The gate now skips a manifest that isn't present in the current build context; its drift is still caught wherever the file exists (the full-tree CI run checks both). **Fixed:** *Asset-manifest drift gate no longer fails the container build* — `generate-asset-manifest.js --check` compared both manifest copies (`lib/` for the container, `worker/` for the edge) against a fresh rebuild. The container image's build context excludes the `worker/` tree, so inside the image the worker copy is absent and the gate read it as empty — reporting false drift and failing `node test/smoke.js`, which is a build gate, so the container image never built. The check now treats a manifest that isn't present in the current context as not-applicable and skips it (requiring at least one copy to be present), so the same drift detection still runs in CI and at the edge build where both files exist, without breaking the container image build.

package/README.md

@@ -69,6 +69,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/addresses.js`** | Per-customer address book at `/account/addresses` — add / edit / set default shipping or billing / remove. One-default-per-role invariant (promoting clears the prior). Every by-id route confirms the address belongs to the signed-in customer before acting (a guessed id returns 404). `b.guardUuid` ids, 2-char ISO country. |
 | **`lib/returns.js`** | Self-serve RMAs. Customer requests a return against their own order at `/account/orders/:id/return` (items + reason, ownership-checked, lines built from the order's own records) and tracks status at `/account/returns`. Operators work `/admin/returns` — approve (refund amount) / mark received / refund / reject — over the pending → approved → received → refunded FSM; illegal transitions are 409, bad ids 404. |
 | **`lib/loyalty.js`** + **`lib/loyalty-earn-rules.js`** + **`lib/loyalty-redemption.js`** | Customer rewards. `loyalty` owns the points balance, lifetime total, tier (bronze → platinum on operator-tunable thresholds), and an audited transaction ledger. `loyalty-earn-rules` defines how points are minted (per-dollar-spent, per-order, signup, birthday, …) keyed to lifecycle events; `loyalty-redemption` is the reward catalog customers spend points against. Customers see all of it at `/account/loyalty` — balance + tier, the earn rules in plain language, the reward catalog with a one-click Redeem, past redemptions, and the paginated earn/redeem ledger (login-gated). Paid orders award points automatically: the order FSM's paid transition fans out to the earn rules fire-and-forget, deduped on the order id so a re-delivered payment webhook never double-credits. At checkout a signed-in customer can spend points for a credit against the order total — valued by the redemption ratio (100 points = $1 default), capped at the order's worth and the balance, debited once behind a balance-guarded SQL decrement, stacking with any gift-card credit; surplus points stay in the balance. |
+| **`lib/referrals.js`** + **`lib/referral-leaderboard.js`** | Refer-a-friend with two-sided rewards. `referrals` issues each customer an 8-character code (32-glyph confusion-resistant alphabet via `b.crypto.generateBytes`) and tracks each referred friend through the funnel (invited → visited → joined → converted); referred emails are stored hash-only (`b.crypto.namespaceHash`), never plaintext. `referral-leaderboard` sits on top for top-referrer rankings + operator-tunable tier bonuses. Customers see all of it at `/account/referrals` — their code, an absolute shareable link, the friends they've referred (funnel stage + dates, no personal data), and an in-account leaderboard (rank + initials only). A public `/r/<code>` landing captures an inbound referral into a short-lived sealed first-party cookie (first-touch), which attributes the new customer to the referrer when they sign up by passkey / Google / Apple — self-referral and double-attribution guarded. When a referred customer's first order reaches paid, the order FSM's paid transition marks that referral converted and bumps the referrer's count fire-and-forget, deduped on the order id so a re-delivered webhook never double-counts; guest orders and a customer's later orders don't qualify. Issuing the payout itself (gift card / store credit / loyalty points) is an explicit operator action via the referrals reward API, so the reward instrument and any fraud review stay the operator's. |
 | **`lib/recently-viewed.js`** | Signed-in customer browse history. A product-page visit records the view server-side against the customer's account (drop-silent — never blocks the page); `/account/recently-viewed` lists them newest-first as a grid with a Clear-history control. De-duped + capped per customer, archived products drop out, login-gated. Guest/session history is opt-in (a client beacon) and not shipped — the lib's `forSession` + `merge` support it. |
 | **`lib/recommendations.js`** | Product-recommendation engine. Operator-curated override pins first (`setOverride` — "when viewing A, show B", kind-scoped + weight-ordered), then a signal-based fallback: co-purchase (products bought in the same orders), category-popular, and in-stock-random filler. `recommendForProduct` / `recommendForCart` / `recommendForCustomer` / `recommendForCategory` each return renderable picks (active + in-stock, source product excluded). The order confirmation page (`/orders/:id`) renders a "Customers also bought" rail from it — best-effort, anchored on the order's items, excluding what was just bought. |
 | **`lib/collections.js`** | Curated + smart product groupings. `GET /collections` lists the shop's active collections; `GET /collections/:slug` renders the grid — manual collections list hand-picked members, smart collections evaluate stored rules against the active catalog and apply the collection's sort strategy. Each product resolves fresh, so archived products drop out. Public, no sign-in; a bad or unknown slug is a 404 (never a 500). Linked from the footer on every page. |
@@ -106,6 +107,8 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 - `migrations-d1/0022_loyalty.sql` — loyalty accounts (balance + lifetime + tier) + audited points transactions
 - `migrations-d1/0085_loyalty_redemptions.sql` — reward catalog + per-redemption records (FSM: active → consumed / expired / cancelled)
 - `migrations-d1/0163_loyalty_earn_rules.sql` — per-event earn rules + dedup-keyed award log
+- `migrations-d1/0025_referrals.sql` — referral codes (one active per customer) + invitation funnel (hash-only referred email)
+- `migrations-d1/0182_referral_leaderboard.sql` — referral tier thresholds (singleton config) + tiered-bonus payout log
 
 ### Demo seed
 

package/SECURITY.md

@@ -174,3 +174,18 @@ node -e "
   the order total and the live balance (a request for more than either
   is refused, not silently clamped to a windfall), and a guest cart
   with no account can't redeem at all.
+- **Referral rewards are fraud-guarded — no self-referral, no
+  double-attribution, no double-reward.** The `/r/<code>` landing only
+  sets the attribution cookie for a live, active code and never reveals
+  whether a guessed code exists (unknown / malformed / disabled all
+  redirect home identically). A new account is attributed to the
+  referrer named in the sealed cookie, with a self-referral guard so a
+  code can never refer its own owner, and each customer is attributed
+  only once (first-touch); an existing customer signing back in is never
+  re-attributed. The reward fires only when a referred customer's first
+  order reaches paid, rides the order's paid transition fire-and-forget,
+  and is recorded once per order so a re-delivered payment webhook can't
+  double-reward — guest orders and later orders don't qualify. Referred
+  emails are stored hash-only (`b.crypto.namespaceHash`), and the
+  account leaderboard exposes rank plus initials only, never an email or
+  account id.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.27",
+  "version": "0.1.28",
   "assets": {
     "css/admin.css": "sha384-rvjL1QySBgNJGEUDusbbMCkL3fsjmzcwUvTp9pljo/0Nn/lErxq2AbY8EYvDF9Ch",
     "css/main.css": "sha384-qBY97FWZDGOploZRppwrDi0A/+R4R3iCFtyS1dfrAlqHNEPluPmY0R3HB9cJntyV",

package/lib/order.js

@@ -150,6 +150,18 @@ function create(opts) {
   // transition has already persisted, so a loyalty read/write must not
   // add latency to (or fail) the order transition.
   var loyaltyEarnRules = opts.loyaltyEarnRules || null;
+  // Optional referrals dispatcher — when present, an order reaching
+  // `paid` records the buyer's first qualifying purchase against any
+  // referral invitation pinned to their account, which completes the
+  // referrer's funnel (bumps referrals_count → the leaderboard). Opt-in
+  // like `webhooks` / `loyaltyEarnRules` so callers and the test suite
+  // run without standing up a referrals primitive. `trackPurchase` is
+  // idempotent (first_purchase_at is set only once) and a no-op when the
+  // buyer was never referred, so a re-delivered mark_paid can't double-
+  // reward and an organic purchase is silently skipped. The award runs
+  // fire-and-forget on the same detached-promise discipline as the
+  // loyalty fan-out: the transition has already persisted.
+  var referrals = opts.referrals || null;
   // Pagination cursors for listForCustomer are HMAC-tagged via
   // b.pagination so an operator can't hand-craft one to skip past a
   // hidden order or replay across deployments. The secret defaults
@@ -348,6 +360,24 @@ function create(opts) {
           });
         }).catch(function () { /* drop-silent — loyalty ledger holds its own audit trail */ });
       }
+      // Referral reward-on-first-order fan-out — fire-and-forget, same
+      // discipline as the loyalty block. Only on the paid transition and
+      // only for an order carrying a customer_id (a guest order has no
+      // account to attribute). trackPurchase pins the buyer's FIRST
+      // qualifying purchase to the invitation that referred them and
+      // completes the referrer's funnel; it is idempotent (first_purchase_at
+      // is written once) so a re-delivered mark_paid never double-rewards,
+      // and it is a no-op for a buyer who was never referred. The promise
+      // is detached so a referrals failure lives in its own tables, never
+      // as an unhandledRejection and never on the transition's latency.
+      if (referrals && typeof referrals.trackPurchase === "function"
+          && result.to === "paid" && refreshed && refreshed.customer_id) {
+        var _refCustomer = refreshed.customer_id;
+        var _refOrderId  = refreshed.id;
+        Promise.resolve().then(function () {
+          return referrals.trackPurchase({ customer_id: _refCustomer, order_id: _refOrderId });
+        }).catch(function () { /* drop-silent — referral funnel holds its own audit trail */ });
+      }
       return refreshed;
     },
 

package/lib/referrals.js

@@ -602,6 +602,50 @@ function create(opts) {
       };
     },
 
+    // Per-friend funnel rows for one referrer, across every code they
+    // hold, newest invitation first. Powers the account page's "friends
+    // you've referred" list. No PII crosses this boundary — the referred
+    // email is stored hash-only, so a row carries only the funnel
+    // timestamps + the reward_status, never an address. `signed_up_at`
+    // / `first_purchase_at` being non-null is what the surface renders
+    // as "joined" / "converted"; `pending` is invited-but-not-converted.
+    invitationsForReferrer: async function (customerId) {
+      var id = _uuid(customerId, "customer_id");
+      var r = await query(
+        "SELECT i.id AS id, i.referral_code_id AS referral_code_id, " +
+        "i.invited_at AS invited_at, i.visited_at AS visited_at, " +
+        "i.signed_up_at AS signed_up_at, i.first_purchase_at AS first_purchase_at, " +
+        "i.reward_status AS reward_status " +
+        "FROM referral_invitations i " +
+        "JOIN referral_codes c ON c.id = i.referral_code_id " +
+        "WHERE c.referrer_customer_id = ?1 " +
+        "ORDER BY i.invited_at DESC, i.id DESC",
+        [id],
+      );
+      return r.rows.map(function (row) {
+        var visited   = row.visited_at        != null;
+        var signedUp  = row.signed_up_at      != null;
+        var converted = row.first_purchase_at != null;
+        // Coarse funnel stage the surface renders. Converted wins over
+        // signed-up wins over visited wins over invited — the furthest
+        // the friend reached.
+        var stage = converted ? "converted"
+                  : signedUp  ? "signed-up"
+                  : visited   ? "visited"
+                  : "pending";
+        return {
+          id:                row.id,
+          referral_code_id:  row.referral_code_id,
+          invited_at:        Number(row.invited_at || 0),
+          visited_at:        row.visited_at        != null ? Number(row.visited_at) : null,
+          signed_up_at:      row.signed_up_at      != null ? Number(row.signed_up_at) : null,
+          first_purchase_at: row.first_purchase_at != null ? Number(row.first_purchase_at) : null,
+          reward_status:     row.reward_status,
+          stage:             stage,
+        };
+      });
+    },
+
     // Top-N referrers by completed referrals (referrals_count is the
     // funnel-complete counter; signups without a first purchase don't
     // count). Defaults to 10; capped at 100 so an operator can't

package/lib/storefront.js

@@ -1593,6 +1593,139 @@ function renderLoyalty(opts) {
   });
 }
 
+// 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.
@@ -2617,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}$/;
 
@@ -2686,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 =
@@ -2785,6 +2942,7 @@ var ACCOUNT_DASH_PAGE =
   "      <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" +
@@ -2938,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
@@ -3631,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
@@ -3693,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");
@@ -3741,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) {
@@ -4016,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("");
@@ -4122,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("");
@@ -4781,6 +5016,167 @@ function mount(router, deps) {
       }
     }
 
+    // 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {