@soloworks/smking-next 0.10.0 → 0.12.1

package/src/lib/crawlers.ts

@@ -0,0 +1,136 @@
+/**
+ * AI bot + referral detection. Shared by `smkingProxy` (Next.js middleware)
+ * and any caller that wants to classify a request before forwarding it to
+ * the smking ingestion endpoint.
+ *
+ * Patterns are 2026-04 active list — see
+ * docs/ai-tracking-implementation.md A.2 for sourcing notes. Quarterly
+ * refresh from Cloudflare Radar / Dark Visitors / each vendor's docs.
+ *
+ * Detection precedence:
+ *   1. Bot UA match → `purpose` derived from bot category
+ *   2. No bot, but referer is an AI search surface → `purpose = ai_referral`
+ *   3. Otherwise → no record (we don't store noise)
+ */
+
+export type AiBotCategory = "training" | "search" | "user_triggered";
+
+export type AiHitPurpose =
+  | "training"
+  | "realtime_citation"
+  | "ai_referral"
+  | "unknown";
+
+interface CrawlerPattern {
+  readonly name: string;
+  readonly regex: RegExp;
+  readonly category: AiBotCategory;
+}
+
+const PATTERNS: readonly CrawlerPattern[] = [
+  // OpenAI
+  { name: "GPTBot", regex: /GPTBot\/[\d.]+/, category: "training" },
+  { name: "OAI-SearchBot", regex: /OAI-SearchBot\/[\d.]+/, category: "search" },
+  { name: "ChatGPT-User", regex: /ChatGPT-User\/[\d.]+/, category: "user_triggered" },
+  // Anthropic
+  { name: "ClaudeBot", regex: /ClaudeBot\/[\d.]+/, category: "training" },
+  { name: "Claude-Web", regex: /Claude-Web\/[\d.]+/, category: "user_triggered" },
+  { name: "anthropic-ai", regex: /anthropic-ai/, category: "training" },
+  // Perplexity
+  { name: "PerplexityBot", regex: /PerplexityBot\/[\d.]+/, category: "training" },
+  { name: "Perplexity-User", regex: /Perplexity-User\/[\d.]+/, category: "user_triggered" },
+  // Google
+  { name: "Google-Extended", regex: /Google-Extended/, category: "training" },
+  { name: "GoogleOther", regex: /GoogleOther/, category: "training" },
+  // Apple
+  { name: "Applebot-Extended", regex: /Applebot-Extended\/[\d.]+/, category: "training" },
+  // Common Crawl (shared corpus for many LLMs)
+  { name: "CCBot", regex: /CCBot\/[\d.]+/, category: "training" },
+  // ByteDance / Doubao
+  { name: "Bytespider", regex: /Bytespider/, category: "training" },
+  // Meta AI
+  { name: "meta-externalagent", regex: /meta-externalagent\/[\d.]+/, category: "training" },
+  // Amazon Alexa+
+  { name: "Amazonbot", regex: /Amazonbot\/[\d.]+/, category: "training" },
+  // Cohere
+  { name: "cohere-ai", regex: /cohere-ai/, category: "training" },
+  // Diffbot
+  { name: "Diffbot", regex: /Diffbot\/[\d.]+/, category: "training" },
+];
+
+/**
+ * Hostnames that indicate the user came from an AI answer surface. Used to
+ * tag `ai_referral` traffic (no bot UA, real human session bounced from
+ * ChatGPT et al.).
+ */
+const AI_REFERRER_HOSTS: ReadonlySet<string> = new Set([
+  "chatgpt.com",
+  "chat.openai.com",
+  "perplexity.ai",
+  "www.perplexity.ai",
+  "claude.ai",
+  "gemini.google.com",
+  "copilot.microsoft.com",
+  "bing.com",
+  "www.bing.com",
+]);
+
+export interface AiBotInfo {
+  readonly name: string;
+  readonly category: AiBotCategory;
+}
+
+/**
+ * Returns bot info if the UA matches a known AI crawler pattern. Linear
+ * scan of ~17 regexes — sub-millisecond per call, fine for a hot path.
+ */
+export function detectAiBot(userAgent: string | null | undefined): AiBotInfo | null {
+  if (!userAgent) return null;
+  for (const p of PATTERNS) {
+    if (p.regex.test(userAgent)) {
+      return { name: p.name, category: p.category };
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns true when the referer header points to an AI answer surface.
+ * NULL-safe and tolerant of malformed URLs.
+ */
+export function detectAiReferral(referer: string | null | undefined): boolean {
+  if (!referer) return false;
+  try {
+    const host = new URL(referer).hostname.toLowerCase();
+    return AI_REFERRER_HOSTS.has(host);
+  } catch {
+    return false;
+  }
+}
+
+export interface AiHitClassification {
+  readonly purpose: AiHitPurpose;
+  readonly bot: string | null;
+  readonly botCategory: AiBotCategory | null;
+}
+
+/**
+ * Classify a request from its UA + referer. Returns `null` when it's
+ * neither a known AI bot nor an AI-referred human session — the caller
+ * should skip recording these to keep ingestion focused.
+ */
+export function classifyAiHit(
+  userAgent: string | null | undefined,
+  referer: string | null | undefined,
+): AiHitClassification | null {
+  const bot = detectAiBot(userAgent);
+  if (bot) {
+    const purpose: AiHitPurpose =
+      bot.category === "training" ? "training" : "realtime_citation";
+    return { purpose, bot: bot.name, botCategory: bot.category };
+  }
+  if (detectAiReferral(referer)) {
+    return { purpose: "ai_referral", bot: null, botCategory: null };
+  }
+  return null;
+}

package/src/lib/path.ts

@@ -43,7 +43,7 @@ export async function resolveRequestPath(): Promise<{
  * Normalize a path so cache tags align across hand-written and
  * auto-resolved callers. `<SmkingAEO path="products/abc" />` and
  * `<SmkingAEO path="/products/abc" />` must hit the same Next.js cache
- * entry — otherwise the webhook handler's `revalidateTag('smking:path:/products/abc')`
+ * entry — otherwise the webhook handler's `revalidateTag('smking:aeo:/products/abc')`
  * misses the version of the entry that lacks the leading slash.
  */
 export function normalizePath(path: string): string {

package/src/lib/proxy.ts

@@ -0,0 +1,147 @@
+import { NextResponse, type NextRequest, after } from "next/server";
+import { classifyAiHit } from "./crawlers";
+
+/**
+ * SmKing AI traffic ingestion proxy (v0.12+, Next.js 16 `proxy.ts`).
+ *
+ * Drop-in install:
+ *
+ * ```ts
+ * // proxy.ts (project root)
+ * import { smkingProxy } from "@soloworks/smking-next/proxy";
+ *
+ * export const proxy = smkingProxy({
+ *   apiKey: process.env.SMKING_API_KEY!,
+ * });
+ *
+ * export const config = {
+ *   matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+ * };
+ * ```
+ *
+ * What it does:
+ *   - Inspects each request's UA + referer
+ *   - If it's an AI bot or AI-referred human session, batches one
+ *     ingestion call via Vercel `after()` (post-response background)
+ *   - Otherwise: passes through with zero overhead
+ *
+ * Composing with an existing proxy:
+ *
+ * ```ts
+ * import { composeProxy, smkingProxy } from "@soloworks/smking-next/proxy";
+ * import { customerProxy } from "./their-proxy";
+ *
+ * export const proxy = composeProxy([
+ *   smkingProxy({ apiKey: process.env.SMKING_API_KEY! }),
+ *   customerProxy,
+ * ]);
+ * ```
+ *
+ * Fail-open posture (matches `getAeoContent`):
+ *   - No `apiKey` → no-op, customer site keeps running
+ *   - No `baseUrl` / `SMKING_BASE_URL` → no-op
+ *   - Ingestion endpoint down / 4xx / 5xx → silent skip, next request retries
+ *
+ * Why `after()` (not fire-and-forget `fetch`):
+ *   - Vercel serverless kills the function once the response flushes,
+ *     which can drop a naked fetch before it's sent
+ *   - `after()` keeps the function alive within the existing lifetime
+ *     for background work — designed exactly for this case
+ */
+export interface SmkingProxyConfig {
+  /** Site's public API key (`pk_*`). Falls back to `SMKING_API_KEY` env. */
+  apiKey?: string;
+  /** Ingestion base URL. Falls back to `SMKING_BASE_URL` env. */
+  baseUrl?: string;
+}
+
+export type ProxyMiddleware = (
+  request: NextRequest,
+) => NextResponse | Promise<NextResponse>;
+
+const INGEST_TIMEOUT_MS = 2000;
+
+/**
+ * Build the proxy middleware. Returns a no-op middleware when the
+ * required env / config is missing so dev / staging installs without
+ * env never crash.
+ */
+export function smkingProxy(config: SmkingProxyConfig = {}): ProxyMiddleware {
+  return (request: NextRequest) => {
+    const apiKey = config.apiKey ?? process.env.SMKING_API_KEY;
+    const baseUrl = (config.baseUrl ?? process.env.SMKING_BASE_URL)?.replace(
+      /\/$/,
+      "",
+    );
+    if (!apiKey || !baseUrl) {
+      return NextResponse.next();
+    }
+
+    const ua = request.headers.get("user-agent");
+    const referer = request.headers.get("referer");
+    const hit = classifyAiHit(ua, referer);
+    if (!hit) return NextResponse.next();
+
+    const path = request.nextUrl.pathname;
+    const pageUrl = request.nextUrl.toString();
+
+    after(async () => {
+      try {
+        await fetch(`${baseUrl}/api/v1/crawler-hit`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "x-public-key": apiKey,
+          },
+          body: JSON.stringify({
+            hits: [
+              {
+                bot: hit.bot,
+                bot_category: hit.botCategory,
+                purpose: hit.purpose,
+                path,
+                page_url: pageUrl,
+                user_agent: ua,
+                referer,
+                timestamp: new Date().toISOString(),
+              },
+            ],
+          }),
+          signal: AbortSignal.timeout(INGEST_TIMEOUT_MS),
+        });
+      } catch {
+        // Ingestion failure must NEVER bubble to the customer site.
+        // Next request will retry — losing a hit is acceptable.
+      }
+    });
+
+    return NextResponse.next();
+  };
+}
+
+/**
+ * Run middlewares in sequence. The first one to return a non-`next()`
+ * response (redirect / rewrite / abort) short-circuits the chain.
+ *
+ * NOTE: this assumes each middleware in the chain only adds headers or
+ * passes through — it does NOT compose response bodies. Use cases:
+ *   - smkingProxy (telemetry only) + customer auth proxy
+ *   - smkingProxy + customer feature flag proxy
+ */
+export function composeProxy(handlers: ProxyMiddleware[]): ProxyMiddleware {
+  return async (request: NextRequest) => {
+    for (const h of handlers) {
+      const result = await h(request);
+      if (!isPassThrough(result)) return result;
+    }
+    return NextResponse.next();
+  };
+}
+
+function isPassThrough(res: NextResponse): boolean {
+  // `NextResponse.next()` carries `x-middleware-next: 1` internally.
+  // Public surface: `res.headers.get('x-middleware-next')` returns "1"
+  // for a pass-through. Anything else (redirect, rewrite, body) is a
+  // terminal response.
+  return res.headers.get("x-middleware-next") === "1";
+}

package/src/lib/webhook-route.ts

@@ -0,0 +1,126 @@
+import { revalidateTag } from "next/cache";
+import { Buffer } from "node:buffer";
+import crypto from "node:crypto";
+
+interface WebhookPayload {
+  kind?: string;
+  paths?: string[];
+  slugs?: string[];
+  deliveredAt?: string;
+}
+
+/**
+ * SmKing unified webhook handler (v0.11+).
+ *
+ * Drop-in install:
+ *
+ * ```ts
+ * // app/api/smking/webhook/route.ts
+ * export { POST } from "@soloworks/smking-next/webhook";
+ * ```
+ *
+ * Replaces v0.10's split handlers:
+ *   - `/route`        AEO, Bearer-authed (SMKING_WEBHOOK_TOKEN) — GONE
+ *   - `/cms-webhook`  CMS, HMAC-signed (SMKING_WEBHOOK_SECRET) — GONE
+ *
+ * Single HMAC-SHA256 endpoint. Payload `.kind` (`"aeo" | "cms_page" |
+ * future kinds`) dispatches which revalidate tag namespace to use:
+ *
+ *   smking:{kind}:{identifier}
+ *
+ * Where identifier is either:
+ *   - path  (AEO: `["/products/foo"]`) — `smking:aeo:/products/foo`
+ *   - slug  (CMS: `["hello"]`) — `smking:cms_page:hello`
+ *
+ * Customer migration from v0.10:
+ *   1. env: SMKING_WEBHOOK_TOKEN → SMKING_WEBHOOK_SECRET (HMAC key)
+ *   2. route path: /api/smking-revalidate + /api/smking/webhook
+ *      → /api/smking/webhook (single)
+ *   3. revalidateTag callers update tag prefix
+ *
+ * Auth: HMAC-SHA256 only. Bearer dropped — single auth model means one
+ * env var, one shim, fewer customer mis-config paths (the disambiguation
+ * problem the v0.10 dual-handler shipped with).
+ */
+export async function POST(request: Request): Promise<Response> {
+  const secret = process.env.SMKING_WEBHOOK_SECRET;
+  if (!secret) {
+    return Response.json(
+      { error: "webhook_secret_missing" },
+      { status: 503 },
+    );
+  }
+
+  // Raw body for HMAC verify — re-encoding via JSON.parse + stringify
+  // would change byte order / spacing and invalidate the signature.
+  const rawBody = await request.text();
+  const providedSig = request.headers.get("x-smking-signature");
+  if (!verifySignature(rawBody, providedSig, secret)) {
+    return Response.json({ error: "invalid_signature" }, { status: 401 });
+  }
+
+  let payload: WebhookPayload;
+  try {
+    payload = JSON.parse(rawBody) as WebhookPayload;
+  } catch {
+    return Response.json({ error: "invalid_payload" }, { status: 400 });
+  }
+
+  const kind = payload.kind;
+  if (typeof kind !== "string" || kind.length === 0) {
+    // Forward-compat: SaaS may emit kinds we haven't taught the SDK
+    // yet — acknowledge (200) without action so SaaS doesn't retry.
+    return Response.json({ ok: true, note: "no_action_taken" });
+  }
+
+  let revalidated = 0;
+  let errors = 0;
+  for (const path of payload.paths ?? []) {
+    try {
+      revalidateTag(`smking:${kind}:${path}`, "default");
+      revalidated++;
+    } catch (err) {
+      errors++;
+      console.warn(
+        `[@soloworks/smking-next/webhook] revalidateTag failed for ${kind}/${path}:`,
+        err,
+      );
+    }
+  }
+  for (const slug of payload.slugs ?? []) {
+    try {
+      revalidateTag(`smking:${kind}:${slug}`, "default");
+      revalidated++;
+    } catch (err) {
+      errors++;
+      console.warn(
+        `[@soloworks/smking-next/webhook] revalidateTag failed for ${kind}/${slug}:`,
+        err,
+      );
+    }
+  }
+
+  return Response.json({ ok: true, kind, revalidated, errors });
+}
+
+function verifySignature(
+  rawBody: string,
+  signatureHeader: string | null,
+  secret: string,
+): boolean {
+  if (!signatureHeader || !signatureHeader.startsWith("sha256=")) return false;
+  const provided = signatureHeader.slice("sha256=".length);
+  const expected = crypto
+    .createHmac("sha256", secret)
+    .update(rawBody)
+    .digest("hex");
+  if (expected.length !== provided.length) return false;
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(expected, "hex"),
+      Buffer.from(provided, "hex"),
+    );
+  } catch {
+    return false;
+  }
+}

package/src/types.ts

@@ -56,16 +56,73 @@ export interface AeoResponse {
 
 export type CmsStatus = "ready" | "pending" | "not_found";
 
+export type CmsContentType = "article" | "landing" | "listing";
+
+/**
+ * v2 substrate block primitives. Mirrors `apps/web/src/features/cms/types.ts`
+ * on the SaaS side (kept in sync manually — when the v1 block catalog
+ * grows past 5 primitives, a shared workspace package replaces this
+ * duplication per `docs/superpowers/specs/2026-05-15-cms-dashboard-editor-design.md`
+ * section §11 + ai-cms-v2 §"擴充性").
+ */
+export interface HeroProps {
+  title: string;
+  subtitle?: string;
+  image?: { url: string; alt: string };
+  cta?: { label: string; href: string };
+}
+export interface ArticleProps {
+  html: string;
+}
+export interface ModuleHeader {
+  heading?: string;
+  viewAll?: { label: string; href: string };
+}
+export type NavLayout = "grid" | "list" | "carousel";
+export interface NavRecentPostsProps extends ModuleHeader {
+  limit: number;
+  layout: NavLayout;
+  contentType?: "article" | "all";
+}
+export interface NavTaxonomyListProps extends ModuleHeader {
+  /** category-by-path: slug prefix; tag: taxonomies.slug */
+  source: "category-by-path" | "tag";
+  path: string;
+  limit: number;
+  layout: NavLayout;
+}
+export interface NavSearchProps {
+  placeholder: string;
+  contentType?: "article" | "all";
+}
+
+export type Block =
+  | { component: "hero"; id: string; props: HeroProps }
+  | { component: "article"; id: string; props: ArticleProps }
+  | {
+      component: "nav-recent-posts";
+      id: string;
+      props: NavRecentPostsProps;
+    }
+  | {
+      component: "nav-taxonomy-list";
+      id: string;
+      props: NavTaxonomyListProps;
+    }
+  | { component: "nav-search"; id: string; props: NavSearchProps };
+
 /**
- * A single published CMS page returned by the smking public API.
- * `body` is the raw Tiptap ProseMirror JSON document the user authored
- * in /write — render it via the SmkingCms server component (which
- * wraps @tiptap/static-renderer/pm/react with our extension list).
+ * A single published CMS page returned by the smking public API
+ * (substrate v2). Render via `<SmkingCms>` server component which
+ * dispatches each block by component type.
  */
 export interface CmsPage {
   slug: string;
   title: string;
-  body: Record<string, unknown>;
+  contentType: CmsContentType;
+  blocks: Block[];
+  excerpt?: string | null;
+  featuredImageUrl?: string | null;
   publishedAt: string | null;
 }
 

package/src/components/cms-nodes/gallery-extension.ts

@@ -1,32 +0,0 @@
-import { Node } from "@tiptap/core";
-
-/**
- * Schema-only Gallery extension for the static renderer.
- *
- * The full SaaS-side `GalleryNode` (apps/web/src/components/tiptap-node/
- * gallery-node/gallery-node-extension.ts) ships with addNodeView,
- * addCommands, parseHTML — everything Tiptap needs in the editor. For
- * read-only static rendering we only need the SCHEMA (name, group,
- * atom, attrs) so `@tiptap/static-renderer` recognises the "gallery"
- * node type when walking the JSON; the actual rendering is handled by
- * the GalleryNodeView passed via `nodeMapping`.
- *
- * Keep attrs in sync with the SaaS schema and the Laravel PHP node
- * (packages/smking-laravel/src/Tiptap/Nodes/Gallery.php). All three
- * must agree on field names + defaults.
- */
-export const Gallery = Node.create({
-  name: "gallery",
-  group: "block",
-  atom: true,
-  draggable: true,
-  selectable: true,
-
-  addAttributes() {
-    return {
-      images: { default: [] },
-      layout: { default: "grid" },
-      columns: { default: 3 },
-    };
-  },
-});

package/src/components/cms-nodes/gallery-node.tsx

@@ -1,68 +0,0 @@
-/**
- * SmKing Gallery — read-only React render for static-renderer's
- * nodeMapping.
- *
- * Markup MUST stay byte-equal to:
- *   - apps/web/src/components/tiptap-node/gallery-node/gallery-node-
- *     extension.ts (SaaS authoring → preview)
- *   - packages/smking-laravel/src/Tiptap/Nodes/Gallery.php (Laravel
- *     SDK PHP renderer)
- *
- * If you change ANY attribute / class / nesting here, change it in the
- * other two and bump version on all three SDKs together. Customer site
- * CSS targets `.smk-gallery`, `.smk-gallery--{layout}`,
- * `.smk-gallery__item` — those names are public API.
- */
-
-interface GalleryImage {
-  url: string;
-  alt?: string;
-  caption?: string;
-}
-
-interface GalleryNodeAttrs {
-  images?: GalleryImage[];
-  layout?: string;
-  columns?: number;
-}
-
-/**
- * Shape matches what `@tiptap/static-renderer/pm/react`'s nodeMapping
- * passes: `{ node: ProseMirror Node }` whose `attrs` are typed via the
- * Gallery extension. We narrow loosely here — the SaaS sometimes ships
- * stringly-typed attrs (jsonb round-trips lose number type for columns).
- */
-export function GalleryNodeView({
-  node,
-}: {
-  node: { attrs?: GalleryNodeAttrs };
-}) {
-  const attrs = node.attrs ?? {};
-  const images = Array.isArray(attrs.images) ? attrs.images : [];
-  const layout = typeof attrs.layout === "string" ? attrs.layout : "grid";
-  const columnsRaw = attrs.columns;
-  const columns =
-    typeof columnsRaw === "number" && columnsRaw > 0
-      ? columnsRaw
-      : typeof columnsRaw === "string" && Number(columnsRaw) > 0
-        ? Number(columnsRaw)
-        : 3;
-
-  return (
-    <div
-      data-type="gallery"
-      data-layout={layout}
-      data-columns={String(columns)}
-      className={`smk-gallery smk-gallery--${layout}`}
-      style={{ "--smk-gallery-cols": columns } as React.CSSProperties}
-    >
-      {images.map((img, i) => (
-        <figure key={i} className="smk-gallery__item">
-          {/* eslint-disable-next-line @next/next/no-img-element */}
-          <img src={img.url} alt={img.alt ?? ""} loading="lazy" />
-          {img.caption && <figcaption>{img.caption}</figcaption>}
-        </figure>
-      ))}
-    </div>
-  );
-}