@ooky/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ooky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# @ooky/sdk
+
+Drop-in middleware for serving AI brand intelligence and capturing AI-bot analytics from your Node, Next.js, or Vercel Edge app — without DNS changes or Cloudflare workers.
+
+When an AI bot (GPTBot, ClaudeBot, Perplexity, etc.) hits any page on your site, the SDK fires a non-blocking event to Ooky. When a request asks for one of the well-known AI paths (`/llms.txt`, `/.well-known/ai-manifest.json`, `/agents.md`, …), the SDK serves the latest manifest you've published from the Ooky dashboard.
+
+## Install
+
+```bash
+npm install @ooky/sdk
+```
+
+You'll need a domain registered in [the Ooky dashboard](https://app.ooky.ai) and an API key from **Integrations → SDK → Generate API Key**. The key looks like `ooky_sk_<random>` and is shown once — store it as an environment variable.
+
+> **Reveal-once key**: Ooky shows the key only at the moment of generation. After your SDK fires its first successful event, the plaintext is purged server-side (only a SHA-256 hash remains, used for ongoing authentication). If you lose the key, rotate it — there's no "show key again" path. This matches the standard set by Stripe, Linear, and GitHub.
+
+## Quickstart
+
+### Express
+
+```js
+import express from "express";
+import { ookyMiddleware } from "@ooky/sdk/express";
+
+const app = express();
+app.use(ookyMiddleware({
+  apiKey: process.env.OOKY_API_KEY,
+  domain: "acme.com",
+}));
+// your routes...
+```
+
+### Next.js
+
+```ts
+// middleware.ts
+import { ookyMiddleware } from "@ooky/sdk/next";
+
+export default ookyMiddleware({
+  apiKey: process.env.OOKY_API_KEY,
+  domain: "acme.com",
+});
+
+export const config = {
+  matcher: ["/llms.txt", "/llms-full.txt", "/agents.md", "/.well-known/:path*", "/(.*)"],
+};
+```
+
+Works in both the Node and Edge runtimes — no code change.
+
+### Vercel Edge / Web Fetch
+
+```ts
+// middleware.ts (Vercel Edge)
+import { ookyEdge } from "@ooky/sdk/edge";
+
+export default ookyEdge({
+  apiKey: process.env.OOKY_API_KEY,
+  domain: "acme.com",
+});
+
+export const config = { matcher: "/(.*)" };
+```
+
+## What gets intercepted
+
+The SDK responds to these paths with the latest published manifest:
+
+| Path | What gets served |
+|---|---|
+| `/llms.txt` | Markdown summary for LLM crawlers |
+| `/llms-full.txt` | Extended markdown with all page sections |
+| `/.well-known/ai-manifest.json` | Full JSON brand manifest (global + per-page) |
+| `/ai-manifest.json` | Same as above (alternate path) |
+| `/agents.md` | Markdown agent guide |
+| `/.well-known/mcp` | MCP server descriptor |
+
+Every other request passes through to your app unchanged.
+
+## What gets logged
+
+For **every** request (manifest or not), the SDK checks the `User-Agent` against the bot registry. When a known AI bot is detected, it fires a fire-and-forget POST to `/api/ingest/events` with:
+
+```json
+{
+  "event_id": "<uuid>",
+  "timestamp": "<ISO 8601>",
+  "bot": { "name": "GPTBot", "verified": true, "ua_string": "<full UA>" },
+  "request": { "page_path": "/pricing", "method": "GET" }
+}
+```
+
+The event scope (which domain it belongs to) is determined server-side from your API key — you cannot accidentally log events for a different customer's domain.
+
+Human traffic produces no events.
+
+## Configuration options
+
+```ts
+ookyMiddleware({
+  // Required
+  apiKey: "ooky_sk_...",
+  domain: "acme.com",
+
+  // Optional — defaults are right for production
+  apiBase: "https://api.ooky.ai/api",                       // Ooky API root
+  cdnBase: "https://api.ooky.ai/api/public/manifest",       // Manifest source (default = apiBase + "/public/manifest")
+  bots: undefined,                       // Override the bot registry; default ships with major AI bots
+  autoRefreshBots: true,                 // Periodically refresh bot UA list from /api/public/bots
+});
+```
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `apiKey` | `string` | — | Required. Per-domain Bearer token from the dashboard. |
+| `domain` | `string` | — | Required. Must match the verified domain in Ooky. |
+| `apiBase` | `string` | `https://api.ooky.ai/api` | Override for self-hosted Ooky or staging. |
+| `cdnBase` | `string` | `${apiBase}/public/manifest` | Manifest source. By default the SDK fetches from Ooky's public manifest endpoint. Override to put your own CDN (Cloudflare, CloudFront, Fastly) in front. |
+| `bots` | `Array<{name, pattern, category}>` | Built-in default list | Ships with the major AI bots. Override only if you have custom UA patterns. |
+| `autoRefreshBots` | `boolean` | `true` | Refresh from `/api/public/bots` once an hour. Disable for fully offline use. |
+
+## Performance
+
+- The manifest fetch is HTTP-cached (`Cache-Control: public, max-age=300, s-maxage=600`) — your CDN/edge will serve repeat requests without hitting Ooky.
+- Event firing uses `fetch(..., { keepalive: true })` so it survives the response cycle without delaying it.
+- Bot detection is a substring check against an in-memory list — sub-millisecond per request.
+
+## Troubleshooting
+
+**"I installed it but no events show up"**
+1. Confirm your domain is verified and the integration method is set to `sdk` (or `wordpress`) in the dashboard.
+2. Check that `process.env.OOKY_API_KEY` is actually set in your runtime — log it once at boot.
+3. Hit your site with a bot UA: `curl -H "User-Agent: GPTBot/1.0" https://your-site.com/` and watch the dashboard's AI Sessions page.
+4. If your app is behind a CDN that strips `User-Agent`, the SDK can't see the bot. Check your CDN config.
+
+**"`/llms.txt` returns 404"**
+- The middleware only intercepts paths the SDK knows about. Make sure your framework's matcher passes those paths to the middleware before falling through to your routes.
+- If you've published the manifest in the dashboard, also check Ooky's edge CDN is reachable from your server: `curl https://edge.ooky.ai/<your-domain>/llms`.
+
+**"Events fail with 401 Unauthorized"**
+- The API key has been revoked or rotated. Generate a new one from the dashboard and update the env var.
+
+**"Manifest is stale"**
+- The HTTP cache is honoring 5 min freshness. Ooky purges the CDN on publish, but your CDN may also cache. Force a fresh fetch by clearing your edge cache for the well-known paths.
+
+## Security & key lifecycle
+
+The SDK runs **server-side only** — Node middleware or the Edge runtime. The
+API key never reaches the browser. Key handling follows the same lifecycle as
+Stripe / Linear / GitHub:
+
+| Stage | Where the key lives |
+|---|---|
+| Generated | Returned once in the dashboard. Plaintext + SHA-256 hash stored server-side. |
+| Customer copies it | Customer pastes into their env (`OOKY_API_KEY`). |
+| First event lands | Server drops the plaintext from the DB. Only the hash remains. |
+| Ongoing auth | Server hashes the incoming Bearer token and compares against the stored hash in constant time. |
+| Lost / leaked | Rotate via **Integrations → SDK → Rotate API Key**. Old key 401s immediately. |
+
+The package is published with [npm provenance attestations](https://docs.npmjs.com/generating-provenance-statements) signed by GitHub Actions OIDC. You can verify the published tarball came from this repo's `release-sdk.yml` workflow:
+
+```bash
+npm view @ooky/sdk dist.attestations
+```
+
+If you're using a private registry mirror, mirror the provenance bundle too — most package proxies (Artifactory, Verdaccio, GitHub Packages) preserve it.
+
+### Recommended rotation cadence
+
+- **Every 90 days** for production deployments.
+- **Immediately** if you suspect leak (committed to a public repo, server compromise, contractor offboarding).
+- Set a calendar reminder; Ooky will surface an in-dashboard warning at 90 days from generation.
+
+### Where the key must never appear
+
+- ✅ Server env vars (`process.env.OOKY_API_KEY`) — yes.
+- ❌ `next.config.js`, `vite.config.js`, or any file shipped to the client — no.
+- ❌ Git commits — never. If you push it by accident, rotate the key first, *then* clean git history.
+- ❌ Logging — the SDK does not log the key. Don't log `process.env` blindly either.
+
+## What this SDK does NOT do
+
+- It does not crawl your site or generate the manifest — that happens in the dashboard.
+- It does not modify HTML responses or rewrite content for bots. (For that, use the Worker or Full DNS integration.)
+- It does not block bots. Your `robots.txt` and any rate limiting still apply.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@ooky/sdk",
+  "version": "0.1.0",
+  "description": "Ooky SDK — middleware for serving AI brand intelligence and capturing AI-bot analytics from your Node, Next.js, or Vercel Edge app.",
+  "keywords": [
+    "ai",
+    "llm",
+    "llms.txt",
+    "ai-bot",
+    "brand-visibility",
+    "express",
+    "nextjs",
+    "vercel-edge",
+    "middleware",
+    "ooky"
+  ],
+  "homepage": "https://ooky.ai",
+  "bugs": {
+    "url": "https://github.com/ooky-ai/ooky/issues",
+    "email": "support@ooky.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ooky-ai/ooky.git",
+    "directory": "packages/sdk"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Ooky",
+    "url": "https://ooky.ai",
+    "email": "hello@ooky.ai"
+  },
+  "type": "module",
+  "main": "./src/core.js",
+  "exports": {
+    ".": "./src/core.js",
+    "./core": "./src/core.js",
+    "./express": "./src/express.js",
+    "./next": "./src/next.js",
+    "./edge": "./src/edge.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "vitest run",
+    "prepack": "node -e \"const f=require('./package.json').files; if(!f.includes('src/')||!f.includes('README.md')||!f.includes('LICENSE')){console.error('files whitelist drift — refusing to pack');process.exit(1)}\""
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "express": "^4.18.2",
+    "supertest": "^6.3.4",
+    "vitest": "^3.2.4"
+  }
+}

