@sonordev/site-kit 7.0.1 → 7.1.0

package/src/proxy/README.md

@@ -0,0 +1,152 @@
+# Proxy — `@sonordev/site-kit/proxy`
+
+Composable Next.js Proxy factory. Zero-config redirects + security headers. Opt-in AI discovery headers.
+
+Next 16 renamed the `middleware` file convention to `proxy`. Through 7.x this
+module is also served on `@sonordev/site-kit/middleware`, with `createMiddleware`
+as an alias of `createProxy`; both go in 8.0. `npx sonor-setup codemod --write`
+moves a site over (the file too).
+
+## Usage
+
+```ts
+// proxy.ts — at the project root, or in src/
+import { createProxy } from '@sonordev/site-kit/proxy'
+
+export default createProxy()
+
+// Inlined on purpose. See "The matcher must be inlined" below — importing
+// siteKitMatcher here is a build error.
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon\\.ico|.*\\.(?:ico|png|jpg|jpeg|gif|webp|svg|woff2?)$).*)',
+  ],
+}
+```
+
+With options:
+
+```ts
+export default createProxy({
+  securityHeaders: { frameAncestors: ["'self'", 'https://partner.example.com'] },
+  llmsDiscovery: { siteUrl: 'https://example.com' },
+  before: (req) => {
+    // Custom auth check, geolocation, etc.
+  },
+})
+```
+
+## The matcher must be inlined
+
+**`export const config = siteKitMatcher` is a build error.** Next statically
+parses `config.matcher` at build time and Turbopack rejects any imported value,
+so the array has to be a literal in your own file. Copy it from the example
+above, or read it off `siteKitMatcher` — but paste the contents, don't export
+the binding.
+
+`siteKitMatcher` exists so the canonical pattern lives in one place that the
+scaffold, the docs, and the tests all read. It is a **reference value**.
+
+## Migrating from `middleware.ts`
+
+```bash
+npx sonor-setup next16
+```
+
+Runs the codemod's `next-16-proxy` transform (deterministic and offline: it
+moves the file, renames a named `middleware` export to `proxy`, and never
+moves onto an existing `proxy.ts`) and re-runs the doctor check afterwards, so
+the result is verified rather than assumed. Safe to run twice. A file that
+sets `runtime` is flagged rather than moved (see below).
+
+Two Next 16 traps to know:
+
+- **No `runtime` export.** Proxy defaults to the Node.js runtime and the
+  `runtime` config option is unavailable in proxy files — setting it throws at
+  build time. (`middleware.ts` still accepts `runtime: 'nodejs'`, and it does
+  run on Netlify; remove the export before moving the file.)
+- **The matcher**, as above.
+
+## Config
+
+```ts
+interface SiteKitProxyConfig {
+  redirects?: boolean | RedirectConfig               // Sonor-managed redirects (default: true)
+  securityHeaders?: boolean | SecurityHeadersConfig  // Security headers (default: true)
+  llmsDiscovery?: LlmsDiscoveryConfig | false        // AI crawler discovery header
+  identity?: boolean | IdentityConfig                // Opt-in edge identity pass
+
+  before?: (req: NextRequest) => NextResponse | undefined | Promise<NextResponse | undefined>
+  after?: (req: NextRequest, res: NextResponse) => NextResponse | Promise<NextResponse>
+}
+
+interface LlmsDiscoveryConfig {
+  siteUrl: string          // e.g. 'https://example.com'
+  llmsPath?: string        // Default: '/llms.txt'
+  mcpServerCard?: boolean | string  // Also link the MCP server card (rel="service-desc"); true = '/.well-known/mcp-server-card'
+}
+```
+
+`redirects: true` (the default) checks managed rules before each page render.
+The rule list is cached in memory for five minutes per instance, and a fetch is
+bounded at 300ms with a 30s cooldown after a failure, so page loads rarely wait
+on it. Set `redirects: false` only on a site that uses no Sonor-managed
+redirects.
+
+Don't resolve redirects in `app/not-found.tsx` with `resolveManagedRedirect()`.
+Next renders the root not-found boundary inside every page, so its `headers()`
+call makes every route dynamic: on a Next 16 build every static route turned
+into a dynamic one. The resolver is deprecated.
+
+## What It Handles (in order)
+
+1. **Before hook** — optional custom logic (return `NextResponse` to short-circuit)
+2. **Sonor-managed redirects** — 301/302/307/308 with query param preservation
+3. **Security headers** — see the table below
+4. **AI discovery header** — `Link: <url>; rel="describedby"; type="text/markdown"` on every request that
+   could be for a page: GET or HEAD, an Accept header that allows HTML (or no Accept header at all, which is
+   how curl and many crawlers ask), not a file-like path (`/llms.txt`, `/sitemap.xml`), not `/api/`, and not
+   a Next RSC navigation request. See `wantsLlmsDiscoveryLink` in `@sonordev/site-kit/llms`.
+5. **After hook** — mutate response headers
+
+## Security Headers (defaults)
+
+| Header | Value |
+|--------|-------|
+| X-DNS-Prefetch-Control | `on` |
+| Content-Security-Policy | `frame-ancestors 'self' https://upforge.io https://*.upforge.io` |
+| X-Content-Type-Options | `nosniff` |
+| X-XSS-Protection | `1; mode=block` |
+| Referrer-Policy | `strict-origin-when-cross-origin` |
+| Permissions-Policy | `camera=(), microphone=(), geolocation=()` |
+
+Note there is no `X-Frame-Options` row — that is deliberate, see below.
+
+### Framing / `frame-ancestors`
+
+Upforge showcases live client work in iframes on its portfolio and area
+pages, so managed sites ship a CSP `frame-ancestors` allowlist instead of
+`X-Frame-Options`. XFO has no allowlist form (`ALLOW-FROM` is dead), and
+emitting both would let a stray `DENY` silently re-block the embed — so
+`X-Frame-Options` is **omitted** whenever `frameAncestors` is active.
+Every origin not on the list is still blocked.
+
+```ts
+createProxy({
+  // extend the allowlist
+  securityHeaders: {
+    frameAncestors: [
+      "'self'",
+      'https://upforge.io',
+      'https://*.upforge.io',
+      'https://partner.example.com',
+    ],
+  },
+})
+
+// opt out entirely → falls back to X-Frame-Options: DENY
+createProxy({ securityHeaders: { frameAncestors: false } })
+```
+
+`DEFAULT_FRAME_ANCESTORS` is the single source of truth — add origins there
+rather than re-forking the list into individual sites.

