@vercel/agent-readability 0.3.0 → 0.4.0

package/dist/nuxt/index.cjs

@@ -0,0 +1,170 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/nuxt/index.ts
+var nuxt_exports = {};
+__export(nuxt_exports, {
+  defineAgentMiddleware: () => defineAgentMiddleware
+});
+module.exports = __toCommonJS(nuxt_exports);
+var import_h3 = require("h3");
+
+// src/patterns.ts
+var AI_AGENT_UA_PATTERNS = [
+  // Anthropic — https://support.claude.com/en/articles/8896518
+  "claudebot",
+  "claude-searchbot",
+  "claude-user",
+  "anthropic-ai",
+  "claude-web",
+  // OpenAI — https://platform.openai.com/docs/bots
+  "chatgpt",
+  "gptbot",
+  "oai-searchbot",
+  "openai",
+  // Google AI
+  "gemini",
+  "bard",
+  "google-cloudvertexbot",
+  "google-extended",
+  // Meta
+  "meta-externalagent",
+  "meta-externalfetcher",
+  "meta-webindexer",
+  // Search/Research AI
+  "perplexity",
+  "youbot",
+  "you.com",
+  "deepseekbot",
+  // Coding assistants
+  "cursor",
+  "github-copilot",
+  "codeium",
+  "tabnine",
+  "sourcegraph",
+  // Other AI agents / data scrapers
+  "cohere-ai",
+  "bytespider",
+  "amazonbot",
+  "ai2bot",
+  "diffbot",
+  "omgili",
+  "omgilibot"
+];
+var SIGNATURE_AGENT_DOMAINS = ["chatgpt.com"];
+var TRADITIONAL_BOT_PATTERNS = [
+  "googlebot",
+  "bingbot",
+  "yandexbot",
+  "baiduspider",
+  "duckduckbot",
+  "slurp",
+  "msnbot",
+  "facebot",
+  "twitterbot",
+  "linkedinbot",
+  "whatsapp",
+  "telegrambot",
+  "pingdom",
+  "uptimerobot",
+  "newrelic",
+  "datadog",
+  "statuspage",
+  "site24x7",
+  "applebot"
+];
+var BOT_LIKE_REGEX = /bot|agent|fetch|crawl|spider|search/i;
+
+// src/detection.ts
+function isAIAgent(request) {
+  const userAgent = request.headers.get("user-agent");
+  const lowerUA = userAgent?.toLowerCase() ?? "";
+  if (lowerUA && AI_AGENT_UA_PATTERNS.some((pattern) => lowerUA.includes(pattern))) {
+    return { detected: true, method: "ua-match" };
+  }
+  const signatureAgent = request.headers.get("signature-agent");
+  if (signatureAgent) {
+    const lowerSig = signatureAgent.toLowerCase();
+    if (SIGNATURE_AGENT_DOMAINS.some((domain) => lowerSig.includes(domain))) {
+      return { detected: true, method: "signature-agent" };
+    }
+  }
+  const secFetchMode = request.headers.get("sec-fetch-mode");
+  if (!secFetchMode && lowerUA && BOT_LIKE_REGEX.test(lowerUA)) {
+    const isTraditionalBot = TRADITIONAL_BOT_PATTERNS.some((pattern) => lowerUA.includes(pattern));
+    if (!isTraditionalBot) {
+      return { detected: true, method: "heuristic" };
+    }
+  }
+  return { detected: false, method: null };
+}
+
+// src/negotiation.ts
+var DEFAULT_MARKDOWN_TYPES = ["text/markdown", "text/x-markdown"];
+function acceptsMarkdown(request, options) {
+  const accept = request.headers.get("accept");
+  if (!accept) return false;
+  const types = options?.mediaTypes ?? DEFAULT_MARKDOWN_TYPES;
+  const lowerAccept = accept.toLowerCase();
+  return types.some((type) => lowerAccept.includes(type));
+}
+function shouldServeMarkdown(request, options) {
+  const detection = isAIAgent(request);
+  if (detection.detected) {
+    return { serve: true, reason: "agent", detection };
+  }
+  if (acceptsMarkdown(request, options)) {
+    return { serve: true, reason: "accept-header", detection };
+  }
+  return { serve: false, reason: null, detection };
+}
+
+// src/nuxt/index.ts
+function defineAgentMiddleware(options) {
+  return (0, import_h3.defineEventHandler)(async (event) => {
+    const pathname = event.path.split("?")[0];
+    const prefix = options.docsPrefix ?? "/docs";
+    if (!pathname.startsWith(prefix)) return;
+    const { serve, detection } = shouldServeMarkdown({ headers: event.headers });
+    if (!serve) return;
+    if (options.onDetection) {
+      try {
+        const method = detection.detected ? detection.method : "accept-header";
+        const p = options.onDetection({
+          path: pathname,
+          method,
+          userAgent: event.headers.get("user-agent")
+        });
+        if (p instanceof Promise) p.catch(() => {
+        });
+      } catch {
+      }
+    }
+    const content = await options.getMarkdown(pathname, event);
+    if (content instanceof Response) return content;
+    return new Response(content, {
+      headers: { "content-type": "text/markdown; charset=utf-8", vary: "Accept" }
+    });
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineAgentMiddleware
+});
+//# sourceMappingURL=index.cjs.map

package/dist/nuxt/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/nuxt/index.ts","../../src/patterns.ts","../../src/detection.ts","../../src/negotiation.ts"],"sourcesContent":["import type { H3Event } from \"h3\";\nimport { defineEventHandler } from \"h3\";\nimport { shouldServeMarkdown } from \"../negotiation\";\nimport type { OnDetectionCallback } from \"../types\";\n\nexport interface NuxtAgentReadabilityOptions {\n\t/** URL prefix to intercept. Default: '/docs' */\n\tdocsPrefix?: string;\n\t/** Returns markdown content for the given path. Can return a string or a full Response. */\n\tgetMarkdown: (pathname: string, event: H3Event) => string | Response | Promise<string | Response>;\n\t/** Fire-and-forget callback for analytics/logging. */\n\tonDetection?: OnDetectionCallback;\n}\n\n/**\n * Nuxt server middleware that detects AI agents and serves markdown.\n *\n * ```ts\n * // server/middleware/agent.ts\n * import { defineAgentMiddleware } from '@vercel/agent-readability/nuxt'\n *\n * export default defineAgentMiddleware({\n *   getMarkdown: async (pathname) => {\n *     const doc = await fetchDoc(pathname)\n *     return doc.markdown\n *   },\n * })\n * ```\n */\nexport function defineAgentMiddleware(options: NuxtAgentReadabilityOptions) {\n\treturn defineEventHandler(async (event: H3Event) => {\n\t\t// h3 event.path includes query string — strip it for prefix matching\n\t\tconst pathname = event.path.split(\"?\")[0];\n\t\tconst prefix = options.docsPrefix ?? \"/docs\";\n\n\t\tif (!pathname.startsWith(prefix)) return; // undefined = h3 cascades to next handler\n\n\t\tconst { serve, detection } = shouldServeMarkdown({ headers: event.headers });\n\t\tif (!serve) return;\n\n\t\t// Fire-and-forget — never block the response\n\t\tif (options.onDetection) {\n\t\t\ttry {\n\t\t\t\tconst method = detection.detected ? detection.method : \"accept-header\";\n\t\t\t\tconst p = options.onDetection({\n\t\t\t\t\tpath: pathname,\n\t\t\t\t\tmethod,\n\t\t\t\t\tuserAgent: event.headers.get(\"user-agent\"),\n\t\t\t\t});\n\t\t\t\tif (p instanceof Promise) p.catch(() => {});\n\t\t\t} catch {\n\t\t\t\t/* swallow sync errors */\n\t\t\t}\n\t\t}\n\n\t\tconst content = await options.getMarkdown(pathname, event);\n\t\tif (content instanceof Response) return content;\n\n\t\treturn new Response(content, {\n\t\t\theaders: { \"content-type\": \"text/markdown; charset=utf-8\", vary: \"Accept\" },\n\t\t});\n\t});\n}\n","/**\n * Layer 1: Known AI agent UA substrings (lowercase).\n * Curated from https://bots.fyi/?tags=ai_assistant + official vendor docs.\n * Last reviewed: 2026-03-20\n */\nexport const AI_AGENT_UA_PATTERNS: readonly string[] = [\n\t// Anthropic — https://support.claude.com/en/articles/8896518\n\t\"claudebot\",\n\t\"claude-searchbot\",\n\t\"claude-user\",\n\t\"anthropic-ai\",\n\t\"claude-web\",\n\n\t// OpenAI — https://platform.openai.com/docs/bots\n\t\"chatgpt\",\n\t\"gptbot\",\n\t\"oai-searchbot\",\n\t\"openai\",\n\n\t// Google AI\n\t\"gemini\",\n\t\"bard\",\n\t\"google-cloudvertexbot\",\n\t\"google-extended\",\n\n\t// Meta\n\t\"meta-externalagent\",\n\t\"meta-externalfetcher\",\n\t\"meta-webindexer\",\n\n\t// Search/Research AI\n\t\"perplexity\",\n\t\"youbot\",\n\t\"you.com\",\n\t\"deepseekbot\",\n\n\t// Coding assistants\n\t\"cursor\",\n\t\"github-copilot\",\n\t\"codeium\",\n\t\"tabnine\",\n\t\"sourcegraph\",\n\n\t// Other AI agents / data scrapers\n\t\"cohere-ai\",\n\t\"bytespider\",\n\t\"amazonbot\",\n\t\"ai2bot\",\n\t\"diffbot\",\n\t\"omgili\",\n\t\"omgilibot\",\n];\n\n/**\n * Layer 2: Known AI service URLs in Signature-Agent header (RFC 9421).\n */\nexport const SIGNATURE_AGENT_DOMAINS: readonly string[] = [\"chatgpt.com\"];\n\n/**\n * Layer 3: Traditional bot exclusion list. Bots that should NOT trigger the\n * heuristic layer (search engine crawlers, social previews, monitoring tools).\n */\nexport const TRADITIONAL_BOT_PATTERNS: readonly string[] = [\n\t\"googlebot\",\n\t\"bingbot\",\n\t\"yandexbot\",\n\t\"baiduspider\",\n\t\"duckduckbot\",\n\t\"slurp\",\n\t\"msnbot\",\n\t\"facebot\",\n\t\"twitterbot\",\n\t\"linkedinbot\",\n\t\"whatsapp\",\n\t\"telegrambot\",\n\t\"pingdom\",\n\t\"uptimerobot\",\n\t\"newrelic\",\n\t\"datadog\",\n\t\"statuspage\",\n\t\"site24x7\",\n\t\"applebot\",\n];\n\n/**\n * Broad regex for bot-like UA strings (used only in Layer 3 heuristic).\n * No word boundaries — keywords commonly appear in compound names.\n */\nexport const BOT_LIKE_REGEX: RegExp = /bot|agent|fetch|crawl|spider|search/i;\n","import {\n\tAI_AGENT_UA_PATTERNS,\n\tBOT_LIKE_REGEX,\n\tSIGNATURE_AGENT_DOMAINS,\n\tTRADITIONAL_BOT_PATTERNS,\n} from \"./patterns\";\nimport type { DetectionResult, MinimalRequest } from \"./types\";\n\n/**\n * Detects AI agents from HTTP request headers.\n *\n * Three detection layers (checked in order):\n * 1. Known UA patterns (definitive)\n * 2. Signature-Agent header (definitive, RFC 9421)\n * 3. Missing sec-fetch-mode heuristic (catches unknown bots)\n *\n * Optimizes for recall over precision: serving markdown to a non-AI bot\n * is low-harm; missing an AI agent means a worse experience.\n */\nexport function isAIAgent(request: MinimalRequest): DetectionResult {\n\tconst userAgent = request.headers.get(\"user-agent\");\n\tconst lowerUA = userAgent?.toLowerCase() ?? \"\";\n\n\t// Layer 1: Known UA pattern match\n\tif (lowerUA && AI_AGENT_UA_PATTERNS.some((pattern) => lowerUA.includes(pattern))) {\n\t\treturn { detected: true, method: \"ua-match\" };\n\t}\n\n\t// Layer 2: Signature-Agent header (RFC 9421, used by ChatGPT agent)\n\tconst signatureAgent = request.headers.get(\"signature-agent\");\n\tif (signatureAgent) {\n\t\tconst lowerSig = signatureAgent.toLowerCase();\n\t\tif (SIGNATURE_AGENT_DOMAINS.some((domain) => lowerSig.includes(domain))) {\n\t\t\treturn { detected: true, method: \"signature-agent\" };\n\t\t}\n\t}\n\n\t// Layer 3: Missing browser fingerprint heuristic\n\t// Real browsers (Chrome 76+, Firefox 90+, Safari 16.4+) send sec-fetch-mode\n\t// on navigation requests. Its absence signals a programmatic client.\n\tconst secFetchMode = request.headers.get(\"sec-fetch-mode\");\n\tif (!secFetchMode && lowerUA && BOT_LIKE_REGEX.test(lowerUA)) {\n\t\tconst isTraditionalBot = TRADITIONAL_BOT_PATTERNS.some((pattern) => lowerUA.includes(pattern));\n\t\tif (!isTraditionalBot) {\n\t\t\treturn { detected: true, method: \"heuristic\" };\n\t\t}\n\t}\n\n\treturn { detected: false, method: null };\n}\n","import { isAIAgent } from \"./detection\";\nimport type { DetectionResult, MinimalRequest } from \"./types\";\n\nconst DEFAULT_MARKDOWN_TYPES = [\"text/markdown\", \"text/x-markdown\"];\n\nexport interface AcceptMarkdownOptions {\n\tmediaTypes?: string[];\n}\n\n/**\n * Check if the request prefers markdown via the Accept header.\n */\nexport function acceptsMarkdown(request: MinimalRequest, options?: AcceptMarkdownOptions): boolean {\n\tconst accept = request.headers.get(\"accept\");\n\tif (!accept) return false;\n\n\tconst types = options?.mediaTypes ?? DEFAULT_MARKDOWN_TYPES;\n\tconst lowerAccept = accept.toLowerCase();\n\treturn types.some((type) => lowerAccept.includes(type));\n}\n\nexport interface ShouldServeMarkdownResult {\n\tserve: boolean;\n\treason: \"agent\" | \"accept-header\" | null;\n\tdetection: DetectionResult;\n}\n\n/**\n * Combines agent detection and content negotiation into one call.\n * Returns whether to serve markdown and why.\n */\nexport function shouldServeMarkdown(\n\trequest: MinimalRequest,\n\toptions?: AcceptMarkdownOptions,\n): ShouldServeMarkdownResult {\n\tconst detection = isAIAgent(request);\n\tif (detection.detected) {\n\t\treturn { serve: true, reason: \"agent\", detection };\n\t}\n\n\tif (acceptsMarkdown(request, options)) {\n\t\treturn { serve: true, reason: \"accept-header\", detection };\n\t}\n\n\treturn { serve: false, reason: null, detection };\n}\n"],"mappings":"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","names":[]}