package/src/bots.js

@@ -0,0 +1,57 @@
+/**
+ * Built-in bot UA patterns. Mirrors worker/src/bots.js DEFAULT_BOT_REGISTRY
+ * so the SDK and Worker behave the same when the public registry endpoint
+ * (/api/public/bots) is unreachable. When you add a bot here, also add it
+ * to worker/src/bots.js and the SQL seed in
+ * backend/src/db/migrations/007_bot_registry.sql.
+ *
+ * The pattern is matched as a case-insensitive substring of the User-Agent.
+ */
+
+export const DEFAULT_BOTS = [
+  { name: "GPTBot", pattern: "GPTBot", category: "ai" },
+  { name: "ChatGPT-User", pattern: "ChatGPT-User", category: "ai" },
+  { name: "OAI-SearchBot", pattern: "OAI-SearchBot", category: "ai" },
+  { name: "Anthropic", pattern: "anthropic-ai", category: "ai" },
+  { name: "ClaudeBot", pattern: "ClaudeBot", category: "ai" },
+  { name: "Claude-Web", pattern: "Claude-Web", category: "ai" },
+  { name: "Google-Extended", pattern: "Google-Extended", category: "ai" },
+  { name: "GoogleOther", pattern: "GoogleOther", category: "ai" },
+  { name: "Googlebot-Extended", pattern: "Googlebot-Extended", category: "ai" },
+  { name: "Googlebot", pattern: "Googlebot", category: "search" },
+  { name: "Applebot-Extended", pattern: "Applebot-Extended", category: "ai" },
+  { name: "Applebot", pattern: "Applebot", category: "search" },
+  { name: "Meta-ExternalAgent", pattern: "meta-externalagent", category: "ai" },
+  { name: "Meta-ExternalFetcher", pattern: "Meta-ExternalFetcher", category: "ai" },
+  { name: "FacebookBot", pattern: "FacebookBot", category: "social" },
+  { name: "facebookexternalhit", pattern: "facebookexternalhit", category: "social" },
+  { name: "Bingbot", pattern: "bingbot", category: "search" },
+  { name: "Perplexity", pattern: "PerplexityBot", category: "ai" },
+  { name: "YouBot", pattern: "YouBot", category: "ai" },
+  { name: "CCBot", pattern: "CCBot", category: "ai" },
+  { name: "Cohere", pattern: "cohere-ai", category: "ai" },
+  { name: "Diffbot", pattern: "Diffbot", category: "ai" },
+  { name: "Bytespider", pattern: "Bytespider", category: "ai" },
+  { name: "Amazonbot", pattern: "Amazonbot", category: "search" },
+  { name: "AI2Bot", pattern: "AI2Bot", category: "ai" },
+  { name: "ImagesiftBot", pattern: "ImagesiftBot", category: "ai" },
+  { name: "Timesbot", pattern: "Timesbot", category: "ai" },
+  { name: "iaskspider", pattern: "iaskspider", category: "ai" },
+  { name: "Twitterbot", pattern: "Twitterbot", category: "social" },
+  { name: "Slurp", pattern: "Slurp", category: "search" },
+  { name: "DuckDuckBot", pattern: "DuckDuckBot", category: "search" },
+  { name: "ia_archiver", pattern: "ia_archiver", category: "other" },
+];
+
+/**
+ * Returns the matched bot { name, pattern, category } or null.
+ * Case-insensitive substring match (the same logic the Worker uses).
+ */
+export function detectBot(userAgent, registry = DEFAULT_BOTS) {
+  if (!userAgent || typeof userAgent !== "string") return null;
+  const ua = userAgent.toLowerCase();
+  for (const b of registry) {
+    if (ua.includes(b.pattern.toLowerCase())) return b;
+  }
+  return null;
+}

