@blamejs/blamejs-shop 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.2.x
 
+- v0.2.5 (2026-05-27) — **Customer surveys — token-gated NPS / CSAT / CES feedback with an admin rollup.** Operators can now collect structured post-experience feedback. Define a survey (NPS, CSAT, CES, or a custom open-ended prompt) from a new Surveys screen in the admin console, then issue a single-use invitation for a customer — the console shows the survey link once for you to send. The customer opens the link and answers without signing in; the token itself is the access. Responses roll up on the survey's detail page with the kind-appropriate score (NPS index, CSAT positive-rate, CES mean) plus a per-question breakdown. Surveys can be archived when a campaign ends; existing invitation links keep working. **Added:** *Token-gated survey page* — A `/survey/:token` page renders the survey's questions — a rating scale, single-select options, or a free-text box — and accepts one response per invitation. The single-use token is the access (no login), and the page degrades cleanly to a clear notice when a link is already used, expired, closed, or invalid. The required-answer check re-renders the form with a message rather than losing the visitor's work. · *Admin console: Surveys* — A new Surveys screen (and matching JSON API) to create a survey for the chosen kind (the console seeds the standard question set; fully custom question lists go through the API), issue a single-use invitation for a customer id (the link is revealed exactly once), read the response rollup with the kind's headline score and per-question results, and archive finished surveys. The screen appears only when the surveys primitive is wired.
+
 - v0.2.4 (2026-05-27) — **Announcement bar — publish a sitewide promo or notice strip from the admin console.** Operators can now publish a sitewide announcement bar — a strip at the very top of every storefront page for a sale, a shipping notice, or an urgent alert. Manage it from a new Announcements screen in the admin console: set the message, an optional call-to-action link, a theme (urgency, promo, info, or success), the audience (everyone, signed-out visitors, or signed-in customers), an optional start/expiry schedule, and whether visitors can dismiss it. The highest-priority active announcement shows automatically (urgency outranks promo outranks info outranks success). The bar renders on both the edge and container paths so it appears on every page including the cached ones, and a dismissed bar stays hidden across navigation. Until an announcement is published, nothing changes. **Added:** *Sitewide announcement bar* — A page-top strip rendered on every storefront page (home, search, product, cart, blog, and the storefront chrome) in one of four themes. The single highest-priority active announcement for the viewer is shown, chosen by theme rank (urgency > promo > info > success). Audience targeting covers everyone, signed-out visitors, and signed-in customers, with an optional scheduled start and expiry. An optional call-to-action link is included; its URL is restricted to https:// or a site-relative path. · *Admin console: Announcements* — A new Announcements screen (and matching JSON API) to create announcements, filter the list to those active right now, and archive ones that are done. The screen appears in the console only when the announcement primitive is wired. · *Dismiss without a round-trip* — Dismissible announcements carry a close control. With JavaScript it's hidden in place and remembered in a local cookie so it doesn't reappear as you browse; with JavaScript off, a form submission records the dismissal and returns you to the page. The bar is always server-rendered identically for everyone, so a dismissed bar never leaks back in from a cached page — it's hidden per-visitor on the client.
 
 - v0.2.3 (2026-05-27) — **Admin console adopts the dark violet brand — the operator dashboard now matches the storefront.** The admin console has been restyled from its previous light theme and orange accent onto the same dark violet identity as the storefront: a neutral near-black canvas with violet reserved for accents, the self-hosted Hanken Grotesk and Space Mono typefaces in place of Inter, and Space Mono carrying the terminal-style chrome (header mark, navigation, micro-labels, figures, SKUs, order ids, and code). Stat cards, tables, status pills, forms, buttons, banners, nav cards, and the sign-in card are all recoloured for the dark surface with contrast preserved — order statuses keep their meaning (green for paid/shipped, amber for pending, violet for refunded, muted for cancelled), form inputs read clearly on the dark wells, and the revenue sparkline is drawn in the brand violet. Operators on the default theme get the new console on upgrade; no admin functionality, routes, or data change. **Changed:** *Dark violet admin theme* — The admin stylesheet is rebuilt on the storefront's palette — near-black surfaces, neutral hairline borders, and violet reserved for accents (active nav, primary buttons, the `/ admin` mark, focus states, and the revenue sparkline) rather than the former light paper and orange. Self-hosted Hanken Grotesk (display/body) and Space Mono (chrome/mono) replace Inter, loaded under the strict `font-src 'self'` policy. · *Components recoloured for the dark surface* — Stat cards, the orders table, status pills, filter chips, forms, buttons (primary/ghost/danger), banners, nav cards, the gift-card detail grid, and the sign-in card are all restyled for dark with contrast maintained. Order-status pills keep their semantics — green for paid/shipped/fulfilling/delivered, amber for pending, violet for refunded, muted for cancelled. Form inputs sit on recessed dark wells with light text and a violet focus ring.

