@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/pages/api/dev/diff.ts

@@ -0,0 +1,68 @@
+/**
+ * GET /api/dev/diff?path= — Phase 2 (cp-diff) of the hosted /dev cockpit
+ * (workstream tot-lime-cloud-dev-cockpit, decision
+ * architecture-environment-aware-cockpit). Diffs the developer's draft
+ * overlay against published for one path, returning the SAME shape as the
+ * local loop's `/__tot/diff` (scripts/dev/git-status.mjs handleDiff —
+ * {ok,path,status,shown,before,after}) so dev.astro's existing diff UI
+ * (doDiff/renderDiff) needs no client-side change.
+ *
+ * No git in the Worker — "status" derives from draft-present-vs-published
+ * instead of `git status`: "unchanged" (no draft, or draft equals
+ * published), "modified" (draft differs from an existing published value),
+ * "added" (a draft exists for a path with no published counterpart yet —
+ * e.g. a brand-new pages-html/<slug>.html the developer hasn't published).
+ * Both sides are the raw-HTML/JSON writable surface, always text — no binary
+ * degrade case exists here (unlike the local loop's arbitrary file tree).
+ */
+import type { APIContext } from "astro";
+import { json } from "@/lib/grants/route.js";
+import {
+  resolveCockpitContext,
+  isCockpitContext,
+  isWritablePath,
+  readPublishedPath,
+  resolveDraftState,
+} from "@/lib/dev/hostedCockpit";
+
+export const prerender = false;
+
+const MAX_DIFF_BYTES = 512 * 1024;
+
+export async function GET(context: APIContext): Promise<Response> {
+  const ctx = await resolveCockpitContext(context);
+  if (!isCockpitContext(ctx)) return ctx;
+
+  const path = new URL(context.request.url).searchParams.get("path");
+  if (!path) return json({ ok: false, status: "no_path", message: "path query param is required" }, 400);
+  if (!isWritablePath(path)) {
+    return json({ ok: false, status: "bad_path", message: `Not available on the hosted panel: ${path}` }, 400);
+  }
+
+  const [published, { draftContent }] = await Promise.all([
+    readPublishedPath(ctx, path),
+    resolveDraftState(context, ctx, path),
+  ]);
+
+  if (published === null && draftContent === null) {
+    return json({ ok: false, status: "not_found", message: `No such file: ${path}` }, 404);
+  }
+
+  const status =
+    draftContent === null
+      ? "unchanged"
+      : published === null
+        ? "added"
+        : draftContent === published
+          ? "unchanged"
+          : "modified";
+
+  const before = published ?? "";
+  const after = draftContent ?? published ?? "";
+  const size = new TextEncoder().encode(before + after).length;
+  if (size > MAX_DIFF_BYTES) {
+    return json({ ok: true, path, status, shown: false, reason: "too_big" });
+  }
+
+  return json({ ok: true, path, status, shown: true, before, after });
+}

package/apps/storefront/src/pages/api/dev/file.ts

