@sonordev/site-kit 7.0.0 → 7.0.2

package/docs.json

@@ -0,0 +1,67 @@
+{
+  "$comment": "What sonor.dev renders for this package, in nav order. sonor.dev reads this file from the published tarball (latest on npm), so a release IS the docs deploy: add a page here and ship it in package.json `files`. scripts/verify-docs.cjs fails the publish if a listed file is missing from the pack.",
+  "schemaVersion": 1,
+  "title": "site-kit",
+  "summary": "One package, one env var, every Sonor module on a Next.js site: SEO, analytics, forms, articles, commerce, chat, AI visibility, agent tools and motion.",
+  "groups": [
+    {
+      "title": "Start here",
+      "pages": [
+        { "slug": "", "title": "Overview", "file": "README.md" },
+        { "slug": "migrating-to-7", "title": "Migrating to 7", "file": "docs/MIGRATING-TO-7.md" },
+        { "slug": "agents", "title": "For coding agents", "file": "AGENTS.md" }
+      ]
+    },
+    {
+      "title": "Core",
+      "pages": [
+        { "slug": "layout", "title": "Layout", "file": "src/layout/README.md" },
+        { "slug": "seo", "title": "SEO", "file": "src/seo/README.md" },
+        { "slug": "analytics", "title": "Analytics", "file": "src/analytics/README.md" },
+        { "slug": "sitemap", "title": "Sitemap", "file": "src/sitemap/README.md" },
+        { "slug": "proxy", "title": "Proxy", "file": "src/proxy/README.md" },
+        { "slug": "redirects", "title": "Redirects", "file": "src/redirects/README.md" },
+        { "slug": "og", "title": "OG cards", "file": "src/og/README.md" }
+      ]
+    },
+    {
+      "title": "Content",
+      "pages": [
+        { "slug": "articles", "title": "Articles", "file": "src/articles/README.md" },
+        { "slug": "images", "title": "Images", "file": "src/images/README.md" },
+        { "slug": "reputation", "title": "Reputation", "file": "src/reputation/README.md" }
+      ]
+    },
+    {
+      "title": "Engagement",
+      "pages": [
+        { "slug": "forms", "title": "Forms", "file": "src/forms/README.md" },
+        { "slug": "chat", "title": "Website chat", "file": "src/engage/README.md" },
+        { "slug": "cta-bar", "title": "CTA bar", "file": "src/cta-bar/README.md" },
+        { "slug": "signal", "title": "Signal (A/B)", "file": "src/signal/README.md" }
+      ]
+    },
+    {
+      "title": "Commerce",
+      "pages": [
+        { "slug": "commerce", "title": "Commerce", "file": "src/commerce/README.md" },
+        { "slug": "booking", "title": "Booking", "file": "src/sync/README.md" }
+      ]
+    },
+    {
+      "title": "AI visibility",
+      "pages": [
+        { "slug": "llms", "title": "llms.txt and AEO", "file": "src/llms/README.md" },
+        { "slug": "mcp", "title": "MCP and agent tools", "file": "src/mcp/README.md" }
+      ]
+    },
+    {
+      "title": "More",
+      "pages": [
+        { "slug": "motion", "title": "Motion", "file": "src/motion/README.md" },
+        { "slug": "admin-auth", "title": "Sign in with Sonor", "file": "src/admin-auth/README.md" }
+      ]
+    }
+  ],
+  "changelog": { "file": "CHANGELOG.md", "since": "7.0.0" }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonordev/site-kit",
-  "version": "7.0.0",
+  "version": "7.0.2",
   "type": "module",
   "packageManager": "pnpm@11.5.3",
   "description": "Complete client-side integration kit for Sonor - SEO, Analytics, Engage, Forms, Blog",
@@ -367,7 +367,11 @@
     "README.md",
     "AGENTS.md",
     "agent-manifest.json",
-    "skills"
+    "skills",
+    "docs.json",
+    "CHANGELOG.md",
+    "docs/MIGRATING-TO-7.md",
+    "src/*/README.md"
   ],
   "scripts": {
     "build": "NODE_OPTIONS=--max-old-space-size=8192 tsup && pnpm build:types && node scripts/gen-agent-manifest.cjs",
@@ -387,8 +391,9 @@
     "typecheck": "tsc --noEmit",
     "typecheck:setup": "tsc --noEmit -p packages/sonor-setup/tsconfig.json",
     "version": "node scripts/sync-version.cjs && node scripts/gen-agent-manifest.cjs && git add src/shared/version.ts agent-manifest.json",
-    "prepublishOnly": "rm -rf dist && NODE_OPTIONS=--max-old-space-size=8192 tsup && pnpm build:types && node scripts/gen-agent-manifest.cjs && node scripts/verify-dts.cjs && node scripts/prepublish-integration.cjs && node scripts/audit-as-consumer.cjs",
-    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --noEmit false && node scripts/alias-dts.cjs"
+    "prepublishOnly": "rm -rf dist && NODE_OPTIONS=--max-old-space-size=8192 tsup && pnpm build:types && node scripts/gen-agent-manifest.cjs && node scripts/verify-dts.cjs && node scripts/prepublish-integration.cjs && node scripts/audit-as-consumer.cjs && node scripts/verify-docs.cjs",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --noEmit false && node scripts/alias-dts.cjs",
+    "verify:docs": "node scripts/verify-docs.cjs"
   },
   "peerDependencies": {
     "@portabletext/react": "^8.0.0",

package/src/admin-auth/README.md

@@ -0,0 +1,88 @@
+# `@sonordev/site-kit/admin-auth` — Sign in with Sonor
+
+Put a site's own admin area behind a Sonor login. Whoever can open the
+project in Sonor (its owners and members, the managing agency, platform
+admins) can sign in; nobody else can. There are no passwords on the site.
+
+## Wiring
+
+```ts
+// lib/sonor-sso.ts
+import { createSonorSso } from '@sonordev/site-kit/admin-auth'
+
+export const sso = createSonorSso({
+  paths: '/admin',            // or ['/bid', '/route'] for several areas
+  // loginPath: '/admin/login' (default: `${paths[0]}/login`)
+  // adminEmails: process.env.ADMIN_EMAILS,
+})
+```
+
+```ts
+// proxy.ts
+import { createProxy } from '@sonordev/site-kit/proxy'
+import { sso } from '@/lib/sonor-sso'
+
+export default createProxy({ before: sso.gate, redirects: true, securityHeaders: true })
+```
+
+```ts
+// app/api/auth/callback/route.ts
+import { sso } from '@/lib/sonor-sso'
+export const GET = sso.handleCallback
+```
+
+```ts
+// app/api/auth/logout/route.ts
+import { sso } from '@/lib/sonor-sso'
+export const GET = sso.handleLogout
+export const POST = sso.handleLogout
+```
+
+```tsx
+// app/admin/login/page.tsx (server component)
+import { SSO_ERROR_MESSAGES } from '@sonordev/site-kit/admin-auth'
+import { sso } from '@/lib/sonor-sso'
+
+export default async function Login({ searchParams }) {
+  const { error, return_to } = await searchParams
+  let href: string | null = null
+  try { href = await sso.getLoginUrl({ returnTo: return_to }) } catch {}
+  return (
+    <>
+      {error && <p>{SSO_ERROR_MESSAGES[error] ?? error}</p>}
+      {href ? <a href={href}>Sign in with Sonor</a> : <p>Sign-in is unavailable.</p>}
+    </>
+  )
+}
+```
+
+```ts
+// Every API route and server action that touches admin data
+const session = await sso.getSession()
+if (!session) return new Response('Unauthorized', { status: 401 })
+```
+
+Designer APIs or other JSON endpoints can be guarded in the middleware too:
+pass `apiPaths: ['/api/studio']` and include them in the matcher. They get a
+401 JSON response instead of a redirect.
+
+## Env
+
+| Var | |
+|---|---|
+| `SONOR_API_KEY` | Already on every site. Identifies the project and verifies tokens. |
+| `SONOR_SESSION_SECRET` | 32+ random chars (`openssl rand -hex 32`). Rotate to sign everyone out. |
+| `NEXT_PUBLIC_SITE_URL` | The site's public origin, for the callback URL. |
+
+The callback route has to be reachable at `callbackPath` (default
+`/api/auth/callback`) on `NEXT_PUBLIC_SITE_URL`.
+
+## Rules
+
+- **The gate doesn't cover `/api/*`.** The standard middleware matcher
+  excludes it. Check `getSession()` in every API route.
+- **Don't trust identity from headers, query strings or bodies.**
+  `getSession()` reads the httpOnly cookie and verifies its signature on
+  every call; that's the only source.
+- **Moving a site onto this module:** pass its existing `cookieName` and
+  `secretEnv` so current sessions stay valid.

package/src/analytics/README.md

@@ -0,0 +1,264 @@
+# Analytics — `@sonordev/site-kit/analytics`
+
+Automatic page view tracking, custom events, conversions, scroll depth, heatmap clicks, and Core Web Vitals. All data flows through the Sonor API.
+
+## Usage
+
+`SiteKitLayout` mounts analytics for you. It renders `{children}` first and
+mounts `AnalyticsProvider` after them as a childless sibling, deferred until
+window load + idle (or the first interaction). Analytics never sits in the
+page's hydration path and can't push a route to client rendering. Configure it
+on the layout:
+
+```tsx
+// app/layout.tsx (server component)
+import { SiteKitLayout } from '@sonordev/site-kit/layout'
+import { ContactTracking } from '@sonordev/site-kit/analytics'
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <SiteKitLayout analytics={{ excludePaths: ['/admin'] }}>{children}</SiteKitLayout>
+        {/* Optional: tel:/mailto: clicks as conversions. Childless, renders null. */}
+        <ContactTracking />
+      </body>
+    </html>
+  )
+}
+```
+
+Don't wrap `{children}` in `AnalyticsProvider` yourself. It puts analytics in
+the hydration path (the page-view code ships in the page's initial scripts),
+and if it's lazy-loaded with `next/dynamic({ ssr: false })` the whole route
+de-opts to client rendering.
+
+### Without `SiteKitLayout`
+
+A layout that doesn't use core `SiteKitLayout` mounts analytics itself, and
+still as a deferred, childless island. Publish the credential server-side
+first with `SiteKitCredential` (see `@sonordev/site-kit/client`). Never pass
+`SONOR_API_KEY` to a client component.
+
+```tsx
+// app/analytics-shell.tsx
+'use client'
+import { AnalyticsProvider, ContactTracking } from '@sonordev/site-kit/analytics'
+
+export default function AnalyticsShell() {
+  return (
+    <AnalyticsProvider trackPageViews trackWebVitals>
+      <ContactTracking />
+    </AnalyticsProvider>
+  )
+}
+```
+
+```tsx
+// app/deferred-analytics.tsx
+'use client'
+import { lazy, Suspense } from 'react'
+import { useDeferredActivation } from '@sonordev/site-kit/client'
+
+const AnalyticsShell = lazy(() => import('./analytics-shell'))
+
+export function DeferredAnalytics() {
+  const ready = useDeferredActivation(true)
+  if (!ready) return null
+  return (
+    <Suspense fallback={null}>
+      <AnalyticsShell />
+    </Suspense>
+  )
+}
+```
+
+```tsx
+// app/layout.tsx (server component): {children} is a SIBLING of the island, never inside it
+import { resolveClientCredential } from '@sonordev/site-kit/server'
+import { SiteKitCredential } from '@sonordev/site-kit/client'
+import { DeferredAnalytics } from './deferred-analytics'
+
+export default async function RootLayout({ children }) {
+  const credential = await resolveClientCredential(process.env.SONOR_API_KEY ?? '', 'https://api.sonor.io')
+  return (
+    <html lang="en">
+      <body>
+        <SiteKitCredential apiKey={credential} />
+        {children}
+        <DeferredAnalytics />
+      </body>
+    </html>
+  )
+}
+```
+
+`AnalyticsProvider` already mounts `WebVitals` when `trackWebVitals` is on.
+Don't add a second `<WebVitals />`, or every metric reports twice.
+
+## Tracking custom events
+
+Under `SiteKitLayout` the provider is childless, so no page component sits
+inside it. Use the standalone functions. They need no provider and queue until
+the deferred provider mounts:
+
+```tsx
+'use client'
+import { trackEvent, trackConversion } from '@sonordev/site-kit/analytics'
+
+trackEvent({ name: 'button_click', category: 'engagement', properties: { buttonId: 'cta' } })
+trackConversion({ type: 'purchase', value: 99.99, currency: 'USD' })
+```
+
+## Hooks
+
+`useAnalytics()` and `useTrackEvent()` read the provider's context, so they
+only work in components rendered inside an `AnalyticsProvider` (children of
+your own analytics island, for example). Anywhere else they throw. Reach for
+the standalone functions above instead of wrapping `{children}` to make a hook
+work. `useAnalyticsOptional()` returns `null` instead of throwing.
+
+### useAnalytics()
+
+```tsx
+const { trackEvent, trackConversion, sessionId, visitorId } = useAnalytics()
+```
+
+### useTrackEvent()
+
+```tsx
+const { trackEvent, trackConversion } = useTrackEvent()
+```
+
+### useContactTracking()
+
+Auto-tracks `tel:` and `mailto:` link clicks as conversions. Works anywhere: it
+uses the standalone dispatch, not the provider's context.
+
+```tsx
+const { trackPhoneClick, trackEmailClick } = useContactTracking()
+```
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| `AnalyticsProvider` | The tracker. `SiteKitLayout` mounts it childless; never wrap `{children}` in it |
+| `WebVitals` | Auto-reports LCP, CLS, TTFB, INP, FCP. `AnalyticsProvider` mounts it when `trackWebVitals` is on |
+| `ContactTracking` | Auto-tracks phone/email link clicks. Childless, renders null |
+
+## AnalyticsProvider Props
+
+```ts
+interface AnalyticsConfig {
+  projectId?: string           // Auto-resolved from API key
+  trackPageViews?: boolean     // Default: true
+  trackWebVitals?: boolean     // Default: true
+  trackScrollDepth?: boolean   // Default: true
+  sessionTimeout?: number      // Minutes (default: 30)
+  excludePaths?: string[]      // Don't track these paths
+  allowInFrame?: boolean       // Default: false — see below
+  allowLocalhost?: boolean     // Default: false — local builds report nothing
+  debug?: boolean              // Log events to console
+}
+```
+
+## What Gets Tracked Automatically
+
+- **Page views** — on every route change (path, URL, title, referrer, UTM params, device/browser/OS)
+- **Web Vitals** — LCP, CLS, TTFB, INP, FCP with good/needs-improvement/poor ratings
+- **Contact clicks** — `tel:` and `mailto:` links tracked as conversions, once `<ContactTracking />` is mounted (it isn't by default)
+- **DOM metadata** — full snapshot per page view (meta tags, H1, word count, links, content, FAQs)
+
+## Embedded pages report nothing (`analytics.allowInFrame`)
+
+When this site is loaded inside a **cross-origin iframe**, nothing is sent —
+no page views, journey/session rows, scroll depth, heatmap clicks, web vitals,
+events or conversions. The visitor is on whoever framed the page, not on this
+site, so every metric the frame produces is phantom traffic in the analytics
+its owner reads.
+
+This is not hypothetical. Upforge case studies embed each client's whole
+production site in three eager iframes, and `securityHeaders`'
+`DEFAULT_FRAME_ANCESTORS` permits that. Before the guard landed, 23 client
+sites carried the signature in `analytics_page_views`: three views of `/`
+sharing one session and visitor id, 21-80ms apart, referrer
+`https://upforge.io/` — the desktop, tablet and mobile frames of one case
+study. The screenshot overlay in those frames hides the pixels, not the
+JavaScript.
+
+**Same-origin frames still report.** A site embedding itself (a preview pane,
+a print view, an on-domain booking frame) has a real visitor really on that
+site and no other tenant to pollute.
+
+Opt back in only when the frame IS the product — a widget or partner-hosted
+page deliberately distributed as an embed:
+
+```tsx
+<SiteKitLayout analytics={{ allowInFrame: true }}>…</SiteKitLayout>
+```
+
+There is deliberately no env var or window global for this. A silent switch
+that turns cross-tenant tracking back on is the failure mode, not the feature.
+
+The decision lives in one place — `shared/reporting-gate.ts`, over the frame
+primitive in `shared/frame.ts`. Every send in the module routes through it, and
+`send-gate.test.ts` fails the build if a new one does not. `isCrossOriginFrame()`
+is exported from `@sonordev/site-kit/analytics` if a site needs the same answer
+for its own third-party pixels.
+
+## Local builds report nothing (`analytics.allowLocalhost`)
+
+The actual browser hostname controls this gate, even in a production build
+with `analytics.site` or `NEXT_PUBLIC_SITE_URL` set to a production domain.
+`localhost`, its subdomains, `127.0.0.1`, `[::1]`, and `0.0.0.0` report nothing
+by default: page views, events, conversions, sessions, vitals, scroll and
+heatmap data, fleet heartbeats, and client-side sitemap registrations all use
+`resolveAnalyticsTarget`. Engage doesn't mount its widgets or chat transport.
+Public hosts and same-origin frames on public hosts still report normally.
+
+For intentional local reporting:
+
+```tsx
+<SiteKitLayout analytics={{ allowLocalhost: true }}>…</SiteKitLayout>
+```
+
+The layout passes this option to AnalyticsProvider, WebVitals, FleetHeartbeat,
+SitemapSync and EngageWidget. Standalone components and `sendFleetHeartbeat`
+accept it too; standalone `trackEvent`/`trackConversion` use their mounted
+AnalyticsProvider's options. A local cross-origin frame needs **both** opt-ins.
+Neither option bypasses authentication. No environment variable or global
+silently enables local reporting.
+
+This is a browser gate: build-time `createSitemap` and Node fleet reporting
+still run. It doesn't disable forms, commerce, or Signal. When verifying those
+modules locally, point them at a test API as well.
+
+## Environment
+
+Uses `SONOR_API_KEY` (injected by `SiteKitLayout`) or `window.__SITE_KIT_API_KEY__`.
+
+## Multi-site projects (`analytics.site`)
+
+A single Sonor project can host many sub-sites (e.g. one project hosting
+example.com + 16 state microsites). Every analytics event is
+tagged with the sub-site host so the dashboard can roll up + filter per
+site without forcing each microsite into its own Sonor project.
+
+`SiteKitLayout` resolves the host in this precedence order:
+
+1. Explicit `analytics.site` config
+2. `NEXT_PUBLIC_SITE_URL` host
+3. `window.location.host`
+
+```tsx
+<SiteKitLayout
+  analytics={{ site: 'ohio.example.com' }}
+>
+  …
+</SiteKitLayout>
+```
+
+Most projects leave it implicit — `NEXT_PUBLIC_SITE_URL` is already set per
+microsite, so the dimension fills in automatically. The dashboard shows a
+"Site" picker + a "Sites" tab as soon as ≥2 distinct hosts are detected.