package/src/core.js

@@ -0,0 +1,230 @@
+/**
+ * Ooky SDK core — runtime-agnostic logic shared across Express, Next, Edge.
+ *
+ * The handler exposes:
+ *   - matchPath(path)   → null | "llms" | "llms-full" | "manifest" | "agents" | "mcp"
+ *   - detectBot(ua)     → null | { name, pattern, category }
+ *   - serveManifest(kind, ctx?)  → { status, body, headers }
+ *   - recordEvent(payload)       → fire-and-forget POST to /api/ingest/events
+ *   - refreshBotRegistry()       → optional manual refresh from /api/public/bots
+ *
+ * Adapters (express/next/edge) wrap this with the framework's request/response
+ * conventions but never duplicate logic.
+ */
+
+import { detectBot as detectFromList, DEFAULT_BOTS } from "./bots.js";
+
+const DEFAULT_API_BASE = "https://api.ooky.ai/api";
+// Manifest content is served from the public Ooky API by default. Customers
+// can override `cdnBase` to point at their own CDN (e.g., Cloudflare or
+// CloudFront) sitting in front of `${apiBase}/public/manifest`.
+const DEFAULT_CDN_PATH = "/public/manifest";
+
+// Five well-known paths the SDK answers on behalf of the customer's app.
+const PATH_MAP = {
+  "/llms.txt": "llms",
+  "/llms-full.txt": "llms-full",
+  "/.well-known/ai-manifest.json": "manifest",
+  "/ai-manifest.json": "manifest",
+  "/agents.md": "agents",
+  "/.well-known/mcp": "mcp",
+};
+
+const CONTENT_TYPE = {
+  llms: "text/plain; charset=utf-8",
+  "llms-full": "text/plain; charset=utf-8",
+  manifest: "application/json; charset=utf-8",
+  agents: "text/markdown; charset=utf-8",
+  mcp: "application/json; charset=utf-8",
+};
+
+/**
+ * Create an Ooky handler instance.
+ *
+ * @param {object} options
+ * @param {string} options.apiKey        Bearer token from /integration/sdk-key (ooky_sk_*)
+ * @param {string} options.domain        Domain registered in Ooky (e.g. "acme.com")
+ * @param {string} [options.apiBase]     Override Ooky API base URL.
+ * @param {string} [options.cdnBase]     Override manifest CDN base URL.
+ * @param {Array}  [options.bots]        Override the bot registry; default uses DEFAULT_BOTS.
+ * @param {boolean}[options.autoRefreshBots=true]  Periodically refresh from /api/public/bots.
+ */
+export function createOokyHandler(options) {
+  if (!options || typeof options !== "object") {
+    throw new TypeError("createOokyHandler: options object is required");
+  }
+  const { apiKey, domain } = options;
+  if (!apiKey || typeof apiKey !== "string") {
+    throw new TypeError("createOokyHandler: options.apiKey is required");
+  }
+  if (!domain || typeof domain !== "string") {
+    throw new TypeError("createOokyHandler: options.domain is required");
+  }
+
+  const apiBase = assertHttpUrl(options.apiBase || DEFAULT_API_BASE, "apiBase").replace(/\/+$/, "");
+  const cdnBase = assertHttpUrl(
+    options.cdnBase || `${apiBase}${DEFAULT_CDN_PATH}`,
+    "cdnBase"
+  ).replace(/\/+$/, "");
+  const autoRefreshBots = options.autoRefreshBots !== false;
+
+  let botRegistry = options.bots || DEFAULT_BOTS;
+  let lastBotRefresh = 0;
+  const BOT_REFRESH_MS = 60 * 60 * 1000; // 1 hour
+
+  async function refreshBotRegistry(force = false) {
+    if (!autoRefreshBots && !force) return botRegistry;
+    if (!force && Date.now() - lastBotRefresh < BOT_REFRESH_MS) return botRegistry;
+    try {
+      const res = await fetch(`${apiBase}/public/bots`, {
+        headers: { Accept: "application/json" },
+      });
+      if (res.ok) {
+        const data = await res.json();
+        if (Array.isArray(data?.bots) && data.bots.length > 0) {
+          botRegistry = data.bots;
+        }
+      }
+      lastBotRefresh = Date.now();
+    } catch {
+      // Network failure — keep stale list.
+    }
+    return botRegistry;
+  }
+
+  function matchPath(path) {
+    if (!path || typeof path !== "string") return null;
+    // Normalize trailing slash and query.
+    const clean = path.split("?")[0].replace(/\/+$/, "") || "/";
+    return PATH_MAP[clean] || PATH_MAP[path.split("?")[0]] || null;
+  }
+
+  function detectBot(userAgent) {
+    return detectFromList(userAgent, botRegistry);
+  }
+
+  async function fetchFromCdn(kind) {
+    // Edge CDN URL convention. The actual route map is owned by the backend
+    // and exposed via the per-domain /api/public/manifest/:domain endpoint.
+    const url = `${cdnBase}/${encodeURIComponent(domain)}/${kind}`;
+    const res = await fetch(url, { headers: { Accept: CONTENT_TYPE[kind] || "*/*" } });
+    return res;
+  }
+
+  /**
+   * Build the response for one of the well-known paths.
+   * Returns { status, headers, body } where body is a string (text formats)
+   * or a JS object (JSON formats). Adapters serialize as needed.
+   */
+  async function serveManifest(kind) {
+    if (!CONTENT_TYPE[kind]) {
+      return { status: 404, headers: {}, body: "Unknown manifest kind" };
+    }
+    try {
+      const res = await fetchFromCdn(kind);
+      if (!res.ok) {
+        return {
+          status: res.status,
+          headers: { "Content-Type": CONTENT_TYPE[kind] },
+          body: kind === "manifest" || kind === "mcp"
+            ? { error: `Manifest unavailable (${res.status})` }
+            : `Manifest unavailable (${res.status})`,
+        };
+      }
+      const headers = {
+        "Content-Type": CONTENT_TYPE[kind],
+        "Cache-Control": "public, max-age=300, s-maxage=600",
+        "X-Ooky-Sdk": "node",
+      };
+      if (kind === "manifest" || kind === "mcp") {
+        const body = await res.json();
+        return { status: 200, headers, body };
+      }
+      const body = await res.text();
+      return { status: 200, headers, body };
+    } catch (err) {
+      return {
+        status: 502,
+        headers: { "Content-Type": "text/plain; charset=utf-8" },
+        body: `Ooky manifest fetch failed: ${err.message}`,
+      };
+    }
+  }
+
+  /**
+   * Fire-and-forget event POST. Returns immediately; the caller should not
+   * `await` it on the request hot path. Errors are swallowed.
+   */
+  function recordEvent(payload) {
+    const body = JSON.stringify({
+      event_id: payload.event_id || cryptoRandomId(),
+      timestamp: payload.timestamp || new Date().toISOString(),
+      domain, // server overrides anyway, but include for backward compat
+      bot: payload.bot || null,
+      request: payload.request || null,
+      session: payload.session || null,
+      geo: payload.geo || null,
+      serve: payload.serve || null,
+    });
+
+    // Use fetch with keepalive=true so it survives the response cycle.
+    return fetch(`${apiBase}/ingest/events`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body,
+      keepalive: true,
+    }).catch(() => {
+      // Fire-and-forget — never throw on the request path.
+    });
+  }
+
+  return {
+    matchPath,
+    detectBot,
+    serveManifest,
+    recordEvent,
+    refreshBotRegistry,
+    // exposed for tests / introspection
+    _options: { apiBase, cdnBase, domain },
+  };
+}
+
+/**
+ * Reject any apiBase / cdnBase override that isn't a real http(s) URL.
+ * Prevents file://, data:, javascript:, etc. from being injected through SDK
+ * options on a misconfigured customer app.
+ */
+function assertHttpUrl(value, optionName) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`createOokyHandler: options.${optionName} must be a non-empty string`);
+  }
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new TypeError(`createOokyHandler: options.${optionName} must be a valid URL`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new TypeError(
+      `createOokyHandler: options.${optionName} must use http or https (got ${parsed.protocol})`
+    );
+  }
+  return value;
+}
+
+/**
+ * Tiny stand-in for crypto.randomUUID() that works in every JS runtime.
+ * Returns a 16-char base36 string — collision risk is negligible for events
+ * (deduped server-side by event_id anyway).
+ */
+function cryptoRandomId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return (
+    Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 11)
+  );
+}