@@ -0,0 +1,57 @@
+/**
+ * GET /api/dev/file?path= — Phase 1 (cp-file) of the hosted /dev cockpit
+ * (workstream tot-lime-cloud-dev-cockpit, decision
+ * architecture-environment-aware-cockpit). Reads one file off the same
+ * synthesized tree cp-tree (/api/dev/tree) lists, mirroring the local loop's
+ * `/__tot/file` response contract (scripts/dev/file-browser.mjs readFile/
+ * handleFile) so dev.astro's filesScript viewer needs no client-side change.
+ *
+ * `path` is one of the three shapes cp-tree ever lists — content/home.html,
+ * content/pages-html/<slug>.html, or theme.json (scripts/dev/safe-path.mjs
+ * WRITE_ALLOWLIST) — so this route is a closed switch on those shapes, not a
+ * general path resolver; anything else is a clean 400, never a traversal risk.
+ *
+ * Reads the developer's OWN draft overlay first (readEffectivePath), falling
+ * back to published — so re-opening a file after a cp-write save shows the
+ * edit, and the `mtimeMs` it hands back is the SAME contentVersion() cp-write
+ * checks on the next save (the C6 stale-write guard).
+ *
+ * `writable:true` on all three is intentional now that cp-write exists: this
+ * is genuinely the editable surface.
+ */
+import type { APIContext } from "astro";
+import { json } from "@/lib/grants/route.js";
+import {
+  resolveCockpitContext,
+  isCockpitContext,
+  isWritablePath,
+  languageForPath,
+  readEffectivePath,
+  contentVersion,
+} from "@/lib/dev/hostedCockpit";
+
+export const prerender = false;
+
+const MAX_FILE_BYTES = 512 * 1024;
+
+export async function GET(context: APIContext): Promise<Response> {
+  const ctx = await resolveCockpitContext(context);
+  if (!isCockpitContext(ctx)) return ctx;
+
+  const path = new URL(context.request.url).searchParams.get("path");
+  if (!path) return json({ ok: false, status: "no_path", message: "path query param is required" }, 400);
+  if (!isWritablePath(path)) {
+    return json({ ok: false, status: "bad_path", message: `Not available on the hosted panel: ${path}` }, 400);
+  }
+
+  const { content } = await readEffectivePath(context, ctx, path);
+  if (content === null) return json({ ok: false, status: "not_found", message: `No such file: ${path}` }, 404);
+
+  const language = languageForPath(path);
+  const mtimeMs = contentVersion(content);
+  const size = new TextEncoder().encode(content).length;
+  if (size > MAX_FILE_BYTES) {
+    return json({ ok: true, status: "ok", path, tooBig: true, size, language, content: null, mtimeMs, writable: true });
+  }
+  return json({ ok: true, status: "ok", path, size, language, content, mtimeMs, writable: true });
+}

package/apps/storefront/src/pages/api/dev/locate.ts

