@soloworks/smking-next 0.16.1 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @soloworks/smking-next
 
+## 0.18.0 — 2026-05-28
+
+**CMS live-URL reporting — `<SmkingCms>` now tells the dashboard each page's real public URL.**
+
+### Added
+
+- `getCmsPage()` appends `sdk` / `sdk_version` / `url` / `path` / `app_env` query params to its `GET /api/v1/public/page` (mirroring the AEO heartbeat). saas stores the real per-slug `pageUrl` — so the dashboard "View page ↗" link points at the actual customer URL instead of a guessed domain — and upserts `sdk_health_snapshots` with the CMS-side heartbeat.
+- `getCmsPage({ url, path })` accept optional overrides; `<SmkingCms>` resolves them from `next/headers` when omitted (same pattern as `<SmkingAEO>`).
+
+### Changed
+
+- `SDK_VERSION` moved into `version.ts`, now the single source shared by `client.ts` (AEO) and `cms-client.ts` (CMS) so the reported heartbeat version can't drift between the two call sites.
+
+### Why
+
+CMS reads are high-frequency and ISR-cached, so the request stays a `GET` — switching to POST to carry a body would break the data cache. Piggybacking query params keeps the cache while letting saas learn each page's real URL + liveness.
+
+## 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.18.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

@@ -4,10 +4,25 @@ import type {} from "next";
 
 import type { AeoResponse, DiscoverParams } from "../types";
 import { normalizePath, resolveRequestPath } from "./path";
+import { SDK_VERSION } from "./version";
 
 const DEFAULT_REVALIDATE_SECONDS = 3600;
 const FETCH_TIMEOUT_MS = 2000;
 
+/**
+ * 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 +96,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,

package/src/lib/cms-client.ts

@@ -3,6 +3,8 @@
 import type {} from "next";
 
 import type { CmsParams, CmsResponse } from "../types";
+import { resolveRequestPath } from "./path";
+import { SDK_VERSION } from "./version";
 
 // CMS-specific TTL — shorter than AEO's 1h because CMS body is
 // hand-edited (frequent updates) vs AEO which is SaaS-generated
@@ -72,11 +74,37 @@ export async function getCmsPage(
     return null;
   }
 
+  let requestPath = params.path;
+  let requestUrl = params.url;
+  if (!requestPath || !requestUrl) {
+    try {
+      const resolved = await resolveRequestPath();
+      if (!requestPath) requestPath = resolved.path;
+      if (!requestUrl) requestUrl = resolved.url;
+    } catch {
+      // Fallback silently if outside request scope
+    }
+  }
+
   try {
-    const url = `${baseUrl}/api/v1/public/page?key=${encodeURIComponent(
+    let apiUrl = `${baseUrl}/api/v1/public/page?key=${encodeURIComponent(
       params.apiKey,
     )}&slug=${encodeURIComponent(params.slug)}`;
-    const res = await fetch(url, {
+
+    if (requestPath) {
+      apiUrl += `&path=${encodeURIComponent(requestPath)}`;
+    }
+    if (requestUrl) {
+      apiUrl += `&url=${encodeURIComponent(requestUrl)}`;
+    }
+
+    apiUrl += `&sdk=next&sdk_version=${encodeURIComponent(SDK_VERSION)}`;
+    const appEnv = params.appEnv ?? process.env.NODE_ENV;
+    if (appEnv) {
+      apiUrl += `&app_env=${encodeURIComponent(appEnv)}`;
+    }
+
+    const res = await fetch(apiUrl, {
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
       next: {
         revalidate: params.revalidate ?? DEFAULT_REVALIDATE_SECONDS,

package/src/lib/version.ts

@@ -0,0 +1 @@
+export const SDK_VERSION = "0.18.0";

package/src/types.ts

@@ -225,6 +225,12 @@ export interface CmsParams {
    * and changes more often; matches `smking/laravel`'s `cms_ttl`).
    */
   revalidate?: number;
+  /** Optional current request URL for live preview link on the SaaS dashboard. */
+  url?: string;
+  /** Optional request path. */
+  path?: string;
+  /** Optional app environment (e.g. 'development', 'production'). */
+  appEnv?: string;
 }
 
 export interface DiscoverParams {