package/src/redirects/README.md

@@ -0,0 +1,74 @@
+# Redirects — `@sonordev/site-kit/redirects`
+
+Sonor-managed 301/302/307/308 redirect rules. Used by `createProxy()` or standalone.
+
+## Usage
+
+Automatically handled when using `createProxy()`:
+
+```ts
+// proxy.ts
+import { createProxy } from '@sonordev/site-kit/proxy'
+
+export default createProxy()  // redirects: true by default
+
+// Inlined: an imported `config.matcher` is a build error. See the proxy README.
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon\\.ico|.*\\.(?:ico|png|jpg|jpeg|gif|webp|svg|woff2?)$).*)',
+  ],
+}
+```
+
+For standalone use:
+
+```ts
+import { handleManagedRedirects } from '@sonordev/site-kit/redirects'
+
+export async function middleware(request: NextRequest) {
+  const redirect = await handleManagedRedirects(request, {})
+  if (redirect) return redirect
+  return NextResponse.next()
+}
+```
+
+## API
+
+```ts
+handleManagedRedirects(request: NextRequest, config: RedirectConfig): Promise<NextResponse | undefined>
+fetchRedirectRules(config: RedirectConfig): Promise<RedirectRule[]>
+generateNextRedirects(config: RedirectConfig): Promise<Redirect[]>  // For next.config.js
+clearRedirectCache(): void  // Dev helper
+```
+
+## Config
+
+```ts
+interface RedirectConfig {
+  domain?: string              // Resolved from Sonor when using apiKey
+  apiKey?: string              // Project API key
+  site?: string                // Multi-site host, sent as ?site= and cached per host (default: NEXT_PUBLIC_SITE_URL host)
+  portalApiUrl?: string        // Default: https://api.sonor.io
+  cacheSeconds?: number        // Default: 300 (5 minutes)
+}
+```
+
+## Behavior
+
+1. Checks in-memory cache first
+2. Fetches rules from Sonor API if expired
+3. Matches pathname (exact or trailing-slash variant)
+4. Preserves query parameters on redirect
+5. Tracks redirect hit (fire-and-forget)
+6. Skips static assets and API routes
+
+## Types
+
+```ts
+interface RedirectRule {
+  from_path: string
+  to_path: string
+  redirect_type: '301' | '302' | '307' | '308'
+  is_enabled: boolean
+}
+```

package/src/reputation/README.md

