mkdnsite 0.0.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mkdnsite",
-  "version": "0.0.1",
+  "version": "1.1.0",
   "description": "Markdown for the web. HTML for humans, Markdown for agents.",
   "type": "module",
   "main": "src/index.ts",
@@ -15,7 +15,10 @@
     "./adapters/fly": "./src/adapters/fly.ts"
   },
   "scripts": {
-    "dev": "bun run --watch src/cli.ts ./content",
+    "dev": "bun run --watch src/cli.ts ./content --static ./static --logo /mkdnsite-logo.png --logo-text mkdnsite",
+    "dev:themed": "bun run --watch src/cli.ts --config themed.config.ts",
+    "dev:light": "bun run --watch src/cli.ts --config themed.config.ts --color-scheme light",
+    "dev:dark": "bun run --watch src/cli.ts --config themed.config.ts --color-scheme dark",
     "start": "bun run src/cli.ts",
     "test": "bun test",
     "lint": "ts-standard src/ test/",
@@ -44,9 +47,11 @@
     "src"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "gray-matter": "^4.0.3",
     "katex": "^0.16.38",
     "lucide-react": "^0.577.0",
+    "picomatch": "^4.0.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^9.0.0",
@@ -57,13 +62,15 @@
     "remark-gfm": "^4.0.0",
     "remark-github-blockquote-alert": "^2.0.1",
     "remark-math": "^6.0.0",
-    "shiki": "^3.0.0"
+    "shiki": "^3.0.0",
+    "zod": "^4.3.6"
   },
   "ts-standard": {
     "project": "./tsconfig.json"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/picomatch": "^4.0.2",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "ts-standard": "^12.0.2",

package/src/adapters/cloudflare.ts

@@ -3,12 +3,23 @@ import type { MkdnSiteConfig } from '../config/schema.ts'
 import type { ContentSource } from '../content/types.ts'
 import type { MarkdownRenderer } from '../render/types.ts'
 import { createRenderer } from '../render/types.ts'
+import { GitHubSource } from '../content/github.ts'
+import { R2ContentSource } from '../content/r2.ts'
+import { AssetsSource } from '../content/assets.ts'
+import type { ContentCache } from '../content/cache.ts'
+import { KVContentCache } from '../content/cache.ts'
+import type { ResponseCache } from '../cache/response.ts'
+import { KVResponseCache } from '../cache/kv.ts'
+import type { TrafficAnalytics, TrafficEvent } from '../analytics/types.ts'
 
 /**
  * Cloudflare Workers deployment adapter.
  *
- * Uses R2 for content storage, KV for caching.
- * Wildcard DNS routes (*.mkdn.io) for hosted service.
+ * Auto-detects content source from env bindings:
+ * - CONTENT_SOURCE=github or config.github set → GitHubSource
+ * - CONTENT_SOURCE=r2 or CONTENT_BUCKET present → R2ContentSource
+ * - CONTENT_SOURCE=assets or ASSETS binding present → AssetsSource
+ * - Explicit CONTENT_SOURCE env var overrides auto-detection
  *
  * Usage in a Worker:
  *
@@ -38,48 +49,298 @@ export class CloudflareAdapter implements DeploymentAdapter {
     this.env = env
   }
 
-  createContentSource (_config: MkdnSiteConfig): ContentSource {
-    // TODO: Implement R2ContentSource
-    // return new R2ContentSource(this.env.CONTENT_BUCKET)
+  private createCache (prefix?: string): ContentCache | undefined {
+    if (this.env.CACHE_KV == null) return undefined
+    return new KVContentCache(this.env.CACHE_KV, { prefix })
+  }
+
+  createContentSource (config: MkdnSiteConfig): ContentSource {
+    const sourceType = this.env.CONTENT_SOURCE
+
+    // GitHub source: explicit CONTENT_SOURCE=github or config.github set
+    if (sourceType === 'github' || (sourceType == null && config.github != null)) {
+      const ghConfig = config.github ?? {
+        owner: this.env.GITHUB_OWNER ?? '',
+        repo: this.env.GITHUB_REPO ?? '',
+        ref: this.env.GITHUB_REF,
+        token: this.env.GITHUB_TOKEN
+      }
+      return new GitHubSource({
+        ...ghConfig,
+        include: config.include,
+        exclude: config.exclude
+      })
+    }
+
+    // R2 source: explicit CONTENT_SOURCE=r2 or CONTENT_BUCKET binding present
+    if (sourceType === 'r2' || (sourceType == null && this.env.CONTENT_BUCKET != null)) {
+      if (this.env.CONTENT_BUCKET == null) {
+        throw new Error(
+          'CloudflareAdapter: CONTENT_SOURCE=r2 requires a CONTENT_BUCKET binding in wrangler.toml.'
+        )
+      }
+      return new R2ContentSource({
+        bucket: this.env.CONTENT_BUCKET,
+        basePath: this.env.CONTENT_BASE_PATH,
+        cache: this.createCache(this.env.CONTENT_BASE_PATH)
+      })
+    }
+
+    // Assets source: explicit CONTENT_SOURCE=assets or ASSETS binding present
+    if (sourceType === 'assets' || (sourceType == null && this.env.ASSETS != null)) {
+      if (this.env.ASSETS == null) {
+        throw new Error(
+          'CloudflareAdapter: CONTENT_SOURCE=assets requires an ASSETS binding in wrangler.toml.'
+        )
+      }
+      const manifest = this.env.CONTENT_MANIFEST != null
+        ? JSON.parse(this.env.CONTENT_MANIFEST) as string[]
+        : undefined
+      return new AssetsSource({
+        assets: this.env.ASSETS,
+        manifest,
+        cache: this.createCache('assets:')
+      })
+    }
+
     throw new Error(
-      'CloudflareAdapter.createContentSource() not yet implemented. ' +
-      'Provide an R2-backed ContentSource implementation.'
+      'CloudflareAdapter: No content source configured. ' +
+      'Set CONTENT_SOURCE=github|r2|assets, provide CONTENT_BUCKET (R2), ASSETS binding, or set config.github.'
     )
   }
 
   async createRenderer (_config: MkdnSiteConfig): Promise<MarkdownRenderer> {
-    // CF Workers don't have Bun.markdown, always use portable
+    // CF Workers don't have Bun.markdown — always use portable renderer
     return await createRenderer('portable')
   }
+
+  /**
+   * Create a TrafficAnalytics instance if the ANALYTICS binding is present.
+   *
+   * Returns `undefined` when the binding is absent so callers can skip
+   * passing analytics to createHandler without any change in behaviour.
+   *
+   * Usage:
+   * ```ts
+   * const handler = createHandler({
+   *   source: adapter.createContentSource(config),
+   *   renderer: await adapter.createRenderer(config),
+   *   config,
+   *   analytics: adapter.createTrafficAnalytics()
+   * })
+   * ```
+   */
+  /**
+   * Create a ResponseCache backed by CACHE_KV when available.
+   * Returns undefined when no KV binding is present.
+   */
+  createResponseCache (): ResponseCache | undefined {
+    if (this.env.CACHE_KV == null) return undefined
+    return new KVResponseCache(this.env.CACHE_KV, { prefix: 'resp:' })
+  }
+
+  createTrafficAnalytics (): TrafficAnalytics | undefined {
+    if (this.env.ANALYTICS == null) return undefined
+    return new WorkersAnalyticsEngineAnalytics(this.env.ANALYTICS)
+  }
+
+  /**
+   * Create a static file handler backed by an R2 bucket.
+   *
+   * When a `STATIC_BUCKET` binding is present in the Worker environment, this
+   * method returns a `staticHandler` function that reads static assets (images,
+   * fonts, CSS, etc.) from R2. Pass the result to `createHandler` via the
+   * `staticHandler` option:
+   *
+   * ```ts
+   * const handler = createHandler({
+   *   source: adapter.createContentSource(config),
+   *   renderer: await adapter.createRenderer(config),
+   *   config,
+   *   staticHandler: adapter.createStaticHandler()
+   * })
+   * ```
+   *
+   * Returns `undefined` when no `STATIC_BUCKET` binding is configured, so
+   * callers can pass the result unconditionally — `createHandler` ignores
+   * `undefined` staticHandler values.
+   *
+   * The handler strips the leading `/` from the pathname before fetching from
+   * R2 (e.g. `/logo.png` → key `logo.png`). Returns `null` for missing objects
+   * so the request falls through to the built-in `serveStatic` or a 404.
+   */
+  createStaticHandler (): ((pathname: string) => Promise<Response | null>) | undefined {
+    const bucket = this.env.STATIC_BUCKET
+    if (bucket == null) return undefined
+
+    return async (pathname: string): Promise<Response | null> => {
+      const key = pathname.replace(/^\//, '')
+      const obj = await bucket.get(key)
+      if (obj == null) return null
+
+      const ext = key.split('.').pop() ?? ''
+      const contentType = MIME_TYPES[ext] ?? 'application/octet-stream'
+      const body = await obj.text()
+
+      return new Response(body, {
+        status: 200,
+        headers: {
+          'Content-Type': contentType,
+          'Cache-Control': 'public, max-age=31536000, immutable'
+        }
+      })
+    }
+  }
+}
+
+/**
+ * Cloudflare Workers Analytics Engine implementation of TrafficAnalytics.
+ *
+ * Writes a data point to a CF Analytics Engine dataset binding (`ANALYTICS`).
+ * Each field maps to an index (string "blobs") or double (numeric values).
+ *
+ * Usage: automatically created by `CloudflareAdapter.createTrafficAnalytics()`
+ * when the `ANALYTICS` binding is present.
+ */
+export class WorkersAnalyticsEngineAnalytics implements TrafficAnalytics {
+  private readonly dataset: AnalyticsEngineDataset
+
+  constructor (dataset: AnalyticsEngineDataset) {
+    this.dataset = dataset
+  }
+
+  logRequest (event: TrafficEvent): void {
+    // Field ordering is significant — CF Analytics Engine queries reference
+    // fields by index (blob1, blob2, ..., double1, double2, ...).
+    // Do NOT reorder without updating all downstream queries.
+    this.dataset.writeDataPoint({
+      indexes: [
+        event.siteId ?? '' // index1: site isolation key (empty for single-site)
+      ],
+      blobs: [
+        event.path, // blob1: URL pathname
+        event.method, // blob2: HTTP method
+        event.format, // blob3: response format (html|markdown|mcp|api|other)
+        event.trafficType, // blob4: traffic classification (human|ai_agent|bot|mcp)
+        event.userAgent // blob5: raw User-Agent string
+      ],
+      doubles: [
+        event.statusCode, // double1: HTTP status code
+        event.latencyMs, // double2: handler latency in ms
+        event.contentLength, // double3: response body size in bytes
+        event.cacheHit ? 1 : 0, // double4: cache hit (1) or miss (0)
+        event.timestamp // double5: request timestamp (epoch ms)
+      ]
+    })
+  }
 }
 
 /**
  * Expected Cloudflare Worker environment bindings.
  */
 export interface CloudflareEnv {
-  /** R2 bucket for markdown content */
+  /** Explicit content source selection */
+  CONTENT_SOURCE?: 'github' | 'r2' | 'assets'
+
+  /** R2 bucket binding for markdown content */
   CONTENT_BUCKET?: R2Bucket
-  /** KV namespace for caching */
+  /** Key prefix within the R2 bucket (e.g. 'sites/abc123/') */
+  CONTENT_BASE_PATH?: string
+
+  /** Workers Static Assets binding */
+  ASSETS?: AssetsFetcher
+  /** JSON array of .md file paths (alternative to _manifest.json in assets) */
+  CONTENT_MANIFEST?: string
+
+  /** KV namespace for caching (future use) */
   CACHE_KV?: KVNamespace
-  /** Site title from env var */
+
+  /** R2 bucket for serving static assets (images, fonts, CSS, etc.) */
+  STATIC_BUCKET?: R2Bucket
+
+  /** GitHub owner (used if config.github not set) */
+  GITHUB_OWNER?: string
+  /** GitHub repo (used if config.github not set) */
+  GITHUB_REPO?: string
+  /** GitHub branch/tag (default: main) */
+  GITHUB_REF?: string
+  /** GitHub token for private repos / higher rate limits */
+  GITHUB_TOKEN?: string
+
+  /** Site title (can override config.site.title) */
   SITE_TITLE?: string
-  /** Site URL from env var */
+  /** Site URL */
   SITE_URL?: string
+
+  /** Secret token for authenticating POST /_refresh requests */
+  REFRESH_TOKEN?: string
+
+  /** Workers Analytics Engine dataset binding for traffic analytics */
+  ANALYTICS?: AnalyticsEngineDataset
 }
 
-// Type stubs for CF runtime types (not available in non-CF environments)
+// ─── Static asset MIME type map ──────────────────────────────────────────────
+const MIME_TYPES: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  ico: 'image/x-icon',
+  css: 'text/css; charset=utf-8',
+  js: 'text/javascript; charset=utf-8',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  pdf: 'application/pdf',
+  json: 'application/json'
+}
+
+// ─── Cloudflare R2 type stubs ─────────────────────────────────────────────────
+// These types are provided by the CF Workers runtime; stubs here for type-checking
+// in non-CF environments.
+
 interface R2Bucket {
   get: (key: string) => Promise<R2Object | null>
-  list: (options?: Record<string, unknown>) => Promise<{ objects: R2Object[] }>
+  list: (options?: R2ListOptions) => Promise<R2ObjectList>
 }
 
 interface R2Object {
   key: string
   uploaded: Date
+  size: number
   text: () => Promise<string>
 }
 
