@farming-labs/docs 0.1.71 → 0.1.73

package/dist/{types-BXgTvFFE.d.mts → types-D-OvczD4.d.mts}

@@ -633,15 +633,17 @@ interface PageActionsConfig {
   alignment?: "left" | "right";
 }
 type DocsAnalyticsSource = "client" | "server" | "mcp";
-type DocsAnalyticsEventType = "page_view" | "search_open" | "search_close" | "search_query" | "search_result_click" | "search_error" | "ai_open" | "ai_close" | "ai_question" | "ai_response" | "ai_error" | "ai_clear" | "page_action_copy_markdown" | "page_action_open_docs_menu" | "page_action_open_docs" | "code_block_copy" | "feedback_select" | "feedback_submit" | "feedback_error" | "agent_read" | "agent_spec_request" | "agent_feedback_schema" | "agent_feedback_submit" | "agent_feedback_error" | "markdown_request" | "llms_request" | "skill_request" | "api_search" | "api_ai_request" | "api_ai_response" | "api_ai_error" | "mcp_request" | "mcp_tool";
+type DocsAgentTraceStatus = "started" | "success" | "error" | "retry" | "timeout";
+type DocsAgentTraceEventType = "run.start" | "run.end" | "run.error" | "user.input" | "prompt.build" | "retrieval.query" | "retrieval.result" | "retrieval.error" | "model.call" | "model.response" | "model.stream" | "model.error" | "tool.call" | "tool.result" | "tool.error" | "retry" | "timeout" | "error" | "agent.final";
+type DocsAnalyticsEventType = "page_view" | "search_open" | "search_close" | "search_query" | "search_result_click" | "search_error" | "ai_open" | "ai_close" | "ai_question" | "ai_response" | "ai_feedback" | "ai_error" | "ai_clear" | "page_action_copy_markdown" | "page_action_open_docs_menu" | "page_action_open_docs" | "code_block_copy" | "feedback_select" | "feedback_submit" | "feedback_error" | "agent_read" | "agent_spec_request" | "agent_feedback_schema" | "agent_feedback_submit" | "agent_feedback_error" | "markdown_request" | "llms_request" | "skill_request" | "api_search" | "api_ai_request" | "api_ai_response" | "api_ai_error" | "mcp_request" | "mcp_tool";
 interface DocsAnalyticsInput {
   query?: string;
   question?: string;
+  feedbackValue?: string;
   feedbackComment?: string;
   content?: string;
 }
