@farming-labs/next 0.2.40 → 0.2.42

package/dist/api.d.mts

@@ -1,8 +1,13 @@
 import { createDocsAPI as createDocsAPI$1, createDocsMCPAPI as createDocsMCPAPI$1 } from "@farming-labs/theme/api";
+import { DocsCloudRouteHandlerOptions, DocsCloudRouteHandlerOptions as DocsCloudRouteHandlerOptions$1, DocsCloudRouteHandlers, DocsCloudServer, DocsCloudServer as DocsCloudServer$1, createDocsCloudRouteHandler } from "@farming-labs/docs/cloud/server";
 
 //#region src/api.d.ts
 type DocsAPIOptions = NonNullable<Parameters<typeof createDocsAPI$1>[0]>;
 type DocsMCPAPIOptions = NonNullable<Parameters<typeof createDocsMCPAPI$1>[0]>;
+interface DocsAPICloudOptions extends DocsCloudRouteHandlerOptions$1 {
+  docsCloud?: DocsCloudServer$1;
+}
+type DocsAPICloudIntegration = DocsCloudServer$1 | DocsAPICloudOptions;
 /**
  * Resolve the app project root for a Next route module.
  *
@@ -10,7 +15,7 @@ type DocsMCPAPIOptions = NonNullable<Parameters<typeof createDocsMCPAPI$1>[0]>;
  * output (`.next/server/app/...` or custom-dist-dir `/server/app/...`).
  */
 declare function resolveNextProjectRoot(metaUrl: string): string;
