@farming-labs/docs 0.2.119 → 0.2.121

package/dist/search.d.mts

@@ -0,0 +1,210 @@
+import { AlgoliaDocsSearchConfig, CustomDocsSearchConfig, DocsAccessPrincipal, DocsAskAIMcpConfig, DocsContentSnapshot, DocsPaginatedSearchResponse, DocsSearchAdapter, DocsSearchAdapterFactory, DocsSearchChunkingConfig, DocsSearchConfig, DocsSearchDocument, DocsSearchFacetsResponse, DocsSearchFilterField, DocsSearchFilterInput, DocsSearchFilters, DocsSearchRequest, DocsSearchResult, DocsSearchSourcePage, McpDocsSearchConfig, TypesenseDocsSearchConfig } from "./types.mjs";
+import { DocsContentAudience } from "./audience-exposure.mjs";
+
+//#region src/search.d.ts
+interface DocsAskAIContextResult extends DocsSearchResult {
+  title: string;
+  contextContent: string;
+}
+interface DocsAskAIContext {
+  context: string;
+  /** Structured production context blocks; avoids reparsing markdown horizontal rules. */
+  blocks: Array<{
+    text: string;
+    result: DocsAskAIContextResult;
+  }>;
+  results: DocsAskAIContextResult[];
+  searchResults: DocsSearchResult[];
+  packageHints: DocsAskAIPackageHints;
+}
+interface DocsAskAIPackageHints {
+  packages: string[];
+  imports: string[];
+  installCommands: string[];
+}
+/** Normalize scalar or array-valued scope filters for programmatic, HTTP, and MCP callers. */
+declare function normalizeDocsSearchFilters(input?: DocsSearchFilterInput | DocsSearchFilters): DocsSearchFilters;
+/** Parse the public search scope parameters from a URL query string. */
+declare function resolveDocsSearchFilters(searchParams: URLSearchParams): DocsSearchFilters;
+declare class DocsSearchRequestError extends Error {
+  readonly code = "invalid_search_request";
+  constructor(message: string);
+}
+declare function resolveDocsSearchError(error: unknown): {
+  code: "invalid_cursor" | "invalid_search_request";
+  message: string;
+} | undefined;
+/** Resolve search filters and the backwards-compatible structured response opt-in. */
+declare function resolveDocsSearchRequest(searchParams: URLSearchParams): DocsSearchRequest;
+declare function inferDocsAskAIPackageHints(content: string): DocsAskAIPackageHints;
+declare function formatDocsAskAIPackageHints(hints: DocsAskAIPackageHints, packageName?: string): string | undefined;
+/**
+ * Build the exact normalized-input projection represented by a retrieval source digest.
+ * This is public so consumers can independently reproduce `source.digest`.
+ */
+declare function buildDocsRetrievalDigestProjection(page: DocsSearchSourcePage, audience?: DocsContentAudience): string;
+declare function resolveDocsRetrievalLastModified(page: DocsSearchSourcePage, audience: DocsContentAudience): string | undefined;
+interface BuildDocsContentSnapshotOptions {
+  pages: readonly DocsSearchSourcePage[];
+  search?: boolean | DocsSearchConfig;
+  audience?: DocsContentAudience;
+  locale?: string;
+  baseUrl?: string;
+  /** @internal Precomputed complete-corpus generation for composed callers. */
+  indexGeneration?: string;
+  /** Authenticated identity used to scope protected pages. */
+  principal?: DocsAccessPrincipal;
+}
+/**
+ * Build a deterministic, body-free inventory for content-change synchronization.
+ *
+ * Its generation is identical to structured search for the same pages, audience,
+ * locale, base URL, and chunking policy.
+ */
+declare function buildDocsContentSnapshot(options: BuildDocsContentSnapshotOptions): Promise<DocsContentSnapshot>;
+interface EnrichDocsSearchDocumentsWithProvenanceOptions {
+  documents: readonly DocsSearchDocument[];
+  pages: readonly DocsSearchSourcePage[];
+  audience?: DocsContentAudience;
+  chunking?: DocsSearchChunkingConfig;
+  locale?: string;
+  baseUrl?: string;
+  indexGeneration?: string;
+}
+/**
+ * Attach the same canonical provenance used by built-in search providers.
+ * Custom adapters can call this before persisting their own hosted records.
+ */
+declare function enrichDocsSearchDocumentsWithProvenance(options: EnrichDocsSearchDocumentsWithProvenanceOptions): Promise<DocsSearchDocument[]>;
+declare function buildDocsSearchDocuments(pages: DocsSearchSourcePage[], chunking?: DocsSearchChunkingConfig, audience?: DocsContentAudience): DocsSearchDocument[];
+declare function createSimpleSearchAdapter(): DocsSearchAdapter;
+declare function createTypesenseSearchAdapter(config: TypesenseDocsSearchConfig): DocsSearchAdapter;
+declare function resolveSearchRequestConfig(search: boolean | DocsSearchConfig | undefined, requestUrl?: string, options?: DocsSearchRequestResolutionOptions): boolean | DocsSearchConfig | undefined;
+interface DocsLocalMcpSearchRuntimeConfig {
+  enabled?: boolean;
+  route?: string;
+  tools?: {
+    searchDocs?: boolean;
+  };
+}
+type DocsLocalMcpSearchRuntimeInput = boolean | DocsLocalMcpSearchRuntimeConfig | null | undefined;
+interface DocsSearchRequestResolutionOptions {
+  /**
+   * The built-in MCP server colocated with this search handler. When the configured
+   * provider points at one of its local aliases, search runs directly instead of
+   * performing a loopback MCP handshake.
+   */
+  localMcp?: DocsLocalMcpSearchRuntimeInput;
+}
+declare function resolveLocalDocsMcpSearchConfig(search: boolean | DocsSearchConfig | undefined, localMcp: DocsLocalMcpSearchRuntimeInput, requestUrl?: string): boolean | DocsSearchConfig | undefined;
+/**
+ * Resolve the public search audience without allowing malformed values to opt into agent content.
+ * Human search remains the default for omitted, legacy, and unknown query values.
+ */
+declare function resolveDocsSearchAudience(value: string | null | undefined): DocsContentAudience;
+declare function resolveAskAISearchRequestConfig(options: {
+  search: boolean | DocsSearchConfig | undefined;
+  useMcp?: boolean | DocsAskAIMcpConfig;
+  mcpEndpoint?: string;
+  mcpEnabled?: boolean;
+  mcpSearchEnabled?: boolean;
+  requestUrl?: string;
+}): boolean | DocsSearchConfig | undefined;
+declare function createMcpSearchAdapter(config: McpDocsSearchConfig): DocsSearchAdapter;
+declare function createAlgoliaSearchAdapter(config: AlgoliaDocsSearchConfig): DocsSearchAdapter;
+interface PerformDocsSearchOptions {
+  pages: DocsSearchSourcePage[];
+  /** Authenticated identity used to scope protected pages before local or hosted indexing. */
+  principal?: DocsAccessPrincipal;
+  /** @internal Complete corpus used for generation when `pages` is pre-scoped by a caller. */
+  generationPages?: DocsSearchSourcePage[];
+  /** @internal Precomputed complete-corpus generation for structured callers. */
+  indexGeneration?: string;
+  query: string;
+  search?: boolean | DocsSearchConfig;
+  /** Selects which audience projection is searchable. Public site search defaults to human. */
+  audience?: DocsContentAudience;
+  locale?: string;
+  pathname?: string;
+  siteTitle?: string;
+  /** Canonical docs URL used to distinguish same-site absolute hits from foreign MCP results. */
+  baseUrl?: string;
+  /**
+   * Canonical origin safe to persist in a hosted index. Pass `null` when `baseUrl`
+   * came from the current request rather than trusted configuration.
+   * @internal
+   */
+  syncBaseUrl?: string | null;
+  limit?: number;
+  /** Opaque continuation cursor used by structured search responses. */
+  cursor?: string;
+  /** Optional framework, version, package, and tag constraints. */
+  filters?: DocsSearchFilterInput;
+  /** Include bounded explanations for the final ranked results. Defaults to false. */
+  explain?: boolean;
+  /**
+   * Controls provider failures. Runtime search keeps the resilient `fallback` default;
+   * diagnostics can request `throw` so a broken configured provider cannot be scored as
+   * successful simple search.
+   */
+  failureMode?: "fallback" | "throw";
+  /**
+   * Whether non-simple provider hits are supplemented with exact/local simple results.
+   * Runtime search defaults to true; provider diagnostics can disable supplementation.
+   */
+  supplementExternalResults?: boolean;
+  /** Keep absolute provider origins distinct when no canonical docs origin is available. */
+  strictExternalOrigins?: boolean;
+  /** Optional cancellation signal forwarded to adapters and their managed requests. */
+  signal?: AbortSignal;
+}
+declare function performDocsSearch(options: PerformDocsSearchOptions): Promise<DocsSearchResult[]>;
+interface BuildDocsSearchFacetsOptions {
+  pages: DocsSearchSourcePage[];
+  search?: boolean | DocsSearchConfig;
+  audience?: DocsContentAudience;
+  locale?: string;
+  baseUrl?: string;
+  filters?: DocsSearchFilterInput;
+  /** Facet field selected for cursor continuation. */
+  facet?: DocsSearchFilterField;
+  /** Opaque `nextCursor` returned for the selected facet. */
+  cursor?: string;
+  /** Maximum facet values returned per page. Defaults to 100. */
+  limit?: number;
+  /** @internal Precomputed complete-corpus generation for composed callers. */
+  indexGeneration?: string;
+  /** Authenticated identity used to scope protected pages. */
+  principal?: DocsAccessPrincipal;
+}
+/**
+ * Build a body-free index of valid search filter values and page counts.
+ *
+ * Each facet applies filters from the other fields while ignoring its own selected
+ * values. This is the conventional faceted-search behavior and lets an agent discover
+ * safe alternatives without guessing or fetching document bodies.
+ */
+declare function buildDocsSearchFacets(options: BuildDocsSearchFacetsOptions): Promise<DocsSearchFacetsResponse>;
+declare function performDocsSearchWithMetadata(options: PerformDocsSearchOptions): Promise<DocsPaginatedSearchResponse>;
+declare function buildDocsAskAIContext(options: {
+  pages: DocsSearchSourcePage[];
+  query: string;
+  search?: boolean | DocsSearchConfig;
+  locale?: string;
+  pathname?: string;
+  siteTitle?: string;
+  baseUrl?: string; /** See `performDocsSearch.syncBaseUrl`. */
+  syncBaseUrl?: string | null;
+  limit?: number;
+  filters?: DocsSearchFilterInput;
+  maxContextChars?: number;
+  maxResultChars?: number; /** See `performDocsSearch.failureMode`. Defaults to resilient runtime fallback. */
+  searchFailureMode?: "fallback" | "throw"; /** See `performDocsSearch.strictExternalOrigins`. */
+  strictExternalOrigins?: boolean; /** Optional cancellation signal forwarded to the configured search provider. */
+  signal?: AbortSignal;
+}): Promise<DocsAskAIContext>;
+declare function createCustomSearchAdapter(adapter: DocsSearchAdapter | DocsSearchAdapterFactory, options?: {
+  paginationRevision?: string;
+}): CustomDocsSearchConfig;
+//#endregion
+export { BuildDocsContentSnapshotOptions, BuildDocsSearchFacetsOptions, DocsLocalMcpSearchRuntimeConfig, DocsLocalMcpSearchRuntimeInput, DocsSearchRequestError, DocsSearchRequestResolutionOptions, EnrichDocsSearchDocumentsWithProvenanceOptions, PerformDocsSearchOptions, buildDocsAskAIContext, buildDocsContentSnapshot, buildDocsRetrievalDigestProjection, buildDocsSearchDocuments, buildDocsSearchFacets, createAlgoliaSearchAdapter, createCustomSearchAdapter, createMcpSearchAdapter, createSimpleSearchAdapter, createTypesenseSearchAdapter, enrichDocsSearchDocumentsWithProvenance, formatDocsAskAIPackageHints, inferDocsAskAIPackageHints, normalizeDocsSearchFilters, performDocsSearch, performDocsSearchWithMetadata, resolveAskAISearchRequestConfig, resolveDocsRetrievalLastModified, resolveDocsSearchAudience, resolveDocsSearchError, resolveDocsSearchFilters, resolveDocsSearchRequest, resolveLocalDocsMcpSearchConfig, resolveSearchRequestConfig };