package/src/edge.js

@@ -0,0 +1,14 @@
+/**
+ * Vercel Edge / generic Web Fetch adapter.
+ *
+ *   // middleware.ts (Vercel Edge runtime)
+ *   import { ookyEdge } from "@ooky/sdk/edge";
+ *   export default ookyEdge({ apiKey: "ooky_sk_...", domain: "acme.com" });
+ *   export const config = { matcher: "/(.*)" };
+ *
+ * Same shape as the Next.js adapter but exported under a different name to
+ * make intent obvious in the customer's middleware file. Both are pure Web
+ * Fetch — no Node-specific APIs are touched.
+ */
+
+export { ookyMiddleware as ookyEdge } from "./next.js";

package/src/express.js

@@ -0,0 +1,47 @@
+/**
+ * Express adapter — `app.use(ookyMiddleware({ apiKey, domain }))`.
+ *
+ * Intercepts the well-known AI paths and serves the manifest. For every
+ * request (manifest or not), checks the User-Agent against the bot registry
+ * and fires a fire-and-forget event when a bot is detected.
+ */
+
+import { createOokyHandler } from "./core.js";
+
+export function ookyMiddleware(options) {
+  const handler = createOokyHandler(options);
+
+  return async function ookyHandler(req, res, next) {
+    const ua = req.headers["user-agent"] || "";
+    const path = req.path || req.url || "/";
+    const bot = handler.detectBot(ua);
+
+    // Fire bot event regardless of whether we serve the manifest. The Ooky
+    // dashboard tracks bot visits across all routes, not just /llms.txt.
+    // `verified: false` — UA-only matching can't prove bot identity. The
+    // Worker tier does IP + reverse-DNS verification; the SDK can't.
+    if (bot) {
+      handler.recordEvent({
+        bot: { name: bot.name, verified: false, ua_string: ua },
+        request: {
+          page_path: path.split("?")[0] || "/",
+          method: req.method || "GET",
+        },
+      });
+    }
+
+    const kind = handler.matchPath(path);
+    if (!kind) return next();
+
+    const { status, headers, body } = await handler.serveManifest(kind);
+    res.status(status);
+    for (const [k, v] of Object.entries(headers)) {
+      res.setHeader(k, v);
+    }
+    if (typeof body === "string") {
+      res.send(body);
+    } else {
+      res.json(body);
+    }
+  };
+}

