@farming-labs/docs 0.2.40 → 0.2.42

package/dist/{sitemap-server-PLcNxmtk.mjs → sitemap-server-xEHtDUDB.mjs}

@@ -1,5 +1,4 @@
-import { F as emitDocsAnalyticsEvent } from "./search-BuOU4idW.mjs";
-import { kt as resolveDocsSitemapConfig } from "./agent-B6szuz_8.mjs";
+import { kt as resolveDocsSitemapConfig } from "./agent-CaOBIVFy.mjs";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import path, { basename, join, relative } from "node:path";
@@ -959,385 +958,6 @@ function humanizeSegment(value) {
 	return value.replace(/^\{/, "").replace(/\}$/, "").replace(/^\[\[?\.{3}/, "").replace(/^\[/, "").replace(/\]\]?$/, "").replace(/^\$/, "").replace(/-/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
 }
 
-//#endregion
-//#region src/cloud-ask-ai.ts
-const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://api.farming-labs.dev";
-const DEFAULT_DOCS_CLOUD_API_KEY_ENV = "DOCS_CLOUD_API_KEY";
-const DOCS_CLOUD_PROJECT_ID_ENVS = [
-	"PUBLIC_DOCS_CLOUD_PROJECT_ID",
-	"DOCS_CLOUD_PROJECT_ID",
-	"NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID"
-];
-const DOCS_CLOUD_API_BASE_URL_ENVS = [
-	"DOCS_CLOUD_API_BASE_URL",
-	"DOCS_CLOUD_API_URL",
-	"PUBLIC_DOCS_CLOUD_URL",
-	"NEXT_PUBLIC_DOCS_CLOUD_URL"
-];
-const DOCS_CLOUD_FOOTER_GUARD_CHARS = 256;
-const docsCloudRelevantDocsPattern = /\n{2,}(?:-{3,}|\*{3,}|_{3,})[ \t]*\n{1,3}(?:#{1,6}[ \t]+)?(?:\*\*)?Relevant docs(?:\*\*)?[ \t]*/i;
-const docsCloudThematicBreakPattern = /^[ \t]*(?:-{3,}|\*{3,}|_{3,})[ \t]*$/gm;
-function isPlainObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function readEnv(name, env) {
-	const trimmed = (env?.[name] ?? (typeof process !== "undefined" ? process.env?.[name] : void 0))?.trim();
-	return trimmed ? trimmed : void 0;
-}
-function readFirstEnv(names, env) {
-	for (const name of names) {
-		const value = readEnv(name, env);
-		if (value) return value;
-	}
-}
-function resolveDocsCloudApiBaseUrl(env) {
-	return (readFirstEnv(DOCS_CLOUD_API_BASE_URL_ENVS, env) ?? DEFAULT_DOCS_CLOUD_API_BASE_URL).replace(/\/+$/, "");
-}
-function resolveDocsCloudProjectId(env) {
-	return readFirstEnv(DOCS_CLOUD_PROJECT_ID_ENVS, env);
-}
-function resolveDocsCloudApiKey(cloudConfig, env) {
-	const envName = cloudConfig?.apiKey?.env?.trim() || DEFAULT_DOCS_CLOUD_API_KEY_ENV;
-	return {
-		envName,
-		apiKey: readEnv(envName, env)
-	};
-}
-function jsonError(message, status) {
-	return Response.json({ error: message }, { status });
-}
-function textFromMessageContent(content) {
-	if (typeof content === "string") return content;
-	if (!Array.isArray(content)) return "";
-	return content.map((part) => {
-		if (typeof part === "string") return part;
-		if (!isPlainObject(part)) return "";
-		if (typeof part.text === "string") return part.text;
-		if (typeof part.content === "string") return part.content;
-		return "";
-	}).filter(Boolean).join("\n");
-}
-function lastUserQuestion(messages) {
-	if (!Array.isArray(messages)) return "";
-	return textFromMessageContent([...messages].reverse().find((message) => message?.role === "user")?.content).trim();
-}
-function resolveQuestion(body) {
-	return typeof body.question === "string" && body.question.trim() ? body.question.trim() : lastUserQuestion(body.messages);
-}
-function shouldStreamResponse(request, body, aiConfig) {
-	if (typeof body.stream === "boolean") return body.stream;
-	if (aiConfig?.stream === false) return false;
-	const accept = request.headers.get("accept")?.toLowerCase();
-	return !accept || accept.includes("text/event-stream") || accept.includes("*/*");
-}
-function stripRelevantDocsFooter(content) {
-	return content.replace(new RegExp(`${docsCloudRelevantDocsPattern.source}[\\s\\S]*$`, "i"), "").trimEnd();
-}
-function stripMarkdownThematicBreaks(content) {
-	return content.replace(docsCloudThematicBreakPattern, "").replace(/\n{3,}/g, "\n\n").trimEnd();
-}
-function cleanDocsCloudAnswer(content) {
-	return stripMarkdownThematicBreaks(stripRelevantDocsFooter(content));
-}
-function safeDocsCloudContent(content, final = false) {
-	const footerStart = content.search(docsCloudRelevantDocsPattern);
-	if (footerStart >= 0) return stripMarkdownThematicBreaks(content.slice(0, footerStart));
-	if (final) return cleanDocsCloudAnswer(content);
-	return stripMarkdownThematicBreaks(content.slice(0, Math.max(0, content.length - DOCS_CLOUD_FOOTER_GUARD_CHARS)));
-}
-function createOpenAICompatibleSseChunk(content) {
-	return `data: ${JSON.stringify({ choices: [{ delta: { content } }] })}\n\n`;
-}
-function createOpenAICompatibleSseResponse(content) {
-	const encoder = new TextEncoder();
-	const stream = new ReadableStream({ start(controller) {
-		if (content) controller.enqueue(encoder.encode(createOpenAICompatibleSseChunk(content)));
-		controller.enqueue(encoder.encode("data: [DONE]\n\n"));
-		controller.close();
-	} });
-	return new Response(stream, { headers: {
-		"Content-Type": "text/event-stream",
-		"Cache-Control": "no-cache, no-transform",
-		Connection: "keep-alive"
-	} });
-}
-function openAICompatibleDeltaContent(value) {
-	if (!isPlainObject(value)) return void 0;
-	const firstChoice = Array.isArray(value.choices) ? value.choices[0] : void 0;
-	if (!isPlainObject(firstChoice) || !isPlainObject(firstChoice.delta)) return void 0;
-	return typeof firstChoice.delta.content === "string" ? firstChoice.delta.content : void 0;
-}
-function docsCloudStreamContent(value) {
-	if (typeof value === "string") return value;
-	if (!isPlainObject(value)) return void 0;
-	for (const key of [
-		"content",
-		"text",
-		"answer",
-		"delta"
-	]) {
-		const content = value[key];
-		if (typeof content === "string") return content;
-	}
-}
-function docsCloudAnswerFromPayload(payload) {
-	if (!isPlainObject(payload)) return "";
-	for (const key of [
-		"answer",
-		"text",
-		"content"
-	]) {
-		const content = payload[key];
-		if (typeof content === "string") return content;
-	}
-	return "";
-}
-function createCleanDocsCloudSseResponse(upstream) {
-	if (!upstream.ok || !upstream.body) return new Response(upstream.body, {
-		status: upstream.status,
-		statusText: upstream.statusText,
-		headers: {
-			"Content-Type": upstream.headers.get("Content-Type") ?? "text/event-stream",
-			"Cache-Control": upstream.headers.get("Cache-Control") ?? "no-cache, no-transform",
-			Connection: upstream.headers.get("Connection") ?? "keep-alive"
-		}
-	});
-	const decoder = new TextDecoder();
-	const encoder = new TextEncoder();
-	const stream = new ReadableStream({ async start(controller) {
-		const reader = upstream.body.getReader();
-		let buffer = "";
-		let content = "";
-		let emittedLength = 0;
-		const enqueue = (chunk) => {
-			controller.enqueue(encoder.encode(chunk));
-		};
-		const emitSafeContent = (final = false) => {
-			const safeContent = safeDocsCloudContent(content, final);
-			if (safeContent.length <= emittedLength) return;
-			enqueue(createOpenAICompatibleSseChunk(safeContent.slice(emittedLength)));
-			emittedLength = safeContent.length;
-		};
-		const flushEvent = (event) => {
-			const data = event.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).filter(Boolean).join("\n").trim();
-			if (!data) return;
-			if (data === "[DONE]") return;
-			try {
-				const parsed = JSON.parse(data);
-				const delta = openAICompatibleDeltaContent(parsed) ?? docsCloudStreamContent(parsed);
-				if (delta) {
-					content += delta;
-					emitSafeContent();
-				}
-			} catch {
-				content += data;
-				emitSafeContent();
-			}
-		};
-		try {
-			while (true) {
-				const { value, done } = await reader.read();
-				if (done) break;
-				buffer += decoder.decode(value, { stream: true });
-				const events = buffer.split(/\r?\n\r?\n/);
-				buffer = events.pop() ?? "";
-				for (const event of events) flushEvent(event);
-			}
-			buffer += decoder.decode();
-			if (buffer.trim()) flushEvent(buffer);
-		} catch {}
-		emitSafeContent(true);
-		enqueue("data: [DONE]\n\n");
-		controller.close();
-	} });
-	return new Response(stream, {
-		status: upstream.status,
-		statusText: upstream.statusText,
-		headers: {
-			"Content-Type": "text/event-stream",
-			"Cache-Control": upstream.headers.get("Cache-Control") ?? "no-cache, no-transform",
-			Connection: upstream.headers.get("Connection") ?? "keep-alive"
-		}
-	});
-}
-function analyticsProperties(request) {
-	const userAgent = request.headers.get("user-agent")?.trim();
-	return userAgent ? { userAgent } : {};
-}
-function isDocsCloudAskAIProvider(config) {
-	return config?.enabled === true && config.provider === "docs-cloud";
-}
-async function createDocsCloudAskAIResponse(request, options = {}) {
-	const config = options.config;
-	const aiConfig = config?.ai;
-	const analytics = config?.analytics;
-	const requestUrl = new URL(request.url);
-	const requestStartedAt = Date.now();
-	const requestProperties = analyticsProperties(request);
-	let body;
-	try {
-		body = await request.json();
-	} catch {
-		await emitDocsAnalyticsEvent(analytics, {
-			type: "api_ai_error",
-			source: "server",
-			url: request.url,
-			path: requestUrl.pathname,
-			locale: options.locale,
-			properties: {
-				...requestProperties,
-				reason: "invalid_json",
-				provider: "docs-cloud",
-				durationMs: Math.max(0, Date.now() - requestStartedAt)
-			}
-		});
-		return jsonError("Invalid JSON body. Expected { messages: [...] }.", 400);
-	}
-	const question = resolveQuestion(body);
-	const messages = Array.isArray(body.messages) ? body.messages : void 0;
-	if (!question) {
-		await emitDocsAnalyticsEvent(analytics, {
-			type: "api_ai_error",
-			source: "server",
-			url: request.url,
-			path: requestUrl.pathname,
-			locale: options.locale,
-			properties: {
-				...requestProperties,
-				reason: "missing_user_message",
-				provider: "docs-cloud",
-				durationMs: Math.max(0, Date.now() - requestStartedAt)
-			}
-		});
-		return jsonError("At least one user message is required.", 400);
-	}
-	const projectId = resolveDocsCloudProjectId(options.env);
-	const { envName, apiKey } = resolveDocsCloudApiKey(config?.cloud, options.env);
-	if (!projectId || !apiKey) {
-		const reason = !projectId ? "missing_docs_cloud_project_id" : "missing_docs_cloud_api_key";
-		await emitDocsAnalyticsEvent(analytics, {
-			type: "api_ai_error",
-			source: "server",
-			url: request.url,
-			path: requestUrl.pathname,
-			locale: options.locale,
-			input: { question },
-			properties: {
-				...requestProperties,
-				reason,
-				provider: "docs-cloud",
-				envName: !apiKey ? envName : void 0,
-				durationMs: Math.max(0, Date.now() - requestStartedAt)
-			}
-		});
-		return jsonError(!projectId ? `Docs Cloud Ask AI is missing ${DOCS_CLOUD_PROJECT_ID_ENVS.join(" or ")}. Add the project id to the deployment environment.` : `Docs Cloud Ask AI is missing ${envName}. Add it to the deployment environment.`, 500);
-	}
-	const stream = shouldStreamResponse(request, body, aiConfig);
-	const apiBaseUrl = resolveDocsCloudApiBaseUrl(options.env);
-	const publicBaseUrl = aiConfig?.docsUrl ?? options.publicBaseUrl ?? requestUrl.origin;
-	const requestedModel = typeof body.model === "string" && body.model.trim() ? body.model.trim() : void 0;
-	await emitDocsAnalyticsEvent(analytics, {
-		type: "api_ai_request",
-		source: "server",
-		url: request.url,
-		path: requestUrl.pathname,
-		locale: options.locale,
-		input: { question },
-		properties: {
-			...requestProperties,
-			provider: "docs-cloud",
-			messageCount: messages?.length,
-			questionLength: question.length,
-			model: requestedModel ?? "docs-cloud"
-		}
-	});
-	let upstream;
-	try {
-		upstream = await (options.fetch ?? fetch)(`${apiBaseUrl}/v1/projects/${encodeURIComponent(projectId)}/knowledge/ask`, {
-			method: "POST",
-			headers: {
-				Accept: stream ? "text/event-stream, application/json" : "application/json",
-				Authorization: `Bearer ${apiKey}`,
-				"Content-Type": "application/json",
-				"X-Docs-Cloud-Public-Base-Url": publicBaseUrl
-			},
-			body: JSON.stringify({
-				messages,
-				question,
-				answerMode: "auto",
-				answerStyle: "public",
-				modelPreference: requestedModel,
-				stream,
-				publicBaseUrl
-			})
-		});
-	} catch {
-		await emitDocsAnalyticsEvent(analytics, {
-			type: "api_ai_error",
-			source: "server",
-			url: request.url,
-			path: requestUrl.pathname,
-			locale: options.locale,
-			input: { question },
-			properties: {
-				...requestProperties,
-				reason: "docs_cloud_fetch_error",
-				provider: "docs-cloud",
-				durationMs: Math.max(0, Date.now() - requestStartedAt)
-			}
-		});
-		return jsonError("Docs Cloud Ask AI request failed.", 502);
-	}
-	if (!upstream.ok) {
-		await upstream.text().catch(() => "");
-		await emitDocsAnalyticsEvent(analytics, {
-			type: "api_ai_error",
-			source: "server",
-			url: request.url,
-			path: requestUrl.pathname,
-			locale: options.locale,
-			input: { question },
-			properties: {
-				...requestProperties,
-				reason: "docs_cloud_error",
-				provider: "docs-cloud",
-				status: upstream.status,
-				durationMs: Math.max(0, Date.now() - requestStartedAt)
-			}
-		});
-		return jsonError(`Docs Cloud Ask AI error (${upstream.status}).`, 502);
-	}
-	await emitDocsAnalyticsEvent(analytics, {
-		type: "api_ai_response",
-		source: "server",
-		url: request.url,
-		path: requestUrl.pathname,
-		locale: options.locale,
-		input: { question },
-		properties: {
-			...requestProperties,
-			provider: "docs-cloud",
-			status: upstream.status,
-			durationMs: Math.max(0, Date.now() - requestStartedAt)
-		}
-	});
-	const contentType = upstream.headers.get("Content-Type") ?? "";
-	if (stream && contentType.includes("text/event-stream")) return createCleanDocsCloudSseResponse(upstream);
-	const upstreamBody = await upstream.text();
-	let payload;
-	let answer = upstreamBody;
-	try {
-		payload = JSON.parse(upstreamBody);
-		answer = docsCloudAnswerFromPayload(payload) || answer;
-	} catch {}
-	const cleanAnswer = cleanDocsCloudAnswer(answer);
-	if (stream) return createOpenAICompatibleSseResponse(cleanAnswer);
-	return Response.json(isPlainObject(payload) ? {
-		...payload,
-		answer: cleanAnswer
-	} : { answer: cleanAnswer });
-}
-
 //#endregion
 //#region src/prompt-utils.ts
 const require = createRequire(import.meta.url);
@@ -1513,4 +1133,4 @@ function readDocsSitemapManifest(rootDir, sitemap) {
 }
 
 //#endregion
-export { isApiReferenceOpenApiRequest as C, remarkCodeGroup as D, resolveApiReferenceRenderer as E, buildApiReferenceScalarCss as S, resolveApiReferenceOpenApiDiscovery as T, buildApiReferenceHtmlDocument as _, DEFAULT_PROMPT_PROVIDER_TEMPLATES as a, buildApiReferenceOpenApiDocumentAsync as b, resolvePromptProviderChoices as c, serializeDocsIconRegistry as d, serializeOpenDocsProvider as f, DEFAULT_API_REFERENCE_OPENAPI_ROUTE as g, isDocsCloudAskAIProvider as h, DEFAULT_OPEN_DOCS_TARGET as i, sanitizePromptText as l, createDocsCloudAskAIResponse as m, DEFAULT_OPEN_DOCS_PROMPT as n, normalizePromptProviderName as o, serializeOpenDocsProviders as p, DEFAULT_OPEN_DOCS_PROVIDER_IDS as r, parsePromptStringArray as s, readDocsSitemapManifest as t, serializeDocsIcon as u, buildApiReferenceHtmlDocumentAsync as v, resolveApiReferenceConfig as w, buildApiReferencePageTitle as x, buildApiReferenceOpenApiDocument as y };
+export { resolveApiReferenceOpenApiDiscovery as C, resolveApiReferenceConfig as S, remarkCodeGroup as T, buildApiReferenceOpenApiDocument as _, DEFAULT_PROMPT_PROVIDER_TEMPLATES as a, buildApiReferenceScalarCss as b, resolvePromptProviderChoices as c, serializeDocsIconRegistry as d, serializeOpenDocsProvider as f, buildApiReferenceHtmlDocumentAsync as g, buildApiReferenceHtmlDocument as h, DEFAULT_OPEN_DOCS_TARGET as i, sanitizePromptText as l, DEFAULT_API_REFERENCE_OPENAPI_ROUTE as m, DEFAULT_OPEN_DOCS_PROMPT as n, normalizePromptProviderName as o, serializeOpenDocsProviders as p, DEFAULT_OPEN_DOCS_PROVIDER_IDS as r, parsePromptStringArray as s, readDocsSitemapManifest as t, serializeDocsIcon as u, buildApiReferenceOpenApiDocumentAsync as v, resolveApiReferenceRenderer as w, isApiReferenceOpenApiRequest as x, buildApiReferencePageTitle as y };

package/dist/{types-DKCNILor.d.mts → types-XqGLsmOD.d.mts}

@@ -766,6 +766,12 @@ interface DocsAnalyticsConfig {
   includeInputs?: boolean;
   /** Callback fired for every emitted event. */
   onEvent?: (event: DocsAnalyticsEvent) => void | Promise<void>;
+  /**
+   * Forward events to Docs Cloud when project env vars are available.
+   *
+   * @default true
+   */
+  cloud?: boolean;
 }
 type DocsTelemetryFramework = "next" | "tanstack-start" | "sveltekit" | "astro" | "nuxt" | "mcp" | (string & {});
 type DocsTelemetryEventType = "project_detected" | "agent_surface_used" | "mcp_request" | "mcp_tool_used" | (string & {});
@@ -873,6 +879,17 @@ interface DocsCloudConfig {
   enabled?: boolean;
   /** API key lookup used by `docs deploy` and other cloud CLI commands. */
   apiKey?: DocsCloudApiKeyConfig;
+  /**
+   * Same-origin route for the generated Docs API handler.
+   *
+   * Next.js layouts use this as the default client analytics proxy when no
+   * hosted analytics endpoint env is configured. Set it when the route is
+   * mounted somewhere other than `/api/docs`, or when a deployment uses a
+   * public base path.
+   *
+   * @default "/api/docs"
+   */
+  apiRoute?: string;
   /** Legacy hosted preview deployment settings. Prefer `deploy` in new configs. */
   preview?: DocsCloudPreviewConfig;
   /** Generated docs publishing settings. */

package/dist/{upgrade-aexO-zom.mjs → upgrade-CkdKWRlk.mjs}

@@ -1,5 +1,5 @@
-import { c as fileExists, o as exec } from "./utils-CoHZJ1i4.mjs";
-import { a as getPackagesForFramework, c as resolveDocsPackageManager, i as frameworkFromPreset, l as validateUpgradeVersion, n as PRESETS, o as presetFromFramework, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework, t as PACKAGES_BY_FRAMEWORK } from "./package-version-CeNAB4NZ.mjs";
+import { c as fileExists, o as exec } from "./utils-D-xTRNuh.mjs";
+import { a as getPackagesForFramework, c as resolveDocsPackageManager, i as frameworkFromPreset, l as validateUpgradeVersion, n as PRESETS, o as presetFromFramework, r as buildDocsPackageInstallCommand, s as resolveDocsPackageFramework, t as PACKAGES_BY_FRAMEWORK } from "./package-version-DPQSBBsX.mjs";
 import path from "node:path";
 import pc from "picocolors";
 import * as p from "@clack/prompts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",
@@ -30,6 +30,16 @@
       "import": "./dist/server.mjs",
       "default": "./dist/server.mjs"
     },
+    "./cloud/server": {
+      "types": "./dist/docs-cloud-server.d.mts",
+      "import": "./dist/docs-cloud-server.mjs",
+      "default": "./dist/docs-cloud-server.mjs"
+    },
+    "./client/react": {
+      "types": "./dist/client/react.d.mts",
+      "import": "./dist/client/react.mjs",
+      "default": "./dist/client/react.mjs"
+    },
     "./mcp": {
       "types": "./dist/mcp.d.mts",
       "import": "./dist/mcp.mjs",
@@ -46,8 +56,18 @@
     "picocolors": "^1.1.1",
     "zod": "^4.3.6"
   },
+  "peerDependencies": {
+    "react": ">=19.2.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/react": "^19.2.2",
+    "react": "^19.2.0",
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8"