-interface DocsAnalyticsEvent {
-  type: DocsAnalyticsEventType | (string & {});
+interface DocsEventBase {
   timestamp: string;
   source: DocsAnalyticsSource;
   url?: string;
@@ -649,17 +651,42 @@ interface DocsAnalyticsEvent {
   referrer?: string;
   locale?: string;
   input?: DocsAnalyticsInput;
+  metadata?: Record<string, unknown>;
   properties?: Record<string, unknown>;
 }
+interface DocsAnalyticsEvent extends DocsEventBase {
+  type: DocsAnalyticsEventType | (string & {});
+}
 type DocsAnalyticsEventInput = Omit<DocsAnalyticsEvent, "timestamp" | "source"> & {
   timestamp?: string;
   source?: DocsAnalyticsSource;
 };
+interface DocsObservabilityEvent extends DocsEventBase {
+  type: DocsAgentTraceEventType | (string & {});
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  name?: string;
+  startedAt?: string;
+  endedAt?: string;
+  durationMs?: number;
+  status?: DocsAgentTraceStatus;
+  inputPreview?: Record<string, unknown>;
+  outputPreview?: Record<string, unknown>;
+}
+type DocsObservabilityEventInput = Omit<DocsObservabilityEvent, "timestamp" | "source"> & {
+  timestamp?: string;
+  source?: DocsAnalyticsSource;
+};
+type DocsAgentTraceEventInput = Omit<DocsObservabilityEventInput, "type"> & {
+  type: DocsAgentTraceEventType;
+  name: string;
+};
 interface DocsAnalyticsConfig {
-  /** Enable analytics event emission. Defaults to `true` when this object is provided. */
+  /** Enable event emission. Defaults to `true` when this object is provided. */
   enabled?: boolean;
   /**
-   * Log analytics events to the console.
+   * Log events to the console.
    *
    * `analytics: true` logs with `console.info`. When `onEvent` is provided,
    * console logging is disabled unless this is set.
@@ -673,9 +700,30 @@ interface DocsAnalyticsConfig {
    * counts, routes, status, and duration.
    */
   includeInputs?: boolean;
-  /** Callback fired for every analytics event. */
+  /** Callback fired for every emitted event. */
   onEvent?: (event: DocsAnalyticsEvent) => void | Promise<void>;
 }
+interface DocsObservabilityConfig {
+  /** Enable trace emission. Defaults to `true` when this object is provided. */
+  enabled?: boolean;
+  /**
+   * Log trace events to the console.
+   *
+   * `observability: true` logs with `console.info`. When `onEvent` is provided,
+   * console logging is disabled unless this is set.
+   */
+  console?: boolean | "log" | "info" | "debug";
+  /**
+   * Include raw `input` fields on observability events.
+   *
+   * Defaults to `false`; events still include safe metadata such as lengths,
+   * counts, routes, status, and duration. Built-in trace events use previews
+   * instead of raw user-authored text.
+   */
+  includeInputs?: boolean;
+  /** Callback fired for every emitted trace event. */
+  onEvent?: (event: DocsObservabilityEvent) => void | Promise<void>;
+}
 /**
  * Configuration for the "Last updated" date display.
  *
@@ -969,6 +1017,51 @@ interface GithubConfig {
    */
   directory?: string;
 }
+type DocsAskAIFeedbackValue = "like" | "dislike";
+type DocsAskAIActionType = "copy" | DocsAskAIFeedbackValue;
+interface DocsAskAIFeedbackMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+interface DocsAskAIActionData {
+  type: DocsAskAIActionType;
+  value?: DocsAskAIFeedbackValue;
+  question: string;
+  answer: string;
+  messageId?: string;
+  messageIndex?: number;
+  model?: string;
+  surface?: string;
+  url?: string;
+  path?: string;
+  messages?: DocsAskAIFeedbackMessage[];
+  copied?: boolean;
+}
+interface DocsAskAIFeedbackData {
+  value: DocsAskAIFeedbackValue;
+  question: string;
+  answer: string;
+  messageId?: string;
+  messageIndex?: number;
+  model?: string;
+  surface?: string;
+  url?: string;
+  path?: string;
+  messages?: DocsAskAIFeedbackMessage[];
+}
+interface DocsAskAIFeedbackConfig {
+  /**
+   * Whether to show response rating controls after each completed Ask AI answer.
+   * @default true
+   */
+  enabled?: boolean;
+  /** Label for the positive rating button. @default "Helpful" */
+  positiveLabel?: string;
+  /** Label for the negative rating button. @default "Not helpful" */
+  negativeLabel?: string;
+  /** Called when a user rates an Ask AI response. */
+  onFeedback?: (data: DocsAskAIFeedbackData) => void | Promise<void>;
+}
 /**
  * Configuration for "Ask AI" — a RAG-powered chat that lets users
  * ask questions about the documentation content.
@@ -1230,8 +1323,8 @@ interface AIConfig {
    */
   aiLabel?: string;
   /**
-   * The npm package name used in import examples.
-   * The AI will use this in code snippets instead of generic placeholders.
+   * Optional npm package-name override used in import examples.
+   * Ask AI normally infers package names and exact imports from retrieved docs context.
    *
    * @example
    * ```ts
@@ -1305,6 +1398,45 @@ interface AIConfig {
   loadingComponent?: (props: {
     name: string;
   }) => unknown;
+  /**
+   * Response rating controls for generated Ask AI answers.
+   *
+   * Set to `false` to hide the buttons. Pass an object to customize labels
+   * and receive callback payloads with the question, answer, model, and UI surface.
+   *
+   * @default true
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   feedback: {
+   *     onFeedback(data) {
+   *       console.log(data.value, data.question, data.answer);
+   *     },
+   *   },
+   * }
+   * ```
+   */
+  feedback?: boolean | DocsAskAIFeedbackConfig;
+  /**
+   * Called when a user clicks an Ask AI response action.
+   *
+   * `data.type` is `"copy"`, `"like"`, or `"dislike"`.
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   onActions(data) {
+   *     if (data.type === "copy") console.log("Copied", data.answer);
+   *     if (data.type === "like") console.log("Helpful", data.question);
+   *     if (data.type === "dislike") console.log("Not helpful", data.question);
+   *   },
+   * }
+   * ```
+   */
+  onActions?: (data: DocsAskAIActionData) => void | Promise<void>;
 }
 /**
  * A single item in the slug-based sidebar ordering.
@@ -1674,13 +1806,27 @@ interface DocsConfig {
    * Built-in analytics event stream for docs interactions.
    *
    * - `false` or omitted -> analytics disabled (default)
-   * - `true` -> log all framework events to the console
+   * - `true` -> log product/usage events to the console
    * - `{ onEvent(event) { ... } }` -> send events to your analytics sink
    *
    * Raw queries, AI questions, feedback comments, and copied content are not
    * included unless `includeInputs: true` is set.
    */
   analytics?: boolean | DocsAnalyticsConfig;
