@soloworks/smking-next 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# @soloworks/smking-next
+
+## 0.8.0 — 2026-05-05
+
+**Renamed from `@smking/next` → `@soloworks/smking-next`.** First-time npm publish discovered the `smking` scope was already taken on the registry; rather than build a new brand around a different scope, we kept the product name `smking-next` in the package name and shipped under the existing `@soloworks` org. No prior version was ever published on npm under `@smking/next`, so no downstream upgrade pain — first install everywhere is `pnpm add @soloworks/smking-next`.
+
+Adds AI bot rules + Cloudflare `Content-Signal` directive helpers, mirroring the new `smking:publish-robots` artisan command in `smking/laravel` v0.8.0. Same defect surfaced from an `isitagentready.com` audit on a customer storefront — two of the four required `robots.txt` agent-readiness checks (RFC 9309 AI bot rules, Cloudflare Content-Signal) require the customer's `robots.txt` to carry directives the SDK can't influence post-render.
+
+### Version jump 0.3 → 0.8
+
+Cross-package version sync with `smking/laravel`. Both SDKs now ship the same robots feature in the same release; pinning to a matching version on both stacks (e.g. internal monorepo with both Next.js and Laravel surfaces) avoids drift confusion. Future releases will keep the major.minor in sync where the change is conceptual parity, even when only one package has code changes.
+
+This skips published 0.4 / 0.5 / 0.6 / 0.7 lines on npm. None of those versions exist on the registry — 0.3.0 is the previous published version, and 0.8.0 is a strict superset (everything 0.3.0 exported is still there at the same import path with the same signature). No deprecations, no removals.
+
+### feat: `@soloworks/smking-next/robots` — two helpers, two surfaces
+
+Next.js's `MetadataRoute.Robots` type doesn't model Cloudflare's `Content-Signal:` directive, so the package ships both shapes:
+
+```ts
+// app/robots.ts — Next.js MetadataRoute (NO Content-Signal)
+import type { MetadataRoute } from 'next';
+import { smkingRobotsRules } from '@soloworks/smking-next/robots';
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      { userAgent: '*', disallow: ['/admin/'] },
+      ...smkingRobotsRules(),
+    ],
+    sitemap: 'https://example.com/sitemap.xml',
+  };
+}
+```
+
+```ts
+// app/robots.txt/route.ts — full robots.txt body (Content-Signal included)
+import { smkingRobotsTxt } from '@soloworks/smking-next/robots';
+
+export function GET() {
+  return new Response(
+    smkingRobotsTxt({
+      rules: [{ userAgent: '*', disallow: ['/admin/'] }],
+      sitemap: 'https://example.com/sitemap.xml',
+    }),
+    { headers: { 'Content-Type': 'text/plain' } },
+  );
+}
+```
+
+Customer rules render *before* the smking AI bot block in both surfaces. `bots` config replaces (not merges) the default list — `{ CCBot: 'disallow' }` produces only one bot block, not eight. `contentSignal: null` (or `""`) drops the directive entirely; passing nothing uses the default `search=yes, ai-input=no, ai-train=no`.
+
+### Default policy
+
+Allow major search + AI crawlers (GPTBot, ChatGPT-User, ClaudeBot, PerplexityBot, Google-Extended, Bingbot, Applebot-Extended). Emit Content-Signal that permits search indexing but disallows AI training/input. Override per-bot or globally.
+
+### Tests
+
+12 new tests in `__tests__/robots.test.ts` covering rules-array shape, customer rules ordering, array-typed userAgent/allow/disallow inputs, contentSignal omission semantics, sitemap + host emission, custom-bots policy replacement, and trailing-newline normalisation. Total suite: 59 tests, all passing.
+
+### Why two functions and not one
+
+`smkingRobotsRules()` returns objects shaped to `MetadataRoute.Robots['rules']`, which is the framework-native path and what most customers will reach for. `smkingRobotsTxt()` returns a string and lets the customer set arbitrary directives Next.js doesn't model — Content-Signal today, anything else tomorrow. Forcing customers who only need bot rules onto the route-handler path would be over-engineering; forcing customers who need Content-Signal onto MetadataRoute would be impossible.
+
+## 0.3.0 — 2026-04-29
+
+Minimal-surface rewrite. The package is now three focused files instead of a 21-task SDK.
+
+### What's in
+
+- **`<SmkingAEO />`** server component. Place once in root layout. Auto-resolves request path via `headers()`, fetches per-URL AEO content from the smking SaaS, and emits:
+  - JSON-LD `<script>` for AI crawlers
+  - `<title>` / `og:*` / `<meta name="description">` head tags (React 19 head hoist)
+  - sr-only `<div>` with FAQ, AI summary, product image (in-DOM for crawlers, visually hidden)
+- **`getAeoContent(params)`** — fetch helper with 2s `AbortSignal.timeout`, 1h ISR backstop, and `next.tags: ['smking:path:<path>']` for webhook-driven invalidation.
+- **`@soloworks/smking-next/route`** — drop-in `POST` + `GET` handlers for the customer's `/api/smking-revalidate` endpoint. Bearer-token auth + per-path `revalidateTag`.
+
+### Public surface
+
+```ts
+import { SmkingAEO, getAeoContent } from '@soloworks/smking-next';
+import { POST, GET } from '@soloworks/smking-next/route';
+```
+
+Plus types: `AeoResponse`, `AeoStatus`, `SeoMeta`, `FaqItem`, `ChatLinks`, `DiscoverParams`.
+
+### What's not in (vs. earlier v0.3 design)
+
+These were dropped after PR review surfaced them as Laravel parity for parity's sake:
+
+- `withSmkingMetadata` HOF — React 19 head dedup + Next.js Metadata API order handles precedence. Customer writes `generateMetadata` to override; doesn't write it to use smking's defaults.
+- `getSmkingHtmlAttrs` — `<html data-smking-injected>` mark was for `doctor` to inspect; both removed.
+- `createSmkingMiddleware` factory — markdown content negotiation, alternate Link header, X-Smking-Path: AI crawlers consume HTML; markdown is a future feature.
+- `serveMarkdown` — same.
+- `defineSmkingConfig` schema — three component props are enough; YAML-style config is over-engineering.
+- `npx @soloworks/smking-next init` codemod (jscodeshift, commander, tsx, fast-glob deps) — two files to paste, no tooling.
+- `npx @soloworks/smking-next doctor` — install too simple to need verification.
+- `npx @soloworks/smking-next status` — no circuit breaker, no status to query.
+- Per-surface circuit breaker (in-memory tombstone) — `AbortSignal.timeout(2000)` + Next.js ISR cache cover the same outage scenarios.
+- `MockSmkingProvider` — customers `vi.mock('@soloworks/smking-next')` directly.
+- `<SmkingDevtools />` — Vercel logs / network tab show injection state.
+- `visibility` prop (sr_only / visible / noscript) — sr-only is the only sensible option for AEO content.
+- Test environment auto-skip — fetch is mocked in customer tests anyway.
+- Defense-in-depth fallback head tag layer — single component owns all SEO emission.
+
+Behavior covered by the three files matches the original design intent (per-URL AEO injection + outage tolerance + push-driven update). The Laravel SDK's `smking/laravel` four-tier TTL + circuit breaker + doctor all map cleanly to Next.js's declarative cache + webhook + ISR — no need for an SDK reimplementation.
+
+## 0.1.0 — 2026-04-28
+
+Initial release: `<SmkingAEO />` + `getSmkingMetadata` + `mergeMetadata` (the metadata helpers were dropped in 0.3.0).