@@ -0,0 +1,125 @@
+/**
+ * POST /api/dev/locate — Phase 2 (cp-locate) of the hosted /dev cockpit
+ * (workstream tot-lime-cloud-dev-cockpit, decision
+ * architecture-environment-aware-cockpit). Click-to-source in the Worker:
+ * given a clicked preview URL + captured DOM path, resolve the source
+ * line:col in the developer's raw-HTML content, using the exact SAME pure
+ * parse5 walk as the local loop (scripts/dev/locate.mjs `locate()`) and the
+ * same URL -> content-path mapping (scripts/dev/locate-handler.mjs
+ * `resolvePageSource`), both imported directly (dependency-free besides
+ * parse5, safe in the Worker).
+ *
+ * Honors decision click-to-source-anchors-at-content-region from the
+ * local-loop board: a click resolves against the raw content region only; the
+ * storefront's own chrome (header/nav/footer, not in tenant source) refuses
+ * explicitly with `not_in_content`, never a coincidental miss.
+ *
+ * Unlike the local route, this reads the developer's DRAFT overlay first
+ * (readEffectivePath) — correct, since that's what their preview iframe is
+ * actually showing once they've saved an edit (cp-write). No open-in-editor
+ * equivalent: the jump lands in the in-cockpit editor via the existing
+ * tot:locate postMessage handler (c8Script), already wired and unchanged.
+ *
+ * Only `locate()` itself is imported from scripts/dev/locate.mjs (pure,
+ * parse5-only — Workers-safe). The URL->content-path mapping
+ * (resolvePageSource in scripts/dev/locate-handler.mjs) is reimplemented
+ * here rather than imported, because that module also pulls in node:fs +
+ * node:child_process (open-in-editor) which have no place in a Worker
+ * bundle; isWritablePath (hostedCockpit.ts) already IS this route's write
+ * allowlist, so the two definitions can't drift.
+ *
+ * NOTE (scope): this ships the server contract only. The client picker
+ * widget (src/lib/dev/ai-widget-client.js) that lets a developer click an
+ * element in the preview has no hosted injection path yet (dev-only today,
+ * see rawMarketingHtml.ts) — tracked separately as cp-locate-widget-injection
+ * so that security-sensitive gating gets its own review rather than riding
+ * in here.
+ */
+import type { APIContext } from "astro";
+import { json } from "@/lib/grants/route.js";
+import { locate } from "../../../../../../scripts/dev/locate.mjs";
+import {
+  resolveCockpitContext,
+  isCockpitContext,
+  readEffectivePath,
+  isWritablePath,
+} from "@/lib/dev/hostedCockpit";
+
+export const prerender = false;
+
+interface LocateBody {
+  path?: unknown;
+  domPath?: unknown;
+}
+
+/**
+ * Map a clicked preview URL to its raw-HTML content source, root-relative.
+ * Mirrors scripts/dev/locate-handler.mjs's resolvePageSource exactly (see
+ * that module's header for the mapping rules); duplicated rather than
+ * imported for the node:fs-free-Worker-bundle reason above.
+ */
+function resolvePreviewPageSource(pathname: string, appDomain: string): string | null {
+  let clean: string;
+  try {
+    clean = decodeURIComponent(pathname.split("?")[0]!.split("#")[0]!);
+  } catch {
+    return null;
+  }
+  const segments = clean.split("/").filter(Boolean);
+  if (segments.length && segments[0] === appDomain) segments.shift();
+  if (segments.some((s) => s === "..")) return null;
+  const rel = segments.length === 0 ? "content/home.html" : `content/pages-html/${segments.join("/")}.html`;
+  return isWritablePath(rel) ? rel : null;
+}
+
+function isDomPath(domPath: unknown): domPath is Array<{ tag: string; index: number }> {
+  return (
+    Array.isArray(domPath) &&
+    domPath.length > 0 &&
+    domPath.every(
+      (s) => s && typeof s === "object" && typeof (s as any).tag === "string" && Number.isFinite(Number((s as any).index)),
+    )
+  );
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const ctx = await resolveCockpitContext(context);
+  if (!isCockpitContext(ctx)) return ctx;
+
+  let body: LocateBody;
+  try {
+    body = (await context.request.json()) as LocateBody;
+  } catch {
+    return json({ ok: false, status: "bad_json", message: "invalid JSON body" }, 400);
+  }
+
+  if (!isDomPath(body.domPath)) {
+    return json({ ok: false, status: "bad_dom_path", message: "domPath must be a non-empty array of {tag,index}" }, 400);
+  }
+
+  const rel = typeof body.path === "string" ? resolvePreviewPageSource(body.path, ctx.tenant.appDomain) : null;
+  if (!rel) {
+    return json({
+      ok: false,
+      status: "not_raw_html",
+      message: "This page isn’t a raw-HTML content page — click-to-source is for content/*.html tenants.",
+    });
+  }
+
+  const { content } = await readEffectivePath(context, ctx, rel);
+  if (content === null) {
+    return json({ ok: false, status: "not_raw_html", message: "No raw-HTML source backs this page." });
+  }
+
+  const found = locate(content, body.domPath);
+  if (typeof (found as { line?: number }).line === "number") {
+    const { line, col } = found as { line: number; col: number };
+    return json({ ok: true, path: rel, line, col });
+  }
+  return json({
+    ok: false,
+    status: "not_in_content",
+    message:
+      "That element is part of the storefront frame (header, nav, or footer), not your content source. Click something inside your page content.",
+  });
+}

package/apps/storefront/src/pages/api/dev/publish.ts