-declare function createDocsAPI(options?: DocsAPIOptions): {
+declare function createDocsAPI(options?: DocsAPIOptions, cloudIntegration?: DocsAPICloudIntegration): {
   GET(request: Request): Promise<Response>;
   POST(request: Request): Promise<Response>;
 };
@@ -20,4 +25,4 @@ declare function createDocsMCPAPI(options?: DocsMCPAPIOptions): {
   DELETE(request: Request): Promise<Response>;
 };
 //#endregion
-export { createDocsAPI, createDocsMCPAPI, resolveNextProjectRoot };
+export { DocsAPICloudIntegration, DocsAPICloudOptions, type DocsCloudRouteHandlerOptions, type DocsCloudRouteHandlers, type DocsCloudServer, createDocsAPI, createDocsCloudRouteHandler, createDocsMCPAPI, resolveNextProjectRoot };

package/dist/api.mjs

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createDocsAPI as createDocsAPI$1, createDocsMCPAPI as createDocsMCPAPI$1 } from "@farming-labs/theme/api";
+import { createDocsCloudRouteHandler } from "@farming-labs/docs/cloud/server";
 
 //#region src/api.ts
 /**
@@ -47,12 +48,87 @@ function inferNextProjectRootFromCaller() {
 		Error.prepareStackTrace = previousPrepareStackTrace;
 	}
 }
-function createDocsAPI(options = {}) {
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeAction(value) {
+	return value?.trim().toLowerCase().replace(/_/g, "-") || void 0;
+}
+function isDocsCloudServer(value) {
+	return isRecord(value) && typeof value.handleRequest === "function";
+}
+function resolveDocsCloudIntegration(integration) {
+	if (!integration) return void 0;
+	if (isDocsCloudServer(integration)) return {
+		docsCloud: integration,
+		routeOptions: {}
+	};
+	if (!integration.docsCloud) return void 0;
+	return {
+		docsCloud: integration.docsCloud,
+		routeOptions: {
+			locale: integration.locale,
+			publicBaseUrl: integration.publicBaseUrl
+		}
+	};
+}
+function isDocsCloudGetRequest(request) {
+	const url = new URL(request.url);
+	const cloud = normalizeAction(url.searchParams.get("cloud"));
+	const action = normalizeAction(url.searchParams.get("action"));
+	const format = normalizeAction(url.searchParams.get("format"));
+	return cloud === "config" || cloud === "public-config" || action === "cloud-config" || action === "docs-cloud-config" || format === "cloud-config" || format === "docs-cloud-config";
+}
+function isDocsCloudAction(action) {
+	return Boolean(action && [
+		"analytics",
+		"track",
+		"track-event",
+		"event",
+		"ask-ai",
+		"ai",
+		"chat",
+		"docs-cloud"
+	].includes(action));
+}
+async function readJson(request) {
+	try {
+		return await request.clone().json();
+	} catch {
+		return;
+	}
+}
+async function isDocsCloudPostRequest(request) {
+	const url = new URL(request.url);
+	const cloud = normalizeAction(url.searchParams.get("cloud"));
+	const action = normalizeAction(url.searchParams.get("action"));
+	if (isDocsCloudAction(cloud) || isDocsCloudAction(action)) return true;
+	const body = await readJson(request);
+	if (!isRecord(body)) return false;
+	if (isDocsCloudAction(normalizeAction(typeof body.action === "string" ? body.action : void 0))) return true;
+	if (typeof body.type === "string") return true;
+	if (isRecord(body.event) && typeof body.event.type === "string") return true;
+	if (isRecord(body.payload) && typeof body.payload.type === "string") return true;
+	return false;
+}
+function createDocsAPI(options = {}, cloudIntegration) {
 	const rootDir = options.rootDir ?? inferNextProjectRootFromCaller();
-	return createDocsAPI$1(rootDir ? {
+	const handlers = createDocsAPI$1(rootDir ? {
 		...options,
 		rootDir
 	} : options);
+	const integration = resolveDocsCloudIntegration(cloudIntegration);
+	if (!integration) return handlers;
+	return {
+		GET(request) {
+			if (isDocsCloudGetRequest(request)) return integration.docsCloud.handleRequest(request, integration.routeOptions);
+			return handlers.GET(request);
+		},
+		async POST(request) {
+			if (await isDocsCloudPostRequest(request)) return integration.docsCloud.handleRequest(request, integration.routeOptions);
+			return handlers.POST(request);
+		}
+	};
 }
 function createDocsMCPAPI(options = {}) {
 	const rootDir = options.rootDir ?? inferNextProjectRootFromCaller();
@@ -63,4 +139,4 @@ function createDocsMCPAPI(options = {}) {
 }
 
 //#endregion
-export { createDocsAPI, createDocsMCPAPI, resolveNextProjectRoot };
+export { createDocsAPI, createDocsCloudRouteHandler, createDocsMCPAPI, resolveNextProjectRoot };

package/dist/client-callbacks.d.mts

@@ -3,6 +3,7 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
 //#region src/client-callbacks.d.ts
 declare function DocsClientCallbacks(props?: {
   apiReferencePrimaryServerUrl?: string;
+  docsCloudEnabled?: boolean;
 }): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { DocsClientCallbacks as default };

package/dist/client-callbacks.mjs

@@ -31,14 +31,32 @@ function DocsClientCallbacks(props) {
 			timers.forEach((timer) => window.clearTimeout(timer));
 		};
 	}, [props?.apiReferencePrimaryServerUrl]);
+	const analytics = resolveDocsClientAnalytics(docsConfig.analytics, props?.docsCloudEnabled);
 	return /* @__PURE__ */ jsx(DocsClientHooks, {
 		onCopyClick: docsConfig.onCopyClick,
-		analytics: docsConfig.analytics,
+		analytics,
 		onFeedback: docsConfig.feedback && typeof docsConfig.feedback === "object" ? docsConfig.feedback.onFeedback : void 0,
 		onAIFeedback: docsConfig.ai?.feedback && typeof docsConfig.ai.feedback === "object" ? docsConfig.ai.feedback.onFeedback : void 0,
 		onAIActions: docsConfig.ai?.onActions
 	});
 }
+function resolveDocsClientAnalytics(analytics, docsCloudEnabled) {
+	if (!docsCloudEnabled) return analytics;
+	if (analytics === true) return {
+		enabled: true,
+		console: true,
+		cloud: false
+	};
+	if (analytics && typeof analytics === "object") return {
+		...analytics,
+		cloud: false
+	};
+	return {
+		enabled: true,
+		console: false,
+		cloud: false
+	};
+}
 
 //#endregion
 export { DocsClientCallbacks as default };

package/dist/config.mjs

@@ -79,8 +79,13 @@ const DOCS_API_ROUTE_TEMPLATE = `\
 ${GENERATED_BANNER}
 import docsConfig from "@/docs.config";
 import { createDocsAPI } from "@farming-labs/next/api";
+import { createDocsCloudServer } from "@farming-labs/docs/cloud/server";
 
-export const { GET, POST } = createDocsAPI(docsConfig);
+const docsCloud = createDocsCloudServer({
+  config: docsConfig,
+});
+
+export const { GET, POST } = createDocsAPI(docsConfig, docsCloud);
 
 export const revalidate = false;
 `;
