@farming-labs/docs 0.2.120 → 0.2.122

package/dist/content-changes.d.mts

@@ -0,0 +1,47 @@
+import { DocsAgentContentChangesConfig, DocsContentChangesResponse, DocsSearchConfig, DocsSearchSourcePage } from "./types.mjs";
+import { BuildDocsContentSnapshotOptions } from "./search.mjs";
+
+//#region src/content-changes.d.ts
+declare const DOCS_CONTENT_CHANGES_FORMAT = "docs-content-changes.v1";
+declare const DOCS_CONTENT_SNAPSHOT_FORMAT = "docs-content-snapshot.v1";
+declare const DOCS_CONTENT_CHANGES_RESPONSE_VALUE = "changes";
+/** Whether a value is a valid content-index generation identifier. */
+declare function isDocsContentChangeGeneration(value: string): boolean;
+interface DocsContentChangesRequest {
+  audience: "human" | "agent";
+  since?: string;
+}
+interface DocsResolvedContentChangesConfig {
+  enabled: boolean;
+  maxSnapshots: number;
+  loadSnapshot?: DocsAgentContentChangesConfig["loadSnapshot"];
+  saveSnapshot?: DocsAgentContentChangesConfig["saveSnapshot"];
+}
+interface ResolveDocsContentChangesOptions extends Omit<BuildDocsContentSnapshotOptions, "pages"> {
+  pages: readonly DocsSearchSourcePage[];
+  since?: string;
+  request?: Request;
+}
+interface DocsContentChangeFeed {
+  resolve(options: ResolveDocsContentChangesOptions): Promise<DocsContentChangesResponse>;
+}
+declare class DocsContentChangesRequestError extends Error {
+  readonly code = "invalid_content_changes_request";
+  constructor(message: string);
+}
+declare function resolveDocsContentChangesConfig(input?: boolean | DocsAgentContentChangesConfig, options?: {
+  staticExport?: boolean;
+}): DocsResolvedContentChangesConfig;
+declare function isDocsContentChangesRequest(url: URL): boolean;
+declare function resolveDocsContentChangesRequest(url: URL): DocsContentChangesRequest;
+declare function createDocsContentChangeFeed(input?: boolean | DocsAgentContentChangesConfig): DocsContentChangeFeed;
+declare function createDocsContentChangesHttpResponse(options: {
+  request: Request;
+  feed: DocsContentChangeFeed;
+  pages: readonly DocsSearchSourcePage[];
+  search?: boolean | DocsSearchConfig;
+  locale?: string;
+  baseUrl?: string;
+}): Promise<Response>;
+//#endregion
+export { DOCS_CONTENT_CHANGES_FORMAT, DOCS_CONTENT_CHANGES_RESPONSE_VALUE, DOCS_CONTENT_SNAPSHOT_FORMAT, DocsContentChangeFeed, DocsContentChangesRequest, DocsContentChangesRequestError, DocsResolvedContentChangesConfig, ResolveDocsContentChangesOptions, createDocsContentChangeFeed, createDocsContentChangesHttpResponse, isDocsContentChangeGeneration, isDocsContentChangesRequest, resolveDocsContentChangesConfig, resolveDocsContentChangesRequest };

package/dist/content-changes.mjs