@@ -0,0 +1,128 @@
+/**
+ * POST /api/dev/publish — Phase 3 (cp-publish) of the hosted /dev cockpit
+ * (workstream tot-lime-cloud-dev-cockpit). Publishes the developer's current
+ * draft content for one file into the tenant's TEST channel — the moment the
+ * private draft overlay (cp-write) becomes something OTHER viewers can see
+ * (still not live).
+ *
+ * SCOPE (see decision cp-publish-scope-correction): the card's literal plan
+ * ("wire to api/preview/promote.ts") doesn't fit this surface — that route
+ * needs a server-to-server bearer secret + a CDP-driven compliance
+ * GateReport, and operates on the Gitea-fed preview/live channel, not the
+ * dev-draft: overlay. Instead this uses the lower-level primitive the
+ * reconcile pipeline itself is built on — `publishToTest`
+ * (private-controlplane/customization-versioning.ts) over `KVVersionStore` —
+ * writing straight into the SAME published-artifact store
+ * `readPublishedArtifact`/`PublishedContentProvider` read. Content-addressed
+ * + idempotent by construction (re-publishing identical bytes is a no-op).
+ *
+ * Deliberately test-only: promoting test -> live is the real external-publish
+ * action and isn't reachable from this surface (see decision + the dispatched
+ * cp-publish-go-live follow-up). "Publish" here closes write -> preview ->
+ * diff -> publish-to-test, honestly, without faking or bypassing the
+ * existing compliance gate.
+ */
+import type { APIContext } from "astro";
+import { json } from "@/lib/grants/route.js";
+import { readKv } from "@/lib/env";
+import {
+  publishToTest,
+  CustomizationError,
+  KVVersionStore,
+  type CustomizationManifest,
+} from "@tot/private-controlplane";
+import { contentArtifactPath, themeArtifactPath } from "@tot/public-runtime";
+import {
+  resolveCockpitContext,
+  isCockpitContext,
+  isWritablePath,
+  pageSlugForPath,
+  resolveDraftState,
+} from "@/lib/dev/hostedCockpit";
+
+export const prerender = false;
+
+// The developer's editable raw-HTML/theme surface, in ARTIFACT-path shape
+// (tenants/<id>/...) — what publishToTest's isEditable check and the
+// published-artifact store both key on. Not the tenant's real
+// declarative-customization manifest (out of scope here): this is
+// defense-in-depth on top of the isWritablePath gate already enforced below.
+const PUBLISH_MANIFEST: CustomizationManifest = {
+  version: 1,
+  classes: {
+    "platform-owned": [],
+    "extension-point": [],
+    "tenant-owned": ["tenants/<id>/content/home.html", "tenants/<id>/content/pages-html/**", "tenants/<id>/theme.json"],
+  },
+  immutableCompliance: [],
+};
+
+/**
+ * Map this route's short content path (content/home.html, theme.json, ...)
+ * to the artifact path the published-artifact store actually keys on
+ * (contentArtifactPath/themeArtifactPath — the SAME mapping
+ * PublishedContentProvider's getHomeHtml/getPageHtml use internally via
+ * `publishedRaw`). Only ever called after isWritablePath(path) passed, so
+ * every branch here has a defined result.
+ */
+function artifactPathFor(tenantId: string, path: string): string {
+  if (path === "theme.json") return themeArtifactPath(tenantId);
+  if (path === "content/home.html") return contentArtifactPath(tenantId, "home.html");
+  return contentArtifactPath(tenantId, `pages-html/${pageSlugForPath(path)}.html`);
+}
+
+interface PublishBody {
+  path?: unknown;
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const ctx = await resolveCockpitContext(context);
+  if (!isCockpitContext(ctx)) return ctx;
+
+  let body: PublishBody;
+  try {
+    body = (await context.request.json()) as PublishBody;
+  } catch {
+    return json({ ok: false, status: "bad_content", message: "invalid JSON body" }, 400);
+  }
+
+  const path = typeof body.path === "string" ? body.path : "";
+  if (!path) return json({ ok: false, status: "no_path", message: "path is required" }, 400);
+  if (!isWritablePath(path)) {
+    return json({ ok: false, status: "not_writable", message: `not in the write allowlist: ${path}` }, 403);
+  }
+
+  const { draftContent } = await resolveDraftState(context, ctx, path);
+  if (draftContent === null) {
+    return json(
+      { ok: false, status: "no_draft", message: "You have no unpublished edit for this file — nothing to publish." },
+      409,
+    );
+  }
+
+  const kv = await readKv("TENANT_CACHE");
+  if (!kv) {
+    // No KV bound (e.g. bare local build) — accept but report unpersisted,
+    // matching cp-write's degraded-mode contract rather than a broken call.
+    return json({ ok: true, status: "ok", path, applied: false });
+  }
+
+  const store = new KVVersionStore(kv);
+  const artifactPath = artifactPathFor(ctx.tenant.tenant_id, path);
+  try {
+    const result = await publishToTest(store, PUBLISH_MANIFEST, ctx.tenant.tenant_id, artifactPath, draftContent);
+    return json({
+      ok: true,
+      status: "ok",
+      path,
+      applied: true,
+      versionId: result.artifact.versionId,
+      channel: "test",
+    });
+  } catch (err) {
+    if (err instanceof CustomizationError) {
+      return json({ ok: false, status: err.code, message: err.message }, 409);
+    }
+    throw err;
+  }
+}