package/README.md

@@ -0,0 +1,133 @@
+# @soloworks/smking-next
+
+AI-native SEO (AEO) for Next.js. One server component injects JSON-LD, OG tags, AI summary, and FAQ on every page so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your content.
+
+- **One server component** in your root layout — every URL gets its own AEO content automatically (`/products/nike-air`, `/products/adidas/red`, anything dynamic, no codemod needed).
+- **Fail-fast, fail-open.** 2-second timeout + Next.js ISR — if smking is down, your page renders without injection. Never blocks.
+- **Push updates** — webhook handler invalidates only the changed paths via `revalidateTag`.
+
+## Install
+
+```bash
+pnpm add @soloworks/smking-next
+```
+
+Set two environment variables:
+
+```bash
+SMKING_API_KEY=pk_...        # public key from smking dashboard
+SMKING_BASE_URL=https://...  # smking deployment origin
+```
+
+### 1. Drop the component into your root layout
+
+```tsx
+// app/layout.tsx
+import { SmkingAEO } from '@soloworks/smking-next';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <SmkingAEO apiKey={process.env.SMKING_API_KEY!} />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+That's it for AEO injection. Every request to any URL fetches that URL's AEO content from smking and emits:
+
+- `<script type="application/ld+json">` for AI crawlers
+- `<title>`, `<meta name="description">`, `og:*` head tags
+- sr-only `<div>` containing FAQ, AI summary, and product image (visually hidden, in-DOM for crawlers)
+
+### 2. Wire the webhook for instant cache invalidation
+
+```ts
+// app/api/smking-revalidate/route.ts
+export { POST, GET } from '@soloworks/smking-next/route';
+```
+
+Add to environment:
+
+```bash
+SMKING_WEBHOOK_TOKEN=...  # any random string; share with smking SaaS
+```
+
+Configure smking SaaS to POST `{ paths: [...] }` to your `/api/smking-revalidate` endpoint with `Authorization: Bearer <token>`. The handler calls `revalidateTag('smking:path:<path>')` for each path.
+
+## How metadata wins / loses
+
+Both `<SmkingAEO />` and your own `generateMetadata` emit head tags. Next.js + React 19 head dedup applies last-write-wins:
+
+- **No `generateMetadata`** → smking's `<title>` / `og:*` are used.
+- **You write `generateMetadata` in a layout / page** → your tags override smking's for that route segment.
+
+This is the pattern: smking provides AEO/SEO baseline, you override per-page when you want. No HOF, no codemod.
+
+For client pages (`'use client'`) that need dynamic metadata, write a sibling `layout.tsx` with `generateMetadata` — standard Next.js workflow, unrelated to smking.
+
+## How outage tolerance works
+
+`getAeoContent` wraps `fetch` with `AbortSignal.timeout(2000)` and Next.js ISR (`next: { revalidate: 3600, tags: ['smking:path:<path>'] }`):
+
+- **Cache hit** (the common path): zero network. Tags allow webhook-driven invalidation.
+- **Cache miss + smking healthy**: one network roundtrip, response cached for 1h.
+- **Cache miss + smking down / hung**: returns null after at most 2s, page renders without injection. Next.js ISR retries on the next request after `revalidate`.
+- **5xx / 4xx / parse error**: same fail-open path.
+
+No circuit breaker, no retry, no status command — Next.js infrastructure already covers what those would do.
+
+## API
+
+### `<SmkingAEO />` props
+
+```ts
+interface SmkingAEOProps {
+  apiKey: string;        // required
+  baseUrl?: string;      // override SMKING_BASE_URL env
+  path?: string;         // explicit path; auto-resolved from headers() otherwise
+  revalidate?: number;   // ISR seconds; default 3600 (1h)
+}
+```
+
+Path auto-detection works for any URL schema (`/products/[slug]`, `/shop/[cat]/[id]/[variant]`). Pass `path` explicitly only for static-export contexts where `headers()` is unavailable.
+
+### `getAeoContent(params)`
+
+Lower-level helper if you want to fetch the AEO response and render yourself. Same params, returns `Promise<AeoResponse | null>`.
+
+```ts
+import { getAeoContent } from '@soloworks/smking-next';
+
+const aeo = await getAeoContent({ apiKey: ..., path: '/products/abc' });
+if (aeo?.status === 'ready') {
+  // aeo.jsonLd, aeo.faq, aeo.summary, aeo.seo, aeo.chatLinks, ...
+}
+```
+
+### Webhook payload
+
+```json
+POST /api/smking-revalidate
+Authorization: Bearer <SMKING_WEBHOOK_TOKEN>
+Content-Type: application/json
+
+{ "paths": ["/products/abc", "/products/xyz"] }
+```
+
+Response: `{ revalidated: number, errors: number }`. `errors > 0` means some tags couldn't be revalidated (others still succeeded — partial-success delivery).
+
+## Versions
+
+See [CHANGELOG.md](./CHANGELOG.md). Aligned with `smking/laravel` for SaaS-side parity.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@soloworks/smking-next",
+  "version": "0.8.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sillyleo/smking",
+    "directory": "packages/smking-next"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./route": {
+      "types": "./src/route.ts",
+      "default": "./src/route.ts"
+    },
+    "./robots": {
+      "types": "./src/lib/robots.ts",
+      "default": "./src/lib/robots.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "nextjs",
+    "react",
+    "seo",
+    "aeo",
+    "ai",
+    "json-ld",
+    "schema",
+    "chatgpt",
+    "perplexity",
+    "smking"
+  ],
+  "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/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^29.1.0",
+    "next": "^16.2.2",
+    "react": "^19.0.0",
+    "typescript": "^5",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/components/smking-aeo.tsx

@@ -0,0 +1,134 @@
+import type { DiscoverParams } from "../types";
+import { getAeoContent } from "../lib/client";
+
+const SR_ONLY_STYLE: React.CSSProperties = {
+  position: "absolute",
+  width: "1px",
+  height: "1px",
+  padding: 0,
+  margin: "-1px",
+  overflow: "hidden",
+  clip: "rect(0,0,0,0)",
+  whiteSpace: "nowrap",
+  border: 0,
+};
+
+export interface SmkingAEOProps extends DiscoverParams {}
+
+/**
+ * Server Component that injects AEO + SEO content for the current
+ * request. Place once in the root layout, inside `<body>`:
+ *
+ *   ```tsx
+ *   import { SmkingAEO } from '@soloworks/smking-next';
+ *
+ *   export default function RootLayout({ children }) {
+ *     return (
+ *       <html>
+ *         <body>
+ *           <SmkingAEO apiKey={process.env.SMKING_API_KEY!} />
+ *           {children}
+ *         </body>
+ *       </html>
+ *     );
+ *   }
+ *   ```
+ *
+ * Each request the component reads the path from request headers, fetches
+ * the SaaS for that exact URL, and emits:
+ *
+ *   - JSON-LD `<script>` for AI crawlers
+ *   - `<title>`, `<meta name="description">`, `og:*` head tags (React 19
+ *     hoists these into `<head>`; if a deeper layout / page also sets
+ *     them, Next.js's last-write-wins semantics let the host override)
+ *   - sr-only body fragments containing FAQ HTML, AI summary, and product
+ *     image — visually hidden but in the DOM for AI crawlers
+ *
+ * Returns null when the response isn't `ready` (pending / not_found /
+ * unreachable / mis-configured). Fail-open by design: the page renders
+ * without injection rather than throwing.
+ *
+ * Security: dangerouslySetInnerHTML is bounded to two trusted sources —
+ * JSON-LD (escaped via `safeJson`) and SaaS-built HTML fragments
+ * (server-side `escapeHtml` on every user-facing field). If you point
+ * `baseUrl` at a custom origin, audit that origin's escape behavior
+ * before deploying — the trust boundary is "smking SaaS output", not
+ * arbitrary content fetched anywhere.
+ */
+export async function SmkingAEO(props: SmkingAEOProps) {
+  const aeo = await getAeoContent(props);
+  if (!aeo || aeo.status !== "ready") return null;
+
+  const seo = aeo.seo ?? null;
+  const description = seo?.ogDescription ?? aeo.metaDescription ?? null;
+  const jsonLdString = aeo.jsonLd ? safeJson(aeo.jsonLd) : null;
+  const hasBodyFragments = Boolean(
+    aeo.summaryHtml || aeo.faqHtml || seo?.ogImageUrl,
+  );
+
+  return (
+    <>
+      {jsonLdString && (
+        <script
+          type="application/ld+json"
+          data-smking="aeo"
+          dangerouslySetInnerHTML={{ __html: jsonLdString }}
+        />
+      )}
+
+      {seo?.title && <title data-smking="aeo">{seo.title}</title>}
+      {description && (
+        <meta name="description" content={description} data-smking="aeo" />
+      )}
+      {seo?.ogTitle && (
+        <meta property="og:title" content={seo.ogTitle} data-smking="aeo" />
+      )}
+      {seo?.ogDescription && (
+        <meta
+          property="og:description"
+          content={seo.ogDescription}
+          data-smking="aeo"
+        />
+      )}
+      {seo?.ogImageUrl && (
+        <meta
+          property="og:image"
+          content={seo.ogImageUrl}
+          data-smking="aeo"
+        />
+      )}
+
+      {hasBodyFragments && (
+        <div data-smking="aeo" style={SR_ONLY_STYLE}>
+          {aeo.summaryHtml && (
+            <div dangerouslySetInnerHTML={{ __html: aeo.summaryHtml }} />
+          )}
+          {aeo.faqHtml && (
+            <div dangerouslySetInnerHTML={{ __html: aeo.faqHtml }} />
+          )}
+          {seo?.ogImageUrl && (
+            <img
+              src={seo.ogImageUrl}
+              alt={seo.ogTitle ?? seo.title ?? ""}
+              loading="lazy"
+            />
+          )}
+        </div>
+      )}
+    </>
+  );
+}
+
+/**
+ * Escape JSON for safe `<script>` embedding. Covers the three values
+ * that can break out:
+ *   - `</` (any `</script>`-like sequence)
+ *   - U+2028 / U+2029 (treated as line terminators inside a JS string
+ *     literal, which would corrupt the embedded JSON)
+ */
+function safeJson(value: Record<string, unknown>): string {
+  return JSON.stringify(value)
+    .replace(/<\//g, "<\\/")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { SmkingAEO } from "./components/smking-aeo";
+export { getAeoContent } from "./lib/client";
+export type {
+  AeoResponse,
+  AeoStatus,
+  ChatLinks,
+  DiscoverParams,
+  FaqItem,
+  SeoMeta,
+} from "./types";

package/src/lib/client.ts

@@ -0,0 +1,95 @@
+// Type-only import loads Next.js's RequestInit augmentation so the
+// `next: { revalidate, tags }` property on fetch options typechecks.
+import type {} from "next";
+
+import type { AeoResponse, DiscoverParams } from "../types";
+import { normalizePath, resolveRequestPath } from "./path";
+
+const DEFAULT_REVALIDATE_SECONDS = 3600;
+const FETCH_TIMEOUT_MS = 2000;
+
+const _warnedKeys = new Set<string>();
+function warnOnce(key: string, message: string): void {
+  if (process.env.NODE_ENV === "production") return;
+  if (_warnedKeys.has(key)) return;
+  _warnedKeys.add(key);
+  console.warn(message);
+}
+
+/**
+ * Fetch AEO content for a path. Returns null when:
+ *   - apiKey or baseUrl missing (fail-open in dev / staging; one-time
+ *     dev warning so customers notice the misconfiguration)
+ *   - request scope unavailable and no path passed
+ *   - network failure / 2s timeout (next request retries via ISR)
+ *   - 4xx / 5xx response
+ *   - JSON parse failure
+ *
+ * On success, cached by Next.js data cache for 1h (ISR backstop). Tagged
+ * with `smking:path:<path>` so the webhook handler at `@soloworks/smking-next/route`
+ * can `revalidateTag` to invalidate instantly when SaaS pushes an update.
+ *
+ * Sends `{ key, path, url }` — `url` is required for first-sight
+ * registration: when the SaaS hasn't seen this path before it queues a
+ * background crawl using the URL. Without it, brand-new pages never
+ * leave `not_found`.
+ *
+ * No circuit breaker / retry / status command — Next.js fetch + ISR +
+ * AbortSignal already cover the outage scenarios. A hung upstream returns
+ * null after 2s and the page renders without injection (fail-open).
+ */
+export async function getAeoContent(
+  params: DiscoverParams,
+): Promise<AeoResponse | null> {
+  if (!params.apiKey) {
+    warnOnce(
+      "missing-api-key",
+      "[@soloworks/smking-next] apiKey is empty — skipping AEO injection. Set SMKING_API_KEY or pass apiKey prop.",
+    );
+    return null;
+  }
+
+  const baseUrl = (params.baseUrl ?? process.env.SMKING_BASE_URL)?.replace(
+    /\/$/,
+    "",
+  );
+  if (!baseUrl) {
+    warnOnce(
+      "missing-base-url",
+      "[@soloworks/smking-next] SMKING_BASE_URL is not configured — skipping AEO injection. Set the env var or pass baseUrl prop.",
+    );
+    return null;
+  }
+
+  let path = params.path;
+  let url = params.url;
+  if (!path || !url) {
+    try {
+      const resolved = await resolveRequestPath();
+      path = path ?? resolved.path;
+      url = url ?? resolved.url;
+    } catch {
+      return null;
+    }
+  }
+  path = normalizePath(path);
+
+  try {
+    const res = await fetch(`${baseUrl}/api/v1/public/aeo`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ key: params.apiKey, path, url }),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      next: {
+        revalidate: params.revalidate ?? DEFAULT_REVALIDATE_SECONDS,
+        tags: [`smking:path:${path}`],
+      },
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as AeoResponse;
+  } catch {
+    // Network failure, 2s timeout, or JSON parse error → fail-open.
+    // The next request after `revalidate` retries via Next.js ISR.
+    return null;
+  }
+}

package/src/lib/path.ts

@@ -0,0 +1,51 @@
+import { headers } from "next/headers";
+
+/**
+ * Resolve the current request's path + absolute URL from Next.js request
+ * headers. Used by `<SmkingAEO />` when the caller didn't pass `path`
+ * explicitly.
+ *
+ * `url` is needed by the SaaS for first-sight registration: when a path
+ * is hit for the first time and no content row exists, the API uses
+ * `url` to enqueue a background crawl. Omitting it (as a previous
+ * minimal pass did) breaks first-sight discovery — every brand-new page
+ * stays `not_found` forever instead of getting registered.
+ *
+ * Throws if called outside a request scope (e.g. during static export
+ * without `generateStaticParams`). Callers should pass `path` explicitly
+ * for static-export pages.
+ */
+export async function resolveRequestPath(): Promise<{
+  path: string;
+  url: string;
+}> {
+  const h = await headers();
+
+  const xUrl = h.get("x-url");
+  if (xUrl) {
+    try {
+      const u = new URL(xUrl);
+      return { path: u.pathname, url: xUrl };
+    } catch {
+      // fall through to header-derived URL
+    }
+  }
+
+  const xPathname = h.get("x-pathname") ?? h.get("x-invoke-path");
+  const host = h.get("x-forwarded-host") ?? h.get("host");
+  const proto = h.get("x-forwarded-proto") ?? "https";
+  const path = xPathname ?? "/";
+  const url = host ? `${proto}://${host}${path}` : path;
+  return { path, url };
+}
+
+/**
+ * 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')`
+ * misses the version of the entry that lacks the leading slash.
+ */
+export function normalizePath(path: string): string {
+  return path.startsWith("/") ? path : "/" + path;
+}

