@farming-labs/docs 0.2.77 → 0.2.78

package/dist/{types-B-5Kzmkn.d.mts → types-CpLnwHak.d.mts}

@@ -825,7 +825,7 @@ interface DocsAnalyticsConfig {
 }
 type DocsTelemetryFramework = "next" | "tanstack-start" | "sveltekit" | "astro" | "nuxt" | "mcp" | (string & {});
 type DocsTelemetryEventType = "project_detected" | "agent_surface_used" | "mcp_request" | "mcp_tool_used" | (string & {});
-type DocsTelemetryAgentSurface = "agent_spec" | "agents" | "skill" | "markdown" | "llms" | "agent_feedback_schema" | "agent_feedback_submit" | "ask_ai" | "mcp";
+type DocsTelemetryAgentSurface = "agent_spec" | "agents" | "skill" | "markdown" | "llms" | "agent_feedback_schema" | "agent_feedback_submit" | "content_changes" | "ask_ai" | "mcp";
 interface DocsTelemetryConfig {
   /** Enable Farming Labs maintainer telemetry. Defaults to production-only enabled. */
   enabled?: boolean;
@@ -845,6 +845,7 @@ interface DocsTelemetryConfig {
 }
 interface DocsTelemetryFeatures {
   search: boolean;
+  contentChanges: boolean;
   ai: boolean;
   mcp: boolean;
   llmsTxt: boolean;
@@ -1201,6 +1202,11 @@ interface DocsMcpToolsConfig {
   readTask?: boolean;
   /** Expose a `search_docs` tool for keyword search over page content. */
   searchDocs?: boolean;
+  /**
+   * Expose a `list_search_facets` tool that returns valid framework, version,
+   * package, and tag values before an agent runs a scoped search.
+   */
+  searchFacets?: boolean;
   /** Expose a `get_navigation` tool for the docs tree. */
   getNavigation?: boolean;
   /** Expose a `get_code_examples` tool for fenced code blocks and their metadata. */
@@ -1377,6 +1383,67 @@ interface DocsRetrievalSourceProvenance {
   digest: string;
   indexGeneration: string;
 }
+/** One canonical document in a content-change snapshot. */
+interface DocsContentSnapshotDocument {
+  /** Framework route that produced this canonical document. */
+  url: string;
+  canonicalUrl: string;
+  /** SHA-256 of the body digest plus fetch-relevant page metadata. */
+  digest: string;
+  lastModified?: string;
+}
+/**
+ * Serializable content inventory stored by the optional durable change-feed callbacks.
+ *
+ * The snapshot contains metadata only, never document bodies.
+ */
+interface DocsContentSnapshot {
+  format: "docs-content-snapshot.v1";
+  audience: "human" | "agent";
+  locale?: string;
+  baseUrl?: string;
+  indexGeneration: string;
+  documents: DocsContentSnapshotDocument[];
+}
+/** Added or removed document metadata in a content-change response. */
+type DocsContentChangeDocument = DocsContentSnapshotDocument;
+/** Changed document metadata, including the immediately compared prior digest. */
+interface DocsContentChangedDocument extends DocsContentChangeDocument {
+  previousDigest: string;
+  previousLastModified?: string;
+}
+/**
+ * Body-free synchronization response for documentation agents.
+ *
+ * `resetRequired` is explicit because a bare SHA-256 generation cannot reconstruct
+ * history that was never retained by this process or a configured durable store.
+ */
+interface DocsContentChangesResponse {
+  format: "docs-content-changes.v1";
+  audience: "human" | "agent";
+  locale?: string;
+  since: string | null;
+  indexGeneration: string;
+  mode: "snapshot" | "delta" | "reset";
+  resetRequired: boolean;
+  documentCount: number;
+  counts: {
+    added: number;
+    changed: number;
+    deleted: number;
+  };
+  added: DocsContentChangeDocument[];
+  changed: DocsContentChangedDocument[];
+  deleted: DocsContentChangeDocument[];
+}
+interface DocsContentChangeSnapshotContext {
+  audience: "human" | "agent";
+  locale?: string;
+  baseUrl?: string;
+  request?: Request;
+}
+type DocsContentChangeSnapshotLoader = (generation: string, context: DocsContentChangeSnapshotContext) => DocsContentSnapshot | null | undefined | Promise<DocsContentSnapshot | null | undefined>;
+type DocsContentChangeSnapshotSaver = (snapshot: DocsContentSnapshot, context: DocsContentChangeSnapshotContext) => void | Promise<void>;
 interface DocsSearchDocument {
   id: string;
   url: string;
@@ -1418,6 +1485,40 @@ interface DocsSearchFilters {
   package?: string[];
   tags?: string[];
 }
+/** One selectable search-scope value and the number of matching source pages. */
+interface DocsSearchFacetValue {
+  value: string;
+  count: number;
+}
+/** Cursor-aware values for one search-scope field. */
+interface DocsSearchFacet {
+  /** Number of distinct values before the response limit is applied. */
+  valueCount: number;
+  /** Total number of distinct values. Alias of `valueCount` for pagination clients. */
+  total: number;
+  /** Whether another page can be requested with `nextCursor`. */
+  hasMore: boolean;
+  /** Opaque cursor for the next page. Omitted when this is the final page. */
+  nextCursor?: string;
+  /** Whether this page omits any values from the complete facet. */
+  truncated: boolean;
+  values: DocsSearchFacetValue[];
+}
+/**
+ * Cheap, body-free discovery response for the search scopes available in an index.
+ *
+ * Counts for each facet apply the other selected filters but intentionally ignore
+ * the selected values for that same field, so agents can discover alternatives.
+ */
+interface DocsSearchFacetsResponse {
+  format: "docs-search-facets.v1";
+  audience: "human" | "agent";
+  filters: DocsSearchFilters;
+  indexGeneration: string;
+  /** Number of source pages matching every selected filter. */
+  matchedPageCount: number;
+  facets: Record<DocsSearchFilterField, DocsSearchFacet>;
+}
 type DocsSearchWarningCode = "ambiguous_scope" | "unknown_filter_value" | "missing_scope_metadata" | "conflicting_scope_metadata";
 interface DocsSearchWarning {
   code: DocsSearchWarningCode;
@@ -1468,9 +1569,13 @@ interface DocsPaginatedSearchResponse extends DocsSearchResponse {
 interface DocsSearchRequest {
   filters: DocsSearchFilters;
   structured: boolean;
-  /** Opaque cursor supplied by a previous structured response. */
+  /** Whether the caller requested the body-free search facet response. */
+  facets?: boolean;
+  /** Facet field selected for cursor continuation. */
+  facet?: DocsSearchFilterField;
+  /** Opaque cursor supplied by a previous structured or facet response. */
   cursor?: string;
-  /** Structured response page size. */
+  /** Structured result or facet value page size. */
   limit?: number;
 }
 interface DocsSearchQuery {
@@ -2954,9 +3059,25 @@ interface DocsAgentConfig {
   evaluations?: boolean | DocsAgentEvaluationsConfig;
   /** Publish reusable Agent Skills through standards discovery, static exports, and MCP. */
   skills?: DocsAgentSkillsInput;
+  /**
+   * Body-free document synchronization feed. Enabled for runtime adapters by default.
+   *
+   * Configure snapshot callbacks when exact deltas must survive server restarts or deployments.
+   */
+  contentChanges?: boolean | DocsAgentContentChangesConfig;
   /** Opt in to an A2A Agent Card for a separately implemented A2A service. */
   a2a?: DocsAgentA2AConfig;
 }
+interface DocsAgentContentChangesConfig {
+  /** Disable the runtime content-change endpoint. @default true */
+  enabled?: boolean;
+  /** Number of metadata-only snapshots retained in this server process. @default 8 */
+  maxSnapshots?: number;
+  /** Load an older snapshot from a durable store for exact cross-deployment deltas. */
+  loadSnapshot?: DocsContentChangeSnapshotLoader;
+  /** Persist the current snapshot to a durable store. */
+  saveSnapshot?: DocsContentChangeSnapshotSaver;
+}
 type DocsReviewSeverity = "off" | "suggestion" | "warn" | "error";
 type DocsReviewCiMode = "off" | "warn" | "block";
 interface DocsReviewRulesConfig {
@@ -3685,4 +3806,4 @@ interface DocsConfig {
   og?: OGConfig;
 }
 //#endregion
-export { DocsAgentSkillsInput as $, PageAgentAppliesTo as $n, DocsReviewCiConfig as $t, DocsAgentA2ASecurityScheme as A, DocsTelemetryEventInput as An, DocsFeedbackData as At, DocsAgentEvaluationSourceReference as B, LlmsTxtMaxCharsConfig as Bn, DocsMcpOriginContext as Bt, DocsAgentA2AOAuthDeviceCodeFlow as C, DocsSearchSourcePage as Cn, DocsCodeBlocksPlannerProvider as Ct, DocsAgentA2AOpenIdConnectSecurityScheme as D, DocsTelemetryAgentSurface as Dn, DocsCodeBlocksValidationMode as Dt, DocsAgentA2AOAuthPasswordFlow as E, DocsSitemapConfig as En, DocsCodeBlocksValidateConfig as Et, DocsAgentEvaluationAnswerInput as F, FeedbackConfig as Fn, DocsMcpAuthenticate as Ft, DocsAgentFeedbackData as G, OpenDocsConfig as Gn, DocsNav as Gt, DocsAgentEvaluationTaskInput as H, LlmsTxtSectionConfig as Hn, DocsMcpSecurityConfig as Ht, DocsAgentEvaluationAnswerProvider as I, FontStyle as In, DocsMcpAuthenticateContext as It, DocsAgentGoldenExpectedExample as J, OpenDocsProviderId as Jn, DocsObservabilityEventInput as Jt, DocsAgentGoldenAnswerExpectation as K, OpenDocsProvider as Kn, DocsObservabilityConfig as Kt, DocsAgentEvaluationAnswerRequest as L, GithubConfig as Ln, DocsMcpAuthenticateResult as Lt, DocsAgentA2ASkill as M, DocsTelemetryFeatures as Mn, DocsI18nConfig as Mt, DocsAgentCompactConfig as N, DocsTelemetryFramework as Nn, DocsMcpAllowedOrigins as Nt, DocsAgentA2AProtocolBinding as O, DocsTelemetryConfig as On, DocsCodeBlocksValidationPolicy as Ot, DocsAgentConfig as P, DocsTheme as Pn, DocsMcpAuthPrincipal as Pt, DocsAgentSkillsConfig as Q, PageActionsConfig as Qn, DocsRetrievalSourceScope as Qt, DocsAgentEvaluationAnswerResult as R, LastUpdatedConfig as Rn, DocsMcpConfig as Rt, DocsAgentA2AOAuthClientCredentialsFlow as S, DocsSearchResultType as Sn, UIConfig as Sr, DocsCodeBlocksPlannerConfig as St, DocsAgentA2AOAuthImplicitFlow as T, DocsSearchWarningCode as Tn, DocsCodeBlocksRunnerProvider as Tt, DocsAgentEvaluationsConfig as U, McpDocsSearchConfig as Un, DocsMcpToolsConfig as Ut, DocsAgentEvaluationSurface as V, LlmsTxtMaxCharsMode as Vn, DocsMcpProtectedResourceConfig as Vt, DocsAgentFeedbackContext as W, OGConfig as Wn, DocsMetadata as Wt, DocsAgentGoldenTaskExpectation as X, OpenGraphImage as Xn, DocsRelatedItem as Xt, DocsAgentGoldenTask as Y, OpenDocsTarget as Yn, DocsPaginatedSearchResponse as Yt, DocsAgentGoldenTaskFilters as Z, OrderingItem as Zn, DocsRetrievalSourceProvenance as Zt, DocsAgentA2AHttpAuthSecurityScheme as _, DocsSearchFilters as _n, SidebarTree as _r, DocsCloudConfig as _t, ApiReferenceRenderer as a, DocsRobotsConfig as an, PageOpenGraph as ar, DocsAnalyticsEventInput as at, DocsAgentA2AOAuth2SecurityScheme as b, DocsSearchResponse as bn, TypesenseDocsSearchConfig as br, DocsCloudPublishConfig as bt, ChangelogFrontmatter as c, DocsSearchAdapterContext as cn, ReadingTimeConfig as cr, DocsAnalyticsSource as ct, CopyMarkdownFormat as d, DocsSearchChunkingConfig as dn, SidebarComponentProps as dr, DocsAskAIFeedbackConfig as dt, DocsReviewCiMode as en, PageAgentCommand as er, DocsAgentTraceEventInput as et, CustomDocsSearchConfig as f, DocsSearchConfig as fn, SidebarConfig as fr, DocsAskAIFeedbackData as ft, DocsAgentA2AExtension as g, DocsSearchFilterInput as gn, SidebarPageNode as gr, DocsCloudApiKeyConfig as gt, DocsAgentA2AConfig as h, DocsSearchFilterField as hn, SidebarNode as hr, DocsAskAIMcpConfig as ht, ApiReferenceConfig as i, DocsReviewSeverity as in, PageFrontmatter as ir, DocsAnalyticsEvent as it, DocsAgentA2ASecurityScopeList as j, DocsTelemetryEventType as jn, DocsFeedbackValue as jt, DocsAgentA2ASecurityRequirement as k, DocsTelemetryEvent as kn, DocsConfig as kt, CodeBlockCopyData as l, DocsSearchAdapterFactory as ln, ReadingTimeFormat as lr, DocsAskAIActionData as lt, DocsAgentA2ACapabilities as m, DocsSearchEmbeddingsConfig as mn, SidebarFolderNode as mr, DocsAskAIFeedbackValue as mt, AgentFeedbackConfig as n, DocsReviewRulesConfig as nn, PageAgentFrontmatter as nr, DocsAgentTraceStatus as nt, BreadcrumbConfig as o, DocsRobotsRule as on, PageSidebarFrontmatter as or, DocsAnalyticsEventType as ot, DocsAgentA2AApiKeySecurityScheme as p, DocsSearchDocument as pn, SidebarFolderIndexBehavior as pr, DocsAskAIFeedbackMessage as pt, DocsAgentGoldenExampleVerification as q, OpenDocsProviderConfig as qn, DocsObservabilityEvent as qt, AlgoliaDocsSearchConfig as r, DocsReviewScoreConfig as rn, PageAgentVerification as rr, DocsAnalyticsConfig as rt, ChangelogConfig as s, DocsSearchAdapter as sn, PageTwitter as sr, DocsAnalyticsInput as st, AIConfig as t, DocsReviewConfig as tn, PageAgentFailureMode as tr, DocsAgentTraceEventType as tt, CopyMarkdownConfig as u, DocsSearchAdapterPage as un, ResolvedDocsRelatedLink as ur, DocsAskAIActionType as ut, DocsAgentA2AInterfaceConfig as v, DocsSearchQuery as vn, SimpleDocsSearchConfig as vr, DocsCloudFeatureConfig as vt, DocsAgentA2AOAuthFlows as w, DocsSearchWarning as wn, DocsCodeBlocksRunnerConfig as wt, DocsAgentA2AOAuthAuthorizationCodeFlow as x, DocsSearchResult as xn, TypographyConfig as xr, DocsCodeBlocksConfig as xt, DocsAgentA2AMutualTlsSecurityScheme as y, DocsSearchRequest as yn, ThemeToggleConfig as yr, DocsCloudPreviewConfig as yt, DocsAgentEvaluationAnswerRunner as z, LlmsTxtConfig as zn, DocsMcpCorsConfig as zt };
+export { DocsAgentSkillsConfig as $, LlmsTxtMaxCharsMode as $n, DocsMetadata as $t, DocsAgentA2ASecurityScheme as A, DocsSearchQuery as An, SimpleDocsSearchConfig as Ar, DocsConfig as At, DocsAgentEvaluationAnswerRunner as B, DocsTelemetryConfig as Bn, DocsFeedbackValue as Bt, DocsAgentA2AOAuthDeviceCodeFlow as C, DocsSearchEmbeddingsConfig as Cn, SidebarComponentProps as Cr, DocsCodeBlocksPlannerConfig as Ct, DocsAgentA2AOpenIdConnectSecurityScheme as D, DocsSearchFilterField as Dn, SidebarNode as Dr, DocsCodeBlocksValidateConfig as Dt, DocsAgentA2AOAuthPasswordFlow as E, DocsSearchFacetsResponse as En, SidebarFolderNode as Er, DocsCodeBlocksRunnerProvider as Et, DocsAgentContentChangesConfig as F, DocsSearchSourcePage as Fn, DocsContentChangedDocument as Ft, DocsAgentFeedbackContext as G, DocsTelemetryFramework as Gn, DocsMcpAuthenticateContext as Gt, DocsAgentEvaluationSurface as H, DocsTelemetryEventInput as Hn, DocsMcpAllowedOrigins as Ht, DocsAgentEvaluationAnswerInput as I, DocsSearchWarning as In, DocsContentChangesResponse as It, DocsAgentGoldenExampleVerification as J, FontStyle as Jn, DocsMcpCorsConfig as Jt, DocsAgentFeedbackData as K, DocsTheme as Kn, DocsMcpAuthenticateResult as Kt, DocsAgentEvaluationAnswerProvider as L, DocsSearchWarningCode as Ln, DocsContentSnapshot as Lt, DocsAgentA2ASkill as M, DocsSearchResponse as Mn, TypesenseDocsSearchConfig as Mr, DocsContentChangeSnapshotContext as Mt, DocsAgentCompactConfig as N, DocsSearchResult as Nn, TypographyConfig as Nr, DocsContentChangeSnapshotLoader as Nt, DocsAgentA2AProtocolBinding as O, DocsSearchFilterInput as On, SidebarPageNode as Or, DocsCodeBlocksValidationMode as Ot, DocsAgentConfig as P, DocsSearchResultType as Pn, UIConfig as Pr, DocsContentChangeSnapshotSaver as Pt, DocsAgentGoldenTaskFilters as Q, LlmsTxtMaxCharsConfig as Qn, DocsMcpToolsConfig as Qt, DocsAgentEvaluationAnswerRequest as R, DocsSitemapConfig as Rn, DocsContentSnapshotDocument as Rt, DocsAgentA2AOAuthClientCredentialsFlow as S, DocsSearchDocument as Sn, ResolvedDocsRelatedLink as Sr, DocsCodeBlocksConfig as St, DocsAgentA2AOAuthImplicitFlow as T, DocsSearchFacetValue as Tn, SidebarFolderIndexBehavior as Tr, DocsCodeBlocksRunnerConfig as Tt, DocsAgentEvaluationTaskInput as U, DocsTelemetryEventType as Un, DocsMcpAuthPrincipal as Ut, DocsAgentEvaluationSourceReference as V, DocsTelemetryEvent as Vn, DocsI18nConfig as Vt, DocsAgentEvaluationsConfig as W, DocsTelemetryFeatures as Wn, DocsMcpAuthenticate as Wt, DocsAgentGoldenTask as X, LastUpdatedConfig as Xn, DocsMcpProtectedResourceConfig as Xt, DocsAgentGoldenExpectedExample as Y, GithubConfig as Yn, DocsMcpOriginContext as Yt, DocsAgentGoldenTaskExpectation as Z, LlmsTxtConfig as Zn, DocsMcpSecurityConfig as Zt, DocsAgentA2AHttpAuthSecurityScheme as _, DocsSearchAdapterContext as _n, PageOpenGraph as _r, DocsCloudApiKeyConfig as _t, ApiReferenceRenderer as a, DocsRelatedItem as an, OpenDocsProviderConfig as ar, DocsAnalyticsEvent as at, DocsAgentA2AOAuth2SecurityScheme as b, DocsSearchChunkingConfig as bn, ReadingTimeConfig as br, DocsCloudPreviewConfig as bt, ChangelogFrontmatter as c, DocsReviewCiConfig as cn, OpenGraphImage as cr, DocsAnalyticsInput as ct, CopyMarkdownFormat as d, DocsReviewRulesConfig as dn, PageAgentAppliesTo as dr, DocsAskAIActionType as dt, DocsNav as en, LlmsTxtSectionConfig as er, DocsAgentSkillsInput as et, CustomDocsSearchConfig as f, DocsReviewScoreConfig as fn, PageAgentCommand as fr, DocsAskAIFeedbackConfig as ft, DocsAgentA2AExtension as g, DocsSearchAdapter as gn, PageFrontmatter as gr, DocsAskAIMcpConfig as gt, DocsAgentA2AConfig as h, DocsRobotsRule as hn, PageAgentVerification as hr, DocsAskAIFeedbackValue as ht, ApiReferenceConfig as i, DocsPaginatedSearchResponse as in, OpenDocsProvider as ir, DocsAnalyticsConfig as it, DocsAgentA2ASecurityScopeList as j, DocsSearchRequest as jn, ThemeToggleConfig as jr, DocsContentChangeDocument as jt, DocsAgentA2ASecurityRequirement as k, DocsSearchFilters as kn, SidebarTree as kr, DocsCodeBlocksValidationPolicy as kt, CodeBlockCopyData as l, DocsReviewCiMode as ln, OrderingItem as lr, DocsAnalyticsSource as lt, DocsAgentA2ACapabilities as m, DocsRobotsConfig as mn, PageAgentFrontmatter as mr, DocsAskAIFeedbackMessage as mt, AgentFeedbackConfig as n, DocsObservabilityEvent as nn, OGConfig as nr, DocsAgentTraceEventType as nt, BreadcrumbConfig as o, DocsRetrievalSourceProvenance as on, OpenDocsProviderId as or, DocsAnalyticsEventInput as ot, DocsAgentA2AApiKeySecurityScheme as p, DocsReviewSeverity as pn, PageAgentFailureMode as pr, DocsAskAIFeedbackData as pt, DocsAgentGoldenAnswerExpectation as q, FeedbackConfig as qn, DocsMcpConfig as qt, AlgoliaDocsSearchConfig as r, DocsObservabilityEventInput as rn, OpenDocsConfig as rr, DocsAgentTraceStatus as rt, ChangelogConfig as s, DocsRetrievalSourceScope as sn, OpenDocsTarget as sr, DocsAnalyticsEventType as st, AIConfig as t, DocsObservabilityConfig as tn, McpDocsSearchConfig as tr, DocsAgentTraceEventInput as tt, CopyMarkdownConfig as u, DocsReviewConfig as un, PageActionsConfig as ur, DocsAskAIActionData as ut, DocsAgentA2AInterfaceConfig as v, DocsSearchAdapterFactory as vn, PageSidebarFrontmatter as vr, DocsCloudConfig as vt, DocsAgentA2AOAuthFlows as w, DocsSearchFacet as wn, SidebarConfig as wr, DocsCodeBlocksPlannerProvider as wt, DocsAgentA2AOAuthAuthorizationCodeFlow as x, DocsSearchConfig as xn, ReadingTimeFormat as xr, DocsCloudPublishConfig as xt, DocsAgentA2AMutualTlsSecurityScheme as y, DocsSearchAdapterPage as yn, PageTwitter as yr, DocsCloudFeatureConfig as yt, DocsAgentEvaluationAnswerResult as z, DocsTelemetryAgentSurface as zn, DocsFeedbackData as zt };

package/package.json

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