+  /**
+   * Built-in observability stream for agent traces, timing, errors, and runtime debugging.
+   * This is separate from `analytics`; it emits span-like Ask AI and MCP trace events.
+   *
+   * ```ts
+   * observability: {
+   *   console: "debug",
+   *   onEvent(event) {
+   *     console.info(event.type, event.traceId, event.durationMs)
+   *   },
+   * }
+   * ```
+   */
+  observability?: boolean | DocsObservabilityConfig;
   /**
    * GitHub repository URL or config. Enables "Edit on GitHub" links
    * on each docs page footer, pointing to the source `.mdx` file.
@@ -2046,4 +2192,4 @@ interface DocsConfig {
   og?: OGConfig;
 }
 //#endregion
-export { PageFrontmatter as $, DocsSearchAdapterContext as A, DocsTheme as B, DocsI18nConfig as C, DocsNav as D, DocsMetadata as E, DocsSearchEmbeddingsConfig as F, LlmsTxtConfig as G, FontStyle as H, DocsSearchQuery as I, OpenDocsConfig as J, McpDocsSearchConfig as K, DocsSearchResult as L, DocsSearchChunkingConfig as M, DocsSearchConfig as N, DocsRelatedItem as O, DocsSearchDocument as P, PageActionsConfig as Q, DocsSearchResultType as R, DocsFeedbackValue as S, DocsMcpToolsConfig as T, GithubConfig as U, FeedbackConfig as V, LastUpdatedConfig as W, OpenGraphImage as X, OpenDocsProvider as Y, OrderingItem as Z, DocsAnalyticsEventType as _, ApiReferenceRenderer as a, SidebarComponentProps as at, DocsConfig as b, ChangelogFrontmatter as c, SidebarFolderNode as ct, CustomDocsSearchConfig as d, SidebarTree as dt, PageOpenGraph as et, DocsAgentFeedbackContext as f, SimpleDocsSearchConfig as ft, DocsAnalyticsEventInput as g, UIConfig as gt, DocsAnalyticsEvent as h, TypographyConfig as ht, ApiReferenceConfig as i, ResolvedDocsRelatedLink as it, DocsSearchAdapterFactory as j, DocsSearchAdapter as k, CodeBlockCopyData as l, SidebarNode as lt, DocsAnalyticsConfig as m, TypesenseDocsSearchConfig as mt, AgentFeedbackConfig as n, PageTwitter as nt, BreadcrumbConfig as o, SidebarConfig as ot, DocsAgentFeedbackData as p, ThemeToggleConfig as pt, OGConfig as q, AlgoliaDocsSearchConfig as r, ReadingTimeConfig as rt, ChangelogConfig as s, SidebarFolderIndexBehavior as st, AIConfig as t, PageSidebarFrontmatter as tt, CopyMarkdownConfig as u, SidebarPageNode as ut, DocsAnalyticsInput as v, DocsMcpConfig as w, DocsFeedbackData as x, DocsAnalyticsSource as y, DocsSearchSourcePage as z };
+export { FeedbackConfig as $, DocsFeedbackData as A, DocsRelatedItem as B, DocsAskAIActionData as C, SidebarTree as Ct, DocsAskAIFeedbackMessage as D, TypographyConfig as Dt, DocsAskAIFeedbackData as E, TypesenseDocsSearchConfig as Et, DocsMetadata as F, DocsSearchConfig as G, DocsSearchAdapterContext as H, DocsNav as I, DocsSearchQuery as J, DocsSearchDocument as K, DocsObservabilityConfig as L, DocsI18nConfig as M, DocsMcpConfig as N, DocsAskAIFeedbackValue as O, UIConfig as Ot, DocsMcpToolsConfig as P, DocsTheme as Q, DocsObservabilityEvent as R, DocsAnalyticsSource as S, SidebarPageNode as St, DocsAskAIFeedbackConfig as T, ThemeToggleConfig as Tt, DocsSearchAdapterFactory as U, DocsSearchAdapter as V, DocsSearchChunkingConfig as W, DocsSearchResultType as X, DocsSearchResult as Y, DocsSearchSourcePage as Z, DocsAnalyticsConfig as _, SidebarComponentProps as _t, ApiReferenceRenderer as a, OGConfig as at, DocsAnalyticsEventType as b, SidebarFolderNode as bt, ChangelogFrontmatter as c, OpenGraphImage as ct, CustomDocsSearchConfig as d, PageFrontmatter as dt, FontStyle as et, DocsAgentFeedbackContext as f, PageOpenGraph as ft, DocsAgentTraceStatus as g, ResolvedDocsRelatedLink as gt, DocsAgentTraceEventType as h, ReadingTimeConfig as ht, ApiReferenceConfig as i, McpDocsSearchConfig as it, DocsFeedbackValue as j, DocsConfig as k, CodeBlockCopyData as l, OrderingItem as lt, DocsAgentTraceEventInput as m, PageTwitter as mt, AgentFeedbackConfig as n, LastUpdatedConfig as nt, BreadcrumbConfig as o, OpenDocsConfig as ot, DocsAgentFeedbackData as p, PageSidebarFrontmatter as pt, DocsSearchEmbeddingsConfig as q, AlgoliaDocsSearchConfig as r, LlmsTxtConfig as rt, ChangelogConfig as s, OpenDocsProvider as st, AIConfig as t, GithubConfig as tt, CopyMarkdownConfig as u, PageActionsConfig as ut, DocsAnalyticsEvent as v, SidebarConfig as vt, DocsAskAIActionType as w, SimpleDocsSearchConfig as wt, DocsAnalyticsInput as x, SidebarNode as xt, DocsAnalyticsEventInput as y, SidebarFolderIndexBehavior as yt, DocsObservabilityEventInput as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.1.71",
+  "version": "0.1.73",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",

package/dist/search-Gvi81BSo.d.mts

@@ -1,41 +0,0 @@
-import { K as McpDocsSearchConfig, L as DocsSearchResult, M as DocsSearchChunkingConfig, N as DocsSearchConfig, P as DocsSearchDocument, d as CustomDocsSearchConfig, g as DocsAnalyticsEventInput, h as DocsAnalyticsEvent, j as DocsSearchAdapterFactory, k as DocsSearchAdapter, m as DocsAnalyticsConfig, mt as TypesenseDocsSearchConfig, r as AlgoliaDocsSearchConfig, z as DocsSearchSourcePage } from "./types-BXgTvFFE.mjs";
-
-//#region src/cloud-analytics.d.ts
-interface DocsCloudAnalyticsOptions {
-  enabled?: boolean;
-  console?: DocsAnalyticsConfig["console"];
-  includeInputs?: boolean;
-  projectId?: string;
-  apiKey?: string;
-}
-declare function createDocsCloudAnalytics(options?: DocsCloudAnalyticsOptions): DocsAnalyticsConfig;
-//#endregion
-//#region src/analytics.d.ts
-interface ResolvedDocsAnalyticsConfig {
-  enabled: boolean;
-  console: false | "log" | "info" | "debug";
-  includeInputs: boolean;
-  onEvent?: (event: DocsAnalyticsEvent) => void | Promise<void>;
-}
-declare function resolveDocsAnalyticsConfig(analytics?: boolean | DocsAnalyticsConfig): ResolvedDocsAnalyticsConfig;
-declare function emitDocsAnalyticsEvent(analytics: boolean | DocsAnalyticsConfig | undefined, event: DocsAnalyticsEventInput): Promise<void>;
-//#endregion
-//#region src/search.d.ts
-declare function buildDocsSearchDocuments(pages: DocsSearchSourcePage[], chunking?: DocsSearchChunkingConfig): DocsSearchDocument[];
-declare function createSimpleSearchAdapter(): DocsSearchAdapter;
-declare function createTypesenseSearchAdapter(config: TypesenseDocsSearchConfig): DocsSearchAdapter;
-declare function resolveSearchRequestConfig(search: boolean | DocsSearchConfig | undefined, requestUrl?: string): boolean | DocsSearchConfig | undefined;
-declare function createMcpSearchAdapter(config: McpDocsSearchConfig): DocsSearchAdapter;
-declare function createAlgoliaSearchAdapter(config: AlgoliaDocsSearchConfig): DocsSearchAdapter;
-declare function performDocsSearch(options: {
-  pages: DocsSearchSourcePage[];
-  query: string;
-  search?: boolean | DocsSearchConfig;
-  locale?: string;
-  pathname?: string;
-  siteTitle?: string;
-  limit?: number;
-}): Promise<DocsSearchResult[]>;
-declare function createCustomSearchAdapter(adapter: DocsSearchAdapter | DocsSearchAdapterFactory): CustomDocsSearchConfig;
-//#endregion
-export { createSimpleSearchAdapter as a, resolveSearchRequestConfig as c, resolveDocsAnalyticsConfig as d, DocsCloudAnalyticsOptions as f, createMcpSearchAdapter as i, ResolvedDocsAnalyticsConfig as l, createAlgoliaSearchAdapter as n, createTypesenseSearchAdapter as o, createDocsCloudAnalytics as p, createCustomSearchAdapter as r, performDocsSearch as s, buildDocsSearchDocuments as t, emitDocsAnalyticsEvent as u };