package/apps/storefront/src/pages/api/dev/tree.ts

@@ -0,0 +1,70 @@
+/**
+ * GET /api/dev/tree — Phase 1 (cp-tree) of the hosted /dev cockpit
+ * (workstream tot-lime-cloud-dev-cockpit, decision
+ * architecture-environment-aware-cockpit). Lists the signed-in developer's OWN
+ * tenant content so the hosted cockpit's Files tab renders the same tree shape
+ * the local loop's `/__tot/tree` does (see scripts/dev/file-browser.mjs
+ * buildTree/handleTree — this route mirrors its {ok,tree} response contract,
+ * consumed unchanged by dev.astro's filesScript via the cp-env apiBase resolver).
+ *
+ * Unlike the local tree (an arbitrary on-disk directory walk), the hosted
+ * Worker has no filesystem — the tree here is SYNTHESIZED from exactly the
+ * raw-HTML surface the content provider chain understands + the write
+ * allowlist (scripts/dev/safe-path.mjs WRITE_ALLOWLIST): content/home.html,
+ * content/pages-html/<slug>.html, and theme.json. A tenant on structured
+ * (Storyblok/JSON) content simply has an emptier tree — nothing to browse/edit
+ * on this raw-HTML surface yet.
+ */
+import type { APIContext } from "astro";
+import { json } from "@/lib/grants/route.js";
+import { readPublishedArtifact, themeArtifactPath } from "@tot/public-runtime";
+import { resolveCockpitContext, isCockpitContext } from "@/lib/dev/hostedCockpit";
+
+export const prerender = false;
+
+type TreeNode =
+  | { name: string; path: string; type: "file"; language: string | null }
+  | { name: string; path: string; type: "dir"; children: TreeNode[] };
+
+export async function GET(context: APIContext): Promise<Response> {
+  const ctx = await resolveCockpitContext(context);
+  if (!isCockpitContext(ctx)) return ctx;
+  const { tenant, provider, kvGet } = ctx;
+
+  const [homeHtml, pageSlugs, themeRaw] = await Promise.all([
+    provider.getHomeHtml(),
+    provider.listPageHtmlSlugs(),
+    readPublishedArtifact(kvGet, tenant.tenant_id, "live", themeArtifactPath(tenant.tenant_id)),
+  ]);
+
+  const contentChildren: TreeNode[] = [];
+  if (homeHtml !== null) {
+    contentChildren.push({ name: "home.html", path: "content/home.html", type: "file", language: "html" });
+  }
+  if (pageSlugs.length > 0) {
+    contentChildren.push({
+      name: "pages-html",
+      path: "content/pages-html",
+      type: "dir",
+      children: pageSlugs
+        .slice()
+        .sort((a, b) => a.localeCompare(b))
+        .map((slug) => ({
+          name: `${slug}.html`,
+          path: `content/pages-html/${slug}.html`,
+          type: "file" as const,
+          language: "html",
+        })),
+    });
+  }
+
+  const tree: TreeNode[] = [];
+  if (contentChildren.length > 0) {
+    tree.push({ name: "content", path: "content", type: "dir", children: contentChildren });
+  }
+  if (themeRaw !== null) {
+    tree.push({ name: "theme.json", path: "theme.json", type: "file", language: "json" });
+  }
+
+  return json({ ok: true, tenantId: tenant.tenant_id, tree });
+}

package/apps/storefront/src/pages/api/dev/write.ts