@@ -139,7 +144,6 @@ const FILE_EXTS = [
 	"js"
 ];
 const INTERNAL_DOCS_CONFIG_ALIAS = "@farming-labs/next-internal-docs-config";
-const DEFAULT_DOCS_CLOUD_ANALYTICS_ENDPOINT = "https://api.farming-labs.dev/v1/analytics/events";
 const NEXT_PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const DEFAULT_AGENT_SPEC_ROUTE = "/api/docs/agent/spec";
 const DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE = "/.well-known/agent";
@@ -212,11 +216,11 @@ function normalizeEnvValue(value) {
 }
 function createPublicDocsCloudAnalyticsEnv() {
 	const projectId = normalizeEnvValue(process.env.NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID) ?? normalizeEnvValue(process.env.PUBLIC_DOCS_CLOUD_PROJECT_ID) ?? normalizeEnvValue(process.env.DOCS_CLOUD_PROJECT_ID);
-	const endpoint = normalizeEnvValue(process.env.NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT) ?? normalizeEnvValue(process.env.PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT) ?? normalizeEnvValue(process.env.DOCS_CLOUD_ANALYTICS_ENDPOINT) ?? (projectId ? DEFAULT_DOCS_CLOUD_ANALYTICS_ENDPOINT : void 0);
+	const configuredEndpoint = normalizeEnvValue(process.env.NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT) ?? normalizeEnvValue(process.env.PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT) ?? normalizeEnvValue(process.env.DOCS_CLOUD_ANALYTICS_ENDPOINT);
 	const enabled = normalizeEnvValue(process.env.NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED) ?? normalizeEnvValue(process.env.PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED) ?? normalizeEnvValue(process.env.DOCS_CLOUD_ANALYTICS_ENABLED);
 	const env = {};
 	if (projectId) env.NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID = projectId;
-	if (endpoint) env.NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT = endpoint;
+	if (configuredEndpoint) env.NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT = configuredEndpoint;
 	if (enabled) env.NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED = enabled;
 	return env;
 }
@@ -250,6 +254,17 @@ function createDocsWorkspaceAliases(root, workspaceRoot) {
 			"src",
 			"server.ts"
 		]),
