@soloworks/smking-next 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @soloworks/smking-next
 
+## 0.17.0 — 2026-05-26
+
+**SDK self-report (heartbeat) — dashboard SDK Health chip stops getting WAF false-negatives.**
+
+### Added
+
+- Every `getAeoContent()` POST now piggybacks an `sdk_meta` field on the request body so saas can upsert `sdk_health_snapshots` with `source='sdk_heartbeat'`. The dashboard "SDK Health" chip reads this signal as primary, falling back to active probe only when fresh (<24h) heartbeat is absent.
+- Payload shape: `{ sdk: "next", sdk_version, app_env, host }`. All fields optional saas-side; host is parsed from the request URL via `new URL(url).hostname`.
+
+### Why
+
+Customer Cloudflare WAFs commonly block saas's Vercel ASN egress (Vercel + Googlebot UA = reverse-DNS mismatch → 403 reject). Active probe from saas → customer site reliably fails on protected sites like sleepytofu.com even when SDK is fully operational. SDK-initiated heartbeat bypasses the WAF because the customer site is the originator — saas never needs to fetch back.
+
+### Migration
+
+No customer action required. Patch your SDK and the dashboard chip updates automatically on the next page render that triggers `getAeoContent`. Saas accepts the field since 2026-05; older saas versions ignore unknown body fields silently.
+
+Minor bump — backward-compatible feature. `^0.16` consumers must update their constraint to `^0.17`.
+
 ## 0.16.1 — 2026-05-25
 
 **New `<SmkingRuntime />` component — one-time mount in customer root layout to load saas-served CSS + Web Component runtime JS.**

package/README.md

@@ -84,6 +84,30 @@ Content-Type: application/json
 
 Response: `{ revalidated: number, errors: number }`. `errors > 0` means some tags couldn't be revalidated (others still succeeded — partial-success delivery).
 
+## Mount the runtime once (v0.16.1+)
+
+Add `<SmkingRuntime />` once in your root layout — it emits a `<link>` to the saas-served CSS and a `<script async>` to the bundled Web Component runtime IIFE. Browser caches both per saas-controlled stale-while-revalidate headers, so the cost amortises across every `<SmkingCms>` instance on the page.
+
+```tsx
+// app/layout.tsx
+import { SmkingRuntime } from "@soloworks/smking-next";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <SmkingRuntime />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+Optional `baseUrl` prop overrides `process.env.SMKING_BASE_URL`. Default: `https://smking.app`.
+
+Without `<SmkingRuntime />`, `<SmkingCms>` content still renders but the Tailwind utility classes from the dashboard's cva variants resolve to dead strings — the page reaches the browser unstyled. The wizard installer auto-adds this mount; if you're upgrading manually from < v0.16.1, add the one line above.
+
 ## CMS rendering (optional, v0.11.0+)
 
 The base install only wires AEO. If you author content in the smking dashboard's CMS and want to render it on your Next.js site, use the `<SmkingCms slug="…" />` Server Component.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soloworks/smking-next",
-  "version": "0.16.1",
+  "version": "0.17.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",

package/src/lib/client.ts

@@ -8,6 +8,27 @@ import { normalizePath, resolveRequestPath } from "./path";
 const DEFAULT_REVALIDATE_SECONDS = 3600;
 const FETCH_TIMEOUT_MS = 2000;
 
+/**
+ * SDK version self-reported in heartbeat `sdk_meta.sdk_version`. Must stay
+ * in sync with package.json `version` — `publish-smking-package` skill
+ * bumps both together.
+ */
+const SDK_VERSION = "0.17.0";
+
+/**
+ * Extract hostname from a full URL string. Returns null on parse failure
+ * (malformed URL would otherwise throw). Used to populate heartbeat
+ * `sdk_meta.host` without pulling next/headers into this client.
+ */
+function safeHostname(input: string | undefined): string | null {
+  if (!input) return null;
+  try {
+    return new URL(input).hostname;
+  } catch {
+    return null;
+  }
+}
+
 const _warnedKeys = new Set<string>();
 function warnOnce(key: string, message: string): void {
   if (process.env.NODE_ENV === "production") return;
@@ -81,7 +102,22 @@ export async function getAeoContent(
     const res = await fetch(`${baseUrl}/api/v1/public/aeo`, {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ key: params.apiKey, path, url }),
+      body: JSON.stringify({
+        key: params.apiKey,
+        path,
+        url,
+        // Heartbeat piggyback — saas upserts into sdk_health_snapshots so
+        // the dashboard can show 'SDK active (last seen Nm ago)' without
+        // needing an outbound probe (which Cloudflare WAFs commonly block).
+        // Saas accepts this optional field via /api/v1/public/aeo POST since
+        // 2026-05; older saas versions silently ignore it.
+        sdk_meta: {
+          sdk: "next",
+          sdk_version: SDK_VERSION,
+          app_env: process.env.NODE_ENV ?? null,
+          host: safeHostname(url),
+        },
+      }),
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
       next: {
         revalidate: params.revalidate ?? DEFAULT_REVALIDATE_SECONDS,