package/src/next.js

@@ -0,0 +1,43 @@
+/**
+ * Next.js adapter — usable in both the Node and Edge runtimes.
+ *
+ *   // middleware.ts
+ *   import { ookyMiddleware } from "@ooky/sdk/next";
+ *   export default ookyMiddleware({ apiKey: "ooky_sk_...", domain: "acme.com" });
+ *   export const config = { matcher: ["/llms.txt", "/llms-full.txt", "/.well-known/:path*", "/agents.md", "/(.*)"] };
+ *
+ * Returns a function with the Next.js middleware signature: it receives a
+ * NextRequest-like object (compatible Web Request) and returns a Response,
+ * or undefined to fall through to the next middleware/route.
+ */
+
+import { createOokyHandler } from "./core.js";
+
+export function ookyMiddleware(options) {
+  const handler = createOokyHandler(options);
+
+  return async function ookyNextMiddleware(request) {
+    const url = new URL(request.url);
+    const ua = request.headers.get("user-agent") || "";
+    const bot = handler.detectBot(ua);
+
+    // `verified: false` — UA-only matching can't prove bot identity. The
+    // Worker tier does IP + reverse-DNS verification; the SDK can't.
+    if (bot) {
+      handler.recordEvent({
+        bot: { name: bot.name, verified: false, ua_string: ua },
+        request: {
+          page_path: url.pathname || "/",
+          method: request.method || "GET",
+        },
+      });
+    }
+
+    const kind = handler.matchPath(url.pathname);
+    if (!kind) return undefined;
+
+    const { status, headers, body } = await handler.serveManifest(kind);
+    const responseBody = typeof body === "string" ? body : JSON.stringify(body);
+    return new Response(responseBody, { status, headers });
+  };
+}