package/dist/nuxt/index.d.cts

@@ -0,0 +1,39 @@
+import * as h3 from 'h3';
+import { H3Event } from 'h3';
+
+type DetectionMethod = "ua-match" | "signature-agent" | "heuristic";
+/** Info passed to onDetection callbacks across all adapters. */
+type OnDetectionInfo = {
+    path: string;
+    method: DetectionMethod | "accept-header";
+    userAgent: string | null;
+};
+/** Fire-and-forget callback shared by Next.js, SvelteKit, and Nuxt adapters. */
+type OnDetectionCallback = (info: OnDetectionInfo) => void | Promise<void>;
+
+interface NuxtAgentReadabilityOptions {
+    /** URL prefix to intercept. Default: '/docs' */
+    docsPrefix?: string;
+    /** Returns markdown content for the given path. Can return a string or a full Response. */
+    getMarkdown: (pathname: string, event: H3Event) => string | Response | Promise<string | Response>;
+    /** Fire-and-forget callback for analytics/logging. */
+    onDetection?: OnDetectionCallback;
+}
+/**
+ * Nuxt server middleware that detects AI agents and serves markdown.
+ *
+ * ```ts
+ * // server/middleware/agent.ts
+ * import { defineAgentMiddleware } from '@vercel/agent-readability/nuxt'
+ *
+ * export default defineAgentMiddleware({
+ *   getMarkdown: async (pathname) => {
+ *     const doc = await fetchDoc(pathname)
+ *     return doc.markdown
+ *   },
+ * })
+ * ```
+ */
+declare function defineAgentMiddleware(options: NuxtAgentReadabilityOptions): h3.EventHandler<h3.EventHandlerRequest, Promise<Response | undefined>>;
+
+export { type NuxtAgentReadabilityOptions, defineAgentMiddleware };

