@blamejs/blamejs-shop 0.1.26 → 0.1.27

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- 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.
 
 - v0.1.25 (2026-05-25) — **Asset integrity and the cache-buster are correct in production now.** The renderers stamped a Subresource Integrity digest and a `?v=` cache-buster onto the theme stylesheet and island scripts by hashing the files at render time — which silently produced nothing in production, where the container image doesn't ship the theme files and the edge has no filesystem to read them. So the integrity attribute was absent live and edge-rendered pages pinned a `0.0.0` version that never changed between releases (a stylesheet update would render against a browser-cached copy). Both now come from a manifest built at release time and read directly by both runtimes. **Fixed:** *Subresource Integrity now applied on server-rendered pages* — The `integrity="sha384-…"` attribute on the default theme's stylesheet and island scripts was computed by reading the asset off disk during the render. That read fails in the deployed container (its image carries the code, not the `themes/` tree) and at the edge (no filesystem), so the attribute was silently dropped — the tamper-evidence it's meant to provide wasn't active. The digests are now computed once at release time into `lib/asset-manifest.json` (bundled for both the container and the edge worker) and read from there, so the browser actually verifies the served bytes against the pinned hash. · *Edge-rendered pages no longer pin a 0.0.0 cache-buster* — Pages rendered at the edge (home, product, search, the empty cart, blog) appended `?v=0.0.0` to the stylesheet URL because the worker had no release version to stamp — so the cache-buster never changed across deploys and a browser could keep serving an old stylesheet after a CSS update (markup against stale styling). The version now comes from the release manifest, so each release invalidates the cached asset as intended. The drift between the manifest and the on-disk assets is caught by a smoke gate (`generate-asset-manifest.js --check`).

package/README.md

@@ -68,6 +68,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/save-for-later.js`** | Per-customer cart holding list. Each cart line gets a login-gated "Save for later" control (`POST /cart/lines/:id/save` → `moveFromCart`); `/account/saved` lists items with Move-to-cart / Remove. `moveToCart` reprices to the current catalog price and stock-gates (out-of-stock + non-backorderable is refused). Composes `catalog.inventory` + `catalog.prices` + `catalog.variants`. |
 | **`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/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. |
@@ -102,6 +103,9 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 - `migrations-d1/0043_collections.sql` — manual + smart product collections (members + rules + sort strategy)
 - `migrations-d1/0050_recently_viewed.sql` — per-customer / per-session product browse history (dedup + per-subject cap)
 - `migrations-d1/0105_recommendations.sql` — operator-curated recommendation overrides (kind-scoped, weight-ordered)
