@ooky/sdk 0.1.0 → 0.6.0

package/src/core.js

@@ -4,15 +4,69 @@
  * The handler exposes:
  *   - matchPath(path)   → null | "llms" | "llms-full" | "manifest" | "agents" | "mcp"
  *   - detectBot(ua)     → null | { name, pattern, category }
- *   - serveManifest(kind, ctx?)  → { status, body, headers }
+ *   - serveManifest(kind)        → { 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.
+ *
+ * IMPORTANT: never import Node-only APIs here (no `node:*`, no `Buffer`, no
+ * `setImmediate`) — this file runs verbatim on the Vercel Edge runtime.
  */
 
-import { detectBot as detectFromList, DEFAULT_BOTS } from "./bots.js";
+import { detectBot as detectFromList, DEFAULT_BOTS, sanitizeBotRegistry } from "./bots.js";
+import { detectAIReferral } from "./referrals.js";
+import { handleMcpJsonRpc, McpToolError } from "./mcp.js";
+
+export const SDK_VERSION = "0.6.0";
+
+// Defensive length caps on untrusted strings copied into the event payload.
+// The load-bearing clamp is server-side (owned by the backend), but capping
+// here keeps a pathological UA / very long path from being POSTed at all.
+export const MAX_UA_LENGTH = 1024;
+export const MAX_PATH_LENGTH = 2048;
+
+/** Truncate an untrusted string to `max` chars; pass through non-strings. */
+export function clampString(value, max) {
+  if (typeof value !== "string") return value;
+  return value.length > max ? value.slice(0, max) : value;
+}
+
+/**
+ * Log (loudly) that the middleware could not be constructed — almost always a
+ * missing/invalid OOKY_API_KEY or OOKY_DOMAIN. The adapters call this and then
+ * return a pass-through middleware: a misconfigured integration must NEVER take
+ * down the customer's site (the middleware runs on every request). Never throws.
+ */
+export function logMiddlewareDisabled(err) {
+  const msg = err && err.message ? err.message : String(err);
+  try {
+    console.error(
+      `[@ooky/sdk] Middleware disabled — ${msg}. Requests pass through ` +
+        `untouched (your app is unaffected); Ooky features are inactive. ` +
+        `Check that OOKY_API_KEY and OOKY_DOMAIN are set.`
+    );
+  } catch {
+    // console may be unavailable in exotic runtimes — never throw from here.
+  }
+}
+
+/**
+ * Hard cap on the MCP request body the adapters will read before answering.
+ * The Express adapter enforces this while streaming; the Next/Edge adapter
+ * uses it for a Content-Length pre-check. Exported so both adapters (and the
+ * Worker tier, for parity) share one number.
+ */
+export const MAX_MCP_BODY_BYTES = 64 * 1024;
+
+/**
+ * Runtime tag stamped into the `X-Ooky-Sdk` response header so we don't claim
+ * "node" on the Edge/Web runtime. Best-effort detection — falls back to
+ * "node" only when we positively look like Node (has `process.versions.node`
+ * and no Web-runtime markers).
+ */
+export const SDK_RUNTIME = detectRuntime();
 
 const DEFAULT_API_BASE = "https://api.ooky.ai/api";
 // Manifest content is served from the public Ooky API by default. Customers
@@ -20,7 +74,9 @@ const DEFAULT_API_BASE = "https://api.ooky.ai/api";
 // 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.
+// Well-known paths the SDK answers on behalf of the customer's app. Must stay
+// feature-equivalent with worker/src/index.js (the Worker also serves bare
+// /mcp because some platforms intercept /.well-known/*).
 const PATH_MAP = {
   "/llms.txt": "llms",
   "/llms-full.txt": "llms-full",
@@ -28,6 +84,7 @@ const PATH_MAP = {
   "/ai-manifest.json": "manifest",
   "/agents.md": "agents",
   "/.well-known/mcp": "mcp",
+  "/mcp": "mcp",
 };
 
 const CONTENT_TYPE = {
@@ -38,6 +95,13 @@ const CONTENT_TYPE = {
   mcp: "application/json; charset=utf-8",
 };
 
+const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_EVENTS_PER_MINUTE = 300;
+const THROTTLE_REPORT_INTERVAL_MS = 10_000;
+const DEFAULT_MANIFEST_CACHE_TTL_MS = 5 * 60 * 1000; // mirrors Cache-Control max-age=300
+const MANIFEST_STALE_MAX_MS = 24 * 60 * 60 * 1000; // serve stale up to 24h on upstream failure
+const BOT_REFRESH_MS = 60 * 60 * 1000; // 1 hour
+
 /**
  * Create an Ooky handler instance.
  *
@@ -48,6 +112,18 @@ const CONTENT_TYPE = {
  * @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.
+ * @param {number} [options.fetchTimeoutMs=10000]  Upstream fetch timeout (manifest + registry).
+ * @param {number} [options.manifestCacheTtlMs=300000]  In-memory manifest cache TTL. 0 disables.
+ * @param {Function}[options.onError]  Called with (error, context) for every failure the
+ *                                     SDK swallows (event POST rejections/non-2xx, manifest
+ *                                     fetch failures, registry refresh failures). Use it to
+ *                                     surface rotated keys / outages in your own logs.
+ *                                     context = { op, status?, kind?, throttled? }. Never
+ *                                     awaited; its own throws are swallowed.
+ * @param {number} [options.maxEventsPerMinute=300]  Token-bucket cap on event POSTs so a
+ *                                     bot storm can't turn your server into an unbounded
+ *                                     POST cannon. Drops are reported via onError (at most
+ *                                     once per 10s). Pass Infinity to disable.
  */
 export function createOokyHandler(options) {
   if (!options || typeof options !== "object") {
@@ -67,29 +143,123 @@ export function createOokyHandler(options) {
     "cdnBase"
   ).replace(/\/+$/, "");
   const autoRefreshBots = options.autoRefreshBots !== false;
+  const onError = typeof options.onError === "function" ? options.onError : null;
+  const maxEventsPerMinute =
+    options.maxEventsPerMinute === Infinity
+      ? Infinity
+      : positiveNumber(options.maxEventsPerMinute, DEFAULT_MAX_EVENTS_PER_MINUTE);
+  const fetchTimeoutMs = positiveNumber(options.fetchTimeoutMs, DEFAULT_FETCH_TIMEOUT_MS);
+  const manifestCacheTtlMs =
+    options.manifestCacheTtlMs === 0
+      ? 0
+      : positiveNumber(options.manifestCacheTtlMs, DEFAULT_MANIFEST_CACHE_TTL_MS);
 
-  let botRegistry = options.bots || DEFAULT_BOTS;
+  // A customer-supplied `options.bots` typo (non-array, entries with no
+  // pattern, an empty-string pattern, a multi-thousand-entry blob) must not be
+  // able to crash the request path or match every UA. Sanitise on the way in;
+  // fall back to the built-in list when the override is unusable.
+  let botRegistry = DEFAULT_BOTS;
+  if (options.bots !== undefined) {
+    const cleaned = sanitizeBotRegistry(options.bots);
+    botRegistry = cleaned && cleaned.length > 0 ? cleaned : DEFAULT_BOTS;
+  }
   let lastBotRefresh = 0;
-  const BOT_REFRESH_MS = 60 * 60 * 1000; // 1 hour
+  let botEtag = null;
+  let botRefreshInFlight = null;
+
+  // kind → { status, headers, body, freshUntil, staleUntil }
+  const manifestCache = new Map();
+  // kind → Promise — dedupes concurrent cold-cache fetches for the same kind.
+  const manifestInFlight = new Map();
+
+  /** Report a swallowed failure to the customer's onError hook, if set. */
+  function reportError(error, context) {
+    if (!onError) return;
+    try {
+      onError(error, context);
+    } catch {
+      // The hook itself must never break the request path.
+    }
+  }
+
+  // Token bucket for event POSTs. Refills continuously at the per-minute
+  // rate; bursts up to one minute's allowance.
+  let eventTokens = maxEventsPerMinute;
+  let lastRefillAt = Date.now();
+  let droppedSinceReport = 0;
+  let lastDropReportAt = 0;
+
+  function takeEventToken() {
+    if (!Number.isFinite(maxEventsPerMinute)) return true;
+    const now = Date.now();
+    eventTokens = Math.min(
+      maxEventsPerMinute,
+      eventTokens + ((now - lastRefillAt) / 60_000) * maxEventsPerMinute
+    );
+    lastRefillAt = now;
+    if (eventTokens >= 1) {
+      eventTokens -= 1;
+      return true;
+    }
+    droppedSinceReport += 1;
+    if (now - lastDropReportAt >= THROTTLE_REPORT_INTERVAL_MS) {
+      lastDropReportAt = now;
+      const dropped = droppedSinceReport;
+      droppedSinceReport = 0;
+      reportError(
+        new Error(
+          `event throttle: dropped ${dropped} event(s) (maxEventsPerMinute=${maxEventsPerMinute})`
+        ),
+        { op: "recordEvent", throttled: true }
+      );
+    }
+    return false;
+  }
 
   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;
+    if (botRefreshInFlight) return botRefreshInFlight;
+
+    botRefreshInFlight = (async () => {
+      try {
+        const headers = { Accept: "application/json" };
+        if (botEtag) headers["If-None-Match"] = botEtag;
+        const res = await fetch(`${apiBase}/public/bots`, {
+          headers,
+          signal: timeoutSignal(fetchTimeoutMs),
+        });
+        if (res.status === 304) {
+          // Registry unchanged — just push the refresh window forward.
+        } else if (res.ok) {
+          const data = await res.json();
+          // Validate + cap before adopting: a malformed payload (empty-string
+          // patterns, non-string entries, a backend row-mapping regression,
+          // or an intermediary corrupting the JSON) must never reach
+          // detectBot on the hot path. A bad registry is re-fetched on every
+          // restart, so swallowing it here is what stops a crash loop.
+          const cleaned = sanitizeBotRegistry(data?.bots);
+          if (cleaned && cleaned.length > 0) {
+            botRegistry = cleaned;
+            botEtag = res.headers?.get?.("etag") || null;
+          } else {
+            reportError(new Error("ignored malformed /public/bots registry"), {
+              op: "refreshBotRegistry",
+            });
+          }
         }
+        lastBotRefresh = Date.now();
+      } catch (err) {
+        // Network failure — keep stale list, but still bump the timestamp so
+        // a dead endpoint can't trigger a refresh attempt on every request.
+        lastBotRefresh = Date.now();
+        reportError(err, { op: "refreshBotRegistry" });
+      } finally {
+        botRefreshInFlight = null;
       }
-      lastBotRefresh = Date.now();
-    } catch {
-      // Network failure — keep stale list.
-    }
-    return botRegistry;
+      return botRegistry;
+    })();
+    return botRefreshInFlight;
   }
 
   function matchPath(path) {
@@ -100,6 +270,11 @@ export function createOokyHandler(options) {
   }
 
   function detectBot(userAgent) {
+    // Opportunistic, non-blocking registry refresh — this is the only hook
+    // that runs on every request, so it's where autoRefreshBots is honoured.
+    if (autoRefreshBots && Date.now() - lastBotRefresh >= BOT_REFRESH_MS) {
+      refreshBotRegistry().catch(() => {});
+    }
     return detectFromList(userAgent, botRegistry);
   }
 
@@ -107,56 +282,117 @@ export function createOokyHandler(options) {
     // 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] || "*/*" } });
+    const res = await fetch(url, {
+      headers: { Accept: CONTENT_TYPE[kind] || "*/*" },
+      signal: timeoutSignal(fetchTimeoutMs),
+    });
     return res;
   }
 
+  function cacheGet(kind) {
+    const entry = manifestCache.get(kind);
+    if (!entry) return { fresh: null, stale: null };
+    const now = Date.now();
+    if (now < entry.freshUntil) return { fresh: entry, stale: entry };
+    if (now < entry.staleUntil) return { fresh: null, stale: entry };
+    manifestCache.delete(kind);
+    return { fresh: null, stale: null };
+  }
+
+  function cachePut(kind, result) {
+    if (manifestCacheTtlMs <= 0) return;
+    const now = Date.now();
+    manifestCache.set(kind, {
+      ...result,
+      freshUntil: now + manifestCacheTtlMs,
+      staleUntil: now + MANIFEST_STALE_MAX_MS,
+    });
+  }
+
+  function toResponseShape(entry) {
+    return { status: entry.status, headers: entry.headers, body: entry.body };
+  }
+
   /**
    * 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.
+   *
+   * Successful responses are cached in-memory for `manifestCacheTtlMs`; when
+   * the upstream fails, a stale copy (up to 24h old) is served instead so a
+   * transient Ooky outage never breaks the customer's well-known endpoints.
    */
   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) {
+
+    const { fresh } = cacheGet(kind);
+    if (fresh) return toResponseShape(fresh);
+
+    const inFlight = manifestInFlight.get(kind);
+    if (inFlight) return inFlight;
+
+    const promise = (async () => {
+      try {
+        const res = await fetchFromCdn(kind);
+        if (!res.ok) {
+          reportError(new Error(`manifest upstream responded ${res.status}`), {
+            op: "serveManifest",
+            kind,
+            status: res.status,
+          });
+          const { stale } = cacheGet(kind);
+          if (stale && res.status >= 500) return toResponseShape(stale);
+          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": `${SDK_RUNTIME}/${SDK_VERSION}`,
+        };
+        const body =
+          kind === "manifest" || kind === "mcp" ? await res.json() : await res.text();
+        const result = { status: 200, headers, body };
+        cachePut(kind, result);
+        return result;
+      } catch (err) {
+        reportError(err, { op: "serveManifest", kind });
+        const { stale } = cacheGet(kind);
+        if (stale) return toResponseShape(stale);
+        // Match the declared content-type for this kind: JSON kinds get a
+        // JSON {error} body, text kinds get a text body. Otherwise a
+        // manifest/mcp consumer parsing application/json chokes on text.
+        const isJson = kind === "manifest" || kind === "mcp";
         return {
-          status: res.status,
+          status: 502,
           headers: { "Content-Type": CONTENT_TYPE[kind] },
-          body: kind === "manifest" || kind === "mcp"
-            ? { error: `Manifest unavailable (${res.status})` }
-            : `Manifest unavailable (${res.status})`,
+          body: isJson
+            ? { error: `Ooky manifest fetch failed: ${err.message}` }
+            : `Ooky manifest fetch failed: ${err.message}`,
         };
+      } finally {
+        manifestInFlight.delete(kind);
       }
-      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}`,
-      };
-    }
+    })();
+    manifestInFlight.set(kind, promise);
+    return promise;
   }
 
   /**
-   * Fire-and-forget event POST. Returns immediately; the caller should not
+   * Fire-and-forget event POST. Returns the underlying promise so edge
+   * runtimes can hand it to `event.waitUntil()`, but the caller must never
    * `await` it on the request hot path. Errors are swallowed.
    */
   function recordEvent(payload) {
-    const body = JSON.stringify({
+    if (!takeEventToken()) return Promise.resolve(undefined);
+    const event = {
       event_id: payload.event_id || cryptoRandomId(),
       timestamp: payload.timestamp || new Date().toISOString(),
       domain, // server overrides anyway, but include for backward compat
@@ -165,7 +401,12 @@ export function createOokyHandler(options) {
       session: payload.session || null,
       geo: payload.geo || null,
       serve: payload.serve || null,
-    });
+    };
+    // ai_referral events carry a referral block instead of a bot block —
+    // see backend ingest.js for how the two row types diverge.
+    if (payload.event_type) event.event_type = payload.event_type;
+    if (payload.referral) event.referral = payload.referral;
+    const body = JSON.stringify(event);
 
     // Use fetch with keepalive=true so it survives the response cycle.
     return fetch(`${apiBase}/ingest/events`, {
@@ -176,19 +417,140 @@ export function createOokyHandler(options) {
       },
       body,
       keepalive: true,
-    }).catch(() => {
-      // Fire-and-forget — never throw on the request path.
-    });
+      signal: timeoutSignal(fetchTimeoutMs),
+    })
+      .then((res) => {
+        // A non-2xx here is the one signal a customer has that their key was
+        // rotated/revoked (401) or the payload drifted (400) — surface it.
+        if (res && !res.ok) {
+          reportError(new Error(`ingest responded ${res.status}`), {
+            op: "recordEvent",
+            status: res.status,
+          });
+        }
+        return res;
+      })
+      .catch((err) => {
+        // Fire-and-forget — never throw on the request path.
+        reportError(err, { op: "recordEvent" });
+      });
+  }
+
+  /**
+   * Detect an AI-platform referral (human arriving from ChatGPT, Perplexity,
+   * Claude, …) from a Referer header and utm_source value. Pure check — the
+   * adapters call this for non-bot traffic and fire an ai_referral event.
+   */
+  function detectReferral(referer, utmSource) {
+    return detectAIReferral(referer, utmSource);
+  }
+
+  // Tool surface for the MCP server. The SDK tier exposes get_brand_info
+  // only (product tools need feed data the SDK doesn't have) — keep in sync
+  // with the descriptor served by backend public_manifest.js.
+  const MCP_TOOLS = [
+    {
+      name: "get_brand_info",
+      description:
+        "Get brand information including company overview, products, contact, and policies.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          section: {
+            type: "string",
+            description:
+              'Optional section filter: "about", "products", "contact", "policies", or omit for all.',
+          },
+        },
+      },
+    },
+  ];
+
+  async function getBrandInfo(args) {
+    const manifest = await serveManifest("manifest");
+    if (manifest.status !== 200 || typeof manifest.body !== "object") {
+      throw new McpToolError("Brand information not available");
+    }
+    return filterBrandSection(manifest.body, args?.section);
+  }
+
+  /**
+   * Handle an MCP request (POST /.well-known/mcp or /mcp).
+   *
+   * Speaks two protocols:
+   *  - Standard MCP — JSON-RPC 2.0 over streamable HTTP (initialize,
+   *    tools/list, tools/call). This is what real MCP clients (Claude, MCP
+   *    Inspector) use. Detected by `jsonrpc: "2.0"` on the body.
+   *  - Legacy Ooky protocol — { tool, arguments } → { result }, kept for
+   *    Worker-tier compatibility.
+   *
+   * Returns the same { status, headers, body } shape as serveManifest
+   * (body null → respond with an empty body).
+   */
+  async function handleMcpInvocation(body) {
+    const headers = {
+      "Content-Type": "application/json; charset=utf-8",
+      "Access-Control-Allow-Origin": "*",
+      "X-Ooky-Sdk": `${SDK_RUNTIME}/${SDK_VERSION}`,
+    };
+
+    // Standard JSON-RPC 2.0 path (also handles null = unparseable body).
+    if (body === null || body === undefined || body.jsonrpc === "2.0" || Array.isArray(body)) {
+      const { status, body: rpcBody } = await handleMcpJsonRpc(body ?? null, {
+        name: `ooky-${domain.replace(/[^a-z0-9-]/gi, "-")}`,
+        version: SDK_VERSION,
+        tools: MCP_TOOLS,
+        callTool: (name, args) => {
+          if (name === "get_brand_info") return getBrandInfo(args);
+          throw new McpToolError(`Unknown tool: ${name}`);
+        },
+      });
+      return { status, headers, body: rpcBody };
+    }
+
+    // Legacy { tool, arguments } path.
+    if (typeof body !== "object") {
+      return { status: 400, headers, body: { error: "JSON body required" } };
+    }
+    if (!body.tool) {
+      return { status: 400, headers, body: { error: 'Missing "tool" field' } };
+    }
+    if (body.tool !== "get_brand_info") {
+      return { status: 404, headers, body: { error: `Unknown tool: ${body.tool}` } };
+    }
+    try {
+      const result = await getBrandInfo(body.arguments);
+      return { status: 200, headers, body: { result } };
+    } catch (err) {
+      return {
+        status: 502,
+        headers,
+        body: { error: err instanceof McpToolError ? err.message : "Tool invocation failed" },
+      };
+    }
+  }
+
+  /**
+   * The in-flight bot-registry refresh, if any. Edge adapters must register
+   * this with `event.waitUntil()` — edge runtimes can cancel outstanding
+   * fetches once the response returns, which would otherwise abort the
+   * refresh kicked off by detectBot on every request.
+   */
+  function pendingBotRefresh() {
+    return botRefreshInFlight;
   }
 
   return {
     matchPath,
     detectBot,
+    detectReferral,
     serveManifest,
+    handleMcpInvocation,
     recordEvent,
     refreshBotRegistry,
+    pendingBotRefresh,
     // exposed for tests / introspection
-    _options: { apiBase, cdnBase, domain },
+    _options: { apiBase, cdnBase, domain, fetchTimeoutMs, manifestCacheTtlMs },
   };
 }
 
@@ -215,6 +577,83 @@ function assertHttpUrl(value, optionName) {
   return value;
 }
 
+function positiveNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+/**
+ * Best-effort runtime tag for the `X-Ooky-Sdk` header. We must not import
+ * `node:*` or touch `process` unconditionally (this file runs on Vercel Edge
+ * verbatim), so everything is feature-detected off globalThis.
+ *
+ *  - "edge"  — a Web-runtime marker is present (EdgeRuntime global, or
+ *              navigator.userAgent reports Cloudflare-Workers/Vercel-Edge).
+ *  - "node"  — process.versions.node exists and no edge marker.
+ *  - "web"   — anything else with a Web Fetch surface but no Node.
+ */
+function detectRuntime() {
+  try {
+    const g = globalThis;
+    // Vercel Edge sets a global `EdgeRuntime` ("edge-runtime").
+    if (typeof g.EdgeRuntime !== "undefined") return "edge";
+    const navUA =
+      g.navigator && typeof g.navigator.userAgent === "string" ? g.navigator.userAgent : "";
+    if (/Cloudflare-Workers|Vercel-Edge|Deno/i.test(navUA)) return "edge";
+    if (g.process && g.process.versions && typeof g.process.versions.node === "string") {
+      return "node";
+    }
+    // Has a Web Fetch surface but isn't Node — generic web/edge worker.
+    if (typeof g.fetch === "function") return "web";
+  } catch {
+    // Fall through to the safe default.
+  }
+  return "node";
+}
+
+/**
+ * Section filter for get_brand_info — mirrors the Worker's getBrandInfo
+ * switch (worker/src/mcp.js). The public manifest JSON doesn't always carry
+ * the Worker's R2 key layout, so when a section's keys are absent we fall
+ * back to the full manifest rather than returning an empty object.
+ */
+function filterBrandSection(manifest, section) {
+  if (!section) return manifest;
+  let picked;
+  switch (section) {
+    case "about":
+      picked = { brand: manifest.brand, audience: manifest.audience };
+      break;
+    case "products":
+      picked = { positioning: manifest.positioning, brand: manifest.brand && { name: manifest.brand.name } };
+      break;
+    case "contact":
+      picked = {
+        support: manifest.support,
+        brand: manifest.brand && { name: manifest.brand.name, website: manifest.brand.website },
+      };
+      break;
+    case "policies":
+      picked = { aiGuidelines: manifest.aiGuidelines };
+      break;
+    default:
+      return manifest;
+  }
+  const hasContent = Object.values(picked).some((v) => v != null);
+  return hasContent ? picked : manifest;
+}
+
+/**
+ * AbortSignal with a deadline, when the runtime supports it (Node ≥18,
+ * Cloudflare Workers, Vercel Edge all do). Returns undefined otherwise so
+ * fetch falls back to no timeout rather than crashing.
+ */
+function timeoutSignal(ms) {
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+    return AbortSignal.timeout(ms);
+  }
+  return undefined;
+}
+
 /**
  * Tiny stand-in for crypto.randomUUID() that works in every JS runtime.
  * Returns a 16-char base36 string — collision risk is negligible for events

package/src/edge.d.ts

@@ -0,0 +1 @@
+export { ookyMiddleware as ookyEdge } from "./next";

package/src/express.d.ts

@@ -0,0 +1,6 @@
+import type { OokyHandlerOptions } from "./index";
+
+/** Express-compatible middleware: `app.use(ookyMiddleware({ apiKey, domain }))`. */
+export function ookyMiddleware(
+  options: OokyHandlerOptions
+): (req: any, res: any, next: (err?: unknown) => void) => Promise<void>;