+		"@farming-labs/docs/cloud/server": workspaceEntrypoint([
+			"packages",
+			"docs",
+			"dist",
+			"docs-cloud-server.mjs"
+		], [
+			"packages",
+			"docs",
+			"src",
+			"docs-cloud-server.ts"
+		]),
 		"@farming-labs/next": workspaceEntrypoint([
 			"packages",
 			"next",
@@ -1830,6 +1845,7 @@ function withDocs(nextConfig = {}) {
 		if (workspaceRoot) Object.assign(resolvedConfig.resolve.alias, {
 			"@farming-labs/docs$": join(workspaceRoot, "packages", "docs", "dist", "index.mjs"),
 			"@farming-labs/docs/server": join(workspaceRoot, "packages", "docs", "dist", "server.mjs"),
+			"@farming-labs/docs/cloud/server": join(workspaceRoot, "packages", "docs", "dist", "docs-cloud-server.mjs"),
 			"@farming-labs/next$": join(workspaceRoot, "packages", "next", "dist", "index.mjs"),
 			"@farming-labs/next/api": join(workspaceRoot, "packages", "next", "dist", "api.mjs"),
 			"@farming-labs/next/changelog": join(workspaceRoot, "packages", "next", "dist", "changelog.mjs"),

package/dist/layout.mjs

@@ -3,8 +3,75 @@ import { withNextApiReferenceBanner } from "./api-reference.mjs";
 import { emitDocsTelemetryProjectEvent } from "@farming-labs/docs";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { createDocsLayout, createDocsMetadata } from "@farming-labs/theme";
+import { DocsCloudAnalytics } from "@farming-labs/docs/client/react";
 
 //#region src/layout.tsx
+const DOCS_CLOUD_PROJECT_ID_ENVS = [
+	"NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID",
+	"PUBLIC_DOCS_CLOUD_PROJECT_ID",
+	"DOCS_CLOUD_PROJECT_ID"
+];
+const DOCS_CLOUD_ANALYTICS_ENDPOINT_ENVS = [
+	"NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT",
+	"PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT",
+	"DOCS_CLOUD_ANALYTICS_ENDPOINT"
+];
+const DOCS_CLOUD_ANALYTICS_ROUTE_ENVS = [
+	"NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ROUTE",
+	"PUBLIC_DOCS_CLOUD_ANALYTICS_ROUTE",
+	"DOCS_CLOUD_ANALYTICS_ROUTE"
+];
+const DOCS_CLOUD_ANALYTICS_ENABLED_ENVS = [
+	"NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED",
+	"PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED",
+	"DOCS_CLOUD_ANALYTICS_ENABLED"
+];
+const DEFAULT_DOCS_CLOUD_ANALYTICS_ROUTE = "/api/docs?action=analytics";
+function normalizeEnvValue(value) {
+	const normalized = value?.trim();
+	return normalized ? normalized : void 0;
+}
+function readFirstEnv(names) {
+	for (const name of names) {
+		const value = normalizeEnvValue(process.env[name]);
+		if (value) return value;
+	}
+}
+function isFalsyEnv(value) {
+	return /^(0|false|no|off)$/i.test(value ?? "");
+}
+function withAnalyticsAction(route) {
+	try {
+		const url = new URL(route, "https://docs.local");
+		if (!url.searchParams.has("action")) url.searchParams.set("action", "analytics");
+		return route.startsWith("http://") || route.startsWith("https://") ? url.toString() : `${url.pathname}${url.search}${url.hash}`;
+	} catch {
+		const [pathAndQuery, hash = ""] = route.split("#", 2);
+		return `${pathAndQuery}${pathAndQuery.includes("?") ? "&" : "?"}action=analytics${hash ? `#${hash}` : ""}`;
+	}
+}
+function normalizeRoute(value) {
+	const normalized = normalizeEnvValue(value);
+	if (!normalized) return void 0;
+	if (normalized.startsWith("http://") || normalized.startsWith("https://")) return withAnalyticsAction(normalized);
+	return withAnalyticsAction(`/${normalized}`.replace(/\/+/g, "/"));
+}
+function resolveNextDocsCloudClientOptions(config) {
+	const analytics = config.analytics;
+	if (analytics === false || analytics && typeof analytics === "object" && (analytics.enabled === false || analytics.cloud === false)) return false;
+	if (isFalsyEnv(readFirstEnv(DOCS_CLOUD_ANALYTICS_ENABLED_ENVS))) return false;
+	const projectId = readFirstEnv(DOCS_CLOUD_PROJECT_ID_ENVS);
+	if (!projectId) return void 0;
+	const endpoint = readFirstEnv(DOCS_CLOUD_ANALYTICS_ENDPOINT_ENVS);
+	const route = normalizeRoute(readFirstEnv(DOCS_CLOUD_ANALYTICS_ROUTE_ENVS)) ?? normalizeRoute(config.cloud?.apiRoute);
+	const includeInputs = typeof analytics === "object" && analytics.includeInputs === true;
+	return {
+		projectId,
+		endpoint: endpoint ?? route ?? DEFAULT_DOCS_CLOUD_ANALYTICS_ROUTE,
+		includeInputs,
+		metadata: { framework: "next" }
+	};
+}
 function createNextDocsMetadata(config) {
 	return createDocsMetadata(config);
 }
@@ -12,7 +79,12 @@ function createNextDocsLayout(config) {
 	emitDocsTelemetryProjectEvent(config, { framework: "next" });
 	const DocsLayout = createDocsLayout(withNextApiReferenceBanner(config));
 	return function NextDocsLayout({ children }) {
-		return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(DocsClientCallbacks, {}), /* @__PURE__ */ jsx(DocsLayout, { children })] });
+		const docsCloud = resolveNextDocsCloudClientOptions(config);
+		return /* @__PURE__ */ jsxs(Fragment, { children: [
+			docsCloud ? /* @__PURE__ */ jsx(DocsCloudAnalytics, { ...docsCloud }) : null,
+			/* @__PURE__ */ jsx(DocsClientCallbacks, { docsCloudEnabled: Boolean(docsCloud) }),
+			/* @__PURE__ */ jsx(DocsLayout, { children })
+		] });
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/next",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "description": "Next.js adapter for @farming-labs/docs — MDX config wrapper",
   "keywords": [
     "docs",
@@ -106,8 +106,8 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8",
-    "@farming-labs/theme": "0.2.40",
-    "@farming-labs/docs": "0.2.40"
+    "@farming-labs/docs": "0.2.42",
+    "@farming-labs/theme": "0.2.42"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",