@blamejs/blamejs-shop 0.3.27 → 0.3.28

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.28 (2026-05-31) — **Customers can now see their store-credit balance and history.** Operators could grant or deduct a customer's store credit, but the customer had no way to see it — the balance only ever surfaced as a silent discount at checkout. A new Store credit page in the account area shows the current balance, a callout for any credit about to expire, and the full ledger of credits, deductions, and expirations with amounts, reasons, and dates. The page is read-only and shows only the signed-in customer's own balance. **Added:** *Store-credit wallet in the account area* — A Store credit page lists a customer's current balance, any credit expiring soon, and the full history of credits, deductions, and expirations — each with its amount, the reason, and the date. It is reachable from the account dashboard and reflects the store credit an operator grants from the customer screen, so a shopper can finally see credit they have been given instead of only discovering it at checkout. The page is read-only and scoped to the signed-in customer.
+
 - v0.3.27 (2026-05-31) — **Shared product and page links now show a preview image, and category pages get breadcrumb rich results.** Social-share previews and search rich results were emitting relative image paths, which Facebook, Slack, Twitter, iMessage, and Google all drop — so a shared product or page link showed no preview image, and product rich results had no image. Every og:image, twitter:image, and Product/Article structured-data image is now a fully-qualified URL built from the page's own origin. Collection and category pages, which already showed an on-page breadcrumb, now also emit BreadcrumbList structured data so the trail can appear in search results, matching what product pages already did. And operator-supplied page keywords or announcement text containing a dollar-sign sequence now render literally instead of being garbled. **Fixed:** *Share and rich-result images are now absolute URLs* — The og:image, twitter:image, and the image in Product and blog-article structured data were relative paths, so social platforms and Google could not load them — a shared link showed no preview image. They are now fully-qualified against the page's origin on every page, in both the edge and container renderers, so shares unfurl with the right image and product rich results carry one. Images an operator already hosts at an absolute URL pass through unchanged. · *Breadcrumb structured data on collection and category pages* — Collection and category pages showed a breadcrumb trail on the page but did not expose it as BreadcrumbList structured data, so search engines could not render the trail in results. They now emit it with absolute URLs, the same way product pages already do. · *Dollar-sign sequences in page metadata render literally* — Page meta-keywords and announcement-bar text containing a dollar-sign sequence (for example a price written with a special character) could be garbled in the page head because of how the value was substituted into the template. The substitution now treats the value as literal text, so it renders exactly as entered.
 
 - v0.3.26 (2026-05-31) — **Customers can raise support tickets and operators work them from a queue.** The support-ticket system had a complete backend — threaded messages, assignment, tags, and a status workflow — but no way in or out: a shopper could not open a ticket and an operator could not see one. Both sides are now wired. A logged-in customer can raise a ticket from their account (with an optional link to one of their own orders), see the thread, and reply while it is open. Operators get a Support queue in the console with an unassigned-triage view, the full thread for each ticket, and controls to reply (with an internal-note option that the customer never sees), assign, tag, and move the ticket through its status workflow. A customer only ever sees their own tickets, and replying to a closed ticket is refused. **Added:** *Customer support tickets* — A Support section in the account area lets a signed-in customer open a ticket (subject, message, category, and an optional reference to one of their own orders), list their tickets with status, read the full message thread, and reply while the ticket is open. Internal operator notes are never shown to the customer, a customer can only see and reply to their own tickets, and a reply to a closed ticket is refused. · *Support queue in the admin console* — A Support screen lists inbound tickets by status with an unassigned-triage view. Opening a ticket shows the full thread, the requester, the current status, the assignee, and tags. From there an operator can reply (optionally as an internal note), assign the ticket, tag it, and move it through its status workflow — in progress, waiting on the customer, resolved, closed, or reopened.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.27",
+  "version": "0.3.28",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",

package/lib/storefront.js

@@ -3625,6 +3625,147 @@ function renderLoyalty(opts) {
   });
 }
 