package/lib/admin.js

@@ -300,7 +300,7 @@ function mount(router, deps) {
   // Which optional console sections are wired — gates their nav links so a
   // signed-in admin is never sent to a route that wasn't mounted. Passed
   // into every authed render call as `nav_available`.
-  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, customerSurveys: !!deps.customerSurveys };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -2171,6 +2171,131 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- customer surveys -----------------------------------------------
+  // Define NPS/CSAT/CES/custom surveys, issue token invitations (the
+  // plaintext link is shown once on issue), and read the rollup. The
+  // console creates surveys with a standard question set for the chosen
+  // kind; fully custom question lists go through the JSON API. Content-
+  // negotiated like the other screens.
+  if (deps.customerSurveys) {
+    var surveys = deps.customerSurveys;
+
+    router.get("/admin/surveys", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var activeS = url && url.searchParams.get("active");
+        _json(res, 200, { rows: await surveys.listSurveys(activeS === "1" ? { active_only: true } : {}) });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var activeS = url && url.searchParams.get("active");
+        var rows = await surveys.listSurveys(activeS === "1" ? { active_only: true } : {});
+        _sendHtml(res, 200, renderAdminSurveys({
+          shop_name: deps.shop_name, nav_available: navAvailable, surveys: rows,
+          active_filter: activeS,
+          created:  url && url.searchParams.get("created"),
+          archived: url && url.searchParams.get("archived"),
+          notice:   (url && url.searchParams.get("err")) ? "That action couldn't be completed for the survey." : null,
+        }));
+      },
+    ));
+
+    router.post("/admin/surveys", _pageOrApi(false,
+      W("survey.define", async function (req, res) {
+        var row = await surveys.defineSurvey(req.body || {});
+        _json(res, 201, row);
+        return { id: row.slug };
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        try {
+          await surveys.defineSurvey({
+            slug:     typeof body.slug === "string" ? body.slug.trim() : body.slug,
+            title:    body.title,
+            kind:     body.kind,
+            trigger:  body.trigger || "manual",
+            questions: _standardSurveyQuestions(body.kind),
+          });
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          var rows = await surveys.listSurveys({});
+          return _sendHtml(res, 400, renderAdminSurveys({
+            shop_name: deps.shop_name, nav_available: navAvailable, surveys: rows,
+            notice: (e.message || "Couldn't create that survey.").replace(/^customerSurveys[.:]\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".survey.define", outcome: "success" });
+        _redirect(res, "/admin/surveys?created=1");
+      },
+    ));
+
+    router.post("/admin/surveys/:slug/archive", _pageOrApi(false,
+      W("survey.archive", async function (req, res) {
+        var row;
+        try { row = await surveys.archiveSurvey(req.params.slug); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!row) return _problem(res, 404, "survey-not-found");
+        _json(res, 200, row);
+        return { id: row.slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var row = null;
+        try { row = await surveys.archiveSurvey(slug); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!row) return _redirect(res, "/admin/surveys?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".survey.archive", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/surveys?archived=1");
+      },
+    ));
+
+    // Detail: rollup + the issue-invitation form. The freshly-issued token
+    // link is rendered once via the ?token= flash (never stored plaintext).
+    router.get("/admin/surveys/:slug", _pageOrApi(true,
+      R(async function (req, res) {
+        var roll = await surveys.rollup({ slug: req.params.slug });
+        if (!roll) return _problem(res, 404, "survey-not-found");
+        _json(res, 200, roll);
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var survey = await surveys.getSurvey(slug);
+        if (!survey) return _sendHtml(res, 404, renderAdminSurveyDetail({ shop_name: deps.shop_name, nav_available: navAvailable, survey: null }));
+        var roll = await surveys.rollup({ slug: slug });
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _sendHtml(res, 200, renderAdminSurveyDetail({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          survey: survey, rollup: roll,
+          issued_link: url && url.searchParams.get("link"),
+          notice: (url && url.searchParams.get("err")) ? "Couldn't issue that invitation — check the customer id." : null,
+        }));
+      },
+    ));
+
+    router.post("/admin/surveys/:slug/issue", _pageOrApi(false,
+      W("survey.issue", async function (req, res) {
+        var out = await surveys.issueInvitation(Object.assign({}, req.body || {}, { survey_slug: req.params.slug }));
+        _json(res, 201, out);
+        return { id: out.invitation_id };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc = encodeURIComponent(slug);
+        var out;
+        try {
+          out = await surveys.issueInvitation({ survey_slug: slug, customer_id: (req.body && req.body.customer_id) });
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          return _redirect(res, "/admin/surveys/" + enc + "?err=1");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".survey.issue", outcome: "success", metadata: { slug: slug } });
+        // The plaintext token is shown exactly once — pass it back via the
+        // detail redirect so the operator can copy the survey link.
+        _redirect(res, "/admin/surveys/" + enc + "?link=" + encodeURIComponent(out.plaintext_token));
+      },
+    ));
+  }
+
   // ---- analytics ------------------------------------------------------
 
   var analytics = deps.analytics || null;
@@ -2846,6 +2971,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "subscriptions", href: "/admin/subscription-plans", label: "Subscriptions", requires: "subscriptions" },
   { key: "collections",  href: "/admin/collections",  label: "Collections",  requires: "collections" },
   { key: "announcements", href: "/admin/announcements", label: "Announcements", requires: "announcementBar" },
+  { key: "surveys",      href: "/admin/surveys",      label: "Surveys",      requires: "customerSurveys" },
   { key: "giftcards",    href: "/admin/gift-cards",    label: "Gift cards",   requires: "giftcards" },
   { key: "webhooks",     href: "/admin/webhooks",     label: "Webhooks",     requires: "webhooks" },
   { key: "integrations", href: "/admin/integrations", label: "Integrations" },
@@ -4076,6 +4202,149 @@ function renderAdminAnnouncements(opts) {
   return _renderAdminShell(opts.shop_name, "Announcements", bodyHtml, "announcements", opts.nav_available);
 }
 
+// Standard question set per survey kind, so the console can create the
+// common surveys without a dynamic question builder (fully custom question
+// lists go through the JSON defineSurvey API). Each question carries a
+// stable id so historical responses survive a later edit.
+function _standardSurveyQuestions(kind) {
+  if (kind === "nps") {
+    return [
+      { id: "score", kind: "rating", label: "How likely are you to recommend us to a friend?", max: 10, required: true },
+      { id: "reason", kind: "free_text", label: "What's the main reason for your score?", required: false },
+    ];
+  }
+  if (kind === "ces") {
+    return [
+      { id: "effort", kind: "rating", label: "How easy was it to get what you needed?", max: 7, required: true },
+      { id: "reason", kind: "free_text", label: "Anything that made it harder than it should have been?", required: false },
+    ];
+  }
+  if (kind === "csat") {
+    return [
+      { id: "score", kind: "rating", label: "How satisfied were you with your experience?", max: 5, required: true },
+      { id: "comment", kind: "free_text", label: "Anything you'd like to add?", required: false },
+    ];
+  }
+  // custom — a single open-ended prompt the operator can refine via the API.
+  return [
+    { id: "feedback", kind: "free_text", label: "Your feedback", required: true },
+  ];
+}
+
+function renderAdminSurveys(opts) {
+  opts = opts || {};
+  var rows = opts.surveys || [];
+  var created  = opts.created  ? "<div class=\"banner banner--ok\">Survey created.</div>" : "";
+  var archived = opts.archived ? "<div class=\"banner banner--ok\">Survey archived.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var af = opts.active_filter;
+  var chips = "<div class=\"order-filters\">" +
+    "<a class=\"chip" + (af == null ? " chip--on" : "") + "\" href=\"/admin/surveys\">All</a>" +
+    "<a class=\"chip" + (af === "1" ? " chip--on" : "") + "\" href=\"/admin/surveys?active=1\">Active</a>" +
+    "</div>";
+
+  var bodyRows = rows.map(function (s) {
+    var isArchived = s.archived_at != null;
+    var enc = _htmlEscape(encodeURIComponent(s.slug));
+    return "<tr>" +
+      "<td><a href=\"/admin/surveys/" + enc + "\"><strong>" + _htmlEscape(s.title) + "</strong></a></td>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(s.slug) + "</code></td>" +
+      "<td><span class=\"status-pill\">" + _htmlEscape(s.kind) + "</span></td>" +
+      "<td>" + _htmlEscape(s.trigger_event || s.trigger || "manual") + "</td>" +
+      "<td><span class=\"status-pill " + (isArchived ? "cancelled" : "paid") + "\">" + (isArchived ? "archived" : "active") + "</span></td>" +
+      "<td><div class=\"actions-row\">" +
+        "<a class=\"btn btn--ghost\" href=\"/admin/surveys/" + enc + "\">Open</a>" +
+        (isArchived ? "" :
+          "<form method=\"post\" action=\"/admin/surveys/" + enc + "/archive\" class=\"form-inline\">" +
+            "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>") +
+      "</div></td>" +
+    "</tr>";
+  }).join("");
+
+  var table = rows.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Title</th><th scope=\"col\">Slug</th><th scope=\"col\">Kind</th><th scope=\"col\">Trigger</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No surveys" + (af === "1" ? " active" : " yet") + ".</p>";
+
+  var kindOpts = [["nps", "NPS — recommend score"], ["csat", "CSAT — satisfaction"], ["ces", "CES — ease of effort"], ["custom", "Custom — open feedback"]]
+    .map(function (k) { return "<option value=\"" + k[0] + "\">" + _htmlEscape(k[1]) + "</option>"; }).join("");
+  var trigOpts = [["manual", "Manual (issue invitations yourself)"], ["after_delivery", "After delivery"], ["after_support_close", "After support close"], ["after_refund", "After refund"]]
+    .map(function (t) { return "<option value=\"" + t[0] + "\">" + _htmlEscape(t[1]) + "</option>"; }).join("");
+
+  var createForm =
+    "<div class=\"panel mt mw-40\">" +
+      "<h3 class=\"subhead\">Create a survey</h3>" +
+      "<p class=\"meta\">The console seeds a standard question set for the chosen kind. After creating, open the survey to issue invitation links + read the rollup.</p>" +
+      "<form method=\"post\" action=\"/admin/surveys\">" +
+        _setupField("Title", "title", "", "text", "", " maxlength=\"200\" required") +
+        _setupField("Slug", "slug", "", "text", "Lowercase, hyphenated — a stable id.", " maxlength=\"64\" required") +
+        "<label class=\"form-field\"><span>Kind</span><select name=\"kind\">" + kindOpts + "</select></label>" +
+        "<label class=\"form-field\"><span>Trigger</span><select name=\"trigger\">" + trigOpts + "</select></label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create survey</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Surveys</h2>" + created + archived + notice + chips + table + createForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Surveys", bodyHtml, "surveys", opts.nav_available);
+}
+
+function renderAdminSurveyDetail(opts) {
+  opts = opts || {};
+  var survey = opts.survey;
+  if (!survey) {
+    var nf = "<section><h2>Survey</h2><p class=\"empty\">Survey not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/surveys\">Back to surveys</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Survey", nf, "surveys", opts.nav_available);
+  }
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  // Freshly-issued invitation link — shown exactly once (the plaintext
+  // token is never persisted). The operator copies it into their own
+  // email/SMS to the customer.
+  var linkReveal = "";
+  if (opts.issued_link) {
+    var path = "/survey/" + _htmlEscape(opts.issued_link);
+    linkReveal =
+      "<div class=\"banner banner--ok\">Invitation issued. Copy this single-use link and send it to the customer — it won't be shown again:" +
+        "<br><code class=\"code-block\">" + path + "</code></div>";
+  }
+
+  var roll = opts.rollup || { response_count: 0, per_question: [] };
+  var headline = "";
+  if (roll.nps)       headline = "NPS score: <strong>" + _htmlEscape(String(roll.nps.score)) + "</strong> (" + _htmlEscape(String(roll.nps.promoter_pct)) + "% promoters, " + _htmlEscape(String(roll.nps.detractor_pct)) + "% detractors)";
+  else if (roll.csat) headline = "CSAT: <strong>" + _htmlEscape(String(roll.csat.positive_pct)) + "%</strong> positive";
+  else if (roll.ces)  headline = "CES mean: <strong>" + _htmlEscape(String(roll.ces.mean)) + "</strong>";
+
+  var qRows = (roll.per_question || []).map(function (pq) {
+    var detail;
+    if (pq.kind === "rating") detail = "mean " + _htmlEscape(String(pq.mean)) + " over " + _htmlEscape(String(pq.count)) + " answers";
+    else if (pq.kind === "select") {
+      detail = Object.keys(pq.buckets || {}).map(function (o) { return _htmlEscape(o) + ": " + _htmlEscape(String(pq.buckets[o])); }).join(", ");
+    } else detail = _htmlEscape(String(pq.count)) + " written responses";
+    return "<tr><td><code class=\"order-id\">" + _htmlEscape(pq.id) + "</code></td><td>" + _htmlEscape(pq.kind) + "</td><td>" + detail + "</td></tr>";
+  }).join("");
+  var rollupPanel =
+    "<div class=\"panel\">" +
+      "<p class=\"meta\">" + _htmlEscape(String(roll.response_count)) + " response(s)." + (headline ? " " + headline : "") + "</p>" +
+      (qRows ? "<table><thead><tr><th scope=\"col\">Question</th><th scope=\"col\">Kind</th><th scope=\"col\">Result</th></tr></thead><tbody>" + qRows + "</tbody></table>" : "") +
+    "</div>";
+
+  var enc = _htmlEscape(encodeURIComponent(survey.slug));
+  var issueForm =
+    "<div class=\"panel mt mw-40\">" +
+      "<h3 class=\"subhead\">Issue an invitation</h3>" +
+      "<p class=\"meta\">Generates a single-use survey link for one customer. You send the link; the customer answers without signing in.</p>" +
+      "<form method=\"post\" action=\"/admin/surveys/" + enc + "/issue\">" +
+        _setupField("Customer id", "customer_id", "", "text", "The customer's UUID.", " maxlength=\"64\" required") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Issue invitation</button>" +
+          "<a class=\"btn btn--ghost\" href=\"/admin/surveys\">Back to surveys</a></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>" + _htmlEscape(survey.title) + "</h2>" + notice + linkReveal + rollupPanel + issueForm + "</section>";
+  return _renderAdminShell(opts.shop_name, survey.title, bodyHtml, "surveys", opts.nav_available);
+}
+
 function renderAdminCollection(opts) {
   opts = opts || {};
   var col = opts.collection;

package/lib/asset-manifest.json

@@ -1,13 +1,13 @@
 {
-  "version": "0.2.4",
+  "version": "0.2.5",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-FgqvXcZygYkJjjOtXAeu9xi6AtYqkchPnJKcS0OeHm8lynhd9r4RfdpoT7P7j7/l",
       "fingerprinted": "css/admin.afd7b964c1f6fe1b.css"
     },
     "css/main.css": {
-      "integrity": "sha384-fMfWbfkIZ29Z4RjHyn3ol0SOf/VodnKqDjkrU7OCQLvzm6hFHRL3kcwMGNnXzdai",
-      "fingerprinted": "css/main.73ee71264ed8de75.css"
+      "integrity": "sha384-G7yMuGZ4ojVoEpiRX70qcuR+YcQU4A1K/jRhRE/yPD7PXkqUH4LruBlu6MPCv+R8",
+      "fingerprinted": "css/main.b99ea24f442deef8.css"
     },
     "js/announcement.js": {
       "integrity": "sha384-z4zcEMn+tScoVnYRE4nEf8N/oyvpxdpaxTNrT4QO/jURChid4+qjAvWkzatCaAPq",

package/lib/customer-surveys.js

@@ -537,6 +537,25 @@ function create(opts) {
     return _decodeSurvey(await _surveyRow(slug));
   }
 
+  // List defined surveys for the operator console, newest first. With
+  // `{ active_only: true }` archived surveys are dropped; otherwise all are
+  // returned so the console can show an archived filter.
+  async function listSurveys(listOpts) {
+    listOpts = listOpts || {};
+    var sql, params;
+    if (listOpts.active_only === true) {
+      sql = "SELECT * FROM customer_surveys WHERE archived_at IS NULL ORDER BY updated_at DESC, slug ASC";
+      params = [];
+    } else {
+      sql = "SELECT * FROM customer_surveys ORDER BY updated_at DESC, slug ASC";
+      params = [];
+    }
+    var r = await query(sql, params);
+    var out = [];
+    for (var i = 0; i < r.rows.length; i += 1) out.push(_decodeSurvey(r.rows[i]));
+    return out;
+  }
+
   async function archiveSurvey(slug) {
     _slug(slug, "slug");
     var ts = _now();
@@ -609,6 +628,25 @@ function create(opts) {
     return _decodeInvitation(r.rows[0]);
   }
 
+  // Resolve an invitation + its parent survey from the single-use plaintext
+  // token, for rendering the survey page (the token IS the access — no login
+  // needed). Returns { invitation, survey } or null when the token matches
+  // nothing. The caller inspects invitation.status / expires_at to decide
+  // whether to render the form, a thank-you, or an expired/closed notice;
+  // this read never mutates state. Constant-time hash compare mirrors
+  // submitResponse so a malformed token can't be a timing oracle.
+  async function previewByToken(token) {
+    var canon = _canonicalToken(token);
+    var hash  = _hashToken(canon);
+    var r = await query("SELECT * FROM survey_invitations WHERE token_hash = ?1", [hash]);
+    if (!r.rows.length) return null;
+    var inv = r.rows[0];
+    if (!b.crypto.timingSafeEqual(inv.token_hash, hash)) return null;
+    var surveyRow = await _surveyRow(inv.survey_slug);
+    if (!surveyRow) return null;
+    return { invitation: _decodeInvitation(inv), survey: _decodeSurvey(surveyRow) };
+  }
+
   async function invitationsForCustomer(customerId, listOpts) {
     var custId = _uuid(customerId, "customer_id");
     listOpts = listOpts || {};
@@ -989,6 +1027,8 @@ function create(opts) {
     archiveSurvey:           archiveSurvey,
     issueInvitation:         issueInvitation,
     getInvitation:           getInvitation,
+    previewByToken:          previewByToken,
+    listSurveys:             listSurveys,
     invitationsForCustomer:  invitationsForCustomer,
     submitResponse:          submitResponse,
     responsesForSurvey:      responsesForSurvey,

package/lib/storefront.js

@@ -4656,6 +4656,85 @@ function renderAccount(opts) {
   });
 }
 
+// ---- customer survey page ----------------------------------------------
+
+// Render one survey question as a fieldset. Rating → a 0/1..max radio
+// scale; select → radio options; free_text → a textarea. Field name is
+// `q_<id>`; the post handler maps it back. All operator-authored strings
+// are HTML-escaped at the sink.
+function _surveyQuestion(q) {
+  var esc = function (s) { return b.template.escapeHtml(String(s == null ? "" : s)); };
+  var name = "q_" + esc(q.id);
+  var req  = q.required ? " <abbr class=\"survey-req\" title=\"Required\">*</abbr>" : "";
+  var control = "";
+  if (q.kind === "rating") {
+    var lo = (q.max >= 9) ? 0 : 1; // 0..10 for NPS-scale, else 1..max
+    var scale = "";
+    for (var n = lo; n <= q.max; n += 1) {
+      scale += "<label class=\"survey-scale__opt\"><input type=\"radio\" name=\"" + name + "\" value=\"" + n + "\"" + (q.required ? " required" : "") + "><span>" + n + "</span></label>";
+    }
+    control = "<div class=\"survey-scale\">" + scale + "</div>";
+  } else if (q.kind === "select") {
+    var opts = "";
+    for (var k = 0; k < q.options.length; k += 1) {
+      var ov = esc(q.options[k]);
+      opts += "<label class=\"survey-opt\"><input type=\"radio\" name=\"" + name + "\" value=\"" + ov + "\"" + (q.required ? " required" : "") + "> " + ov + "</label>";
+    }
+    control = "<div class=\"survey-opts\">" + opts + "</div>";
+  } else {
+    control = "<textarea name=\"" + name + "\" maxlength=\"" + (q.max || 2000) + "\"" + (q.required ? " required" : "") + "></textarea>";
+  }
+  return "<fieldset class=\"survey-q\"><legend>" + esc(q.label) + req + "</legend>" + control + "</fieldset>";
+}
+
+// The token survey page. `state` selects the panel: form (answerable),
+// thankyou (just submitted), responded (already done), expired, closed, or
+// notfound. The token is rendered into the form action so the POST carries
+// it back (it's path-segment-safe — 43 base64url chars).
+function renderSurveyPage(opts) {
+  opts = opts || {};
+  var esc = function (s) { return b.template.escapeHtml(String(s == null ? "" : s)); };
+  var state = opts.state || "notfound";
+  var body;
+  if (state === "form") {
+    var survey = opts.survey || {};
+    var qs = (survey.questions || []).map(_surveyQuestion).join("");
+    var notice = opts.notice ? "<p class=\"form-notice\">" + esc(opts.notice) + "</p>" : "";
+    body =
+      "<section class=\"survey-page\"><div class=\"survey-page__inner\">" +
+        "<p class=\"eyebrow\">Your feedback</p>" +
+        "<h1 class=\"survey-page__title\">" + esc(survey.title) + "</h1>" +
+        notice +
+        "<form class=\"survey-form\" method=\"post\" action=\"/survey/" + esc(opts.token) + "\">" +
+          qs +
+          "<div class=\"survey-form__actions\"><button class=\"btn-primary\" type=\"submit\">Submit feedback</button></div>" +
+        "</form>" +
+      "</div></section>";
+  } else {
+    var heads = {
+      thankyou:  ["Thank you", "Your feedback's in — we appreciate you taking the time."],
+      responded: ["Already answered", "This feedback link has already been used. Thank you."],
+      expired:   ["This link has expired", "The feedback window for this survey has closed."],
+      closed:    ["This survey is closed", "This feedback link is no longer active."],
+      notfound:  ["Survey not found", "This feedback link isn't valid. Check the link from your email."],
+    };
+    var h = heads[state] || heads.notfound;
+    body =
+      "<section class=\"survey-page\"><div class=\"survey-page__inner survey-page__inner--msg\">" +
+        "<h1 class=\"survey-page__title\">" + esc(h[0]) + "</h1>" +
+        "<p class=\"survey-page__lede\">" + esc(h[1]) + "</p>" +
+        "<a class=\"btn-ghost\" href=\"/\">Back to the shop</a>" +
+      "</div></section>";
+  }
+  return _wrap({
+    title:      opts.title || "Survey",
+    shop_name:  opts.shop_name || "blamejs.shop",
+    cart_count: opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:  opts.theme_css,
+    body:       body,
+  });
+}
+
 function mount(router, deps) {
   if (!router || typeof router.get !== "function") throw new TypeError("storefront.mount: router with .get() required");
   if (!deps || !deps.catalog || !deps.cart) throw new TypeError("storefront.mount: deps.catalog + deps.cart required");
@@ -5046,6 +5125,93 @@ function mount(router, deps) {
     });
   }
 
+  // ---- customer survey (token-gated) ----------------------------------
+  // The invitation token IS the access — no login. GET renders the survey
+  // (or a state notice); POST records the response. Container-only (the
+  // token page is never edge-cached). Resilient: an unknown/garbage token,
+  // a used/expired/closed invitation, and a missing surveys table all
+  // resolve to a clean state page, never a 500.
+  if (deps.customerSurveys) {
+    var _surveyCtx = function (_req) {
+      return {
+        shop_name: (deps.config && deps.config.shop_name) || "blamejs.shop",
+        cart_count: 0,
+        theme_css: (deps.theme && deps.theme.assetUrl) ? deps.theme.assetUrl("css/main.css") : DEFAULT_THEME_CSS_URL,
+      };
+    };
+
+    router.get("/survey/:token", async function (req, res) {
+      var token = (req.params && req.params.token) || "";
+      var state = "notfound", survey = null;
+      try {
+        var preview = await deps.customerSurveys.previewByToken(token);
+        if (preview) {
+          survey = preview.survey;
+          var inv = preview.invitation;
+          if (inv.status === "responded")      state = "responded";
+          else if (inv.status === "closed")    state = "closed";
+          else if (inv.status === "expired" || Number(inv.expires_at) < Date.now()) state = "expired";
+          else state = "form";
+        }
+      } catch (_e) { state = "notfound"; }
+      var ctx = _surveyCtx(req);
+      _send(res, state === "notfound" ? 404 : 200, renderSurveyPage({
+        state: state, survey: survey, token: token,
+        shop_name: ctx.shop_name, cart_count: ctx.cart_count, theme_css: ctx.theme_css,
+      }));
+    });
+
+    router.post("/survey/:token", async function (req, res) {
+      var token = (req.params && req.params.token) || "";
+      var body = req.body || {};
+      var ctx = _surveyCtx(req);
+      // Resolve the survey first so we can re-render the form on a
+      // validation error (and map the token to its questions).
+      var preview = null;
+      try { preview = await deps.customerSurveys.previewByToken(token); }
+      catch (_e) { preview = null; }
+      if (!preview) {
+        return _send(res, 404, renderSurveyPage({ state: "notfound", token: token, shop_name: ctx.shop_name, theme_css: ctx.theme_css }));
+      }
+      // Build the answers object from the q_<id> fields, typed per question
+      // kind (rating → integer, select/free_text → string). Blank fields are
+      // omitted so optional questions stay unanswered.
+      var answers = {};
+      var questions = preview.survey.questions || [];
+      for (var i = 0; i < questions.length; i += 1) {
+        var q = questions[i];
+        var raw = body["q_" + q.id];
+        if (raw == null || raw === "") continue;
+        if (q.kind === "rating") {
+          var n = parseInt(raw, 10);
+          if (isFinite(n)) answers[q.id] = n;
+        } else {
+          answers[q.id] = String(raw);
+        }
+      }
+      try {
+        await deps.customerSurveys.submitResponse({ token: token, answers: answers });
+      } catch (e) {
+        // Known terminal states → the matching notice; a validation
+        // TypeError → re-render the form with the cleaned message.
+        var code = e && e.code;
+        if (code === "SURVEY_INVITATION_ALREADY_RESPONDED") return _send(res, 200, renderSurveyPage({ state: "responded", token: token, shop_name: ctx.shop_name, theme_css: ctx.theme_css }));
+        if (code === "SURVEY_INVITATION_EXPIRED")           return _send(res, 200, renderSurveyPage({ state: "expired", token: token, shop_name: ctx.shop_name, theme_css: ctx.theme_css }));
+        if (code === "SURVEY_INVITATION_CLOSED")            return _send(res, 200, renderSurveyPage({ state: "closed", token: token, shop_name: ctx.shop_name, theme_css: ctx.theme_css }));
+        if (code === "SURVEY_INVITATION_NOT_FOUND")         return _send(res, 404, renderSurveyPage({ state: "notfound", token: token, shop_name: ctx.shop_name, theme_css: ctx.theme_css }));
+        if (e instanceof TypeError) {
+          return _send(res, 400, renderSurveyPage({
+            state: "form", survey: preview.survey, token: token,
+            notice: (e.message || "Please check your answers.").replace(/^customerSurveys[.:]\s*/, ""),
+            shop_name: ctx.shop_name, theme_css: ctx.theme_css,
+          }));
+        }
+        throw e;
+      }
+      _send(res, 200, renderSurveyPage({ state: "thankyou", token: token, shop_name: ctx.shop_name, theme_css: ctx.theme_css }));
+    });
+  }
+
   // Persist a locale choice. A GET form (works with JS off) from the
   // footer switcher submits `lang` (the chosen tag) + `to` (the path to
   // return to). We validate the tag against the active locale set, set

package/package.json

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