@stack-mode/site-manager-kit 0.0.0-stage → 1.44.1

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@stack-mode/site-manager-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.44.1",
+  "description": "Reads a site's content from Site Manager and builds its metadata, sitemap, robots, redirects, forms and refreshes. For Next.js App Router sites on Vercel.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stack-mode/site-manager-kit.git"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./revalidate-route": "./src/revalidate-route.ts",
+    "./health-route": "./src/health-route.ts",
+    "./forms": "./src/forms.ts",
+    "./waitlist": "./src/waitlist.ts",
+    "./form-guard": "./src/form-guard.tsx",
+    "./redirects": "./src/redirects.ts",
+    "./not-found": "./src/not-found.ts",
+    "./not-found-reporter": "./src/not-found-reporter.tsx",
+    "./indexnow": "./src/indexnow.ts",
+    "./config": "./src/config.ts",
+    "./analytics": "./src/analytics.tsx",
+    "./preview-route": "./src/preview-route.ts",
+    "./preview-banner": "./src/preview-banner.tsx",
+    "./attribution": "./src/attribution.tsx",
+    "./phone": "./src/phone-input.tsx",
+    "./rss-route": "./src/rss-route.ts",
+    "./visual": "./src/visual.ts",
+    "./visual-tags": "./src/visual-tags.ts",
+    "./visual-accents": "./src/visual-accents.ts",
+    "./visual-editing": "./src/visual-bridge.tsx",
+    "./copy-keys": "./src/copy-keys.ts",
+    "./copy-keys-route": "./src/copy-keys-route.ts",
+    "./chat": "./src/site-chat.tsx",
+    "./chat-route": "./src/chat-route.ts"
+  },
+  "bin": {
+    "site-manager-kit": "./bin/site-manager-kit.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "audit",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "botid": ">=1",
+    "next": ">=16",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "botid": "^1.5.12",
+    "next": "^16.4.3",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/analytics.tsx

@@ -0,0 +1,23 @@
+import Script from "next/script";
+import { getSite } from "./data";
+
+/** Where the StackOS tracker loads from. A site with its own Content-Security-Policy allows it in script-src and connect-src. */
+export const STACKOS_TRACKER_ORIGIN = "https://app.mystackos.com";
+
+/**
+ * Put once inside <body> in app/layout.tsx. Adds StackOS's visitor tracking with the key the agency set in Site
+ * Manager, so changing or removing the key needs no code change. Renders nothing when there's no key, or when Site
+ * Manager can't be reached, so tracking never breaks a page.
+ */
+export async function SiteAnalytics() {
+  let key: string | undefined;
+  try {
+    const site = await getSite();
+    key = site?.tracking?.provider === "stackos" ? site.tracking.siteKey : undefined;
+  } catch {
+    return null;
+  }
+  // Site Manager only stores plain tokens; checked again because it ends up in every page.
+  if (!key || !/^[A-Za-z0-9_-]{8,64}$/.test(key)) return null;
+  return <Script src={`${STACKOS_TRACKER_ORIGIN}/v.js`} data-site={key} data-attribution="on" strategy="afterInteractive" />;
+}

package/src/announcements.ts

@@ -0,0 +1,13 @@
+import type { Announcement } from "./types";
+
+/** Notices live at `now`: started (or no start) and not yet ended. Start inclusive, end exclusive, as in Site Manager. */
+export function announcementsLiveAt(list: Announcement[], now = new Date()): Announcement[] {
+  const t = now.getTime();
+  return list.filter((a) => (!a.startsAt || Date.parse(a.startsAt) <= t) && (!a.endsAt || Date.parse(a.endsAt) > t));
+}
+
+/** True while a cached response is still current: Site Manager's `meta.nextChangeAt` hasn't passed. */
+export function cachedUntilPassed(meta: Record<string, unknown>, now = new Date()): boolean {
+  const next = typeof meta.nextChangeAt === "string" ? Date.parse(meta.nextChangeAt) : NaN;
+  return Number.isNaN(next) || next > now.getTime();
+}

package/src/attribution-fields.ts

@@ -0,0 +1,52 @@
+// Where a visitor came from, as hidden form fields. Shared by the browser side (attribution.tsx) and the form action
+// (forms.ts), so both use the same names. No cookies: values live in the tab's session storage.
+
+export const ATTRIBUTION_STORAGE_KEY = "bp_attribution";
+
+/** Hidden field name for each value Site Manager accepts as `attribution`. */
+export const ATTRIBUTION_FIELDS = {
+  source: "bp_utm_source",
+  medium: "bp_utm_medium",
+  campaign: "bp_utm_campaign",
+  content: "bp_utm_content",
+  term: "bp_utm_term",
+  landingPath: "bp_landing",
+  referrer: "bp_referrer",
+} as const;
+
+export type Attribution = Partial<Record<keyof typeof ATTRIBUTION_FIELDS, string>>;
+
+const MAX = 300;
+
+/**
+ * The visit's first touch, from the landing page's address and referrer: utm_ values, the path (no query), and the
+ * referring site's host when it's another site. Pure, for tests and for the browser.
+ */
+export function firstTouch(href: string, referrer: string): Attribution {
+  const url = new URL(href);
+  const a: Attribution = {};
+  for (const k of ["source", "medium", "campaign", "content", "term"] as const) {
+    const v = url.searchParams.get(`utm_${k}`)?.trim();
+    if (v) a[k] = v.slice(0, MAX);
+  }
+  a.landingPath = url.pathname.slice(0, MAX);
+  try {
+    const ref = referrer ? new URL(referrer) : null;
+    if (ref && ref.host !== url.host && (ref.protocol === "https:" || ref.protocol === "http:")) a.referrer = ref.host;
+  } catch {
+    // An unreadable referrer is simply left out.
+  }
+  return a;
+}
+
+/** The attribution a submitted form carries, read from its hidden fields. Undefined when there's none. */
+export function attributionFrom(formData: FormData): Attribution | undefined {
+  const a: Attribution = {};
+  for (const [k, name] of Object.entries(ATTRIBUTION_FIELDS) as [keyof Attribution, string][]) {
+    const v = formData.get(name);
+    if (typeof v === "string" && v.trim()) a[k] = v.trim().slice(0, MAX);
+  }
+  return Object.keys(a).length ? a : undefined;
+}
+
+export const ATTRIBUTION_FIELD_NAMES: ReadonlySet<string> = new Set(Object.values(ATTRIBUTION_FIELDS));

package/src/attribution.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { ATTRIBUTION_FIELDS, ATTRIBUTION_STORAGE_KEY, firstTouch, type Attribution } from "./attribution-fields";
+
+/** The visit's first touch: stored once per tab, so later pages keep where the visitor first came from. */
+function rememberedTouch(): Attribution | null {
+  try {
+    const saved = sessionStorage.getItem(ATTRIBUTION_STORAGE_KEY);
+    if (saved) return JSON.parse(saved) as Attribution;
+    const a = firstTouch(window.location.href, document.referrer);
+    sessionStorage.setItem(ATTRIBUTION_STORAGE_KEY, JSON.stringify(a));
+    return a;
+  } catch {
+    // Storage can be off (some private modes). The current page is then the best we know.
+    try {
+      return firstTouch(window.location.href, document.referrer);
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Put once inside <body> in app/layout.tsx. Remembers where the visitor first came from (utm_ values, landing page,
+ * referring site) for this browser tab, with no cookie, so forms can send it with a submission. Renders nothing.
+ */
+export function SiteAttribution() {
+  useEffect(() => {
+    rememberedTouch();
+  }, []);
+  return null;
+}
+
+/** Hidden fields with the remembered first touch. FormGuard includes these, so forms send them with no extra code. */
+export function AttributionFields() {
+  const [a, setA] = useState<Attribution | null>(null);
+  useEffect(() => {
+    setA(rememberedTouch());
+  }, []);
+  if (!a) return null;
+  return (
+    <>
+      {(Object.entries(ATTRIBUTION_FIELDS) as [keyof Attribution, string][]).map(([k, name]) => (a[k] ? <input key={name} type="hidden" name={name} value={a[k]} /> : null))}
+    </>
+  );
+}

package/src/blog.ts

@@ -0,0 +1,122 @@
+import { bp, bpWithMeta, tagsFor } from "./client";
+import type { BlogCategory, BlogFeed, BlogPage, BlogPost, BlogPostSummary, BlogTag, Paging } from "./types";
+
+// Reads for the Blog section. Posts are cached under the blog tag; a single post also under seo, since its search
+// listing is edited in Search Listings.
+
+type PageOpts = { page?: number; perPage?: number };
+
+const q = (params: Record<string, string | number | undefined | null>) => {
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null && v !== "") sp.set(k, String(v));
+  const s = sp.toString();
+  return s ? `?${s}` : "";
+};
+
+const emptyPaging = (o: PageOpts): Paging => ({ page: o.page ?? 1, perPage: o.perPage ?? 10, total: 0, totalPages: 0 });
+
+function paging(meta: Record<string, unknown>, o: PageOpts): Paging {
+  const n = (k: keyof Paging) => (typeof meta[k] === "number" ? (meta[k] as number) : emptyPaging(o)[k]);
+  return { page: n("page"), perPage: n("perPage"), total: n("total"), totalPages: n("totalPages") };
+}
+
+/** Published posts, newest first, a page at a time (`perPage` up to 50), optionally in one category or with one tag (by slug). */
+export async function getPosts(opts: PageOpts & { category?: string; tag?: string } = {}): Promise<BlogPage> {
+  const r = await bpWithMeta<BlogPostSummary[]>(`/blog/posts${q({ page: opts.page, perPage: opts.perPage, category: opts.category, tag: opts.tag })}`, { tags: tagsFor("blog") });
+  return r ? { posts: r.data, paging: paging(r.meta, opts) } : { posts: [], paging: emptyPaging(opts) };
+}
+
+/** One published post with its body and search listing, or null. */
+export const getPost = (slug: string) => bp<BlogPost>(`/blog/posts/${encodeURIComponent(slug)}`, { tags: tagsFor("blog", "seo") });
+
+export const getBlogCategories = async () => (await bp<BlogCategory[]>("/blog/categories", { tags: tagsFor("blog") })) ?? [];
+
+/** One category and a page of its posts, or null when there's no such category. */
+export async function getBlogCategory(slug: string, opts: PageOpts = {}): Promise<{ category: BlogCategory; posts: BlogPostSummary[]; paging: Paging } | null> {
+  const r = await bpWithMeta<{ category: BlogCategory; posts: BlogPostSummary[] }>(`/blog/categories/${encodeURIComponent(slug)}${q({ page: opts.page, perPage: opts.perPage })}`, { tags: tagsFor("blog") });
+  return r ? { ...r.data, paging: paging(r.meta, opts) } : null;
+}
+
+export const getBlogTags = async () => (await bp<BlogTag[]>("/blog/tags", { tags: tagsFor("blog") })) ?? [];
+
+/** The newest posts with full bodies, shaped for RSS (`limit` up to 50, default 20). */
+export const getBlogFeed = (opts: { limit?: number } = {}) => bp<BlogFeed>(`/blog/feed${q({ limit: opts.limit })}`, { tags: tagsFor("blog", "business_info", "seo") });
+
+const xml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+// CDATA can't contain its own end marker, so one is split across two sections.
+const cdata = (s: string) => `<![CDATA[${s.replace(/]]>/g, "]]]]><![CDATA[>")}]]>`;
+
+/**
+ * Pure: an RSS 2.0 document from the feed. `feedUrl` is this feed's own address (for the atom:link self reference),
+ * and `link` overrides the website address when Site Manager doesn't have one.
+ */
+export function buildRss(feed: BlogFeed, opts: { feedUrl?: string; link?: string; title?: string; description?: string } = {}): string {
+  const link = opts.link ?? feed.link ?? "";
+  const self = opts.feedUrl ?? feed.feedUrl;
+  const items = feed.items.map((i) =>
+    [
+      "<item>",
+      `<title>${xml(i.title)}</title>`,
+      i.link ? `<link>${xml(i.link)}</link>` : "",
+      `<guid isPermaLink="${i.guidIsPermaLink ? "true" : "false"}">${xml(i.guid)}</guid>`,
+      i.pubDate ? `<pubDate>${xml(i.pubDate)}</pubDate>` : "",
+      i.author ? `<dc:creator>${xml(i.author)}</dc:creator>` : "",
+      ...i.categories.map((c) => `<category>${xml(c)}</category>`),
+      i.summary ? `<description>${xml(i.summary)}</description>` : "",
+      i.contentHtml ? `<content:encoded>${cdata(i.contentHtml)}</content:encoded>` : "",
+      i.image ? `<enclosure url="${xml(i.image.url)}" type="${xml(imageType(i.image.url))}" length="0"/>` : "",
+      "</item>",
+    ]
+      .filter(Boolean)
+      .join(""),
+  );
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/">',
+    "<channel>",
+    `<title>${xml(opts.title ?? feed.title)}</title>`,
+    `<link>${xml(link)}</link>`,
+    `<description>${xml(opts.description ?? feed.description ?? feed.title)}</description>`,
+    `<language>${xml(feed.language)}</language>`,
+    feed.updatedAt ? `<lastBuildDate>${new Date(feed.updatedAt).toUTCString()}</lastBuildDate>` : "",
+    self ? `<atom:link href="${xml(self)}" rel="self" type="application/rss+xml"/>` : "",
+    ...items,
+    "</channel>",
+    "</rss>",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function imageType(url: string): string {
+  const ext = url.split("?")[0].split(".").pop()?.toLowerCase();
+  return ext === "png" ? "image/png" : ext === "webp" ? "image/webp" : ext === "gif" ? "image/gif" : ext === "avif" ? "image/avif" : "image/jpeg";
+}
+
+/**
+ * Pure: schema.org BlogPosting JSON-LD for a post page. Put it in a `<script type="application/ld+json">` with
+ * `JSON.stringify(...).replace(/</g, "\\u003c")`. Fields that aren't known are left out rather than guessed.
+ */
+export function blogPostingJsonLd(post: BlogPost, opts: { publisherName?: string; publisherLogo?: string; url?: string } = {}): Record<string, unknown> {
+  const url = opts.url ?? post.seo?.canonical ?? post.url ?? undefined;
+  const image = post.cover?.url ?? post.seo?.ogImage?.url;
+  const out: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": "BlogPosting",
+    headline: post.title.slice(0, 110),
+  };
+  if (url) {
+    out.url = url;
+    out.mainEntityOfPage = { "@type": "WebPage", "@id": url };
+  }
+  if (post.seo?.description ?? post.excerpt) out.description = post.seo?.description ?? post.excerpt;
+  if (image) out.image = [image];
+  if (post.publishedAt) out.datePublished = post.publishedAt;
+  out.dateModified = post.updatedAt;
+  if (post.author) out.author = { "@type": "Person", name: post.author.name, ...(post.author.url ? { url: post.author.url } : {}) };
+  if (opts.publisherName) out.publisher = { "@type": "Organization", name: opts.publisherName, ...(opts.publisherLogo ? { logo: { "@type": "ImageObject", url: opts.publisherLogo } } : {}) };
+  if (post.categories.length) out.articleSection = post.categories.map((c) => c.name);
+  if (post.tags.length) out.keywords = post.tags.map((t) => t.name).join(", ");
+  if (post.wordCount) out.wordCount = post.wordCount;
+  return out;
+}

package/src/chat-route.ts

@@ -0,0 +1,136 @@
+import { createHash } from "node:crypto";
+
+/*
+ * The website's own chat route, between the visitor's browser and Site Manager: the browser never sees the API key,
+ * Site Manager never sees the visitor's IP address (only its hash), and only this website's pages can use it.
+ *
+ *   // app/api/blueprint/chat/route.ts
+ *   export { GET, POST } from "site-manager-kit/chat-route";
+ *
+ * POST { type: "message", conversationId?, visitorId, message, pageUrl?, hp? }   streams the reply (NDJSON)
+ * POST { type: "lead", conversationId, visitorId, name, email, phone, message, slot?, hp?, attribution? }
+ * GET  ?slots=1&from=YYYY-MM-DD                                                  open times the chat can book
+ */
+
+const MAX_BODY = 20_000;
+
+function env(name: string): string {
+  const v = process.env[name]?.trim();
+  if (!v) throw new Error(`${name} is not set`);
+  return v;
+}
+
+const json = (body: unknown, status = 200, headers: Record<string, string> = {}) => Response.json(body, { status, headers: { "cache-control": "no-store", ...headers } });
+
+/** Only this website's own pages may use the route, so nobody else can spend the site's AI key through it. */
+export function sameOrigin(req: Request): boolean {
+  const host = req.headers.get("x-forwarded-host") ?? req.headers.get("host");
+  if (!host) return false;
+  const origin = req.headers.get("origin");
+  if (!origin) return req.headers.get("sec-fetch-site") === "same-origin";
+  try {
+    return new URL(origin).host === host;
+  } catch {
+    return false;
+  }
+}
+
+function visitorIpHash(req: Request): string | undefined {
+  const ip = req.headers.get("x-real-ip") ?? req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "";
+  return ip ? createHash("sha256").update(ip).digest("hex") : undefined;
+}
+
+async function isBot(): Promise<boolean> {
+  try {
+    const { checkBotId } = await import("botid/server");
+    const r = await checkBotId();
+    return r.isBot && !r.isVerifiedBot;
+  } catch {
+    // BotID isn't set up on this site. Site Manager's limits and the honeypot still apply.
+    return false;
+  }
+}
+
+async function upstream(path: string, init: RequestInit): Promise<Response> {
+  const base = env("BLUEPRINT_URL").replace(/\/+$/, "");
+  return fetch(`${base}/api/v1${path}`, {
+    cache: "no-store",
+    ...init,
+    headers: { authorization: `Bearer ${env("BLUEPRINT_API_KEY")}`, ...(init.body ? { "content-type": "application/json" } : {}) },
+  });
+}
+
+const str = (v: unknown, max: number) => (typeof v === "string" ? v.slice(0, max) : undefined);
+
+export async function POST(req: Request): Promise<Response> {
+  if (!sameOrigin(req)) return json({ error: "forbidden" }, 403);
+  const raw = await req.text();
+  if (raw.length > MAX_BODY) return json({ error: "too_large" }, 413);
+  let body: Record<string, unknown>;
+  try {
+    body = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return json({ error: "bad_request" }, 400);
+  }
+  const common = {
+    conversationId: str(body.conversationId, 64),
+    visitorId: str(body.visitorId, 100),
+    ipHash: visitorIpHash(req),
+    userAgent: req.headers.get("user-agent")?.slice(0, 500) ?? undefined,
+    hp: str(body.hp, 200),
+  };
+
+  if (body.type === "message") {
+    if (await isBot()) return json({ error: "forbidden" }, 403);
+    const res = await upstream("/chat", {
+      method: "POST",
+      body: JSON.stringify({ ...common, message: str(body.message, 5000) ?? "", pageUrl: str(body.pageUrl, 2000) ?? req.headers.get("referer") ?? undefined }),
+    });
+    if (!res.ok || !res.body) {
+      const err = (await res.json().catch(() => null)) as { error?: { code?: string; reason?: string } } | null;
+      const retry = res.headers.get("retry-after");
+      const status = res.status === 429 || res.status === 422 || res.status === 404 || res.status === 400 ? res.status : 502;
+      return json({ error: err?.error?.reason ?? err?.error?.code ?? "unavailable" }, status, retry ? { "retry-after": retry } : {});
+    }
+    // Passed through as it streams, so the visitor sees the reply being written.
+    return new Response(res.body, { status: 200, headers: { "content-type": "application/x-ndjson; charset=utf-8", "cache-control": "no-store", "x-accel-buffering": "no" } });
+  }
+
+  if (body.type === "lead") {
+    const attribution = body.attribution && typeof body.attribution === "object" ? (body.attribution as Record<string, unknown>) : {};
+    const res = await upstream("/chat/lead", {
+      method: "POST",
+      body: JSON.stringify({
+        ...common,
+        name: str(body.name, 200) ?? "",
+        email: str(body.email, 320) ?? "",
+        phone: str(body.phone, 40) ?? "",
+        message: str(body.message, 2000) ?? "",
+        slot: str(body.slot, 40),
+        // A bot gets the usual thanks and nothing is stored, as with forms.
+        ...((await isBot()) ? { hp: "kit:bot" } : {}),
+        attribution: { landingPath: str(attribution.landingPath, 2000), referrer: str(attribution.referrer, 2000) },
+      }),
+    });
+    const out = (await res.json().catch(() => null)) as { data?: { successMessage: string }; error?: { fields?: Record<string, string> } } | null;
+    if (res.status === 201 && out?.data) return json({ ok: true, successMessage: out.data.successMessage });
+    if (res.status === 422) return json({ ok: false, error: "invalid", fields: out?.error?.fields ?? {} });
+    if (res.status === 409) return json({ ok: false, error: "slot_taken", fields: out?.error?.fields ?? {} });
+    if (res.status === 429) return json({ ok: false, error: "rate_limited" });
+    return json({ ok: false, error: "unavailable" });
+  }
+
+  return json({ error: "bad_request" }, 400);
+}
+
+export async function GET(req: Request): Promise<Response> {
+  if (!sameOrigin(req)) return json({ error: "forbidden" }, 403);
+  const url = new URL(req.url);
+  if (!url.searchParams.has("slots")) return json({ error: "bad_request" }, 400);
+  const q = new URLSearchParams({ days: "7" });
+  const from = url.searchParams.get("from");
+  if (from && /^\d{4}-\d{2}-\d{2}$/.test(from)) q.set("from", from);
+  const res = await upstream(`/chat/slots?${q}`, { method: "GET" });
+  const out = (await res.json().catch(() => null)) as { data?: unknown } | null;
+  return res.ok && out?.data ? json(out.data) : json({ error: "unavailable" }, 404);
+}

package/src/chat-types.ts

@@ -0,0 +1,76 @@
+// Website Chat shapes and the reader for its streamed replies. Plain code, safe in the browser and on the server.
+
+/** GET /api/v1/chat. `live` false: the site shows no chat. */
+export type ChatConfig = {
+  live: boolean;
+  name: string;
+  greeting: string;
+  suggestedQuestions: string[];
+  /** The chat can offer open times and book one. */
+  canBook: boolean;
+  /** The site's accent color from Site Manager, or null. The component's own `accent` prop wins. */
+  accent: string | null;
+  retentionDays: number;
+};
+
+/** One line of a streamed reply. */
+export type ChatEvent =
+  | { type: "start"; conversationId: string }
+  | { type: "delta"; text: string }
+  | { type: "done"; unanswered: boolean; handoff: boolean; booking: boolean }
+  | { type: "error"; code: string };
+
+export type ChatSlotDay = { date: string; slots: { start: string; end: string; label: string }[] };
+export type ChatSlots = { timezone: string; slotMinutes: number; days: ChatSlotDay[] };
+
+export type ChatLeadResult = { ok: true; successMessage: string } | { ok: false; error: "invalid" | "slot_taken" | "rate_limited" | "unavailable"; fields?: Record<string, string> };
+
+/** Splits streamed NDJSON into events, keeping a partial last line for the next chunk. Unknown lines are skipped. */
+export function parseChatLines(buffer: string): { events: ChatEvent[]; rest: string } {
+  const events: ChatEvent[] = [];
+  const lines = buffer.split("\n");
+  const rest = lines.pop() ?? "";
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line) as ChatEvent;
+      if (e && typeof e === "object" && typeof e.type === "string") events.push(e);
+    } catch {
+      // A broken line: skip it rather than lose the rest of the reply.
+    }
+  }
+  return { events, rest };
+}
+
+/** Reads a streamed reply, calling `onEvent` for each event as it arrives. */
+export async function readChatStream(body: ReadableStream<Uint8Array>, onEvent: (e: ChatEvent) => void): Promise<void> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    const { events, rest } = parseChatLines(buf);
+    buf = rest;
+    for (const e of events) onEvent(e);
+  }
+  for (const e of parseChatLines(`${buf}\n`).events) onEvent(e);
+}
+
+/**
+ * Text color on the accent: near-black on a light accent (a lime or yellow), white on a dark one, so the button and
+ * the visitor's messages stay readable whatever the site's color. Colors it can't read get white.
+ */
+export function textOn(color: string): string {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+  if (!m) return "#ffffff";
+  const hex = m[1].length === 3 ? [...m[1]].map((c) => c + c).join("") : m[1];
+  const [r, g, b] = [0, 2, 4].map((i) => {
+    const c = parseInt(hex.slice(i, i + 2), 16) / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  // White wins below this luminance (the point where both have equal contrast).
+  return lum > 0.179 ? "#111318" : "#ffffff";
+}

package/src/client.ts

@@ -0,0 +1,116 @@
+/*
+ * The one place requests to Site Manager are made. Server only: the API key must never reach a browser.
+ *
+ * Env (server only, never NEXT_PUBLIC_):
+ *   BLUEPRINT_URL         Site Manager's address, for example https://manager.example.com
+ *   BLUEPRINT_API_KEY     this site's key (bp_...)
+ *   BLUEPRINT_SITE_ID     this site's id, shown on its Connection tab in Site Manager
+ *   BLUEPRINT_REVALIDATE_SECRET  the website connection secret, also used to sign preview reads
+ */
+
+import { unstable_cache } from "next/cache";
+import { draftMode } from "next/headers";
+import { PREVIEW_HEADER, signPreviewHeader } from "./preview";
+
+export class BlueprintError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public code?: string,
+  ) {
+    super(message);
+    this.name = "BlueprintError";
+  }
+}
+
+function env(name: string): string {
+  const v = process.env[name]?.trim();
+  if (!v) throw new BlueprintError(`${name} is not set`, 0, "config");
+  return v;
+}
+
+export function siteId(): string {
+  return env("BLUEPRINT_SITE_ID");
+}
+
+/** Cache tags match what Site Manager sends when content changes: bp:<siteId> and bp:<siteId>:<module>. */
+export function tagsFor(...modules: string[]): string[] {
+  const id = siteId();
+  return [`bp:${id}`, ...modules.map((m) => `bp:${id}:${m}`)];
+}
+
+type Options = { tags?: string[]; method?: "GET" | "POST"; body?: unknown; cache?: "no-store" };
+
+type Envelope<T> = { data: T; meta: Record<string, unknown> };
+
+async function request<T>(base: string, path: string, init: RequestInit, whole = false): Promise<T | null> {
+  const res = await fetch(`${base}/api/v1${path}`, init);
+  if (res.status === 404) return null;
+  if (res.status === 204) return null;
+  const json = (await res.json().catch(() => null)) as { data?: unknown; meta?: Record<string, unknown>; error?: { code?: string } } | null;
+  if (!res.ok) throw new BlueprintError(`Site Manager answered ${res.status} for ${path}`, res.status, json?.error?.code);
+  if (whole) return (json && json.data !== undefined ? { data: json.data, meta: json.meta ?? {} } : null) as T | null;
+  return (json?.data ?? null) as T | null;
+}
+
+/**
+ * Fetches `/api/v1<path>`. Reads are cached for an hour and refreshed early by tag when Site Manager says content
+ * changed. Returns null for a 404, throws BlueprintError for anything else that isn't OK (errors aren't cached).
+ *
+ * Reads use unstable_cache rather than fetch's own cache options because it behaves the same with Cache Components
+ * on or off, and like the fetch cache it lasts across deployments and servers.
+ *
+ * In a preview opened from Site Manager (draft mode), reads skip the cache and include drafts and scheduled changes.
+ */
+export async function bp<T>(path: string, opts: Options = {}): Promise<T | null> {
+  return read<T>(path, opts, false);
+}
+
+/** Like bp, but keeps the response's `meta` too (paging counts), as `{ data, meta }`. */
+export async function bpWithMeta<T>(path: string, opts: Options = {}): Promise<Envelope<T> | null> {
+  return read<Envelope<T>>(path, opts, true);
+}
+
+async function read<T>(path: string, opts: Options, whole: boolean): Promise<T | null> {
+  const base = env("BLUEPRINT_URL").replace(/\/+$/, "");
+  const method = opts.method ?? "GET";
+  const preview = method === "GET" && (await inPreview());
+  const headers: Record<string, string> = { authorization: `Bearer ${env("BLUEPRINT_API_KEY")}` };
+  if (opts.body !== undefined) headers["content-type"] = "application/json";
+  if (preview) headers[PREVIEW_HEADER] = signPreviewHeader(env("BLUEPRINT_REVALIDATE_SECRET"));
+  const init: RequestInit = {
+    method,
+    cache: "no-store",
+    headers,
+    ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
+  };
+  if (preview || opts.cache === "no-store" || method === "POST") return request<T>(base, path, init, whole);
+  return unstable_cache(() => request<T>(base, path, init, whole), ["site-manager-kit", base, siteId(), path, ...(whole ? ["meta"] : [])], {
+    tags: opts.tags ?? tagsFor(),
+    revalidate: 3600,
+  })();
+}
+
+/**
+ * Whether this request is a preview opened from Site Manager (Next.js draft mode). Readable inside `use cache`
+ * scopes too. Outside a request (build time, generateStaticParams) there is no preview.
+ */
+async function inPreview(): Promise<boolean> {
+  try {
+    return (await draftMode()).isEnabled;
+  } catch {
+    return false;
+  }
+}
+
+/** For writes that return an error body worth reading (form submits). */
+export async function bpRaw(path: string, body: unknown): Promise<{ status: number; json: unknown }> {
+  const base = env("BLUEPRINT_URL").replace(/\/+$/, "");
+  const res = await fetch(`${base}/api/v1${path}`, {
+    method: "POST",
+    cache: "no-store",
+    headers: { authorization: `Bearer ${env("BLUEPRINT_API_KEY")}`, "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, json: await res.json().catch(() => null) };
+}