package/dist/nuxt/index.d.ts

@@ -0,0 +1,39 @@
+import * as h3 from 'h3';
+import { H3Event } from 'h3';
+
+type DetectionMethod = "ua-match" | "signature-agent" | "heuristic";
+/** Info passed to onDetection callbacks across all adapters. */
+type OnDetectionInfo = {
+    path: string;
+    method: DetectionMethod | "accept-header";
+    userAgent: string | null;
+};
+/** Fire-and-forget callback shared by Next.js, SvelteKit, and Nuxt adapters. */
+type OnDetectionCallback = (info: OnDetectionInfo) => void | Promise<void>;
+
+interface NuxtAgentReadabilityOptions {
+    /** URL prefix to intercept. Default: '/docs' */
+    docsPrefix?: string;
+    /** Returns markdown content for the given path. Can return a string or a full Response. */
+    getMarkdown: (pathname: string, event: H3Event) => string | Response | Promise<string | Response>;
+    /** Fire-and-forget callback for analytics/logging. */
+    onDetection?: OnDetectionCallback;
+}
+/**
+ * Nuxt server middleware that detects AI agents and serves markdown.
+ *
+ * ```ts
+ * // server/middleware/agent.ts
+ * import { defineAgentMiddleware } from '@vercel/agent-readability/nuxt'
+ *
+ * export default defineAgentMiddleware({
+ *   getMarkdown: async (pathname) => {
+ *     const doc = await fetchDoc(pathname)
+ *     return doc.markdown
+ *   },
+ * })
+ * ```
+ */
+declare function defineAgentMiddleware(options: NuxtAgentReadabilityOptions): h3.EventHandler<h3.EventHandlerRequest, Promise<Response | undefined>>;
+
+export { type NuxtAgentReadabilityOptions, defineAgentMiddleware };