+interface R2ObjectList {
+  objects: R2Object[]
+  truncated: boolean
+  cursor?: string
+}
+
+interface R2ListOptions {
+  prefix?: string
+  cursor?: string
+  limit?: number
+}
+
+interface AssetsFetcher {
+  fetch: (input: Request | string) => Promise<Response>
+}
+
 interface KVNamespace {
   get: (key: string) => Promise<string | null>
-  put: (key: string, value: string, options?: Record<string, unknown>) => Promise<void>
+  put: (key: string, value: string, options?: { expirationTtl?: number }) => Promise<void>
+  delete: (key: string) => Promise<void>
+  list: (options?: { prefix?: string }) => Promise<{ keys: Array<{ name: string }> }>
+}
+
+interface AnalyticsEngineDataset {
+  writeDataPoint: (data: {
+    blobs?: string[]
+    doubles?: number[]
+    indexes?: string[]
+  }) => void
 }

package/src/adapters/local.ts

@@ -1,9 +1,11 @@
+import { Buffer } from 'node:buffer'
 import type { DeploymentAdapter } from './types.ts'
 import { detectRuntime } from './types.ts'
 import type { MkdnSiteConfig } from '../config/schema.ts'
 import type { ContentSource } from '../content/types.ts'
 import type { MarkdownRenderer } from '../render/types.ts'
 import { FilesystemSource } from '../content/filesystem.ts'