package/src/lib/robots.ts

@@ -0,0 +1,168 @@
+/**
+ * AI-bot directives + Cloudflare `Content-Signal` for the customer's
+ * `robots.txt`. Two surfaces because Next.js `MetadataRoute.Robots` doesn't
+ * model `Content-Signal:` — customers who care about that directive must
+ * serve from a route handler that returns `text/plain` directly.
+ *
+ *   - `smkingRobotsRules()` — drop into `app/robots.ts` rules array.
+ *     Bot User-agent blocks only; no Content-Signal (Next.js limitation).
+ *   - `smkingRobotsTxt()`   — full robots.txt body string for
+ *     `app/robots.txt/route.ts`. Includes Content-Signal directive.
+ */
+
+export type SmkingRobotsRule = "allow" | "disallow";
+
+export type SmkingRobotsBots = Record<string, SmkingRobotsRule>;
+
+export interface SmkingRobotsConfig {
+  /** Override the bot list. Default policy below. */
+  bots?: SmkingRobotsBots;
+  /**
+   * Cloudflare Content-Signal directive value. Default permits search
+   * indexing but disallows AI training/input use. Pass `null` to omit
+   * the directive entirely; pass an empty string for the same effect.
+   */
+  contentSignal?: string | null;
+}
+
+/** Default bot list — major search + AI crawlers, all allowed. */
+export const SMKING_DEFAULT_BOTS: SmkingRobotsBots = {
+  GPTBot: "allow",
+  "ChatGPT-User": "allow",
+  ClaudeBot: "allow",
+  PerplexityBot: "allow",
+  "Google-Extended": "allow",
+  Bingbot: "allow",
+  "Applebot-Extended": "allow",
+};
+
+/** Default Content-Signal: allow search indexing, deny AI training. */
+export const SMKING_DEFAULT_CONTENT_SIGNAL =
+  "search=yes, ai-input=no, ai-train=no";
+
+/**
+ * One rule per bot, suitable for spreading into a Next.js `app/robots.ts`
+ * `MetadataRoute.Robots['rules']` array.
+ *
+ * ```ts
+ * // app/robots.ts
+ * import type { MetadataRoute } from 'next';
+ * import { smkingRobotsRules } from '@soloworks/smking-next/robots';
+ *
+ * export default function robots(): MetadataRoute.Robots {
+ *   return {
+ *     rules: [
+ *       { userAgent: '*', disallow: ['/admin/'] },
+ *       ...smkingRobotsRules(),
+ *     ],
+ *     sitemap: 'https://example.com/sitemap.xml',
+ *   };
+ * }
+ * ```
+ *
+ * NOTE: `MetadataRoute.Robots` doesn't model `Content-Signal:` —
+ * customers who need that directive should switch to
+ * `smkingRobotsTxt()` and serve via a route handler.
+ */
+export function smkingRobotsRules(
+  config: SmkingRobotsConfig = {},
+): Array<{
+  userAgent: string;
+  allow?: string;
+  disallow?: string;
+}> {
+  const bots = config.bots ?? SMKING_DEFAULT_BOTS;
+  return Object.entries(bots).map(([userAgent, rule]) =>
+    rule === "disallow"
+      ? { userAgent, disallow: "/" }
+      : { userAgent, allow: "/" },
+  );
+}
+
+export interface SmkingRobotsTxtRule {
+  userAgent: string | string[];
+  allow?: string | string[];
+  disallow?: string | string[];
+}
+
+export interface SmkingRobotsTxtOptions extends SmkingRobotsConfig {
+  /** Customer rules emitted *before* the smking AI bot block. */
+  rules?: SmkingRobotsTxtRule[];
+  /** One or more Sitemap entries, emitted at the end of the file. */
+  sitemap?: string | string[];
+  /** Optional `Host:` directive, emitted after Sitemap. */
+  host?: string;
+}
+
+/**
+ * Full robots.txt body string including AI bot rules + Content-Signal.
+ * Use from a route handler:
+ *
+ * ```ts
+ * // app/robots.txt/route.ts
+ * import { smkingRobotsTxt } from '@soloworks/smking-next/robots';
+ *
+ * export function GET() {
+ *   return new Response(
+ *     smkingRobotsTxt({
+ *       rules: [{ userAgent: '*', disallow: ['/admin/'] }],
+ *       sitemap: 'https://example.com/sitemap.xml',
+ *     }),
+ *     { headers: { 'Content-Type': 'text/plain' } },
+ *   );
+ * }
+ * ```
+ *
+ * Content-Signal is omitted when `contentSignal` is `null` or `""`.
+ */
+export function smkingRobotsTxt(options: SmkingRobotsTxtOptions = {}): string {
+  const lines: string[] = [];
+
+  for (const rule of options.rules ?? []) {
+    for (const ua of toArray(rule.userAgent)) {
+      lines.push(`User-agent: ${ua}`);
+    }
+    for (const path of toArray(rule.allow)) {
+      lines.push(`Allow: ${path}`);
+    }
+    for (const path of toArray(rule.disallow)) {
+      lines.push(`Disallow: ${path}`);
+    }
+    lines.push("");
+  }
+
+  const bots = options.bots ?? SMKING_DEFAULT_BOTS;
+  for (const [userAgent, rule] of Object.entries(bots)) {
+    lines.push(`User-agent: ${userAgent}`);
+    lines.push(rule === "disallow" ? "Disallow: /" : "Allow: /");
+    lines.push("");
+  }
+
+  // contentSignal === undefined → use default
+  // contentSignal === null or "" → omit the directive entirely
+  const signalRaw =
+    options.contentSignal === undefined
+      ? SMKING_DEFAULT_CONTENT_SIGNAL
+      : options.contentSignal;
+  if (signalRaw !== null && signalRaw !== "") {
+    lines.push("User-agent: *");
+    lines.push(`Content-Signal: ${signalRaw}`);
+    lines.push("");
+  }
+
+  for (const sm of toArray(options.sitemap)) {
+    lines.push(`Sitemap: ${sm}`);
+  }
+  if (options.host !== undefined && options.host !== "") {
+    lines.push(`Host: ${options.host}`);
+  }
+
+  // Collapse trailing empty lines into a single newline so the file
+  // ends cleanly regardless of which optional sections were emitted.
+  return lines.join("\n").replace(/\n+$/, "") + "\n";
+}
+
+function toArray<T>(value: T | T[] | undefined): T[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}