package/dist/nuxt/index.js

@@ -0,0 +1,145 @@
+// src/nuxt/index.ts
+import { defineEventHandler } from "h3";
+
+// src/patterns.ts
+var AI_AGENT_UA_PATTERNS = [
+  // Anthropic — https://support.claude.com/en/articles/8896518
+  "claudebot",
+  "claude-searchbot",
+  "claude-user",
+  "anthropic-ai",
+  "claude-web",
+  // OpenAI — https://platform.openai.com/docs/bots
+  "chatgpt",
+  "gptbot",
+  "oai-searchbot",
+  "openai",
+  // Google AI
+  "gemini",
+  "bard",
+  "google-cloudvertexbot",
+  "google-extended",
+  // Meta
+  "meta-externalagent",
+  "meta-externalfetcher",
+  "meta-webindexer",
+  // Search/Research AI
+  "perplexity",
+  "youbot",
+  "you.com",
+  "deepseekbot",
+  // Coding assistants
+  "cursor",
+  "github-copilot",
+  "codeium",
+  "tabnine",
+  "sourcegraph",
+  // Other AI agents / data scrapers
+  "cohere-ai",
+  "bytespider",
+  "amazonbot",
+  "ai2bot",
+  "diffbot",
+  "omgili",
+  "omgilibot"
+];
+var SIGNATURE_AGENT_DOMAINS = ["chatgpt.com"];
+var TRADITIONAL_BOT_PATTERNS = [
+  "googlebot",
+  "bingbot",
+  "yandexbot",
+  "baiduspider",
+  "duckduckbot",
+  "slurp",
+  "msnbot",
+  "facebot",
+  "twitterbot",
+  "linkedinbot",
+  "whatsapp",
+  "telegrambot",
+  "pingdom",
+  "uptimerobot",
+  "newrelic",
+  "datadog",
+  "statuspage",
+  "site24x7",
+  "applebot"
+];
+var BOT_LIKE_REGEX = /bot|agent|fetch|crawl|spider|search/i;
+
+// src/detection.ts
+function isAIAgent(request) {
+  const userAgent = request.headers.get("user-agent");
+  const lowerUA = userAgent?.toLowerCase() ?? "";
+  if (lowerUA && AI_AGENT_UA_PATTERNS.some((pattern) => lowerUA.includes(pattern))) {
+    return { detected: true, method: "ua-match" };
+  }
+  const signatureAgent = request.headers.get("signature-agent");
+  if (signatureAgent) {
+    const lowerSig = signatureAgent.toLowerCase();
+    if (SIGNATURE_AGENT_DOMAINS.some((domain) => lowerSig.includes(domain))) {
+      return { detected: true, method: "signature-agent" };
+    }
+  }
+  const secFetchMode = request.headers.get("sec-fetch-mode");
+  if (!secFetchMode && lowerUA && BOT_LIKE_REGEX.test(lowerUA)) {
+    const isTraditionalBot = TRADITIONAL_BOT_PATTERNS.some((pattern) => lowerUA.includes(pattern));
+    if (!isTraditionalBot) {
+      return { detected: true, method: "heuristic" };
+    }
+  }
+  return { detected: false, method: null };
+}
+
+// src/negotiation.ts
+var DEFAULT_MARKDOWN_TYPES = ["text/markdown", "text/x-markdown"];
+function acceptsMarkdown(request, options) {
+  const accept = request.headers.get("accept");
+  if (!accept) return false;
+  const types = options?.mediaTypes ?? DEFAULT_MARKDOWN_TYPES;
+  const lowerAccept = accept.toLowerCase();
+  return types.some((type) => lowerAccept.includes(type));
+}
+function shouldServeMarkdown(request, options) {
+  const detection = isAIAgent(request);
+  if (detection.detected) {
+    return { serve: true, reason: "agent", detection };
+  }
+  if (acceptsMarkdown(request, options)) {
+    return { serve: true, reason: "accept-header", detection };
+  }
+  return { serve: false, reason: null, detection };
+}
+
+// src/nuxt/index.ts
+function defineAgentMiddleware(options) {
+  return defineEventHandler(async (event) => {
+    const pathname = event.path.split("?")[0];
+    const prefix = options.docsPrefix ?? "/docs";
+    if (!pathname.startsWith(prefix)) return;
+    const { serve, detection } = shouldServeMarkdown({ headers: event.headers });
+    if (!serve) return;
+    if (options.onDetection) {
+      try {
+        const method = detection.detected ? detection.method : "accept-header";
+        const p = options.onDetection({
+          path: pathname,
+          method,
+          userAgent: event.headers.get("user-agent")
+        });
+        if (p instanceof Promise) p.catch(() => {
+        });
+      } catch {
+      }
+    }
+    const content = await options.getMarkdown(pathname, event);
+    if (content instanceof Response) return content;
+    return new Response(content, {
+      headers: { "content-type": "text/markdown; charset=utf-8", vary: "Accept" }
+    });
+  });
+}
+export {
+  defineAgentMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/nuxt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/nuxt/index.ts","../../src/patterns.ts","../../src/detection.ts","../../src/negotiation.ts"],"sourcesContent":["import type { H3Event } from \"h3\";\nimport { defineEventHandler } from \"h3\";\nimport { shouldServeMarkdown } from \"../negotiation\";\nimport type { OnDetectionCallback } from \"../types\";\n\nexport interface NuxtAgentReadabilityOptions {\n\t/** URL prefix to intercept. Default: '/docs' */\n\tdocsPrefix?: string;\n\t/** Returns markdown content for the given path. Can return a string or a full Response. */\n\tgetMarkdown: (pathname: string, event: H3Event) => string | Response | Promise<string | Response>;\n\t/** Fire-and-forget callback for analytics/logging. */\n\tonDetection?: OnDetectionCallback;\n}\n\n/**\n * Nuxt server middleware that detects AI agents and serves markdown.\n *\n * ```ts\n * // server/middleware/agent.ts\n * import { defineAgentMiddleware } from '@vercel/agent-readability/nuxt'\n *\n * export default defineAgentMiddleware({\n *   getMarkdown: async (pathname) => {\n *     const doc = await fetchDoc(pathname)\n *     return doc.markdown\n *   },\n * })\n * ```\n */\nexport function defineAgentMiddleware(options: NuxtAgentReadabilityOptions) {\n\treturn defineEventHandler(async (event: H3Event) => {\n\t\t// h3 event.path includes query string — strip it for prefix matching\n\t\tconst pathname = event.path.split(\"?\")[0];\n\t\tconst prefix = options.docsPrefix ?? \"/docs\";\n\n\t\tif (!pathname.startsWith(prefix)) return; // undefined = h3 cascades to next handler\n\n\t\tconst { serve, detection } = shouldServeMarkdown({ headers: event.headers });\n\t\tif (!serve) return;\n\n\t\t// Fire-and-forget — never block the response\n\t\tif (options.onDetection) {\n\t\t\ttry {\n\t\t\t\tconst method = detection.detected ? detection.method : \"accept-header\";\n\t\t\t\tconst p = options.onDetection({\n\t\t\t\t\tpath: pathname,\n\t\t\t\t\tmethod,\n\t\t\t\t\tuserAgent: event.headers.get(\"user-agent\"),\n\t\t\t\t});\n\t\t\t\tif (p instanceof Promise) p.catch(() => {});\n\t\t\t} catch {\n\t\t\t\t/* swallow sync errors */\n\t\t\t}\n\t\t}\n\n\t\tconst content = await options.getMarkdown(pathname, event);\n\t\tif (content instanceof Response) return content;\n\n\t\treturn new Response(content, {\n\t\t\theaders: { \"content-type\": \"text/markdown; charset=utf-8\", vary: \"Accept\" },\n\t\t});\n\t});\n}\n","/**\n * Layer 1: Known AI agent UA substrings (lowercase).\n * Curated from https://bots.fyi/?tags=ai_assistant + official vendor docs.\n * Last reviewed: 2026-03-20\n */\nexport const AI_AGENT_UA_PATTERNS: readonly string[] = [\n\t// Anthropic — https://support.claude.com/en/articles/8896518\n\t\"claudebot\",\n\t\"claude-searchbot\",\n\t\"claude-user\",\n\t\"anthropic-ai\",\n\t\"claude-web\",\n\n\t// OpenAI — https://platform.openai.com/docs/bots\n\t\"chatgpt\",\n\t\"gptbot\",\n\t\"oai-searchbot\",\n\t\"openai\",\n\n\t// Google AI\n\t\"gemini\",\n\t\"bard\",\n\t\"google-cloudvertexbot\",\n\t\"google-extended\",\n\n\t// Meta\n\t\"meta-externalagent\",\n\t\"meta-externalfetcher\",\n\t\"meta-webindexer\",\n\n\t// Search/Research AI\n\t\"perplexity\",\n\t\"youbot\",\n\t\"you.com\",\n\t\"deepseekbot\",\n\n\t// Coding assistants\n\t\"cursor\",\n\t\"github-copilot\",\n\t\"codeium\",\n\t\"tabnine\",\n\t\"sourcegraph\",\n\n\t// Other AI agents / data scrapers\n\t\"cohere-ai\",\n\t\"bytespider\",\n\t\"amazonbot\",\n\t\"ai2bot\",\n\t\"diffbot\",\n\t\"omgili\",\n\t\"omgilibot\",\n];\n\n/**\n * Layer 2: Known AI service URLs in Signature-Agent header (RFC 9421).\n */\nexport const SIGNATURE_AGENT_DOMAINS: readonly string[] = [\"chatgpt.com\"];\n\n/**\n * Layer 3: Traditional bot exclusion list. Bots that should NOT trigger the\n * heuristic layer (search engine crawlers, social previews, monitoring tools).\n */\nexport const TRADITIONAL_BOT_PATTERNS: readonly string[] = [\n\t\"googlebot\",\n\t\"bingbot\",\n\t\"yandexbot\",\n\t\"baiduspider\",\n\t\"duckduckbot\",\n\t\"slurp\",\n\t\"msnbot\",\n\t\"facebot\",\n\t\"twitterbot\",\n\t\"linkedinbot\",\n\t\"whatsapp\",\n\t\"telegrambot\",\n\t\"pingdom\",\n\t\"uptimerobot\",\n\t\"newrelic\",\n\t\"datadog\",\n\t\"statuspage\",\n\t\"site24x7\",\n\t\"applebot\",\n];\n\n/**\n * Broad regex for bot-like UA strings (used only in Layer 3 heuristic).\n * No word boundaries — keywords commonly appear in compound names.\n */\nexport const BOT_LIKE_REGEX: RegExp = /bot|agent|fetch|crawl|spider|search/i;\n","import {\n\tAI_AGENT_UA_PATTERNS,\n\tBOT_LIKE_REGEX,\n\tSIGNATURE_AGENT_DOMAINS,\n\tTRADITIONAL_BOT_PATTERNS,\n} from \"./patterns\";\nimport type { DetectionResult, MinimalRequest } from \"./types\";\n\n/**\n * Detects AI agents from HTTP request headers.\n *\n * Three detection layers (checked in order):\n * 1. Known UA patterns (definitive)\n * 2. Signature-Agent header (definitive, RFC 9421)\n * 3. Missing sec-fetch-mode heuristic (catches unknown bots)\n *\n * Optimizes for recall over precision: serving markdown to a non-AI bot\n * is low-harm; missing an AI agent means a worse experience.\n */\nexport function isAIAgent(request: MinimalRequest): DetectionResult {\n\tconst userAgent = request.headers.get(\"user-agent\");\n\tconst lowerUA = userAgent?.toLowerCase() ?? \"\";\n\n\t// Layer 1: Known UA pattern match\n\tif (lowerUA && AI_AGENT_UA_PATTERNS.some((pattern) => lowerUA.includes(pattern))) {\n\t\treturn { detected: true, method: \"ua-match\" };\n\t}\n\n\t// Layer 2: Signature-Agent header (RFC 9421, used by ChatGPT agent)\n\tconst signatureAgent = request.headers.get(\"signature-agent\");\n\tif (signatureAgent) {\n\t\tconst lowerSig = signatureAgent.toLowerCase();\n\t\tif (SIGNATURE_AGENT_DOMAINS.some((domain) => lowerSig.includes(domain))) {\n\t\t\treturn { detected: true, method: \"signature-agent\" };\n\t\t}\n\t}\n\n\t// Layer 3: Missing browser fingerprint heuristic\n\t// Real browsers (Chrome 76+, Firefox 90+, Safari 16.4+) send sec-fetch-mode\n\t// on navigation requests. Its absence signals a programmatic client.\n\tconst secFetchMode = request.headers.get(\"sec-fetch-mode\");\n\tif (!secFetchMode && lowerUA && BOT_LIKE_REGEX.test(lowerUA)) {\n\t\tconst isTraditionalBot = TRADITIONAL_BOT_PATTERNS.some((pattern) => lowerUA.includes(pattern));\n\t\tif (!isTraditionalBot) {\n\t\t\treturn { detected: true, method: \"heuristic\" };\n\t\t}\n\t}\n\n\treturn { detected: false, method: null };\n}\n","import { isAIAgent } from \"./detection\";\nimport type { DetectionResult, MinimalRequest } from \"./types\";\n\nconst DEFAULT_MARKDOWN_TYPES = [\"text/markdown\", \"text/x-markdown\"];\n\nexport interface AcceptMarkdownOptions {\n\tmediaTypes?: string[];\n}\n\n/**\n * Check if the request prefers markdown via the Accept header.\n */\nexport function acceptsMarkdown(request: MinimalRequest, options?: AcceptMarkdownOptions): boolean {\n\tconst accept = request.headers.get(\"accept\");\n\tif (!accept) return false;\n\n\tconst types = options?.mediaTypes ?? DEFAULT_MARKDOWN_TYPES;\n\tconst lowerAccept = accept.toLowerCase();\n\treturn types.some((type) => lowerAccept.includes(type));\n}\n\nexport interface ShouldServeMarkdownResult {\n\tserve: boolean;\n\treason: \"agent\" | \"accept-header\" | null;\n\tdetection: DetectionResult;\n}\n\n/**\n * Combines agent detection and content negotiation into one call.\n * Returns whether to serve markdown and why.\n */\nexport function shouldServeMarkdown(\n\trequest: MinimalRequest,\n\toptions?: AcceptMarkdownOptions,\n): ShouldServeMarkdownResult {\n\tconst detection = isAIAgent(request);\n\tif (detection.detected) {\n\t\treturn { serve: true, reason: \"agent\", detection };\n\t}\n\n\tif (acceptsMarkdown(request, options)) {\n\t\treturn { serve: true, reason: \"accept-header\", detection };\n\t}\n\n\treturn { serve: false, reason: null, detection };\n}\n"],"mappings":"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","names":[]}