+import { GitHubSource } from '../content/github.ts'
 import { createRenderer } from '../render/types.ts'
 
 export class LocalAdapter implements DeploymentAdapter {
@@ -15,7 +17,17 @@ export class LocalAdapter implements DeploymentAdapter {
   }
 
   createContentSource (config: MkdnSiteConfig): ContentSource {
-    return new FilesystemSource(config.contentDir)
+    if (config.github != null) {
+      return new GitHubSource({
+        ...config.github,
+        include: config.include,
+        exclude: config.exclude
+      })
+    }
+    return new FilesystemSource(config.contentDir, {
+      include: config.include,
+      exclude: config.exclude
+    })
   }
 
   async createRenderer (config: MkdnSiteConfig): Promise<MarkdownRenderer> {
@@ -129,25 +141,43 @@ export class LocalAdapter implements DeploymentAdapter {
 
   private printStartup (config: MkdnSiteConfig, port: number): void {
     const url = `http://localhost:${String(port)}`
+    const DIM_CYAN = '\x1b[2;36m'
+    const BOLD_GREEN = '\x1b[1;32m'
+    const DIM = '\x1b[2m'
+    const RESET = '\x1b[0m'
+
+    // ASCII art header
     console.log('')
-    console.log('  ┌──────────────────────────────────────────────┐')
-    console.log('  │                                              │')
-    console.log('  │   mkdnsite is running                       │')
-    console.log(`  │   ${url.padEnd(42)} │`)
-    console.log('  │                                              │')
-    console.log(`  │   Runtime: ${this.name.padEnd(32)} │`)
-    console.log(`  │   Content: ${config.contentDir.padEnd(32)} │`)
-    console.log(`  │   Renderer: ${this.rendererEngine.padEnd(30)} │`)
-    console.log(`  │   Theme mode: ${config.theme.mode.padEnd(28)} │`)
-    console.log(`  │   Client JS: ${(config.client.enabled ? 'on' : 'off').padEnd(29)} │`)
-    console.log(`  │   Content negotiation: ${(config.negotiation.enabled ? 'on' : 'off').padEnd(19)} │`)
-    console.log('  │                                              │')
-    console.log('  └──────────────────────────────────────────────┘')
+    console.log(`${DIM_CYAN}   ▌  ▌    ▘▗   `)
+    console.log('▛▛▌▙▘▛▌▛▌▛▘▌▜▘█▌')
+    console.log(`▌▌▌▛▖▙▌▌▌▄▌▌▐▖▙▖${RESET}`)
+    console.log('')
+    console.log(`  ${BOLD_GREEN}\u2192 ${url}${RESET}`)
+    console.log('')
+
+    const row = (label: string, value: string): void => {
+      console.log(`  ${DIM}${label.padEnd(12)}${RESET}${value}`)
+    }
+
+    row('Runtime', `local (${this.name})`)
+    if (config.github != null) {
+      const owner: string = config.github.owner
+      const repo: string = config.github.repo
+      const ref: string = config.github.ref ?? 'main'
+      row('GitHub', `${owner}/${repo}@${ref}`)
+    } else {
+      row('Content', config.contentDir)
+    }
+    row('Renderer', this.rendererEngine)
+    if (config.mcp.enabled) {
+      row('MCP', config.mcp.endpoint ?? '/mcp')
+    }
+    if (config.client.search) {
+      row('Search', '/api/search')
+    }
+
     console.log('')
-    console.log('  Try:')
-    console.log(`    curl ${url}`)
-    console.log(`    curl -H "Accept: text/markdown" ${url}`)
-    console.log(`    curl ${url}/llms.txt`)
+    console.log(`  ${DIM}Ctrl+C to stop${RESET}`)
     console.log('')
   }
 }

package/src/analytics/classify.ts

@@ -0,0 +1,65 @@
+import type { TrafficType, AnalyticsResponseFormat } from './types.ts'
+
+/**
+ * Known crawler / bot User-Agent patterns.
+ * Checked case-insensitively.
+ *
+ * This list is intentionally extensible — add entries as new crawlers appear.
+ */
+export const BOT_PATTERNS: RegExp[] = [
+  /googlebot/i,
+  /bingbot/i,
+  /slurp/i, // Yahoo
+  /duckduckbot/i,
+  /baiduspider/i,
+  /yandexbot/i,
+  /sogou/i,
+  /exabot/i,
+  /facebot/i,
+  /ia_archiver/i, // Alexa / Internet Archive
+  /semrushbot/i,
+  /ahrefsbot/i,
+  /mj12bot/i,
+  /dotbot/i,
+  /rogerbot/i,
+  /archive\.org_bot/i,
+  /petalbot/i,
+  /bytespider/i, // TikTok
+  /applebot/i,
+  /linkedinbot/i,
+  /twitterbot/i,
+  /facebookexternalhit/i,
+  /whatsapp/i,
+  /telegrambot/i,
+  /discordbot/i,
+  /slackbot/i
+]
+
+/**
+ * Classify a request as human, ai_agent, bot, or mcp traffic.
+ *
+ * Rules (evaluated in order):
+ * 1. MCP format → 'mcp'
+ * 2. markdown format (already resolved by the handler from Accept header / .md URL) → 'ai_agent'
+ * 3. User-Agent matches a known bot pattern → 'bot'
+ * 4. Otherwise → 'human'
+ *
+ * The `format` parameter is pre-resolved by the handler's `resolveAnalyticsFormat()`,
+ * which already checks Content-Type, Accept headers, and .md URL suffix — so we
+ * avoid duplicating that logic here.
+ */
+export function classifyTraffic (request: Request, format: AnalyticsResponseFormat): TrafficType {
+  // MCP traffic
+  if (format === 'mcp') return 'mcp'
+
+  // AI agent: served raw markdown (format resolved from Accept header / .md URL / Content-Type)
+  if (format === 'markdown') return 'ai_agent'
+
+  // Known bot by User-Agent
+  const ua = request.headers.get('User-Agent') ?? ''
+  if (ua !== '' && BOT_PATTERNS.some(pattern => pattern.test(ua))) {
+    return 'bot'
+  }
+
+  return 'human'
+}

package/src/analytics/console.ts

@@ -0,0 +1,39 @@
+import type { TrafficAnalytics, TrafficEvent } from './types.ts'
+
+/**
+ * Console analytics implementation — writes a structured log line to stdout.
+ *
+ * Useful during development and debugging. Output format is a single JSON line
+ * per request so it can be piped to `jq` or similar tools.
+ *
+ * Example output:
+ * {"ts":1710000000000,"method":"GET","path":"/docs","format":"html","type":"human","status":200,"ms":12,"bytes":4321,"cache":false}
+ */
+export class ConsoleAnalytics implements TrafficAnalytics {
+  private readonly output: (line: string) => void
+
+  /**
+   * @param output - Write function (defaults to console.log). Injectable for
+   *   testing without polluting test output.
+   */
+  constructor (output?: (line: string) => void) {
+    this.output = output ?? console.log
+  }
+
+  logRequest (event: TrafficEvent): void {
+    const obj: Record<string, unknown> = {
+      ts: event.timestamp,
+      method: event.method,
+      path: event.path,
+      format: event.format,
+      type: event.trafficType,
+      status: event.statusCode,
+      ms: event.latencyMs,
+      bytes: event.contentLength,
+      cache: event.cacheHit,
+      ua: event.userAgent
+    }
+    if (event.siteId != null) obj.site = event.siteId
+    this.output(JSON.stringify(obj))
+  }
+}

package/src/analytics/noop.ts

@@ -0,0 +1,15 @@
+import type { TrafficAnalytics, TrafficEvent } from './types.ts'
+
+/**
+ * No-op analytics implementation.
+ *
+ * The default when no analytics backend is configured. logRequest() is a
+ * genuine no-op — zero allocations, zero overhead beyond the null check in
+ * the handler.
+ */
+export class NoopAnalytics implements TrafficAnalytics {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  logRequest (_event: TrafficEvent): void {
+    // intentionally empty
+  }
+}

package/src/analytics/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Traffic analytics types for mkdnsite.
+ *
+ * The TrafficAnalytics interface is the core extension point — implement it
+ * to route request events to any analytics backend (console, CF Analytics Engine,
+ * ClickHouse, Plausible, etc.).
+ */
+
+/** Classification of who sent the request */
+export type TrafficType = 'human' | 'ai_agent' | 'bot' | 'mcp'
+
+/** What format was served in the response */
+export type AnalyticsResponseFormat = 'html' | 'markdown' | 'mcp' | 'api' | 'other'
+
+/** A single request event captured by the analytics hook */
+export interface TrafficEvent {
+  /** Unix timestamp (ms) when the request started — Date.now() */
+  timestamp: number
+  /** URL pathname */
+  path: string
+  /** HTTP method (GET, POST, etc.) */
+  method: string
+  /** What was served */
+  format: AnalyticsResponseFormat
+  /** Classified caller type */
+  trafficType: TrafficType
+  /** HTTP status code of the response */
+  statusCode: number
+  /** End-to-end handler latency in milliseconds */
+  latencyMs: number
+  /** Raw User-Agent string */
+  userAgent: string
+  /** Response body size in bytes */
+  contentLength: number
+  /** Whether the response was served from cache */
+  cacheHit: boolean
+  /** Site identifier for multi-tenant deployments (e.g. mkdn.io). Undefined for single-site. */
+  siteId?: string
+}
+
+/**
+ * Pluggable traffic analytics backend.
+ *
+ * `logRequest` is fire-and-forget and must be synchronous (or fire async work
+ * without blocking the response). Implementations must never throw.
+ */
+export interface TrafficAnalytics {
+  logRequest: (event: TrafficEvent) => void
+}