@@ -0,0 +1,216 @@
+import { digestDocsRetrievalContent, isDocsRetrievalCanonicalUrl } from "./retrieval-digest.mjs";
+import { buildDocsContentSnapshot } from "./search.mjs";
+
+//#region src/content-changes.ts
+const DOCS_CONTENT_CHANGES_FORMAT = "docs-content-changes.v1";
+const DOCS_CONTENT_SNAPSHOT_FORMAT = "docs-content-snapshot.v1";
+const DOCS_CONTENT_CHANGES_RESPONSE_VALUE = "changes";
+const DEFAULT_DOCS_CONTENT_CHANGE_SNAPSHOTS = 8;
+const MAX_DOCS_CONTENT_CHANGE_SNAPSHOTS = 64;
+const DOCS_RETRIEVAL_DIGEST_PATTERN = /^sha256:[a-f\d]{64}$/u;
+/** Whether a value is a valid content-index generation identifier. */
+function isDocsContentChangeGeneration(value) {
+	return DOCS_RETRIEVAL_DIGEST_PATTERN.test(value);
+}
+var DocsContentChangesRequestError = class extends Error {
+	code = "invalid_content_changes_request";
+	constructor(message) {
+		super(message);
+		this.name = "DocsContentChangesRequestError";
+	}
+};
+function resolveDocsContentChangesConfig(input, options = {}) {
+	const configured = input && typeof input === "object" ? input : void 0;
+	const enabled = !options.staticExport && input !== false && configured?.enabled !== false;
+	const requestedMax = configured?.maxSnapshots ?? DEFAULT_DOCS_CONTENT_CHANGE_SNAPSHOTS;
+	return {
+		enabled,
+		maxSnapshots: Number.isSafeInteger(requestedMax) && requestedMax >= 1 && requestedMax <= MAX_DOCS_CONTENT_CHANGE_SNAPSHOTS ? requestedMax : DEFAULT_DOCS_CONTENT_CHANGE_SNAPSHOTS,
+		...configured?.loadSnapshot ? { loadSnapshot: configured.loadSnapshot } : {},
+		...configured?.saveSnapshot ? { saveSnapshot: configured.saveSnapshot } : {}
+	};
+}
+function isDocsContentChangesRequest(url) {
+	return url.searchParams.get("response") === DOCS_CONTENT_CHANGES_RESPONSE_VALUE;
+}
+function resolveDocsContentChangesRequest(url) {
+	if (!isDocsContentChangesRequest(url)) throw new DocsContentChangesRequestError("Content changes require `response=changes`.");
+	const rawAudience = url.searchParams.get("audience");
+	if (rawAudience !== null && rawAudience !== "human" && rawAudience !== "agent") throw new DocsContentChangesRequestError("Content-change audience must be `human` or `agent`.");
+	const since = url.searchParams.get("since") ?? void 0;
+	if (since !== void 0 && !isDocsContentChangeGeneration(since)) throw new DocsContentChangesRequestError("Content-change `since` must be a SHA-256 index generation.");
+	return {
+		audience: rawAudience ?? "agent",
+		...since ? { since } : {}
+	};
+}
+function snapshotScope(snapshot) {
+	return JSON.stringify({
+		audience: snapshot.audience,
+		locale: snapshot.locale,
+		baseUrl: snapshot.baseUrl
+	});
+}
+function snapshotKey(snapshot) {
+	return `${snapshotScope(snapshot)}\0${snapshot.indexGeneration}`;
+}
+function snapshotContext(snapshot, request) {
+	return {
+		audience: snapshot.audience,
+		...snapshot.locale ? { locale: snapshot.locale } : {},
+		...snapshot.baseUrl ? { baseUrl: snapshot.baseUrl } : {},
+		...request ? { request } : {}
+	};
+}
+function isSnapshotDocument(value) {
+	if (!value || typeof value !== "object") return false;
+	const document = value;
+	return typeof document.url === "string" && document.url.length > 0 && typeof document.canonicalUrl === "string" && isDocsRetrievalCanonicalUrl(document.canonicalUrl) && typeof document.digest === "string" && DOCS_RETRIEVAL_DIGEST_PATTERN.test(document.digest) && (document.lastModified === void 0 || typeof document.lastModified === "string" && Number.isFinite(Date.parse(document.lastModified)));
+}
+function validateLoadedSnapshot(value, generation, current) {
+	if (value.format !== DOCS_CONTENT_SNAPSHOT_FORMAT || value.indexGeneration !== generation || !DOCS_RETRIEVAL_DIGEST_PATTERN.test(value.indexGeneration) || snapshotScope(value) !== snapshotScope(current) || !Array.isArray(value.documents) || !value.documents.every(isSnapshotDocument)) throw new TypeError("Content-change snapshot storage returned an invalid snapshot.");
+	const documents = value.documents.map((document) => ({ ...document }));
+	documents.sort((left, right) => left.canonicalUrl === right.canonicalUrl ? left.url.localeCompare(right.url) : left.canonicalUrl.localeCompare(right.canonicalUrl));
+	if (documents.some((document, index) => index > 0 && documents[index - 1]?.canonicalUrl === document.canonicalUrl)) throw new TypeError("Content-change snapshot storage returned duplicate canonical URLs.");
+	return {
+		...value,
+		documents
+	};
+}
+function asChangeDocument(document) {
+	return { ...document };
+}
+function buildDelta(current, previous, since) {
+	const currentByUrl = new Map(current.documents.map((document) => [document.canonicalUrl, document]));
+	const previousByUrl = new Map(previous?.documents.map((document) => [document.canonicalUrl, document]) ?? []);
+	const added = [];
+	const changed = [];
+	const deleted = [];
+	if (!since || !previous) added.push(...current.documents.map(asChangeDocument));
+	else {
+		for (const document of current.documents) {
+			const old = previousByUrl.get(document.canonicalUrl);
+			if (!old) added.push(asChangeDocument(document));
+			else if (old.digest !== document.digest || old.lastModified !== document.lastModified || old.url !== document.url) changed.push({
+				...asChangeDocument(document),
+				previousDigest: old.digest,
+				...old.lastModified ? { previousLastModified: old.lastModified } : {}
+			});
+		}
+		for (const document of previous.documents) if (!currentByUrl.has(document.canonicalUrl)) deleted.push(asChangeDocument(document));
+	}
+	const mode = !since ? "snapshot" : previous ? "delta" : "reset";
+	return {
+		format: DOCS_CONTENT_CHANGES_FORMAT,
+		audience: current.audience,
+		...current.locale ? { locale: current.locale } : {},
+		since: since ?? null,
+		indexGeneration: current.indexGeneration,
+		mode,
+		resetRequired: mode === "reset",
+		documentCount: current.documents.length,
+		counts: {
+			added: added.length,
+			changed: changed.length,
+			deleted: deleted.length
+		},
+		added,
+		changed,
+		deleted
+	};
+}
+function createDocsContentChangeFeed(input) {
+	const config = resolveDocsContentChangesConfig(input);
+	const snapshots = /* @__PURE__ */ new Map();
+	const saved = /* @__PURE__ */ new Set();
+	const remember = (snapshot) => {
+		const key = snapshotKey(snapshot);
+		snapshots.delete(key);
+		snapshots.set(key, snapshot);
+		while (snapshots.size > config.maxSnapshots) {
+			const oldest = snapshots.keys().next().value;
+			if (!oldest) break;
+			snapshots.delete(oldest);
+			saved.delete(oldest);
+		}
+	};
+	return { async resolve(options) {
+		if (!config.enabled) throw new DocsContentChangesRequestError("Content changes are disabled.");
+		const current = await buildDocsContentSnapshot(options);
+		const currentKey = snapshotKey(current);
+		let previous;
+		if (options.since === current.indexGeneration) previous = current;
+		else if (options.since) {
+			const scopedKey = `${snapshotScope(current)}\0${options.since}`;
+			previous = snapshots.get(scopedKey);
+			if (!previous && config.loadSnapshot) {
+				const loaded = await config.loadSnapshot(options.since, snapshotContext(current, options.request));
+				if (loaded) {
+					previous = validateLoadedSnapshot(loaded, options.since, current);
+					remember(previous);
+				}
+			}
+		}
+		remember(current);
+		if (config.saveSnapshot && !saved.has(currentKey)) {
+			await config.saveSnapshot({
+				...current,
+				documents: current.documents.map((document) => ({ ...document }))
+			}, snapshotContext(current, options.request));
+			saved.add(currentKey);
+		}
+		return buildDelta(current, previous, options.since);
+	} };
+}
+function contentChangesEtag(response) {
+	return `"${digestDocsRetrievalContent(JSON.stringify([
+		response.format,
+		response.audience,
+		response.locale ?? null,
+		response.since,
+		response.indexGeneration,
+		response.mode
+	]))}"`;
+}
+function requestMatchesEtag(request, etag) {
+	const header = request.headers.get("if-none-match");
+	if (!header) return false;
+	return header.split(",").map((value) => value.trim().replace(/^W\//u, "")).some((value) => value === "*" || value === etag);
+}
+async function createDocsContentChangesHttpResponse(options) {
+	let resolved;
+	try {
+		resolved = resolveDocsContentChangesRequest(new URL(options.request.url));
+	} catch (error) {
+		if (!(error instanceof DocsContentChangesRequestError)) throw error;
+		return Response.json({ error: {
+			code: error.code,
+			message: error.message
+		} }, { status: 400 });
+	}
+	const response = await options.feed.resolve({
+		pages: options.pages,
+		search: options.search,
+		audience: resolved.audience,
+		locale: options.locale,
+		baseUrl: options.baseUrl,
+		since: resolved.since,
+		request: options.request
+	});
+	const etag = contentChangesEtag(response);
+	const headers = {
+		"Cache-Control": "public, max-age=0, s-maxage=60, stale-while-revalidate=300",
+		ETag: etag,
+		"X-Docs-Index-Generation": response.indexGeneration,
+		"X-Robots-Tag": "noindex"
+	};
+	if (requestMatchesEtag(options.request, etag)) return new Response(null, {
+		status: 304,
+		headers
+	});
+	if (options.request.method.toUpperCase() === "HEAD") return new Response(null, { headers });
+	return Response.json(response, { headers });
+}
+
+//#endregion
+export { DOCS_CONTENT_CHANGES_FORMAT, DOCS_CONTENT_CHANGES_RESPONSE_VALUE, DOCS_CONTENT_SNAPSHOT_FORMAT, DocsContentChangesRequestError, createDocsContentChangeFeed, createDocsContentChangesHttpResponse, isDocsContentChangeGeneration, isDocsContentChangesRequest, resolveDocsContentChangesConfig, resolveDocsContentChangesRequest };

package/dist/create-theme.d.mts

@@ -0,0 +1,48 @@
+import { DocsTheme } from "./types.mjs";
+
+//#region src/create-theme.d.ts
+/**
+ * Create a theme preset factory.
+ *
+ * Returns a function that accepts optional overrides and deep-merges them
+ * with the base theme defaults. This is the same pattern used by the
+ * built-in `fumadocs()`, `darksharp()`, and `pixelBorder()` presets.
+ *
+ * @param baseTheme - The default theme configuration
+ * @returns A factory function `(overrides?) => DocsTheme`
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from "@farming-labs/docs";
+ *
+ * export const myTheme = createTheme({
+ *   name: "my-theme",
+ *   ui: {
+ *     colors: { primary: "#6366f1" },
+ *     layout: { contentWidth: 800 },
+ *   },
+ * });
+ * ```
+ */
+declare function createTheme(baseTheme: DocsTheme): (overrides?: Partial<DocsTheme>) => DocsTheme;
+/**
+ * Extend an existing theme preset with additional defaults.
+ *
+ * Useful when you want to build on top of an existing theme (e.g. fumadocs)
+ * rather than starting from scratch.
+ *
+ * @example
+ * ```ts
+ * import { extendTheme } from "@farming-labs/docs";
+ * import { fumadocs } from "@farming-labs/theme/default";
+ *
+ * // Start with fumadocs defaults, override some values
+ * export const myTheme = extendTheme(fumadocs(), {
+ *   name: "my-custom-fumadocs",
+ *   ui: { colors: { primary: "#22c55e" } },
+ * });
+ * ```
+ */
+declare function extendTheme(baseTheme: DocsTheme, extensions: Partial<DocsTheme>): DocsTheme;
+//#endregion
+export { createTheme, extendTheme };

package/dist/create-theme.mjs

@@ -0,0 +1,57 @@
+import { deepMerge } from "./utils.mjs";
+
+//#region src/create-theme.ts
+/**
+* Create a theme preset factory.
+*
+* Returns a function that accepts optional overrides and deep-merges them
+* with the base theme defaults. This is the same pattern used by the
+* built-in `fumadocs()`, `darksharp()`, and `pixelBorder()` presets.
+*
+* @param baseTheme - The default theme configuration
+* @returns A factory function `(overrides?) => DocsTheme`
+*
+* @example
+* ```ts
+* import { createTheme } from "@farming-labs/docs";
+*
+* export const myTheme = createTheme({
+*   name: "my-theme",
+*   ui: {
+*     colors: { primary: "#6366f1" },
+*     layout: { contentWidth: 800 },
+*   },
+* });
+* ```
+*/
+function createTheme(baseTheme) {
+	return function themeFactory(overrides = {}) {
+		const merged = deepMerge(baseTheme, overrides);
+		if (overrides.ui?.colors) merged._userColorOverrides = { ...overrides.ui.colors };
+		return merged;
+	};
+}
+/**
+* Extend an existing theme preset with additional defaults.
+*
+* Useful when you want to build on top of an existing theme (e.g. fumadocs)
+* rather than starting from scratch.
+*
+* @example
+* ```ts
+* import { extendTheme } from "@farming-labs/docs";
+* import { fumadocs } from "@farming-labs/theme/default";
+*
+* // Start with fumadocs defaults, override some values
+* export const myTheme = extendTheme(fumadocs(), {
+*   name: "my-custom-fumadocs",
+*   ui: { colors: { primary: "#22c55e" } },
+* });
+* ```
+*/
+function extendTheme(baseTheme, extensions) {
+	return deepMerge(baseTheme, extensions);
+}
+
+//#endregion
+export { createTheme, extendTheme };

package/dist/date.d.mts

@@ -0,0 +1,5 @@
+//#region src/date.d.ts
+/** Formats docs timestamps without allowing the deployment timezone to change the calendar day. */
+declare function formatDocsLastModifiedDate(value: string | Date): string | undefined;
+//#endregion
+export { formatDocsLastModifiedDate };

package/dist/date.mjs

@@ -0,0 +1,17 @@
+//#region src/date.ts
+const DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+/** Formats docs timestamps without allowing the deployment timezone to change the calendar day. */
+function formatDocsLastModifiedDate(value) {
+	const normalized = typeof value === "string" && DATE_ONLY_PATTERN.test(value) ? `${value}T00:00:00.000Z` : value;
+	const date = normalized instanceof Date ? normalized : new Date(normalized);
+	if (Number.isNaN(date.getTime())) return void 0;
+	return date.toLocaleDateString("en-US", {
+		year: "numeric",
+		month: "long",
+		day: "numeric",
+		timeZone: "UTC"
+	});
+}
+
+//#endregion
+export { formatDocsLastModifiedDate };

package/dist/define-docs.d.mts

@@ -0,0 +1,9 @@
+import { DocsConfig } from "./types.mjs";
+
+//#region src/define-docs.d.ts
+/**
+ * Define docs configuration. Validates and returns the config.
+ */
+declare function defineDocs(config: DocsConfig): DocsConfig;
+//#endregion
+export { defineDocs };

package/dist/define-docs.mjs

@@ -0,0 +1,46 @@
+//#region src/define-docs.ts
+/**
+* Define docs configuration. Validates and returns the config.
+*/
+function defineDocs(config) {
+	return {
+		entry: config.entry ?? "docs",
+		docsPath: config.docsPath,
+		contentDir: config.contentDir,
+		i18n: config.i18n,
+		theme: config.theme,
+		nav: config.nav,
+		github: config.github,
+		themeToggle: config.themeToggle,
+		breadcrumb: config.breadcrumb,
+		sidebar: config.sidebar,
+		components: config.components,
+		analytics: config.analytics,
+		telemetry: config.telemetry,
+		cloud: config.cloud,
+		observability: config.observability,
+		onCopyClick: config.onCopyClick,
+		codeBlocks: config.codeBlocks,
+		feedback: config.feedback,
+		search: config.search,
+		mcp: config.mcp,
+		icons: config.icons,
+		pageActions: config.pageActions,
+		lastUpdated: config.lastUpdated,
+		readingTime: config.readingTime,
+		llmsTxt: config.llmsTxt,
+		sitemap: config.sitemap,
+		robots: config.robots,
+		ai: config.ai,
+		ordering: config.ordering,
+		metadata: config.metadata,
+		og: config.og,
+		changelog: config.changelog,
+		apiReference: config.apiReference,
+		agent: config.agent,
+		review: config.review
+	};
+}
+
+//#endregion
+export { defineDocs };

package/dist/docs-cloud-client.d.mts

@@ -0,0 +1,18 @@
+//#region src/docs-cloud-client.d.ts
+type DocsCloudClientRuntimeValue<T = string> = T | undefined | null | (() => T | undefined | null);
+type DocsCloudClientRuntimeEnv = Record<string, string | undefined> | (() => Record<string, string | undefined>);
+interface DocsCloudClientOptions {
+  projectId?: DocsCloudClientRuntimeValue;
+  endpoint?: DocsCloudClientRuntimeValue;
+  analyticsEndpoint?: DocsCloudClientRuntimeValue;
+  apiBaseUrl?: DocsCloudClientRuntimeValue;
+  analyticsKey?: DocsCloudClientRuntimeValue;
+  enabled?: DocsCloudClientRuntimeValue<boolean | string>;
+  includeInputs?: DocsCloudClientRuntimeValue<boolean>;
+  env?: DocsCloudClientRuntimeEnv;
+  fetch?: typeof fetch;
+  metadata?: Record<string, unknown>;
+  properties?: Record<string, unknown>;
+}
+//#endregion
+export { DocsCloudClientOptions, DocsCloudClientRuntimeValue };

package/dist/docs-cloud-client.mjs

@@ -0,0 +1,161 @@
+"use client";
+
+import { sendDocsCloudAnalyticsEvent } from "./cloud-analytics.mjs";
+
+//#region src/docs-cloud-client.ts
+const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://api.farming-labs.dev";
+const DOCS_CLOUD_PROJECT_ID_ENVS = [
+	"NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID",
+	"PUBLIC_DOCS_CLOUD_PROJECT_ID",
+	"DOCS_CLOUD_PROJECT_ID"
+];
+const DOCS_CLOUD_API_BASE_URL_ENVS = [
+	"NEXT_PUBLIC_DOCS_CLOUD_URL",
+	"PUBLIC_DOCS_CLOUD_URL",
+	"DOCS_CLOUD_API_BASE_URL",
+	"DOCS_CLOUD_API_URL"
+];
+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_ENABLED_ENVS = [
+	"NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED",
+	"PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED",
+	"DOCS_CLOUD_ANALYTICS_ENABLED"
+];
+const DOCS_CLOUD_ANALYTICS_KEY_ENVS = [
+	"NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_KEY",
+	"PUBLIC_DOCS_CLOUD_ANALYTICS_KEY",
+	"DOCS_CLOUD_ANALYTICS_KEY"
+];
+function normalizeRuntimeString(value) {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function resolveRuntimeValue(value) {
+	return (typeof value === "function" ? value() : value) ?? void 0;
+}
+function resolveRuntimeString(value) {
+	return normalizeRuntimeString(resolveRuntimeValue(value));
+}
+function resolveRuntimeEnv(env) {
+	return typeof env === "function" ? env() : env ?? {};
+}
+function readProcessEnv(name) {
+	if (typeof process === "undefined") return void 0;
+	if (!process.env) return void 0;
+	switch (name) {
+		case "NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID": return normalizeRuntimeString(process.env.NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID);
+		case "NEXT_PUBLIC_DOCS_CLOUD_URL": return normalizeRuntimeString(process.env.NEXT_PUBLIC_DOCS_CLOUD_URL);
+		case "NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT": return normalizeRuntimeString(process.env.NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENDPOINT);
+		case "NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED": return normalizeRuntimeString(process.env.NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_ENABLED);
+		case "NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_KEY": return normalizeRuntimeString(process.env.NEXT_PUBLIC_DOCS_CLOUD_ANALYTICS_KEY);
+		default: return;
+	}
+}
+function readEnv(name, env) {
+	return normalizeRuntimeString(env[name]) ?? readProcessEnv(name);
+}
+function readFirstEnv(names, env) {
+	for (const name of names) {
+		const value = readEnv(name, env);
+		if (value) return value;
+	}
+}
+function isFalsy(value) {
+	if (value === false) return true;
+	if (typeof value !== "string") return false;
+	return /^(0|false|no|off)$/i.test(value.trim());
+}
+function stripTrailingSlash(value) {
+	return value.replace(/\/+$/, "");
+}
+function mergeRecords(...records) {
+	const merged = {};
+	for (const record of records) {
+		if (!record) continue;
+		Object.assign(merged, record);
+	}
+	return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function getBrowserLocation() {
+	return typeof window !== "undefined" ? window.location : void 0;
+}
+function getBrowserReferrer() {
+	if (typeof document === "undefined") return void 0;
+	return document.referrer || void 0;
+}
+function createDocsCloudClient(options = {}) {
+	function env() {
+		return resolveRuntimeEnv(options.env);
+	}
+	function projectId() {
+		const runtimeEnv = env();
+		return resolveRuntimeString(options.projectId) ?? readFirstEnv(DOCS_CLOUD_PROJECT_ID_ENVS, runtimeEnv);
+	}
+	function apiBaseUrl() {
+		const runtimeEnv = env();
+		return stripTrailingSlash(resolveRuntimeString(options.apiBaseUrl) ?? readFirstEnv(DOCS_CLOUD_API_BASE_URL_ENVS, runtimeEnv) ?? DEFAULT_DOCS_CLOUD_API_BASE_URL);
+	}
+	function endpoint() {
+		const runtimeEnv = env();
+		return resolveRuntimeString(options.endpoint) ?? resolveRuntimeString(options.analyticsEndpoint) ?? readFirstEnv(DOCS_CLOUD_ANALYTICS_ENDPOINT_ENVS, runtimeEnv) ?? `${apiBaseUrl()}/v1/analytics/events`;
+	}
+	function analyticsKey() {
+		const runtimeEnv = env();
+		return resolveRuntimeString(options.analyticsKey) ?? readFirstEnv(DOCS_CLOUD_ANALYTICS_KEY_ENVS, runtimeEnv);
+	}
+	function enabled() {
+		const runtimeEnv = env();
+		return !isFalsy(resolveRuntimeValue(options.enabled) ?? readFirstEnv(DOCS_CLOUD_ANALYTICS_ENABLED_ENVS, runtimeEnv));
+	}
+	function includeInputs() {
+		return resolveRuntimeValue(options.includeInputs) === true;
+	}
+	function getConfig() {
+		const id = projectId();
+		return {
+			enabled: enabled(),
+			configured: Boolean(id),
+			...id ? { projectId: id } : {},
+			endpoint: endpoint()
+		};
+	}
+	async function trackEvent(event, trackOptions = {}) {
+		const config = getConfig();
+		if (!config.enabled || !config.projectId) return false;
+		const location = getBrowserLocation();
+		const normalized = {
+			...event,
+			source: event.source ?? "client",
+			timestamp: event.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+			url: event.url ?? location?.href,
+			path: event.path ?? location?.pathname,
+			referrer: event.referrer ?? getBrowserReferrer(),
+			locale: event.locale ?? trackOptions.locale,
+			metadata: mergeRecords(options.metadata, trackOptions.metadata, event.metadata),
+			properties: mergeRecords(options.properties, trackOptions.properties, event.properties)
+		};
+		if (!includeInputs()) delete normalized.input;
+		await sendDocsCloudAnalyticsEvent({
+			endpoint: config.endpoint,
+			projectId: config.projectId,
+			apiKey: analyticsKey(),
+			fetch: options.fetch
+		}, normalized);
+		return true;
+	}
+	return {
+		analytics: { track: trackEvent },
+		trackEvent,
+		getConfig,
+		isConfigured() {
+			const config = getConfig();
+			return config.enabled && config.configured;
+		}
+	};
+}
+
+//#endregion
+export { createDocsCloudClient };

package/dist/docs-cloud-server.d.mts

@@ -1,5 +1,5 @@
-import { bt as DocsAnalyticsEventInput, vt as DocsAnalyticsConfig, yt as DocsAnalyticsEvent } from "./types-BJFeMXWZ.mjs";
-import { n as DocsCloudAskAIResponseOptions, t as DocsCloudAskAIConfig } from "./cloud-ask-ai-BrsTXQf6.mjs";
+import { DocsAnalyticsConfig, DocsAnalyticsEvent, DocsAnalyticsEventInput } from "./types.mjs";
+import { DocsCloudAskAIConfig, DocsCloudAskAIResponseOptions } from "./cloud-ask-ai.mjs";
 
 //#region src/docs-cloud-server.d.ts
 type DocsCloudRuntimeValue<T = string> = T | undefined | null | (() => T | undefined | null);

package/dist/docs-cloud-server.mjs

@@ -1,6 +1,5 @@
-import "./http-body-DkAPk6D5.mjs";
-import { n as sendDocsCloudAnalyticsEvent } from "./cloud-analytics-D14HplI7.mjs";
-import { t as createDocsCloudAskAIResponse } from "./cloud-ask-ai-BqKhjpS5.mjs";
+import { sendDocsCloudAnalyticsEvent } from "./cloud-analytics.mjs";
+import { createDocsCloudAskAIResponse } from "./cloud-ask-ai.mjs";
 
 //#region src/docs-cloud-server.ts
 const DEFAULT_DOCS_CLOUD_API_BASE_URL = "https://api.farming-labs.dev";

package/dist/heading-toc.d.mts

@@ -0,0 +1,10 @@
+//#region src/heading-toc.d.ts
+/**
+ * Encode heading fragments emitted by a renderer's nested table of contents.
+ *
+ * Fumadocs stores fragment URLs as raw DOM ids. Encoding the fragment after its
+ * heading visitor runs keeps links valid without changing path prefixes.
+ */
+declare function encodeDocsHeadingTocUrls(value: unknown): void;
+//#endregion
+export { encodeDocsHeadingTocUrls };