@soloworks/smking-next 0.22.2 → 0.22.3-beta.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @soloworks/smking-next
 
+## 0.22.3-beta.2 — 2026-10-01
+
+- Optional CMS v2 reads now use the Next.js data cache. A verified page remains
+  visible when source revalidation fails; a confirmed signed withdrawal expires
+  the data tag immediately. Strict publication evidence and explicit source
+  denial prevent proxy errors from masquerading as withdrawal or revocation.
+  Never-published slugs with a valid v2 source envelope still return 404.
+- The default remains v1. A fresh deployment has no previous cache, and AEO
+  and site files do not yet have the same v2 failure protection. Do not enable
+  whole-site v2 solely because this beta is installed.
+- Preserve the `smking-next` command-line installer in the npm package.
+
 ## 0.22.2 — 2026-07-26
 
 - `<SmkingCms>` now calls Next.js `notFound()` when Page Zero explicitly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.22.2",
+  "version": "0.22.3-beta.2",
   "description": "AI-native SEO (AEO) for Next.js — auto-inject JSON-LD, FAQ, AI summary, and SEO metadata so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your pages.",
   "license": "MIT",
   "homepage": "https://github.com/sillyleo/smking/tree/main/packages/smking-next",
@@ -65,31 +65,32 @@
     "perplexity",
     "smking"
   ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:cms-v2-runtime": "node scripts/test-cms-v2-runtime.mjs",
+    "test:watch": "vitest"
+  },
   "peerDependencies": {
     "next": "^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.2",
-    "@tiptap/core": "^3.23.4",
-    "@tiptap/extension-image": "^3.23.4",
-    "@tiptap/extension-link": "^3.23.4",
-    "@tiptap/starter-kit": "^3.23.4",
-    "@tiptap/static-renderer": "^3.23.4",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19",
-    "@vitejs/plugin-react": "^6.0.1",
-    "jsdom": "^29.1.0",
-    "next": "^16.2.2",
-    "react": "^19.0.0",
-    "react-dom": "19.2.4",
-    "typescript": "^5",
-    "vitest": "^4.1.5"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "@tiptap/core": "^3.29.2",
+    "@tiptap/extension-image": "^3.29.2",
+    "@tiptap/extension-link": "^3.29.2",
+    "@tiptap/starter-kit": "^3.29.2",
+    "@tiptap/static-renderer": "^3.29.2",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
+    "jsdom": "^30.0.1",
+    "next": "^16.2.12",
+    "react": "^19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   }
-}
+}

package/src/cms-blocks.ts

@@ -365,6 +365,7 @@ export interface CollageProps {
 }
 
 export type SocialSharePlatform =
+  | "x"
   | "threads"
   | "instagram"
   | "facebook"