+- `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
 
 ### Demo seed
 

package/SECURITY.md

@@ -160,3 +160,17 @@ node -e "
   Redemption decrements with an atomic `balance >= amount` SQL guard
   keyed on the order id, so concurrent or replayed checkouts can never
   overdraw a card or apply more than the remaining balance.
+- **Loyalty points are account-scoped money — earned and spent under
+  the same double-spend discipline.** The `/account/loyalty` page and
+  the redeem actions are login-gated and read the customer id from the
+  sealed session cookie, never from request input, so a customer only
+  ever sees and spends their own balance. Points earned on a paid order
+  are awarded fire-and-forget off the request path and deduped on the
+  order id (`loyalty_earn_log`'s `(rule, customer, event-ref)` UNIQUE),
+  so a re-delivered payment webhook can't double-credit. Spending points
+  — redeeming a reward or applying a checkout credit — debits through
+  the same atomic `balance >= points` SQL guard, so concurrent or
+  replayed requests can't overdraw. A checkout credit is capped at both
+  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.

package/lib/asset-manifest.json

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

package/lib/checkout.js

@@ -112,6 +112,15 @@ function create(deps) {
   // either is absent — the rest of the flow is unchanged.
   var giftcards     = deps.giftcards || null;
   var giftCardLedger = deps.giftCardLedger || null;
+  // Optional loyalty points credit. When wired, a signed-in customer
+  // can spend points at checkout for a storefront credit against the
+  // grand total. `loyalty.balance` reads the spendable balance;
+  // `loyalty.redeem` is the atomic debit (its `balance >= ?` SQL guard
+  // is the authoritative double-spend defense). The redemption value is
+  // derived from the ledger's own `REDEMPTION_POINTS_PER_USD` ratio so
+  // checkout never re-derives the conversion constant. Disabled when
+  // the handle is absent — the rest of the flow is unchanged.
+  var loyalty       = deps.loyalty || null;
 
   // Validate a gift-card code against a priced quote: the card exists,
   // is active, not expired, and matches the order currency. Returns
@@ -194,6 +203,82 @@ function create(deps) {
     return redemption;
   }
 
+  // Resolve an optional loyalty points credit against a priced quote.
+  // `points` is the number of points the customer asked to spend;
+  // `customerId` is the signed-in customer's UUID (a guest cart has
+  // none — loyalty redemption needs an account, so a points request on
+  // a guest order is refused). Returns the credit to apply (the points
+  // converted to minor units via the ledger's redemption ratio, then
+  // capped at the grand total so a customer can't redeem more value
+  // than the order is worth) plus the integer points that credit
+  // actually consumes. Throws a structured (non-TypeError) error on a
+  // request that can't be honored so callers surface a clean re-prompt;
+  // returns null when no points were requested or loyalty isn't wired.
+  //
+  // Capping in points-space (not minor-units) matters: redeeming 250
+  // points worth $2.50 against a $1.00 order should debit only the 100
+  // points the $1.00 credit consumes, leaving the remaining 150 points
+  // in the balance — never silently burning the surplus.
+  async function _resolveLoyaltyCredit(points, customerId, quote) {
+    if (points == null) return null;
+    if (!Number.isInteger(points) || points <= 0) {
+      var bad = new Error("checkout: loyalty_redeem_points must be a positive integer");
+      bad.code = "LOYALTY_REDEEM_INVALID";
+      throw bad;
+    }
+    if (!loyalty) {
+      var unwired = new Error("checkout: loyalty redemption is not configured");
+      unwired.code = "LOYALTY_NOT_CONFIGURED";
+      throw unwired;
+    }
+    if (!customerId) {
+      var guest = new Error("checkout: sign in to redeem loyalty points");
+      guest.code = "LOYALTY_REQUIRES_ACCOUNT";
+      throw guest;
+    }
+    var perUsd = loyalty.REDEMPTION_POINTS_PER_USD;
+    var bal = await loyalty.balance(customerId);
+    if (bal.balance < points) {
+      var insuff = new Error("checkout: loyalty balance is " + bal.balance + ", cannot redeem " + points);
+      insuff.code = "LOYALTY_INSUFFICIENT_BALANCE";
+      throw insuff;
+    }
+    // Value the requested points in minor units, then cap at the grand
+    // total. The applied minor-units are floored to a whole point's
+    // worth so the points actually debited map exactly to the credit
+    // granted (no fractional-point credit).
+    var grand = quote.totals.grand_total_minor;
+    var requestedMinor = Math.floor((points * 100) / perUsd);
+    var appliedMinor = requestedMinor < grand ? requestedMinor : grand;
+    if (appliedMinor <= 0) {
+      var tooFew = new Error("checkout: " + points + " points is worth less than the minimum redeemable credit");
+      tooFew.code = "LOYALTY_REDEEM_TOO_SMALL";
+      throw tooFew;
+    }
+    // Points the applied credit actually consumes — re-derived from the
+    // capped minor-units so a partial cap only spends the points the
+    // granted credit is worth.
+    var spentPoints = Math.ceil((appliedMinor * perUsd) / 100);
+    if (spentPoints > points) spentPoints = points;          // floor/ceil guard — never spend more than asked
+    return { points: spentPoints, applied_minor: appliedMinor };
+  }
+
+  // Burn the resolved loyalty credit against the created order. The
+  // `loyalty.redeem` decrement is the authoritative double-spend guard
+  // (its `balance_points >= ?` SQL predicate refuses an overdraw), and
+  // the `order_id` link records the redemption against the order in the
+  // loyalty audit trail. Called once per order, after the order row
+  // exists, so points are never spent for an order that failed to
+  // create.
+  async function _redeemLoyalty(resolved, customerId, orderId) {
+    await loyalty.redeem({
+      customer_id: customerId,
+      points:      resolved.points,
+      order_id:    orderId,
+      notes:       "checkout-credit:" + orderId,
+    });
+  }
+
   // Compose a quote from a cart + ship-to + (optional) selected
   // shipping service. Pure read — no DB writes.
   async function _buildQuote(input) {
@@ -292,7 +377,27 @@ function create(deps) {
       // credit reduces the amount due; the order still records the
       // full grand total it owed.
       var gc = await _resolveGiftCard(input.gift_card_code, quote);
-      var amountDue = quote.totals.grand_total_minor - (gc ? gc.applied_minor : 0);
+      // Loyalty points credit stacks on top of any gift-card credit —
+      // both reduce the same amount due. The loyalty credit is capped
+      // at the grand total inside the resolver, but since the gift card
+      // may already cover part of the order, cap the loyalty credit
+      // again at what's still due so the two credits together never
+      // drive the amount due below zero.
+      var cartRowForCustomer = await cart.get(quote.cart_id);
+      var loyaltyCustomerId = cartRowForCustomer ? (cartRowForCustomer.customer_id || null) : null;
+      var loy = await _resolveLoyaltyCredit(input.loyalty_redeem_points, loyaltyCustomerId, quote);
+      var afterGiftCard = quote.totals.grand_total_minor - (gc ? gc.applied_minor : 0);
+      if (loy && loy.applied_minor > afterGiftCard) {
+        // The gift card already covers more of the order than the
+        // points were valued against — re-cap the points credit to the
+        // residual so the two never overlap. Re-derive the spent points
+        // from the smaller credit so surplus points stay in the balance.
+        loy.applied_minor = afterGiftCard < 0 ? 0 : afterGiftCard;
+        var perUsd = loyalty.REDEMPTION_POINTS_PER_USD;
+        loy.points = Math.ceil((loy.applied_minor * perUsd) / 100);
+        if (loy.applied_minor <= 0) loy = null;
+      }
+      var amountDue = afterGiftCard - (loy ? loy.applied_minor : 0);
 
       var orderLines = quote.lines.map(function (l) {
         return {
@@ -303,15 +408,17 @@ function create(deps) {
           unit_currency:     l.unit_currency,
         };
       });
-      var cartRow = await cart.get(quote.cart_id);
+      // Reuse the cart row already fetched for the loyalty
+      // customer-id lookup above — one read, not two.
+      var cartRow = cartRowForCustomer;
       // Hash of the buyer email (same key as the customers table) so a
       // later verified-email sign-in can claim this guest order.
       var emailHash = customers ? customers.hashEmail(email) : null;
 
-      // Zero amount due — the gift card fully covers the order. No
-      // PaymentIntent (Stripe refuses a zero-amount intent); create
-      // the order, burn the card against it, and advance it straight
-      // to paid via the FSM.
+      // Zero amount due — gift-card + loyalty credit fully cover the
+      // order. No PaymentIntent (Stripe refuses a zero-amount intent);
+      // create the order, burn the credits against it, and advance it
+      // straight to paid via the FSM.
       if (amountDue === 0) {
         var paidOrder = await order.createFromCart({
           cart_id:            quote.cart_id,
@@ -328,15 +435,17 @@ function create(deps) {
           customer_email_hash: emailHash,
           lines:             orderLines,
         });
-        await _redeemGiftCard(gc, paidOrder.id);
+        if (gc) await _redeemGiftCard(gc, paidOrder.id);
+        if (loy) await _redeemLoyalty(loy, loyaltyCustomerId, paidOrder.id);
         await cart.setStatus(quote.cart_id, "converted");
         var settled = await order.transition(paidOrder.id, "mark_paid", {
-          reason: "gift_card:full",
+          reason: loy && !gc ? "loyalty:full" : "gift_card:full",
         });
         return {
           order: settled,
           payment_intent: null,
-          gift_card: { applied_minor: gc.applied_minor, amount_due_minor: 0 },
+          gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: 0 } : null,
+          loyalty: loy ? { points: loy.points, applied_minor: loy.applied_minor, amount_due_minor: 0 } : null,
         };
       }
 
@@ -354,6 +463,7 @@ function create(deps) {
           tax_minor:      String(quote.totals.tax_minor),
           shipping_minor: String(quote.totals.shipping_minor),
           gift_card_applied_minor: String(gc ? gc.applied_minor : 0),
+          loyalty_applied_minor:   String(loy ? loy.applied_minor : 0),
         },
       }, idempotencyKey);
 
@@ -374,10 +484,12 @@ function create(deps) {
         lines:             orderLines,
       });
 
-      // Burn the gift-card credit against the created order. Runs
-      // after the order row exists so a failed order never burns the
-      // card; the redeem decrement is the double-spend guard.
+      // Burn the gift-card + loyalty credits against the created order.
+      // Runs after the order row exists so a failed order never spends
+      // either credit; each redeem decrement is its own double-spend
+      // guard.
       if (gc) await _redeemGiftCard(gc, createdOrder.id);
+      if (loy) await _redeemLoyalty(loy, loyaltyCustomerId, createdOrder.id);
 
       // Mark the cart converted so a refresh of the storefront
       // doesn't accidentally re-quote the same cart.
@@ -391,6 +503,7 @@ function create(deps) {
           status:        pi.status,
         },
         gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: amountDue } : null,
+        loyalty: loy ? { points: loy.points, applied_minor: loy.applied_minor, amount_due_minor: amountDue } : null,
       };
     },
 

package/lib/order.js

@@ -141,6 +141,15 @@ function create(opts) {
   // dependency is opt-in so existing callers (and the test suite)
   // can run without standing up a webhooks primitive.
   var webhooks = opts.webhooks || null;
+  // Optional loyalty earn dispatcher — when present, an order reaching
+  // `paid` fans out to the customer's loyalty balance via the earn
+  // rules (per_dollar_spent / per_purchase / first_purchase). Opt-in
+  // like `webhooks` so callers and the test suite can run without
+  // standing up a loyalty primitive. The award runs fire-and-forget on
+  // the same detached-promise discipline as the webhook fan-out: the
+  // transition has already persisted, so a loyalty read/write must not
+  // add latency to (or fail) the order transition.
+  var loyaltyEarnRules = opts.loyaltyEarnRules || 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
@@ -306,6 +315,39 @@ function create(opts) {
           return webhooks.send("order." + event, _whPayload);
         }).catch(function () { /* drop-silent — delivery rows hold the failure */ });
       }
+      // Loyalty earn-on-purchase fan-out — fire-and-forget, same
+      // discipline as the webhook block. Only on the paid transition
+      // and only for an order that carries a customer_id (guest orders
+      // have no loyalty account to credit). The per-event dedup on
+      // `loyalty_earn_log` (rule_slug, customer_id, trigger_event_ref)
+      // collapses a re-delivered mark_paid (Stripe + PayPal webhook
+      // backstops both fire it) onto one award, so a retried transition
+      // never double-credits. dollars_spent is derived from the order
+      // subtotal (the revenue the customer actually spent on goods,
+      // excluding tax + shipping); per_purchase / first_purchase rules
+      // ignore it. The award is detached so a loyalty failure lives in
+      // the loyalty ledger's own audit trail, never as an
+      // unhandledRejection and never on the transition's latency.
+      if (loyaltyEarnRules && typeof loyaltyEarnRules.awardForEvent === "function"
+          && result.to === "paid" && refreshed && refreshed.customer_id) {
+        var _loyCustomer = refreshed.customer_id;
+        var _loyOrderId  = refreshed.id;
+        var _loyDollars  = Math.floor((Number(refreshed.subtotal_minor) || 0) / 100);
+        Promise.resolve().then(function () {
+          return loyaltyEarnRules.awardForEvent({
+            trigger:           "per_dollar_spent",
+            customer_id:       _loyCustomer,
+            dollars_spent:     _loyDollars,
+            trigger_event_ref: "order:" + _loyOrderId,
+          });
+        }).then(function () {
+          return loyaltyEarnRules.awardForEvent({
+            trigger:           "per_purchase",
+            customer_id:       _loyCustomer,
+            trigger_event_ref: "order:" + _loyOrderId,
+          });
+        }).catch(function () { /* drop-silent — loyalty ledger holds its own audit trail */ });
+      }
       return refreshed;
     },
 

package/lib/storefront.js

@@ -1413,6 +1413,186 @@ 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,
+  });
+}
+
 // 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 +1928,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 +1966,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
@@ -2569,6 +2784,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/loyalty\">Rewards</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 +2910,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
@@ -3021,7 +3251,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 +3309,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 +3330,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);
@@ -4414,6 +4663,124 @@ 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("");
+        });
+      }
+    }
+
     // 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.26",
+  "version": "0.1.27",
   "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": {