package/dist/sveltekit/index.cjs

@@ -0,0 +1,178 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sveltekit/index.ts
+var sveltekit_exports = {};
+__export(sveltekit_exports, {
+  handleAgentReadability: () => handleAgentReadability
+});
+module.exports = __toCommonJS(sveltekit_exports);
+
+// src/patterns.ts
+var AI_AGENT_UA_PATTERNS = [
+  // Anthropic — https://support.claude.com/en/articles/8896518
+  "claudebot",
+  "claude-searchbot",
+  "claude-user",
+  "anthropic-ai",
+  "claude-web",
+  // OpenAI — https://platform.openai.com/docs/bots
+  "chatgpt",
+  "gptbot",
+  "oai-searchbot",
+  "openai",
+  // Google AI
+  "gemini",
+  "bard",
+  "google-cloudvertexbot",
+  "google-extended",
+  // Meta
+  "meta-externalagent",
+  "meta-externalfetcher",
+  "meta-webindexer",
+  // Search/Research AI
+  "perplexity",
+  "youbot",
+  "you.com",
+  "deepseekbot",
+  // Coding assistants
+  "cursor",
+  "github-copilot",
+  "codeium",
+  "tabnine",
+  "sourcegraph",
+  // Other AI agents / data scrapers
+  "cohere-ai",
+  "bytespider",
+  "amazonbot",
+  "ai2bot",
+  "diffbot",
+  "omgili",
+  "omgilibot"
+];
+var SIGNATURE_AGENT_DOMAINS = ["chatgpt.com"];
+var TRADITIONAL_BOT_PATTERNS = [
+  "googlebot",
+  "bingbot",
+  "yandexbot",
+  "baiduspider",
+  "duckduckbot",
+  "slurp",
+  "msnbot",
+  "facebot",
+  "twitterbot",
+  "linkedinbot",
+  "whatsapp",
+  "telegrambot",
+  "pingdom",
+  "uptimerobot",
+  "newrelic",
+  "datadog",
+  "statuspage",
+  "site24x7",
+  "applebot"
+];
+var BOT_LIKE_REGEX = /bot|agent|fetch|crawl|spider|search/i;
+
+// src/detection.ts
+function isAIAgent(request) {
+  const userAgent = request.headers.get("user-agent");
+  const lowerUA = userAgent?.toLowerCase() ?? "";
+  if (lowerUA && AI_AGENT_UA_PATTERNS.some((pattern) => lowerUA.includes(pattern))) {
+    return { detected: true, method: "ua-match" };
+  }
+  const signatureAgent = request.headers.get("signature-agent");
+  if (signatureAgent) {
+    const lowerSig = signatureAgent.toLowerCase();
+    if (SIGNATURE_AGENT_DOMAINS.some((domain) => lowerSig.includes(domain))) {
+      return { detected: true, method: "signature-agent" };
+    }
+  }
+  const secFetchMode = request.headers.get("sec-fetch-mode");
+  if (!secFetchMode && lowerUA && BOT_LIKE_REGEX.test(lowerUA)) {
+    const isTraditionalBot = TRADITIONAL_BOT_PATTERNS.some((pattern) => lowerUA.includes(pattern));
+    if (!isTraditionalBot) {
+      return { detected: true, method: "heuristic" };
+    }
+  }
+  return { detected: false, method: null };
+}
+
+// src/negotiation.ts
+var DEFAULT_MARKDOWN_TYPES = ["text/markdown", "text/x-markdown"];
+function acceptsMarkdown(request, options) {
+  const accept = request.headers.get("accept");
+  if (!accept) return false;
+  const types = options?.mediaTypes ?? DEFAULT_MARKDOWN_TYPES;
+  const lowerAccept = accept.toLowerCase();
+  return types.some((type) => lowerAccept.includes(type));
+}
+function shouldServeMarkdown(request, options) {
+  const detection = isAIAgent(request);
+  if (detection.detected) {
+    return { serve: true, reason: "agent", detection };
+  }
+  if (acceptsMarkdown(request, options)) {
+    return { serve: true, reason: "accept-header", detection };
+  }
+  return { serve: false, reason: null, detection };
+}
+
+// src/sveltekit/index.ts
+function handleAgentReadability(options) {
+  return async ({ event, resolve }) => {
+    const { pathname } = event.url;
+    const prefix = options.docsPrefix ?? "/docs";
+    if (!pathname.startsWith(prefix) || event.isDataRequest || event.isSubRequest) {
+      return resolve(event);
+    }
+    const { serve, detection } = shouldServeMarkdown(event.request);
+    if (!serve) return resolve(event);
+    if (options.onDetection) {
+      try {
+        const method = detection.detected ? detection.method : "accept-header";
+        const p = options.onDetection({
+          path: pathname,
+          method,
+          userAgent: event.request.headers.get("user-agent")
+        });
+        if (p instanceof Promise) p.catch(() => {
+        });
+      } catch {
+      }
+    }
+    const response = await event.fetch(options.rewrite(pathname));
+    if (!response.ok) return resolve(event);
+    const headers = new Headers(response.headers);
+    const varyTokens = (headers.get("vary") ?? "").toLowerCase().split(/\s*,\s*/);
+    if (!varyTokens.includes("accept")) {
+      headers.append("vary", "Accept");
+    }
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  handleAgentReadability
+});
+//# sourceMappingURL=index.cjs.map