@@ -372,8 +373,8 @@ export type SocialSharePlatform =
   | "copy";
 
 /**
- * `social-share` block — Threads / Instagram / Facebook / LINE share links +
- * copy-link.
+ * `social-share` block — X / Threads / Instagram / Facebook / LINE share
+ * links + copy-link.
  * Platform visibility is site-wide; `shareUrl` is the optional no-JS fallback
  * target (the `<smking-share>` web component overrides every link from
  * window.location at runtime, so the live share always points at the real

package/src/lib/client.ts

@@ -1,8 +1,12 @@
 // Type-only import loads Next.js's RequestInit augmentation so the
 // `next: { revalidate, tags }` property on fetch options typechecks.
 import type {} from "next";
+import { connection } from "next/server";
 
 import type { AeoResponse, DiscoverParams } from "../types";
+import { usesPublishedV2 } from "./delivery-v2";
+import { reportObservedPath } from "./report-v2";
+import { isPublishedReady } from "./published-v2";
 import { isPathWithinPrefix, normalizePath, resolveRequestPath } from "./path";
 import { SDK_VERSION } from "./version";
 
@@ -81,13 +85,14 @@ export async function getAeoContent(
 
   let path = params.path;
   let url = params.url;
+  const publishedV2 = usesPublishedV2();
   if (!path || !url) {
     try {
       const resolved = await resolveRequestPath();
       path = path ?? resolved.path;
       url = url ?? resolved.url;
     } catch {
-      return null;
+      if (!publishedV2 || !path) return null;
     }
   }
   path = normalizePath(path);
@@ -95,7 +100,30 @@ export async function getAeoContent(
     return null;
   }
 
+  // A v2 withdrawal cannot wait for a pre-rendered page or an ISR refresh.
+  // If the host cannot render this path dynamically, fail visibly at build
+  // instead of producing a success-shaped empty or stale page.
+  if (publishedV2) await connection();
+
   try {
+    if (publishedV2) {
+      const query = new URLSearchParams({ key: params.apiKey, path });
+      // A supplied URL can also be used while prerendering. Only a real
+      // request-scoped path is an observation of a visitor request.
+      try {
+        const current = await resolveRequestPath();
+        if (normalizePath(current.path) === path) {
+          reportObservedPath({ apiKey: params.apiKey, baseUrl, path, url: current.url });
+        }
+      } catch { /* Static rendering has no request observation. */ }
+      const res = await fetch(`${baseUrl}/api/v2/public/aeo?${query}`, {
+        cache: "no-store",
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      });
+      if (!res.ok) return null;
+      const body = (await res.json()) as AeoResponse;
+      return isPublishedReady(body, "aeo", `path:${path}`) ? body : null;
+    }
     const res = await fetch(`${baseUrl}/api/v1/public/aeo`, {
       method: "POST",
       headers: { "content-type": "application/json" },

package/src/lib/cms-client.ts

@@ -1,8 +1,13 @@
 // Type-only import loads Next.js's RequestInit augmentation so the
 // `next: { revalidate, tags }` property on fetch options typechecks.
 import type {} from "next";
+import { unstable_cache } from "next/cache";
+import { connection } from "next/server";
 
 import type { CmsParams, CmsResponse } from "../types";
+import { cmsV2CacheTag, usesPublishedV2 } from "./delivery-v2";
+import { reportObservedPath } from "./report-v2";
+import { isPublishedAbsent, isPublishedReady, isPublishedWithdrawal, publishedCmsDenial } from "./published-v2";
 import { resolveRequestPath } from "./path";
 import { SDK_VERSION } from "./version";
 
@@ -15,6 +20,36 @@ import { SDK_VERSION } from "./version";
 const DEFAULT_REVALIDATE_SECONDS = 300;
 const FETCH_TIMEOUT_MS = 2000;
 
+type PublishedCmsResult = CmsResponse | { status: "access_denied"; scope: "site" | "cms" };
+
+async function fetchPublishedCms(baseUrl: string, apiKey: string, slug: string): Promise<PublishedCmsResult> {
+  const query = new URLSearchParams({ key: apiKey, slug });
+  const res = await fetch(`${baseUrl}/api/v2/public/cms-page?${query}`, {
+    cache: "no-store",
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (res.status === 401 || res.status === 403) {
+    const type = res.headers.get("content-type")?.split(";")[0].trim().toLowerCase();
+    const length = Number(res.headers.get("content-length") ?? 0);
+    if (type === "application/json" && length <= 8192) {
+      const raw = await res.text();
+      if (raw.length <= 8192) {
+        try {
+          const scope = publishedCmsDenial(JSON.parse(raw), res.status);
+          if (scope) return { status: "access_denied", scope };
+        } catch { /* A proxy failure is not proof of lost authority. */ }
+      }
+    }
+    throw new Error("smking_v2_cms_unavailable");
+  }
+  if (res.status !== 200 && res.status !== 404) throw new Error("smking_v2_cms_unavailable");
+  const body = (await res.json()) as CmsResponse;
+  const identifier = `slug:${slug}`;
+  if (res.status === 404 && (isPublishedWithdrawal(body, "cms-page", identifier) || isPublishedAbsent(body))) return body;
+  if (res.status === 200 && isPublishedReady(body, "cms-page", identifier)) return body;
+  throw new Error("smking_v2_cms_unavailable");
+}
+
 const _warnedKeys = new Set<string>();
 function warnOnce(key: string, message: string): void {
   if (process.env.NODE_ENV === "production") return;
@@ -26,8 +61,10 @@ function warnOnce(key: string, message: string): void {
 /**
  * Fetch a published CMS page from the smking public API.
  *
- * Mirrors `getAeoContent` shape — same fail-open posture, same Next.js
- * data-cache integration. Returns null when:
+ * v1 mirrors `getAeoContent`'s fail-open posture and data-cache integration.
+ * v2 preserves explicit 404 and throws on source failure, so a Blog page
+ * never renders an empty successful response for a delivery failure.
+ * v1 returns null when:
  *   - apiKey or baseUrl missing (one-time dev warning)
  *   - network failure / 2s timeout
  *   - 4xx / 5xx response
@@ -43,7 +80,9 @@ function warnOnce(key: string, message: string): void {
 export async function getCmsPage(
   params: CmsParams,
 ): Promise<CmsResponse | null> {
+  const publishedV2 = usesPublishedV2() && !params.previewToken;
   if (!params.apiKey) {
+    if (publishedV2) throw new Error("smking_v2_cms_unavailable");
     warnOnce(
       "missing-api-key",
       "[@soloworks/smking-next/cms] apiKey is empty — skipping CMS render. Set SMKING_API_KEY or pass apiKey prop.",
@@ -56,6 +95,7 @@ export async function getCmsPage(
     "",
   );
   if (!baseUrl) {
+    if (publishedV2) throw new Error("smking_v2_cms_unavailable");
     warnOnce(
       "missing-base-url",
       "[@soloworks/smking-next/cms] SMKING_BASE_URL is not configured — skipping CMS render. Set the env var or pass baseUrl prop.",
@@ -67,6 +107,7 @@ export async function getCmsPage(
   // `/blog`. Only reject `undefined` / `null` — empty string is valid
   // and routes to the site's root page row in `productContent`.
   if (params.slug === undefined || params.slug === null) {
+    if (publishedV2) throw new Error("smking_v2_cms_unavailable");
     warnOnce(
       "missing-slug",
       "[@soloworks/smking-next/cms] slug prop is required (use \"\" for the root page).",
@@ -74,6 +115,28 @@ export async function getCmsPage(
     return null;
   }
 
+  // Public v2 is intentionally read-only. Draft preview keeps its separate,
+  // uncached v1 contract; neither request reports page URLs as a side effect.
+  if (publishedV2) {
+    await connection();
+    try {
+      try {
+        const current = await resolveRequestPath();
+        if (!params.path || params.path === current.path) {
+          reportObservedPath({ apiKey: params.apiKey, baseUrl, path: current.path, url: current.url });
+        }
+      } catch { /* Static rendering has no request observation. */ }
+      const result = await unstable_cache(fetchPublishedCms, ["smking:cms-page:v2"], {
+        revalidate: params.revalidate ?? DEFAULT_REVALIDATE_SECONDS,
+        tags: [cmsV2CacheTag(params.slug)],
+      })(baseUrl, params.apiKey, params.slug);
+      if (result.status === "access_denied") throw new Error("smking_v2_cms_unavailable");
+      return result;
+    } catch {
+      throw new Error("smking_v2_cms_unavailable");
+    }
+  }
+
   let requestPath = params.path;
   let requestUrl = params.url;
   if (!requestPath || !requestUrl) {

package/src/lib/delivery-notification-v2.ts

@@ -0,0 +1,238 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { revalidatePath, revalidateTag } from "next/cache";
+import { cmsV2CacheTag, usesPublishedV2 } from "./delivery-v2";
+
+type Resource = "aeo" | "cms-page" | "site-file";
+type Action = "update" | "withdraw";
+type Target = {
+  resource: Resource;
+  identifier: string;
+  action: Action;
+  revision: number;
+  generation: number;
+  withdrawalRevision: number;
+  contentVersion: string | null;
+};
+type Envelope = {
+  kind: "content_delivery_probe_v2" | "content_delivery_v2";
+  contract: "2";
+  deliveryId: string;
+  deliveredAt: string;
+  sourceUrl: string;
+  scope: string;
+  keyFingerprint: string;
+};
+type Probe = Envelope & { kind: "content_delivery_probe_v2"; resources: Resource[] };
+type Notification = Envelope & { kind: "content_delivery_v2"; targets: Target[] };
+type Configuration = {
+  sourceUrl: string;
+  apiKey: string;
+  scope: string;
+  keyFingerprint: string;
+  resources: Set<Resource>;
+  cmsPath: string | null;
+};
+
+const MAX_BODY_BYTES = 65_536;
+const MAX_SOURCE_BYTES = 2_097_152;
+const VERSION = /^sha256:[a-f0-9]{64}$/;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
+const RESOURCES = new Set<Resource>(["aeo", "cms-page", "site-file"]);
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function keys(value: Record<string, unknown>, expected: string[]): boolean {
+  return Object.keys(value).sort().join("\n") === expected.sort().join("\n");
+}
+
+function safePath(path: string): boolean {
+  if (!path.startsWith("/") || path.startsWith("//") || path.length > 500
+    || /[?#\\\x00-\x1f\x7f]/.test(path) || /%(2f|5c)/i.test(path)) return false;
+  try {
+    let decoded = path;
+    for (let i = 0; i < 3; i++) {
+      const next = decodeURIComponent(decoded);
+      if (next === decoded) break;
+      decoded = next;
+    }
+    return !/%[a-f0-9]{2}/i.test(decoded) && !decoded.startsWith("//")
+      && !/[?#\\\x00-\x1f\x7f]/.test(decoded)
+      && !decoded.split("/").some((part) => part === "." || part === "..");
+  } catch { return false; }
+}
+
+function validTarget(value: unknown): value is Target {
+  if (!record(value) || !keys(value, ["resource", "identifier", "action", "revision", "generation", "withdrawalRevision", "contentVersion"])) return false;
+  if (!RESOURCES.has(value.resource as Resource) || typeof value.identifier !== "string" || value.identifier.length > 512) return false;
+  const identifier = value.identifier;
+  if (value.resource === "aeo" && (!identifier.startsWith("path:") || !safePath(identifier.slice(5)))) return false;
+  if (value.resource === "cms-page") {
+    const slug = identifier.slice(5);
+    if (!identifier.startsWith("slug:") || slug.length > 200 || slug.startsWith("/")
+      || slug.endsWith("/") || !safePath(`/${slug}`)) return false;
+  }
+  if (value.resource === "site-file" && !["kind:sitemap", "kind:robots", "kind:llms_txt"].includes(identifier)) return false;
+  if (value.action !== "update" && value.action !== "withdraw") return false;
+  for (const field of ["revision", "generation", "withdrawalRevision"] as const) {
+    if (!Number.isSafeInteger(value[field]) || Number(value[field]) < 0 || Number(value[field]) > 2_147_483_647) return false;
+  }
+  if (Number(value.revision) < 1 || value.generation !== value.revision) return false;
+  return value.action === "withdraw"
+    ? value.withdrawalRevision === value.revision && value.contentVersion === null
+    : Number(value.withdrawalRevision) <= Number(value.revision)
+      && typeof value.contentVersion === "string" && VERSION.test(value.contentVersion);
+}
+
+function parse(value: unknown, bodyBytes: number): Probe | Notification | null {
+  if (bodyBytes < 1 || bodyBytes > MAX_BODY_BYTES || !record(value)) return null;
+  const probe = value.kind === "content_delivery_probe_v2";
+  if (!probe && value.kind !== "content_delivery_v2") return null;
+  if (!keys(value, ["kind", "contract", "deliveryId", "deliveredAt", "sourceUrl", "scope", "keyFingerprint", probe ? "resources" : "targets"])) return null;
+  if (value.contract !== "2" || typeof value.deliveryId !== "string" || !UUID.test(value.deliveryId)
+    || typeof value.deliveredAt !== "string" || typeof value.sourceUrl !== "string"
+    || typeof value.scope !== "string" || typeof value.keyFingerprint !== "string" || !/^[a-f0-9]{64}$/.test(value.keyFingerprint)) return null;
+  if (probe) {
+    if (!Array.isArray(value.resources) || value.resources.length < 1 || value.resources.length > 3
+      || new Set(value.resources).size !== value.resources.length
+      || !value.resources.every((item) => RESOURCES.has(item))) return null;
+    return value as Probe;
+  }
+  if (!Array.isArray(value.targets) || value.targets.length < 1 || value.targets.length > 16
+    || !value.targets.every(validTarget)
+    || new Set(value.targets.map((item: Target) => `${item.resource}\n${item.identifier}`)).size !== value.targets.length) return null;
+  return value as Notification;
+}
+
+function strictSource(input: string | undefined): string | null {
+  if (!input) return null;
+  try {
+    const url = new URL(input);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || !["", "/"].includes(url.pathname)) return null;
+    return url.origin;
+  } catch { return null; }
+}
+
+function configuration(): Configuration | null {
+  if (!usesPublishedV2()) return null;
+  const sourceUrl = strictSource(process.env.SMKING_BASE_URL);
+  const apiKey = process.env.SMKING_API_KEY;
+  const scope = process.env.SMKING_DELIVERY_NOTIFICATIONS_SCOPE;
+  const selected = process.env.SMKING_DELIVERY_NOTIFICATION_RESOURCES?.split(",");
+  if (!sourceUrl || !apiKey || !/^pk_[A-Za-z0-9_-]+$/.test(apiKey) || !scope
+    || !selected || selected.length < 1 || new Set(selected).size !== selected.length
+    || !selected.every((item) => RESOURCES.has(item as Resource))) return null;
+  const cmsPath = process.env.SMKING_CMS_PATH === "/"
+    ? "/" : process.env.SMKING_CMS_PATH?.replace(/\/+$/, "") || null;
+  if (selected.includes("cms-page") && (!cmsPath || !safePath(cmsPath))) return null;
+  return { sourceUrl, apiKey, scope, resources: new Set(selected as Resource[]), cmsPath,
+    keyFingerprint: createHash("sha256").update(apiKey).digest("hex") };
+}
+
+function equalDigest(left: string, right: string): boolean {
+  return left.length === right.length && timingSafeEqual(Buffer.from(left), Buffer.from(right));
+}
+
+function targetPath(target: Target, config: Configuration): string | null {
+  if (target.resource === "aeo") return target.identifier.slice(5);
+  if (target.resource === "cms-page") {
+    if (!config.cmsPath) return null;
+    const slug = target.identifier.slice(5);
+    return slug ? `${config.cmsPath === "/" ? "" : config.cmsPath}/${slug}` : config.cmsPath;
+  }
+  return ({ "kind:sitemap": "/sitemap.xml", "kind:robots": "/robots.txt", "kind:llms_txt": "/llms.txt" } as Record<string, string>)[target.identifier] ?? null;
+}
+
+function sourceUrl(target: Target, config: Configuration): string {
+  const query = new URLSearchParams({ key: config.apiKey });
+  if (target.resource === "aeo") query.set("path", target.identifier.slice(5));
+  if (target.resource === "cms-page") query.set("slug", target.identifier.slice(5));
+  if (target.resource === "site-file") query.set("kind", target.identifier.slice(5));
+  return `${config.sourceUrl}/api/v2/public/${target.resource}?${query}`;
+}
+
+async function boundedJson(response: Response): Promise<unknown> {
+  const declared = response.headers.get("content-length");
+  if (declared && (!/^\d+$/.test(declared) || Number(declared) > MAX_SOURCE_BYTES)) throw new Error("source_too_large");
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error("source_empty");
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      if (bytes > MAX_SOURCE_BYTES) throw new Error("source_too_large");
+      chunks.push(value);
+    }
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}
+
+/** The published source is the ordering authority; no per-instance Map is trusted. */
+async function sourceState(target: Target, config: Configuration): Promise<"match" | "obsolete" | null> {
+  try {
+    const response = await fetch(sourceUrl(target, config), {
+      method: "GET", cache: "no-store", credentials: "omit", redirect: "error",
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (response.status !== 200 && response.status !== 404) return null;
+    const body = await boundedJson(response);
+    if (!record(body) || !record(body.delivery) || body.delivery.contract !== "2"
+      || !record(body.delivery.publication)) return null;
+    const publication = body.delivery.publication;
+    if (publication.resource !== target.resource || publication.identifier !== target.identifier
+      || !Number.isSafeInteger(publication.revision)) return null;
+    if (Number(publication.revision) > target.revision) return "obsolete";
+    if (publication.revision !== target.revision || publication.generation !== target.generation
+      || publication.withdrawalRevision !== target.withdrawalRevision
+      || publication.action !== target.action || publication.contentVersion !== target.contentVersion) return null;
+    if (target.action === "withdraw") return response.status === 404 && body.status === "not_found" ? "match" : null;
+    return response.status === 200 && body.status === "ready" && body.delivery.content_version === target.contentVersion
+      ? "match" : null;
+  } catch { return null; }
+}
+
+function error(message: string, status: number): Response {
+  return Response.json({ ok: false, error: message }, { status, headers: { "Cache-Control": "no-store" } });
+}
+
+/** Called only after the common webhook has authenticated the exact raw body. */
+export async function receiveV2Notification(value: unknown, bodyBytes: number): Promise<Response> {
+  const payload = parse(value, bodyBytes);
+  if (!payload) return error("invalid_notification", 400);
+  const config = configuration();
+  if (!config) return error("notifications_unavailable", 503);
+  if (payload.sourceUrl !== config.sourceUrl || payload.scope !== config.scope
+    || !equalDigest(payload.keyFingerprint, config.keyFingerprint)) return error("notification_scope_mismatch", 401);
+  const resources = payload.kind === "content_delivery_probe_v2"
+    ? payload.resources : payload.targets.map((target) => target.resource);
+  if (!resources.every((resource) => config.resources.has(resource))) return error("unsupported_resource", 400);
+  const common = { ok: true, kind: payload.kind, contract: "2", deliveryId: payload.deliveryId,
+    sourceUrl: config.sourceUrl, scope: config.scope, keyFingerprint: config.keyFingerprint };
+  if (payload.kind === "content_delivery_probe_v2") {
+    return Response.json({ ...common, resources: payload.resources }, { headers: { "Cache-Control": "no-store" } });
+  }
+  const results: Array<{ target: Target; status: "registered" | "withdrawn" | "obsolete" }> = [];
+  for (const target of payload.targets) {
+    const path = targetPath(target, config);
+    if (!path) return error("unsupported_target", 400);
+    const state = await sourceState(target, config);
+    if (!state) return error("publication_unconfirmed", 503);
+    if (state === "match") {
+      try {
+        if (target.resource === "cms-page") {
+          revalidateTag(cmsV2CacheTag(target.identifier.slice(5)), target.action === "withdraw" ? { expire: 0 } : "max");
+        }
+        revalidatePath(path);
+      } catch { return error("revalidation_failed", 503); }
+    }
+    results.push({ target, status: state === "obsolete" ? "obsolete" : target.action === "withdraw" ? "withdrawn" : "registered" });
+  }
+  return Response.json({ ...common, results }, { headers: { "Cache-Control": "no-store" } });
+}

package/src/lib/delivery-v2.ts

@@ -0,0 +1,20 @@
+/** Installing the package alone never switches a site to the new source. */
+export function usesPublishedV2(): boolean {
+  return process.env.SMKING_CONTENT_API_VERSION === "2";
+}
+
+/** The CMS data-cache tag is shared by the reader and signed notification. */
+export function cmsV2CacheTag(slug: string): string {
+  return `smking:cms-page:v2:${slug}`;
+}
+
+export function siteFileUrl(
+  baseUrl: string,
+  apiKey: string,
+  kind: "sitemap" | "robots" | "llms_txt",
+): string {
+  // JSON includes delivery.publication; format=text does not carry the
+  // version or withdrawal evidence required before rendering v2 content.
+  const query = new URLSearchParams({ key: apiKey, kind });
+  return `${baseUrl.replace(/\/$/, "")}/api/v2/public/site-file?${query}`;
+}

package/src/lib/llms-txt-route.ts

@@ -1,3 +1,6 @@
+import { siteFileUrl, usesPublishedV2 } from "./delivery-v2";
+import { publishedSiteFile } from "./published-v2";
+
 /**
  * Drop-in `app/llms.txt/route.ts` GET handler. Proxies the canonical
  * llms.txt served by Page Zero at `/api/v1/public/llms-txt?key=...`.
@@ -25,24 +28,35 @@ export async function GET(): Promise<Response> {
   const baseUrl = process.env.SMKING_BASE_URL ?? "https://getpagezero.com";
 
   try {
+    const v2 = usesPublishedV2();
     const res = await fetch(
-      `${baseUrl}/api/v1/public/llms-txt?key=${encodeURIComponent(apiKey)}`,
-      {
+      v2
+        ? siteFileUrl(baseUrl, apiKey, "llms_txt")
+        : `${baseUrl}/api/v1/public/llms-txt?key=${encodeURIComponent(apiKey)}`,
+      v2 ? { cache: "no-store", signal: AbortSignal.timeout(10_000) } : {
         next: { revalidate: 3600 },
         signal: AbortSignal.timeout(10_000),
       },
     );
     if (!res.ok) {
-      return new Response("Not found", { status: 404 });
+      return v2
+        ? new Response("Unavailable", { status: res.status === 404 ? 404 : 503, headers: { "Cache-Control": "no-store" } })
+        : new Response("Not found", { status: 404 });
     }
-    const body = await res.text();
+    const body = v2
+      ? publishedSiteFile(await res.json(), "llms_txt")?.body
+      : await res.text();
+    if (body === undefined || body === null) return new Response("Unavailable", { status: 503, headers: { "Cache-Control": "no-store" } });
     return new Response(body, {
       headers: {
         "Content-Type": "text/plain; charset=utf-8",
         "X-Smking-Takeover": "llms_txt",
+        ...(v2 ? { "Cache-Control": "no-store" } : {}),
       },
     });
   } catch {
-    return new Response("Not found", { status: 404 });
+    return usesPublishedV2()
+      ? new Response("Unavailable", { status: 503, headers: { "Cache-Control": "no-store" } })
+      : new Response("Not found", { status: 404 });
   }
 }

package/src/lib/published-v2.ts

@@ -0,0 +1,91 @@
+type Resource = "aeo" | "cms-page" | "site-file";
+
+type PublishedDocument = {
+  status: "ready";
+  document: { kind: "sitemap" | "robots" | "llms_txt"; body: string; content_type: string };
+};
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+const VERSION = /^sha256:[a-f0-9]{64}$/;
+
+/** Validate the source's committed version before allowing v2 content into a page. */
+export function isPublishedReady(
+  value: unknown,
+  resource: Resource,
+  identifier: string,
+  now = Date.now(),
+): boolean {
+  if (!record(value) || value.status !== "ready" || !record(value.delivery)) return false;
+  const delivery = value.delivery;
+  if (delivery.contract !== "2" || typeof delivery.content_version !== "string"
+    || !VERSION.test(delivery.content_version) || !record(delivery.publication)) return false;
+  const validated = Date.parse(String(delivery.validated_at));
+  const fresh = Date.parse(String(delivery.fresh_until));
+  const usable = Date.parse(String(delivery.usable_until));
+  if (![validated, fresh, usable].every(Number.isFinite) || validated > fresh || fresh > usable || usable <= now) return false;
+  const publication = delivery.publication;
+  return publication.resource === resource && publication.identifier === identifier
+    && publication.action === "update" && Number.isSafeInteger(publication.revision)
+    && Number(publication.revision) >= 1 && publication.generation === publication.revision
+    && Number.isSafeInteger(publication.withdrawalRevision)
+    && Number(publication.withdrawalRevision) <= Number(publication.revision)
+    && publication.contentVersion === delivery.content_version;
+}
+
+/** A bare 404 (for example a proxy error) is not proof of withdrawal. */
+export function isPublishedWithdrawal(
+  value: unknown,
+  resource: Resource,
+  identifier: string,
+): boolean {
+  if (!record(value) || value.status !== "not_found" || !record(value.delivery)
+    || value.delivery.contract !== "2" || !record(value.delivery.publication)) return false;
+  const publication = value.delivery.publication;
+  return publication.resource === resource && publication.identifier === identifier
+    && publication.action === "withdraw" && Number.isSafeInteger(publication.revision)
+    && Number(publication.revision) >= 1 && publication.generation === publication.revision
+    && publication.withdrawalRevision === publication.revision
+    && publication.contentVersion === null;
+}
+
+/** A missing target with no publication record is an ordinary 404, not a withdrawal. */
+export function isPublishedAbsent(value: unknown, now = Date.now()): boolean {
+  if (!record(value) || value.status !== "not_found" || !record(value.delivery)) return false;
+  const delivery = value.delivery;
+  if (delivery.contract !== "2" || "publication" in delivery
+    || typeof delivery.content_version !== "string" || !VERSION.test(delivery.content_version)) return false;
+  const validated = Date.parse(String(delivery.validated_at));
+  const fresh = Date.parse(String(delivery.fresh_until));
+  const usable = Date.parse(String(delivery.usable_until));
+  return [validated, fresh, usable].every(Number.isFinite)
+    && validated <= fresh && fresh <= usable && usable > now;
+}
+
+/** Only Page Zero's exact JSON denial shape may revoke cached CMS content. */
+export function publishedCmsDenial(value: unknown, status: number): "site" | "cms" | null {
+  if (!record(value) || value.status !== "unavailable") return null;
+  const keys = Object.keys(value).sort().join(",");
+  if (status === 401) {
+    return keys === "error,status" && value.error === "invalid_key" ? "site" : null;
+  }
+  if (status !== 403 || keys !== "denial,error,status" || !record(value.denial)) return null;
+  const denial = value.denial;
+  if (Object.keys(denial).sort().join(",") !== "contract,scope" || denial.contract !== "2") return null;
+  if (denial.scope === "site" && value.error === "site_disabled") return "site";
+  if (denial.scope === "cms" && value.error === "cms_disabled") return "cms";
+  return null;
+}
+
+export function publishedSiteFile(
+  value: unknown,
+  kind: "sitemap" | "robots" | "llms_txt",
+): PublishedDocument["document"] | null {
+  if (!isPublishedReady(value, "site-file", `kind:${kind}`) || !record(value)) return null;
+  const document = value.document;
+  if (!record(document) || document.kind !== kind || typeof document.body !== "string"
+    || typeof document.content_type !== "string" || document.body.length > 2_097_152) return null;
+  return document as PublishedDocument["document"];
+}

package/src/lib/report-v2.ts

@@ -0,0 +1,69 @@
+import { createHmac, randomUUID } from "node:crypto";
+import { after } from "next/server";
+import { SDK_VERSION } from "./version";
+
+const seen = new Map<string, number>();
+const MAX_SEEN = 500;
+const REPORT_INTERVAL_MS = 60_000;
+
+/** Reports are independent of the public content GET and never delay rendering. */
+export function reportObservedPath(input: {
+  apiKey: string;
+  baseUrl: string;
+  path: string;
+  url?: string;
+}): void {
+  const secret = process.env.SMKING_WEBHOOK_SECRET;
+  if (!secret || !input.url || !input.path.startsWith("/") || input.path.startsWith("//") || /[?#\\]/.test(input.path)) return;
+  let host: string;
+  try {
+    const siteUrl = new URL(input.url);
+    if (siteUrl.protocol !== "https:" && siteUrl.protocol !== "http:") return;
+    host = siteUrl.host;
+  } catch { return; }
+
+  const key = `${host}\n${input.path}`;
+  const now = Date.now();
+  if (now - (seen.get(key) ?? 0) < REPORT_INTERVAL_MS) return;
+  for (const [candidate, queuedAt] of seen) {
+    if (now - queuedAt > REPORT_INTERVAL_MS) seen.delete(candidate);
+  }
+  if (seen.size >= MAX_SEEN) return;
+  seen.set(key, now);
+  try {
+    after(async () => {
+      const body = JSON.stringify({
+        key: input.apiKey,
+        report_id: randomUUID(),
+        observed_at: new Date().toISOString(),
+        sdk_meta: {
+          sdk: "next", sdk_version: SDK_VERSION,
+          app_env: process.env.NODE_ENV ?? null,
+          host,
+          cms_base_path: process.env.SMKING_CMS_PATH?.startsWith("/")
+            ? process.env.SMKING_CMS_PATH : null,
+        },
+        paths: [input.path],
+      });
+      const signature = createHmac("sha256", secret)
+        .update("smking-sdk-report-v2\n").update(body).digest("hex");
+      try {
+        const result = await fetch(`${input.baseUrl}/api/v2/sdk/report`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-smking-report-signature": `sha256=${signature}`,
+          },
+          body,
+          cache: "no-store",
+          signal: AbortSignal.timeout(2_000),
+        });
+        if (!result.ok) seen.delete(key);
+      } catch {
+        seen.delete(key);
+      }
+    });
+  } catch {
+    seen.delete(key); // Static export and non-request scopes cannot schedule work.
+  }
+}

package/src/lib/robots.ts

@@ -1,3 +1,6 @@
+import { siteFileUrl, usesPublishedV2 } from "./delivery-v2";
+import { publishedSiteFile } from "./published-v2";
+
 /**
  * AI-bot directives + Cloudflare `Content-Signal` for the customer's
  * `robots.txt`. Two surfaces because Next.js `MetadataRoute.Robots` doesn't
@@ -198,26 +201,39 @@ export default async function smkingRobotsRoute(): Promise<Response> {
     return permissiveFallback();
   }
   const apiKey = process.env.SMKING_API_KEY;
-  if (!apiKey) return permissiveFallback();
+  if (!apiKey) return usesPublishedV2()
+    ? new Response("Unavailable", { status: 503, headers: { "Cache-Control": "no-store" } })
+    : permissiveFallback();
   const baseUrl = process.env.SMKING_BASE_URL ?? "https://getpagezero.com";
 
   try {
+    const v2 = usesPublishedV2();
     const res = await fetch(
-      `${baseUrl}/api/v1/public/robots.txt?key=${encodeURIComponent(apiKey)}`,
-      {
+      v2
+        ? siteFileUrl(baseUrl, apiKey, "robots")
+        : `${baseUrl}/api/v1/public/robots.txt?key=${encodeURIComponent(apiKey)}`,
+      v2 ? { cache: "no-store", signal: AbortSignal.timeout(10_000) } : {
         next: { revalidate: 86_400 },
         signal: AbortSignal.timeout(10_000),
       },
     );
-    if (!res.ok) return permissiveFallback();
-    const body = await res.text();
+    if (!res.ok) return v2
+      ? new Response("Unavailable", { status: res.status === 404 ? 404 : 503, headers: { "Cache-Control": "no-store" } })
+      : permissiveFallback();
+    const body = v2
+      ? publishedSiteFile(await res.json(), "robots")?.body
+      : await res.text();
+    if (body === undefined || body === null) return new Response("Unavailable", { status: 503, headers: { "Cache-Control": "no-store" } });
     return new Response(body, {
       headers: {
         "Content-Type": "text/plain; charset=utf-8",
         "X-Smking-Takeover": "robots",
+        ...(v2 ? { "Cache-Control": "no-store" } : {}),
       },
     });
   } catch {
-    return permissiveFallback();
+    return usesPublishedV2()
+      ? new Response("Unavailable", { status: 503, headers: { "Cache-Control": "no-store" } })
+      : permissiveFallback();
   }
 }

package/src/lib/sitemap.ts

@@ -1,4 +1,7 @@
 import type { MetadataRoute } from "next";
+import { connection } from "next/server";
+import { siteFileUrl, usesPublishedV2 } from "./delivery-v2";
+import { publishedSiteFile } from "./published-v2";
 
 export const SMKING_SITEMAP_CACHE_TAG = "smking:sitemap";
 
@@ -29,14 +32,21 @@ export const SMKING_SITEMAP_CACHE_TAG = "smking:sitemap";
 export default async function smkingSitemap(): Promise<MetadataRoute.Sitemap> {
   if (process.env.SMKING_DISABLE_TAKEOVER_SITEMAP === "1") return [];
   const apiKey = process.env.SMKING_API_KEY;
-  if (!apiKey) return [];
+  const v2 = usesPublishedV2();
+  if (!apiKey) {
+    if (v2) throw new Error("smking_v2_sitemap_unavailable");
+    return [];
+  }
   const baseUrl = process.env.SMKING_BASE_URL ?? "https://getpagezero.com";
+  if (v2) await connection();
 
   let body: string;
   try {
     const res = await fetch(
-      `${baseUrl}/api/v1/public/sitemap.xml?key=${encodeURIComponent(apiKey)}`,
-      {
+      v2
+        ? siteFileUrl(baseUrl, apiKey, "sitemap")
+        : `${baseUrl}/api/v1/public/sitemap.xml?key=${encodeURIComponent(apiKey)}`,
+      v2 ? { cache: "no-store", signal: AbortSignal.timeout(10_000) } : {
         // Daily revalidation — sitemap doesn't change second-to-second.
         // The signed publish webhook invalidates this tag immediately when
         // AEO or CMS content changes; the TTL remains the fail-safe.
@@ -47,9 +57,23 @@ export default async function smkingSitemap(): Promise<MetadataRoute.Sitemap> {
         signal: AbortSignal.timeout(10_000),
       },
     );
-    if (!res.ok) return [];
-    body = await res.text();
+    if (!res.ok) {
+      if (v2) throw new Error(`smking_v2_sitemap_${res.status}`);
+      return [];
+    }
+    if (v2) {
+      const document = publishedSiteFile(await res.json(), "sitemap");
+      if (!document) throw new Error("smking_v2_sitemap_unverified");
+      body = document.body;
+      if (!/<urlset\b[^>]*>[\s\S]*<\/urlset>/.test(body)) {
+        throw new Error("smking_v2_sitemap_malformed");
+      }
+    } else {
+      body = await res.text();
+    }
   } catch {
+    // A transient v2 source failure must never become a successful empty 200.
+    if (usesPublishedV2()) throw new Error("smking_v2_sitemap_unavailable");
     return [];
   }
 

package/src/lib/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.22.2";
+export const SDK_VERSION = "0.22.3-beta.2";

package/src/lib/webhook-route.ts

@@ -1,6 +1,7 @@
 import { revalidateTag } from "next/cache";
 import { Buffer } from "node:buffer";
 import crypto from "node:crypto";
+import { receiveV2Notification } from "./delivery-notification-v2";
 import { SMKING_SITEMAP_CACHE_TAG } from "./sitemap";
 
 interface WebhookPayload {
@@ -120,6 +121,10 @@ export async function POST(request: Request): Promise<Response> {
     return Response.json({ error: "duplicate_delivery" }, { status: 401 });
   }
 
+  if (payload.kind === "content_delivery_probe_v2" || payload.kind === "content_delivery_v2") {
+    return receiveV2Notification(payload, Buffer.byteLength(rawBody));
+  }
+
   const kind = payload.kind;
   if (typeof kind !== "string" || kind.length === 0) {
     // Forward-compat: SaaS may emit kinds we haven't taught the SDK