@blamejs/blamejs-shop 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
 - v0.2.2 (2026-05-27) — **Bespoke line-art illustrations across the storefront — category tiles, image placeholders, and every empty state.** The storefront's stand-in graphics are now a single, cohesive set of hand-drawn line illustrations in the brand violet, replacing the previous mix of gradient-only tiles, single-letter image marks, and emoji. The six featured-collection tiles carry a matching icon (apparel, hardware, digital, subscriptions, bundles, gift cards). Products without an image — in the grid and on the product page — show a bespoke "no image yet" placeholder instead of a letter glyph. Every empty state has its own illustration: cart, search, wishlist, saved-for-later, addresses, returns, and orders. The artwork is inline SVG (no extra files fetched, consistent with the strict asset policy) and adapts to the surface — the fine detail strokes follow the text colour, so the same set reads correctly on a dark or a light background. **Changed:** *Category tiles carry line-art icons* — Each of the six featured-collection tiles now shows a violet line icon for its category, centered over the existing tile gradient. The tile links and labels are unchanged. · *Bespoke image placeholder replaces the letter mark* — When a product has no image, the grid card and the product-page gallery render a line-art "no image yet" placeholder — an isometric package on a faint grid (the product page adds a shield motif and a terminal-prompt accent) — instead of the previous single uppercase letter. The no-image grid card now uses the same media-card layout as image-bearing cards for a consistent grid. · *Every empty state has matching artwork* — The empty cart, no-search-results, empty wishlist, saved-for-later, addresses, returns, and orders states now show a bespoke line illustration in place of the previous emoji or unicode glyphs, so the storefront and account sections share one visual language. · *Inline, theme-adaptive SVG* — All of the new artwork is inline SVG with presentation attributes only — nothing is fetched from a CDN and no inline styles are used, consistent with the strict content-security and asset policies. The detail strokes use currentColor, so the set adapts to the background it sits on. The edge and container renderers emit identical markup.

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 };
+  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 */ }
 