package/dist/sveltekit/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sveltekit/index.ts","../../src/patterns.ts","../../src/detection.ts","../../src/negotiation.ts"],"sourcesContent":["import type { Handle } from \"@sveltejs/kit\";\nimport { shouldServeMarkdown } from \"../negotiation\";\nimport type { OnDetectionCallback } from \"../types\";\n\nexport interface SvelteKitAgentReadabilityOptions {\n\t/** URL prefix to intercept. Default: '/docs' */\n\tdocsPrefix?: string;\n\t/** Maps request path to internal +server.ts route returning markdown */\n\trewrite: (pathname: string) => string;\n\t/** Fire-and-forget callback for analytics/logging. */\n\tonDetection?: OnDetectionCallback;\n}\n\n/**\n * SvelteKit handle hook that detects AI agents and rewrites to markdown routes.\n *\n * ```ts\n * // hooks.server.ts\n * import { handleAgentReadability } from '@vercel/agent-readability/sveltekit'\n * import { sequence } from '@sveltejs/kit/hooks'\n *\n * export const handle = sequence(\n *   handleAgentReadability({ rewrite: (p) => `/api/docs-md${p}` }),\n *   // other handles...\n * )\n * ```\n */\nexport function handleAgentReadability(options: SvelteKitAgentReadabilityOptions): Handle {\n\treturn async ({ event, resolve }) => {\n\t\tconst { pathname } = event.url;\n\t\tconst prefix = options.docsPrefix ?? \"/docs\";\n\n\t\t// Skip: outside prefix, data requests (__data.json), sub-requests (prevent loop)\n\t\tif (!pathname.startsWith(prefix) || event.isDataRequest || event.isSubRequest) {\n\t\t\treturn resolve(event);\n\t\t}\n\n\t\tconst { serve, detection } = shouldServeMarkdown(event.request);\n\t\tif (!serve) return resolve(event);\n\n\t\t// Fire-and-forget — never block the response\n\t\tif (options.onDetection) {\n\t\t\ttry {\n\t\t\t\tconst method = detection.detected ? detection.method : \"accept-header\";\n\t\t\t\tconst p = options.onDetection({\n\t\t\t\t\tpath: pathname,\n\t\t\t\t\tmethod,\n\t\t\t\t\tuserAgent: event.request.headers.get(\"user-agent\"),\n\t\t\t\t});\n\t\t\t\tif (p instanceof Promise) p.catch(() => {});\n\t\t\t} catch {\n\t\t\t\t/* swallow sync errors */\n\t\t\t}\n\t\t}\n\n\t\t// Internal fetch — zero network hop via SvelteKit's event.fetch\n\t\tconst response = await event.fetch(options.rewrite(pathname));\n\t\tif (!response.ok) return resolve(event);\n\n\t\t// Ensure Vary: Accept for correct CDN caching (token match, not substring)\n\t\tconst headers = new Headers(response.headers);\n\t\tconst varyTokens = (headers.get(\"vary\") ?? \"\").toLowerCase().split(/\\s*,\\s*/);\n\t\tif (!varyTokens.includes(\"accept\")) {\n\t\t\theaders.append(\"vary\", \"Accept\");\n\t\t}\n\n\t\treturn new Response(response.body, {\n\t\t\tstatus: response.status,\n\t\t\tstatusText: response.statusText,\n\t\t\theaders,\n\t\t});\n\t};\n}\n","/**\n * Layer 1: Known AI agent UA substrings (lowercase).\n * Curated from https://bots.fyi/?tags=ai_assistant + official vendor docs.\n * Last reviewed: 2026-03-20\n */\nexport const AI_AGENT_UA_PATTERNS: readonly string[] = [\n\t// Anthropic — https://support.claude.com/en/articles/8896518\n\t\"claudebot\",\n\t\"claude-searchbot\",\n\t\"claude-user\",\n\t\"anthropic-ai\",\n\t\"claude-web\",\n\n\t// OpenAI — https://platform.openai.com/docs/bots\n\t\"chatgpt\",\n\t\"gptbot\",\n\t\"oai-searchbot\",\n\t\"openai\",\n\n\t// Google AI\n\t\"gemini\",\n\t\"bard\",\n\t\"google-cloudvertexbot\",\n\t\"google-extended\",\n\n\t// Meta\n\t\"meta-externalagent\",\n\t\"meta-externalfetcher\",\n\t\"meta-webindexer\",\n\n\t// Search/Research AI\n\t\"perplexity\",\n\t\"youbot\",\n\t\"you.com\",\n\t\"deepseekbot\",\n\n\t// Coding assistants\n\t\"cursor\",\n\t\"github-copilot\",\n\t\"codeium\",\n\t\"tabnine\",\n\t\"sourcegraph\",\n\n\t// Other AI agents / data scrapers\n\t\"cohere-ai\",\n\t\"bytespider\",\n\t\"amazonbot\",\n\t\"ai2bot\",\n\t\"diffbot\",\n\t\"omgili\",\n\t\"omgilibot\",\n];\n\n/**\n * Layer 2: Known AI service URLs in Signature-Agent header (RFC 9421).\n */\nexport const SIGNATURE_AGENT_DOMAINS: readonly string[] = [\"chatgpt.com\"];\n\n/**\n * Layer 3: Traditional bot exclusion list. Bots that should NOT trigger the\n * heuristic layer (search engine crawlers, social previews, monitoring tools).\n */\nexport const TRADITIONAL_BOT_PATTERNS: readonly string[] = [\n\t\"googlebot\",\n\t\"bingbot\",\n\t\"yandexbot\",\n\t\"baiduspider\",\n\t\"duckduckbot\",\n\t\"slurp\",\n\t\"msnbot\",\n\t\"facebot\",\n\t\"twitterbot\",\n\t\"linkedinbot\",\n\t\"whatsapp\",\n\t\"telegrambot\",\n\t\"pingdom\",\n\t\"uptimerobot\",\n\t\"newrelic\",\n\t\"datadog\",\n\t\"statuspage\",\n\t\"site24x7\",\n\t\"applebot\",\n];\n\n/**\n * Broad regex for bot-like UA strings (used only in Layer 3 heuristic).\n * No word boundaries — keywords commonly appear in compound names.\n */\nexport const BOT_LIKE_REGEX: RegExp = /bot|agent|fetch|crawl|spider|search/i;\n","import {\n\tAI_AGENT_UA_PATTERNS,\n\tBOT_LIKE_REGEX,\n\tSIGNATURE_AGENT_DOMAINS,\n\tTRADITIONAL_BOT_PATTERNS,\n} from \"./patterns\";\nimport type { DetectionResult, MinimalRequest } from \"./types\";\n\n/**\n * Detects AI agents from HTTP request headers.\n *\n * Three detection layers (checked in order):\n * 1. Known UA patterns (definitive)\n * 2. Signature-Agent header (definitive, RFC 9421)\n * 3. Missing sec-fetch-mode heuristic (catches unknown bots)\n *\n * Optimizes for recall over precision: serving markdown to a non-AI bot\n * is low-harm; missing an AI agent means a worse experience.\n */\nexport function isAIAgent(request: MinimalRequest): DetectionResult {\n\tconst userAgent = request.headers.get(\"user-agent\");\n\tconst lowerUA = userAgent?.toLowerCase() ?? \"\";\n\n\t// Layer 1: Known UA pattern match\n\tif (lowerUA && AI_AGENT_UA_PATTERNS.some((pattern) => lowerUA.includes(pattern))) {\n\t\treturn { detected: true, method: \"ua-match\" };\n\t}\n\n\t// Layer 2: Signature-Agent header (RFC 9421, used by ChatGPT agent)\n\tconst signatureAgent = request.headers.get(\"signature-agent\");\n\tif (signatureAgent) {\n\t\tconst lowerSig = signatureAgent.toLowerCase();\n\t\tif (SIGNATURE_AGENT_DOMAINS.some((domain) => lowerSig.includes(domain))) {\n\t\t\treturn { detected: true, method: \"signature-agent\" };\n\t\t}\n\t}\n\n\t// Layer 3: Missing browser fingerprint heuristic\n\t// Real browsers (Chrome 76+, Firefox 90+, Safari 16.4+) send sec-fetch-mode\n\t// on navigation requests. Its absence signals a programmatic client.\n\tconst secFetchMode = request.headers.get(\"sec-fetch-mode\");\n\tif (!secFetchMode && lowerUA && BOT_LIKE_REGEX.test(lowerUA)) {\n\t\tconst isTraditionalBot = TRADITIONAL_BOT_PATTERNS.some((pattern) => lowerUA.includes(pattern));\n\t\tif (!isTraditionalBot) {\n\t\t\treturn { detected: true, method: \"heuristic\" };\n\t\t}\n\t}\n\n\treturn { detected: false, method: null };\n}\n","import { isAIAgent } from \"./detection\";\nimport type { DetectionResult, MinimalRequest } from \"./types\";\n\nconst DEFAULT_MARKDOWN_TYPES = [\"text/markdown\", \"text/x-markdown\"];\n\nexport interface AcceptMarkdownOptions {\n\tmediaTypes?: string[];\n}\n\n/**\n * Check if the request prefers markdown via the Accept header.\n */\nexport function acceptsMarkdown(request: MinimalRequest, options?: AcceptMarkdownOptions): boolean {\n\tconst accept = request.headers.get(\"accept\");\n\tif (!accept) return false;\n\n\tconst types = options?.mediaTypes ?? DEFAULT_MARKDOWN_TYPES;\n\tconst lowerAccept = accept.toLowerCase();\n\treturn types.some((type) => lowerAccept.includes(type));\n}\n\nexport interface ShouldServeMarkdownResult {\n\tserve: boolean;\n\treason: \"agent\" | \"accept-header\" | null;\n\tdetection: DetectionResult;\n}\n\n/**\n * Combines agent detection and content negotiation into one call.\n * Returns whether to serve markdown and why.\n */\nexport function shouldServeMarkdown(\n\trequest: MinimalRequest,\n\toptions?: AcceptMarkdownOptions,\n): ShouldServeMarkdownResult {\n\tconst detection = isAIAgent(request);\n\tif (detection.detected) {\n\t\treturn { serve: true, reason: \"agent\", detection };\n\t}\n\n\tif (acceptsMarkdown(request, options)) {\n\t\treturn { serve: true, reason: \"accept-header\", detection };\n\t}\n\n\treturn { serve: false, reason: null, detection };\n}\n"],"mappings":"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","names":[]}