@@ -0,0 +1,116 @@
+/**
+ * POST /api/dev/write — Phase 2 (cp-write) of the hosted /dev cockpit
+ * (workstream tot-lime-cloud-dev-cockpit, decision
+ * architecture-environment-aware-cockpit). The heart of cloud editing: a
+ * direct text edit (not an AI prompt) written into the developer's PRIVATE
+ * draft overlay, reusing /api/content-edit/ai-edit.ts's exact materialization
+ * mechanism (dev-draft: KV keys + signed tot_dev_draft cookie the middleware
+ * overlay reads) — so the /dev live preview reflects the edit and no other
+ * viewer/channel is touched. Same request/response contract as the local
+ * loop's `/__tot/write` (scripts/dev/file-writer.mjs handleWrite), including
+ * the C6 baseVersion 409 conflict guard — but "version" here is
+ * contentVersion() (a content hash), not a filesystem mtime, since the Worker
+ * has none; cp-file hands back the same hash so the two agree.
+ *
+ * Deviates from file-writer.mjs in one place: a theme.json write must parse as
+ * JSON before it lands (mirrors ai-edit.ts's guard) — this draft overlay feeds
+ * the SAME live preview theme.json ai-edit writes, and a malformed draft would
+ * degrade that preview for the developer, unlike a plain on-disk write.
+ *
+ * When KV or the signing secret is unavailable (e.g. no CUSTOMIZATION_PREVIEW_SECRET
+ * configured for this env), the edit is accepted but not persisted —
+ * `applied:false`, exactly ai-edit's degraded-mode contract — never a broken call.
+ */
+import type { APIContext } from "astro";
+import { json } from "@/lib/grants/route.js";
+import { DEV_DRAFT_TTL_SECONDS, devDraftKey } from "@/lib/dev/devDraft";
+import {
+  resolveCockpitContext,
+  isCockpitContext,
+  isWritablePath,
+  readPublishedPath,
+  resolveDraftState,
+  contentVersion,
+  setDraftCookie,
+} from "@/lib/dev/hostedCockpit";
+
+export const prerender = false;
+
+const MAX_WRITE_BYTES = 2 * 1024 * 1024;
+
+interface WriteBody {
+  path?: unknown;
+  content?: unknown;
+  baseVersion?: unknown;
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  const ctx = await resolveCockpitContext(context);
+  if (!isCockpitContext(ctx)) return ctx;
+
+  let body: WriteBody;
+  try {
+    body = (await context.request.json()) as WriteBody;
+  } catch {
+    return json({ ok: false, status: "bad_content", message: "invalid JSON body" }, 400);
+  }
+
+  const path = typeof body.path === "string" ? body.path : "";
+  if (!path) return json({ ok: false, status: "no_path", message: "path is required" }, 400);
+  if (!isWritablePath(path)) {
+    return json({ ok: false, status: "not_writable", message: `not in the write allowlist: ${path}` }, 403);
+  }
+
+  const content = body.content;
+  if (typeof content !== "string") {
+    return json({ ok: false, status: "bad_content", message: "content must be a string" }, 400);
+  }
+  if (new TextEncoder().encode(content).length > MAX_WRITE_BYTES) {
+    return json({ ok: false, status: "too_large", message: "content exceeds the write size limit" }, 413);
+  }
+  if (path === "theme.json") {
+    try {
+      JSON.parse(content);
+    } catch {
+      return json({ ok: false, status: "bad_content", message: "theme.json must be valid JSON" }, 400);
+    }
+  }
+
+  // Stale-write guard (C6): compare the caller's baseVersion against the
+  // developer's CURRENT value for this path (their draft if one exists, else
+  // published) — omit baseVersion to force-save, exactly the local contract.
+  const { draftId, draftContent } = await resolveDraftState(context, ctx, path);
+  const currentContent = draftContent !== null ? draftContent : await readPublishedPath(ctx, path);
+  const currentVersion = contentVersion(currentContent);
+  const baseVersion = typeof body.baseVersion === "number" ? body.baseVersion : undefined;
+  if (baseVersion !== undefined && currentVersion !== baseVersion) {
+    return json(
+      {
+        ok: false,
+        status: "conflict",
+        current: currentVersion,
+        message:
+          currentVersion === null
+            ? `${path} was deleted since you opened it`
+            : `${path} changed since you opened it`,
+      },
+      409,
+    );
+  }
+
+  const bytes = new TextEncoder().encode(content).length;
+  const mtimeMs = contentVersion(content);
+
+  if (!ctx.kvPut || !ctx.draftSecret) {
+    // Nothing to persist against (e.g. bare local build with no KV/secret) —
+    // report success without pretending the draft landed, like ai-edit.
+    return json({ ok: true, status: "ok", path, bytes, mtimeMs, applied: false });
+  }
+
+  await ctx.kvPut(devDraftKey(ctx.tenant.tenant_id, draftId, path), content, {
+    expirationTtl: DEV_DRAFT_TTL_SECONDS,
+  });
+  await setDraftCookie(context, ctx, draftId);
+
+  return json({ ok: true, status: "ok", path, bytes, mtimeMs, applied: true });
+}