@@ -2098,6 +2098,204 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- announcements --------------------------------------------------
+  // Sitewide promo/notice strip. Content-negotiated like the other console
+  // screens: bearer → the JSON contract; signed-in browser → the HTML
+  // table + create form. The console exposes the all / guest / logged_in
+  // audiences; the primitive's segment audience needs an isMember handle
+  // that isn't wired (see server.js), so it isn't offered here.
+  if (deps.announcementBar) {
+    var announcements = deps.announcementBar;
+
+    router.get("/admin/announcements", _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");
+        var rows = await announcements.listAnnouncements(activeS === "1" ? { active_only: true } : {});
+        _json(res, 200, { rows: rows });
+      }),
+      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 announcements.listAnnouncements(activeS === "1" ? { active_only: true } : {});
+        _sendHtml(res, 200, renderAdminAnnouncements({
+          shop_name: deps.shop_name, nav_available: navAvailable, announcements: 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 announcement." : null,
+        }));
+      },
+    ));
+
+    router.post("/admin/announcements", _pageOrApi(false,
+      W("announcement.define", async function (req, res) {
+        var row = await announcements.defineAnnouncement(req.body || {});
+        _json(res, 201, row);
+        return { id: row.slug };
+      }),
+      async function (req, res) {
+        try {
+          await announcements.defineAnnouncement(_announcementFromForm(req.body || {}));
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          var rows = await announcements.listAnnouncements({});
+          return _sendHtml(res, 400, renderAdminAnnouncements({
+            shop_name: deps.shop_name, nav_available: navAvailable, announcements: rows,
+            notice: (e && e.message || "Couldn't save that announcement.").replace(/^announcementBar[.:]\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".announcement.define", outcome: "success" });
+        _redirect(res, "/admin/announcements?created=1");
+      },
+    ));
+
+    router.post("/admin/announcements/:slug/archive", _pageOrApi(false,
+      W("announcement.archive", async function (req, res) {
+        var row;
+        try { row = await announcements.archiveAnnouncement(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, "announcement-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 announcements.archiveAnnouncement(slug); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!row) return _redirect(res, "/admin/announcements?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".announcement.archive", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/announcements?archived=1");
+      },
+    ));
+  }
+
+  // ---- 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;
@@ -2772,6 +2970,8 @@ var ADMIN_NAV_ITEMS = [
   { key: "questions",    href: "/admin/questions",    label: "Q&A",          requires: "productQa" },
   { 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" },
@@ -3910,6 +4110,241 @@ function renderAdminCollections(opts) {
   return _renderAdminShell(opts.shop_name, "Collections", bodyHtml, "collections", opts.nav_available);
 }
 
+// A <datetime-local> form value → epoch ms (integer) for the lib's
+// starts_at/expires_at, or null when blank/unparseable (open-ended). The
+// announcement primitive validates the result; a blank schedule field just
+// omits the bound.
+function _epochFromForm(v) {
+  if (typeof v !== "string" || !v.trim()) return null;
+  var t = Date.parse(v.trim());
+  return Number.isFinite(t) ? t : null;
+}
+
+// Coerce the create form into the shape announcementBar.defineAnnouncement
+// expects: trimmed slug, strict boolean `dismissible`, integer epoch
+// schedule bounds, and link_url/link_label as a both-or-neither pair.
+function _announcementFromForm(body) {
+  body = body || {};
+  var out = {
+    slug:        typeof body.slug === "string" ? body.slug.trim() : body.slug,
+    message:     body.message,
+    theme:       body.theme,
+    audience:    body.audience,
+    dismissible: body.dismissible === "on" || body.dismissible === "1" || body.dismissible === true,
+  };
+  var lu = typeof body.link_url === "string" ? body.link_url.trim() : "";
+  var ll = typeof body.link_label === "string" ? body.link_label.trim() : "";
+  if (lu || ll) { out.link_url = lu; out.link_label = ll; }
+  var sa = _epochFromForm(body.starts_at);  if (sa != null) out.starts_at = sa;
+  var ea = _epochFromForm(body.expires_at); if (ea != null) out.expires_at = ea;
+  return out;
+}
+
+function renderAdminAnnouncements(opts) {
+  opts = opts || {};
+  var rows = opts.announcements || [];
+  var created  = opts.created  ? "<div class=\"banner banner--ok\">Announcement saved.</div>" : "";
+  var archived = opts.archived ? "<div class=\"banner banner--ok\">Announcement 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/announcements\">All</a>" +
+    "<a class=\"chip" + (af === "1" ? " chip--on" : "") + "\" href=\"/admin/announcements?active=1\">Active now</a>" +
+    "</div>";
+
+  var bodyRows = rows.map(function (a) {
+    var isArchived = a.archived_at != null;
+    return "<tr>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(a.slug) + "</code></td>" +
+      "<td>" + _htmlEscape(a.message) + "</td>" +
+      "<td><span class=\"status-pill\">" + _htmlEscape(a.theme) + "</span></td>" +
+      "<td>" + _htmlEscape(a.audience) + "</td>" +
+      "<td><span class=\"status-pill " + (isArchived ? "cancelled" : "paid") + "\">" + (isArchived ? "archived" : "active") + "</span></td>" +
+      "<td><div class=\"actions-row\">" +
+        (isArchived ? "" :
+          "<form method=\"post\" action=\"/admin/announcements/" + _htmlEscape(encodeURIComponent(a.slug)) + "/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\">Slug</th><th scope=\"col\">Message</th><th scope=\"col\">Theme</th><th scope=\"col\">Audience</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No announcements" + (af === "1" ? " active right now" : " yet") + ".</p>";
+
+  var themeOpts = ["urgency", "promo", "info", "success"].map(function (t) {
+    return "<option value=\"" + t + "\"" + (t === "info" ? " selected" : "") + ">" + t + "</option>";
+  }).join("");
+  var audienceOpts = ["all", "guest", "logged_in"].map(function (au) {
+    return "<option value=\"" + au + "\">" + au + "</option>";
+  }).join("");
+
+  var createForm =
+    "<div class=\"panel mt mw-40\">" +
+      "<h3 class=\"subhead\">Create an announcement</h3>" +
+      "<p class=\"meta\">The highest-priority active announcement shows at the top of every page (urgency &gt; promo &gt; info &gt; success). Leave the schedule blank for an open-ended notice.</p>" +
+      "<form method=\"post\" action=\"/admin/announcements\">" +
+        _setupField("Slug", "slug", "", "text", "Lowercase, hyphenated — a stable id.", " maxlength=\"64\" required") +
+        "<label class=\"form-field\"><span>Message</span><textarea name=\"message\" maxlength=\"500\" required></textarea></label>" +
+        _setupField("Link URL (optional)", "link_url", "", "text", "https:// or a /-rooted path.", " maxlength=\"2048\"") +
+        _setupField("Link label (optional)", "link_label", "", "text", "", " maxlength=\"120\"") +
+        "<label class=\"form-field\"><span>Theme</span><select name=\"theme\">" + themeOpts + "</select></label>" +
+        "<label class=\"form-field\"><span>Audience</span><select name=\"audience\">" + audienceOpts + "</select></label>" +
+        "<label class=\"form-field\"><span>Starts at (optional)</span><input type=\"datetime-local\" name=\"starts_at\"></label>" +
+        "<label class=\"form-field\"><span>Expires at (optional)</span><input type=\"datetime-local\" name=\"expires_at\"></label>" +
+        "<label class=\"kv\"><input type=\"checkbox\" name=\"dismissible\" value=\"on\" checked> Visitors can dismiss this</label>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create announcement</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Announcements</h2>" + created + archived + notice + chips + table + createForm + "</section>";
+  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,17 @@
 {
-  "version": "0.2.3",
+  "version": "0.2.5",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-FgqvXcZygYkJjjOtXAeu9xi6AtYqkchPnJKcS0OeHm8lynhd9r4RfdpoT7P7j7/l",
       "fingerprinted": "css/admin.afd7b964c1f6fe1b.css"
     },
     "css/main.css": {
-      "integrity": "sha384-iKbkn3AR4k733EgN+1Ju51qbKfz9yVmDk8lE2l99asnRGbSo4BJu4Lo+OTxcBME4",
-      "fingerprinted": "css/main.5678b2596038b019.css"
+      "integrity": "sha384-G7yMuGZ4ojVoEpiRX70qcuR+YcQU4A1K/jRhRE/yPD7PXkqUH4LruBlu6MPCv+R8",
+      "fingerprinted": "css/main.b99ea24f442deef8.css"
+    },
+    "js/announcement.js": {
+      "integrity": "sha384-z4zcEMn+tScoVnYRE4nEf8N/oyvpxdpaxTNrT4QO/jURChid4+qjAvWkzatCaAPq",
+      "fingerprinted": "js/announcement.59eab4872d2f3b4c.js"
     },
     "js/consent.js": {
       "integrity": "sha384-KKMQ0og8HPOykRRPpUyxX7dMhTvKySfVtpGX/jGWzZwNaN/c4OykvRvXpqBHcQST",

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,