+// Store credit is account-bound and carries no per-row currency — the
+// ledger stores integer minor units in the shop's single display
+// currency. The storefront's other account surfaces (loyalty "worth",
+// the order-history total fallback) format in USD, so the wallet does
+// too; a future multi-currency store threads the resolved code in here.
+var STORE_CREDIT_CURRENCY = "USD";
+
+// A human label for the credit-row provenance enum
+// (store_credit_ledger.source). Falls back to the raw code so a future
+// source the renderer hasn't learned still shows something sensible.
+var STORE_CREDIT_SOURCE_LABELS = {
+  refund:             "Refund",
+  goodwill:           "Goodwill",
+  promotional:        "Promotion",
+  manual:             "Manual adjustment",
+  loyalty_redemption: "Loyalty redemption",
+};
+
+// A ledger row's amount, signed by its kind: credit adds (+), debit and
+// expire subtract (−). The amount is always stored positive, so the
+// sign comes from `kind`. The minor-unit amount is formatted through the
+// shared `pricing.format` money helper (Intl-backed, ISO 4217 exponent),
+// never hand-rolled.
+function _storeCreditSignedAmount(row) {
+  var minor = Number(row.amount_minor) || 0;
+  var money = pricing.format(minor, STORE_CREDIT_CURRENCY);
+  if (row.kind === "credit") return "+" + money;
+  return "−" + money;   // U+2212 MINUS SIGN
+}
+
+// A ledger row's reason text. Credit rows carry an operator-authored
+// free-form `source_ref` plus the provenance enum; expire rows carry the
+// operator's justification in `source_ref` (the primitive writes the
+// `reason` there). Debit rows settle an order and carry neither — they
+// read as a plain "Spent". The caller escapes on output.
+function _storeCreditReasonText(row) {
+  if (row.kind === "credit") {
+    var label = STORE_CREDIT_SOURCE_LABELS[row.source] || String(row.source || "Credit");
+    return row.source_ref ? (label + " — " + String(row.source_ref)) : label;
+  }
+  if (row.kind === "expire") {
+    return row.source_ref ? ("Expired — " + String(row.source_ref)) : "Expired";
+  }
+  return "Spent";   // debit — settles an order
+}
+
+// The signed-in customer's store-credit wallet: the current balance, an
+// expiring-soon callout when any credit is within the warning window,
+// and the credit/debit/expire ledger (paginated, newest first). A wallet
+// with zero balance + no history renders a clean empty state, not an
+// error. Read-only — granting/deducting is operator-only on the admin
+// customer-detail screen. Every amount, reason, and date is escaped on
+// output. Reuses the account/returns + loyalty layout classes — no new
+// CSS.
+function renderAccountStoreCredit(opts) {
+  opts = opts || {};
+  var esc = b.template.escapeHtml;
+
+  var balanceMinor = Number(opts.balance_minor) || 0;
+  var balanceStr   = pricing.format(balanceMinor, STORE_CREDIT_CURRENCY);
+
+  // Balance stat strip.
+  var stats =
+    "<dl class=\"account-dash__stats\">" +
+      "<div><dt>Store credit</dt><dd>" + esc(balanceStr) + "</dd></div>" +
+    "</dl>";
+
+  // Expiring-soon callout — only when a credit row is inside the warning
+  // window. Sums the exposed (still-spendable) amounts and names the
+  // soonest deadline.
+  var expiring = opts.expiring || [];
+  var expiringSection = "";
+  if (expiring.length) {
+    var expMinor = 0;
+    var soonest = null;
+    for (var e = 0; e < expiring.length; e += 1) {
+      expMinor += Number(expiring[e].amount_minor) || 0;
+      var ea = Number(expiring[e].expires_at);
+      if (isFinite(ea) && (soonest == null || ea < soonest)) soonest = ea;
+    }
+    var expStr  = pricing.format(expMinor, STORE_CREDIT_CURRENCY);
+    var expDate = soonest != null ? new Date(soonest).toISOString().slice(0, 10) : "";
+    expiringSection =
+      "<p class=\"form-notice\" role=\"status\">" +
+        esc(expStr) + " of your store credit expires soon" +
+        (expDate ? " &mdash; use it by <time datetime=\"" + esc(expDate) + "\">" + esc(expDate) + "</time>" : "") +
+      "</p>";
+  }
+
+  // The credit/debit/expire ledger, newest first.
+  var hist = opts.history || [];
+  var histInner = "";
+  for (var h = 0; h < hist.length; h += 1) {
+    var row = hist[h];
+    var tdate = row.occurred_at ? new Date(Number(row.occurred_at)).toISOString().slice(0, 10) : "";
+    var rowExpiry = (row.kind === "credit" && row.expires_at != null)
+      ? new Date(Number(row.expires_at)).toISOString().slice(0, 10)
+      : "";
+    histInner +=
+      "<li class=\"return-card\"><div class=\"return-card__head\">" +
+        "<span class=\"pdp__badge store-credit-tx--" + esc(String(row.kind)) + "\">" + esc(String(row.kind)) + "</span>" +
+        "<span class=\"return-card__rma\">" + esc(_storeCreditSignedAmount(row)) + "</span>" +
+      "</div>" +
+      "<p class=\"return-card__meta\">" + esc(_storeCreditReasonText(row)) +
+        (tdate ? " &middot; <time datetime=\"" + esc(tdate) + "\">" + esc(tdate) + "</time>" : "") +
+        (rowExpiry ? " &middot; expires <time datetime=\"" + esc(rowExpiry) + "\">" + esc(rowExpiry) + "</time>" : "") +
+      "</p></li>";
+  }
+  var historySection;
+  if (histInner) {
+    var more = opts.history_next_cursor != null
+      ? "<p class=\"loyalty-more\"><a class=\"btn-secondary\" href=\"/account/credit?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 store credit yet. Refunds and goodwill credit will show up here.</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\">Store credit</li>" +
+      "</ol></nav>" +
+      "<h1 class=\"account-returns__title\">Store credit</h1>" +
+      stats +
+      expiringSection +
+      historySection +
+    "</section>";
+
+  return _wrap({
+    title:      "Store credit",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 // Human-readable funnel stage for a referred friend. The referred
 // email is stored hash-only, so a row never carries an address — the
 // surface shows the stage + dates only.
@@ -6276,6 +6417,7 @@ var ACCOUNT_DASH_PAGE =
   "      <a class=\"btn-secondary\" href=\"/account/returns\">Returns</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/support\">Support</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/loyalty\">Rewards</a>\n" +
+  "      <a class=\"btn-secondary\" href=\"/account/credit\">Store credit</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/referrals\">Refer a friend</a>\n" +
   "      <a class=\"btn-secondary\" href=\"/account/subscriptions\">Subscriptions</a>\n" +
   // begin: profile + passkey management actions
@@ -11152,6 +11294,99 @@ function mount(router, deps) {
       }
     }
 
+    // Store-credit wallet — the signed-in customer's READ-ONLY view of
+    // their account-bound store credit. One surface:
+    //   * GET /account/credit — the current balance, an expiring-soon
+    //     callout, and the credit/debit/expire ledger (paginated). A
+    //     browser gets the server-rendered page; an API client (Accept:
+    //     application/json) gets the balance + ledger payload.
+    //
+    // SESSION-SCOPED, no IDOR surface: the route reads the customer id
+    // from the signed-in session (`auth.customer_id`) and passes ONLY
+    // that id to storeCredit.balance / .history / .expiringWithin. There
+    // is no `:id` path param and the route never reads a customer id from
+    // the query string or body, so a signed-in shopper can only ever see
+    // their OWN wallet. Granting / deducting credit is operator-only on
+    // the admin customer-detail screen — this surface writes nothing.
+    if (deps.storeCredit) {
+      function _storeCreditAuth(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 /account/credit render context for the SESSION
+      // customer. `opts2.cursor` is the optional history-page cursor
+      // (epoch-ms). The expiring-soon read is best-effort so an
+      // unmigrated table or a read error degrades that callout rather
+      // than the page; balance + history are the core reads.
+      async function _storeCreditView(req, auth, opts2) {
+        opts2 = opts2 || {};
+        var bal  = await deps.storeCredit.balance(auth.customer_id);
+        var hist = await deps.storeCredit.history({
+          customer_id: auth.customer_id,
+          limit:       20,
+          cursor:      opts2.cursor,
+        });
+        var expiring = [];
+        try {
+          expiring = await deps.storeCredit.expiringWithin({
+            customer_id: auth.customer_id,
+            days:        30,
+          });
+        } catch (_e) { expiring = []; }
+        var cartCount = await _cartCountForReq(req);
+        return {
+          balance_minor:       bal.balance_minor,
+          history:             hist.rows,
+          history_next_cursor: hist.next_cursor,
+          expiring:            expiring,
+          shop_name:           shopName,
+          cart_count:          cartCount,
+        };
+      }
+
+      router.get("/account/credit", async function (req, res) {
+        var auth = _storeCreditAuth(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 _storeCreditView(req, auth, { cursor: cursor });
+        // Content negotiation: an API client (Accept: application/json)
+        // gets the balance + ledger payload; a browser gets the rendered
+        // wallet page. Both read the SAME session customer id.
+        var accept = (req.headers && (req.headers.accept || req.headers.Accept)) || "";
+        if (/\bapplication\/json\b/.test(String(accept))) {
+          res.status(200);
+          res.setHeader && res.setHeader("content-type", "application/json; charset=utf-8");
+          var payload = JSON.stringify({
+            balance_minor:       view.balance_minor,
+            currency:            "USD",
+            expiring:            view.expiring,
+            ledger:              view.history,
+            history_next_cursor: view.history_next_cursor,
+          });
+          return res.end ? res.end(payload) : res.send(payload);
+        }
+        _send(res, 200, renderAccountStoreCredit(view));
+      });
+    }
+
     // Referrals — refer-a-friend. Three surfaces:
     //   * GET  /r/:code            — the attribution landing. Sets a
     //     short-lived sealed first-party cookie naming the code, records

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.3.27",
+  "version": "0.3.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": {