package/apps/storefront/src/pages/api/newsletter.ts

@@ -0,0 +1,104 @@
+/**
+ * Newsletter signup endpoint.
+ *
+ * ASSUMPTION (Phase 1): there is no ESP integration yet. We persist the email to
+ * the TENANT_CACHE KV namespace when the Cloudflare runtime binding is present
+ * (key `newsletter:<email>`), and otherwise just log. Wiring a real ESP
+ * (Klaviyo/Mailchimp) is a documented Phase 2 swap at the marked spot below.
+ *
+ * Robustness: a signup must NEVER 500. All failures degrade to a friendly
+ * thank-you so the visitor is never shown an error for handing us their email.
+ */
+import type { APIContext } from "astro";
+import { readKv } from "@/lib/env";
+
+// Minimal, permissive email shape check — we are not the source of truth for
+// deliverability; the ESP validates properly downstream.
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function thankYou(message: string, status = 200): Response {
+  const html = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>Thank you</title>
+    <style>
+      :root { color-scheme: light dark; }
+      body { font-family: ui-serif, Georgia, serif; margin: 0; min-height: 100vh;
+        display: grid; place-items: center; padding: 2rem; text-align: center;
+        background: #f4f1ea; color: #2f3a34; }
+      .card { max-width: 30rem; }
+      h1 { font-size: clamp(1.6rem, 4vw, 2.2rem); margin: 0 0 0.75rem; }
+      p { color: #5a655e; line-height: 1.6; }
+      a { color: #2f3a34; font-weight: 600; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>You're on the list.</h1>
+      <p>${message}</p>
+      <p><a href="/">Back to the shop →</a></p>
+    </div>
+  </body>
+</html>`;
+  return new Response(html, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  // Off for marketing tenants — they capture leads via external CTAs.
+  if (!context.locals.features.newsletter) {
+    return new Response(null, { status: 404 });
+  }
+  try {
+    const form = await context.request.formData();
+    const email = String(form.get("email") ?? "").trim().toLowerCase();
+    const source = String(form.get("source") ?? "unknown").trim();
+
+    if (!EMAIL_RE.test(email)) {
+      return thankYou(
+        "That address didn't look quite right — head back and try again.",
+        200,
+      );
+    }
+
+    // Persist. Phase 1: KV stub. Phase 2: replace with an ESP API call here.
+    const kv = await readKv("TENANT_CACHE");
+    if (kv) {
+      await kv.put(
+        `newsletter:${email}`,
+        JSON.stringify({ email, source, at: new Date().toISOString() }),
+      );
+    } else {
+      // No KV binding (local/dev): log and move on.
+      console.log(`[newsletter] signup ${email} (source: ${source})`);
+    }
+
+    // Redirect back where they came from (or home) with a success flag, so the
+    // page can show its own confirmation in-context. Falls back to the
+    // thank-you page if there's no usable referer.
+    const referer = context.request.headers.get("referer");
+    if (referer) {
+      try {
+        const back = new URL(referer);
+        back.searchParams.set("subscribed", "1");
+        return Response.redirect(back.toString(), 303);
+      } catch {
+        // fall through to thank-you
+      }
+    }
+    return thankYou("We'll send word when something worth knowing lands.");
+  } catch {
+    // Never 500 on a signup.
+    return thankYou("We'll send word when something worth knowing lands.");
+  }
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  // Nothing to render here directly — bounce back to the shop.
+  return context.redirect("/", 303);
+}