package/src/route.ts

@@ -0,0 +1,112 @@
+import { revalidateTag } from "next/cache";
+import { Buffer } from "node:buffer";
+import crypto from "node:crypto";
+
+interface WebhookPayload {
+  paths?: string[];
+}
+
+const BEARER_PREFIX = "Bearer ";
+
+/**
+ * Webhook handler for SaaS-pushed cache invalidation. Drop-in install:
+ *
+ *   ```ts
+ *   // app/api/smking-revalidate/route.ts
+ *   export { POST, GET } from '@soloworks/smking-next/route';
+ *   ```
+ *
+ * Then set `SMKING_WEBHOOK_TOKEN` in your environment and configure the
+ * SaaS to POST `{ paths: [...] }` with `Authorization: Bearer <token>`.
+ *
+ * Bearer-token auth (not HMAC body signing) — sufficient for v1.
+ * HMAC-signed body verification can layer on later if attack surface
+ * justifies it. Token compare runs through `crypto.timingSafeEqual` to
+ * avoid leaking length / prefix info via response time.
+ */
+export async function POST(request: Request): Promise<Response> {
+  const expected = process.env.SMKING_WEBHOOK_TOKEN;
+  if (!expected) {
+    return Response.json(
+      { error: "webhook_not_configured" },
+      { status: 503 },
+    );
+  }
+
+  const auth = request.headers.get("authorization");
+  if (!auth || !verifyBearer(auth, expected)) {
+    return Response.json({ error: "unauthorized" }, { status: 401 });
+  }
+
+  let payload: WebhookPayload;
+  try {
+    payload = (await request.json()) as WebhookPayload;
+  } catch {
+    return Response.json({ error: "invalid_json" }, { status: 400 });
+  }
+
+  let revalidated = 0;
+  let errors = 0;
+  for (const p of payload.paths ?? []) {
+    try {
+      // Next.js 16 requires a cache profile; 'default' matches the
+      // implicit profile a normal `'use cache'` block uses.
+      revalidateTag(`smking:path:${p}`, "default");
+      revalidated++;
+    } catch (err) {
+      errors++;
+      console.warn(
+        `[@soloworks/smking-next] revalidateTag failed for path "${p}":`,
+        err,
+      );
+    }
+  }
+
+  return Response.json({ revalidated, errors });
+}
+
+/**
+ * Liveness probe — POST-only public endpoint, but `GET` returns 401 with
+ * a `WWW-Authenticate` header so customers can verify the route is wired
+ * up by sending a token. Discourages anonymous probes from confirming
+ * the endpoint exists.
+ */
+export async function GET(request: Request): Promise<Response> {
+  const expected = process.env.SMKING_WEBHOOK_TOKEN;
+  if (!expected) {
+    return Response.json(
+      { error: "webhook_not_configured" },
+      { status: 503 },
+    );
+  }
+  const auth = request.headers.get("authorization");
+  if (auth && verifyBearer(auth, expected)) {
+    return new Response("OK", { status: 200 });
+  }
+  return new Response("Unauthorized", {
+    status: 401,
+    headers: { "WWW-Authenticate": 'Bearer realm="smking-webhook"' },
+  });
+}
+
+/**
+ * Constant-time bearer-token compare. Returns false on:
+ *   - missing or non-Bearer header
+ *   - presented token has different length than expected (early-out;
+ *     the lengths themselves leak nothing because the secret is set by
+ *     the customer with a known length)
+ *   - byte-different but same-length token
+ */
+function verifyBearer(authHeader: string, expected: string): boolean {
+  if (!authHeader.startsWith(BEARER_PREFIX)) return false;
+  const presented = authHeader.slice(BEARER_PREFIX.length);
+  if (presented.length !== expected.length) return false;
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(presented),
+      Buffer.from(expected),
+    );
+  } catch {
+    return false;
+  }
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+/**
+ * TypeScript shape of the smking Public AEO API response. Mirrors the
+ * server-side AeoResponse — every field is either a usable value or
+ * absent / null, and consumers should treat null as "no signal".
+ */
+
+export type AeoStatus = "ready" | "pending" | "not_found";
+
+export interface FaqItem {
+  q: string;
+  a: string;
+}
+
+export interface ChatLinks {
+  chatgpt: string;
+  perplexity: string;
+  google: string;
+}
+
+/**
+ * Server-resolved SEO metadata. Public API does fallback chains
+ * server-side (ogTitle → title, ogDescription → metaDescription,
+ * ogImageUrl → imageUrl, canonicalUrl → pageUrl).
+ */
+export interface SeoMeta {
+  title: string | null;
+  ogTitle: string | null;
+  ogDescription: string | null;
+  ogImageUrl: string | null;
+  canonicalUrl: string | null;
+}
+
+export interface AeoResponse {
+  status: AeoStatus;
+  jsonLd?: Record<string, unknown>;
+  faq?: FaqItem[];
+  summary?: string;
+  metaDescription?: string;
+  faqHtml?: string;
+  summaryHtml?: string;
+  chatLinks?: ChatLinks;
+  seo?: SeoMeta | null;
+}
+
+export interface DiscoverParams {
+  /** Public API key (`pk_*`). Required. */
+  apiKey: string;
+  /**
+   * URL path to look up. Auto-resolved from request headers when omitted.
+   * Pass explicitly only when you know it (saves one header read) or for
+   * static-export contexts where `headers()` is unavailable.
+   */
+  path?: string;
+  /**
+   * Full request URL — used by the SaaS to register a new path for
+   * background crawling on first sight. Auto-resolved from headers when
+   * omitted; pass explicitly alongside `path` only when overriding.
+   */
+  url?: string;
+  /**
+   * smking deployment origin. Required — pass directly or set
+   * `SMKING_BASE_URL` env. Missing value short-circuits to fail-open
+   * (no fetch, no inject, dev-only warning).
+   */
+  baseUrl?: string;
+  /** Next.js `fetch` revalidate seconds. Defaults to 3600 (1h ISR backstop). */
+  revalidate?: number;
+}