@@ -0,0 +1,64 @@
+# Reputation — `@sonordev/site-kit/reputation`
+
+Display client reviews, testimonials, and rating statistics from Sonor.
+
+## Usage
+
+```tsx
+import { TestimonialSection } from '@sonordev/site-kit/reputation'
+
+export default function ReviewsPage() {
+  return (
+    <TestimonialSection
+      title="What Our Clients Say"
+      showRating
+      maxReviews={6}
+    />
+  )
+}
+```
+
+## TestimonialSection Props
+
+```ts
+interface TestimonialSectionProps {
+  title?: string
+  subtitle?: string
+  autoplay?: boolean              // Auto-rotate reviews
+  autoplayInterval?: number       // ms between rotations
+  showRating?: boolean            // Display star ratings
+  maxReviews?: number             // Limit displayed count
+  featuredOnly?: boolean          // Show featured reviews only
+  service?: string                // Filter by service tag
+  className?: string
+}
+```
+
+## API Functions
+
+```ts
+import { fetchReviews, fetchReviewStats } from '@sonordev/site-kit/reputation'
+
+const reviews = await fetchReviews({ service: 'divorce', limit: 10, featured: true })
+const stats = await fetchReviewStats()  // { total_reviews, average_rating, distribution }
+```
+
+## Types
+
+```ts
+interface Review {
+  id: string; quote: string; name: string; role?: string;
+  rating: number; image?: string; date?: string;
+  platform?: string; isFeatured?: boolean; serviceTags?: string[];
+}
+
+interface ReviewStats {
+  total_reviews: number
+  average_rating: number
+  distribution: { 1: number; 2: number; 3: number; 4: number; 5: number }
+}
+```
+
+## Caching
+
+Uses in-memory cache (60s TTL) with retry-on-429 backoff to prevent rate limiting during dev hot reload.

package/src/revalidate/README.md

@@ -0,0 +1,82 @@
+# Live updates
+
+Your pages stay cached, and when someone changes content in Sonor, the pages
+that use it refresh within seconds. It takes one route file:
+
+```ts
+// app/api/seo-revalidate/route.ts
+export { POST } from '@sonordev/site-kit/revalidate'
+```
+
+`npx sonor-setup scaffold` writes it for you, and `npx sonor-setup doctor`
+tells you when it's missing.
+
+## How it works
+
+Everything site-kit fetches from Sonor is cached, and pages built from those
+fetches are served from your host's CDN. When content changes in Sonor
+(managed copy, a page's title or description, an article, a portfolio item),
+Sonor sends this route the paths and cache tags that changed. The route checks
+the call was signed with your project's API key, then expires only those
+pages and tags. The next visitor gets the new version, and every other page
+stays cached.
+
+It's the same `SONOR_API_KEY` the rest of site-kit reads, so there's no
+extra secret to set. Sonor finds the route on its own: the first sitemap sync
+after a deploy registers `https://your-domain/api/seo-revalidate` and checks
+that it answers.
+
+Without the route, nothing breaks. Edits still show up, but only once each
+cached fetch ages out: about five minutes for managed copy, up to a day for
+metadata.
+
+## Sites with a publication
+
+If your site publishes articles, tell the route where they live so the index
+and feeds refresh with each article:
+
+```ts
+// app/api/seo-revalidate/route.ts
+import { createRevalidateRoute } from '@sonordev/site-kit/revalidate'
+
+export const POST = createRevalidateRoute({ publicationBasePath: '/insights' })
+```
+
+| Option | What it does |
+|---|---|
+| `publicationBasePath` | Where your articles live, e.g. `/insights`. The index and its RSS and Atom feeds refresh on every call. |
+| `extraPaths` | Local paths to refresh on every call, e.g. a hub page like `/work`. |
+| `extendPayload` | Map extra fields Sonor sends to more paths or tags. The result is validated again, so it can't widen what a caller may refresh. |
+| `secret` | The key calls are signed with. Defaults to `SONOR_API_KEY`, read on every call. |
+
+## What Sonor sends
+
+A POST with `Authorization: Bearer <SONOR_API_KEY>` and a JSON body:
+
+```json
+{ "paths": ["/services/roofing"], "tags": ["sonor-slots"] }
+```
+
+| Field | Meaning |
+|---|---|
+| `paths` | Local paths to regenerate. `/sitemap.xml`, `/llms.txt` and `/llms-full.txt` are always refreshed too. |
+| `tags` | Cache tags to expire. The ones Sonor uses are `SITE_CACHE_TAGS`: `sonor-slots` (managed copy), `seo` (metadata, schema, FAQs), `blog` (articles), `editorial-taxonomy` and `portfolio`. |
+| `revalidateAll` | Regenerate every page. |
+| `ping` | `{ "ping": true }` on its own regenerates nothing and answers `{ "ok": true, "ping": true, "version": "…" }`. Sonor uses it to confirm the route is installed. |
+
+The route refuses a bad key (401), a body over 16 KB (413) and any path that
+isn't a plain local path or any malformed tag (400). A refused call refreshes
+nothing.
+
+## Checking it
+
+```bash
+curl -s -X POST https://your-domain/api/seo-revalidate \
+  -H "Authorization: Bearer $SONOR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"ping":true}'
+```
+
+`{"ok":true,"ping":true,...}` means Sonor's edits will go live in seconds. A
+404 means the route isn't deployed. A 401 means the key on the site doesn't
+match the project's key.