@salesforce/b2c-tooling-sdk 1.17.0 → 1.19.0

package/dist/esm/docs/search.d.ts

@@ -1,70 +1,143 @@
-import { type DocEntry, type SearchIndex, type SearchResult } from './types.js';
+import type { ProjectType } from '../discovery/types.js';
+import { type DocCategory, type DocEntry, type SearchIndex, type SearchResult } from './types.js';
 /**
- * Loads the pre-built search index from the bundled data directories.
+ * The canonical list of documentation categories, in a stable display order.
+ * Exported so the CLI and MCP surfaces validate against a single source of truth
+ * instead of maintaining their own copies. Derived from {@link CATEGORY_TAXONOMY}.
+ */
+export declare const DOC_CATEGORIES: readonly DocCategory[];
+/**
+ * Parses and validates a user-supplied set of documentation categories into a
+ * "topics" allowlist that bounds the entire available corpus (see
+ * {@link SearchDocsOptions.enabledCategories}). Accepts a comma-separated string
+ * or an array; names are trimmed and lower-cased.
  *
- * Combines the Script API documentation corpus with the standard job-step
- * reference so both are searchable through the same functions.
+ * Unknown names are dropped (and reported via `onInvalid`, if provided). Returns
+ * `undefined` when the input is empty or contains no valid categories, which
+ * means "no restriction" — matching the tolerant behavior of the MCP `--toolsets`
+ * flag, so a typo yields a warning and the full corpus rather than a dead tool.
+ *
+ * @param input - Comma-separated category names, or an array of names
+ * @param onInvalid - Optional callback invoked with any unrecognized names
+ * @returns The validated, de-duplicated categories, or `undefined` for no restriction
+ */
+export declare function resolveEnabledCategories(input: string | readonly string[] | undefined, onInvalid?: (invalid: string[]) => void): DocCategory[] | undefined;
+/**
+ * Computes the set of doc categories relevant to the given workspace marker(s):
+ * the always-relevant categories plus the union of each marker's categories
+ * (merged, not summed).
+ */
+export declare function categoriesForWorkspace(workspace: ProjectType | ProjectType[]): DocCategory[];
+/**
+ * Loads the combined search index from every bundled corpus directory.
+ *
+ * Combines the Script API reference, standard job steps, Developer Center
+ * guides, and this project's own docs so all are searchable through the same
+ * functions. Corpora that have not been generated are skipped.
  *
  * @returns The combined search index with all documentation entries
- * @throws Error if the Script API index file cannot be read
  */
 export declare function loadSearchIndex(): SearchIndex;
 /**
- * Searches the documentation index with fuzzy matching.
+ * Options for {@link searchDocs}.
+ */
+export interface SearchDocsOptions {
+    /** Maximum number of results to return (default: 20). */
+    limit?: number;
+    /** Restrict results to one or more corpora/categories (hard filter). */
+    category?: DocCategory | DocCategory[];
+    /**
+     * The current workspace marker(s) (e.g. from workspace detection). When set,
+     * the categories relevant to those markers rank higher (always a boost — never
+     * hides anything). To hard-scope instead, use {@link SearchDocsOptions.category}
+     * or {@link SearchDocsOptions.enabledCategories}.
+     */
+    workspace?: ProjectType | ProjectType[];
+    /**
+     * A hard allowlist of categories that bounds the ENTIRE available corpus for
+     * this call — a configuration boundary, distinct from the per-query
+     * {@link SearchDocsOptions.category} filter and the soft workspace boost.
+     *
+     * When set, only entries in these categories are ever eligible; any `category`
+     * narrows *within* this set (their intersection wins). Intended to be resolved
+     * once from a launch-time flag/env var (see {@link resolveEnabledCategories}) so
+     * operators can pin the docs surface to exactly the topics they want exposed.
+     * `undefined` means no restriction.
+     */
+    enabledCategories?: readonly DocCategory[];
+}
+/**
+ * Searches the combined documentation index.
+ *
+ * Higher scores are better. Results carry the full {@link DocEntry} (including
+ * `category`, `summary`, `keywords`, and `url` when available) so callers can
+ * triage matches without a follow-up read.
+ *
+ * When `workspace` is provided, the categories relevant to those markers (e.g.
+ * `sfra` for an SFRA project, `script-api`/`job-step` for any cartridge project,
+ * `pwa-kit-managed-runtime`/`commerce-api` for PWA Kit, `sfnext`/`commerce-api`
+ * for Storefront Next — plus the always-relevant docs) are boosted. It only ever
+ * reorders results; use `category`/`enabledCategories` to hard-scope.
  *
  * @param query - The search query string
- * @param limit - Maximum number of results to return (default: 20)
- * @returns Array of search results sorted by relevance
+ * @param limitOrOptions - Result limit (number) or {@link SearchDocsOptions}
+ * @returns Array of search results sorted by relevance (best first)
  *
  * @example
  * ```typescript
- * const results = searchDocs('ProductMgr');
- * results.forEach(r => console.log(r.entry.id, r.score));
+ * // Favor the current workspace's docs (nothing hidden)
+ * searchDocs('deploy bundle', {workspace: 'pwa-kit-v3'});
+ * // Hard-scope to one category instead
+ * searchDocs('components', {category: 'sfnext'});
  * ```
  */
-export declare function searchDocs(query: string, limit?: number): SearchResult[];
+export declare function searchDocs(query: string, limitOrOptions?: number | SearchDocsOptions): SearchResult[];
 /**
- * Reads the content of a documentation file by its ID.
+ * Lists documentation entries, optionally filtered by category.
  *
- * @param id - The documentation ID (filename without .md extension)
- * @returns The raw markdown content of the document
- * @throws Error if the document is not found
+ * @param category - Optional corpus/category (or list) to restrict to
+ * @param enabledCategories - Optional launch-time allowlist that bounds the
+ *   entire corpus (see {@link SearchDocsOptions.enabledCategories}). When set,
+ *   only entries in these categories are eligible; `category` narrows within it.
+ * @returns Array of matching documentation entries
+ */
+export declare function listDocs(category?: DocCategory | DocCategory[], enabledCategories?: readonly DocCategory[]): DocEntry[];
+/**
+ * Reads the full content of a documentation entry by its exact id.
  *
- * @example
- * ```typescript
- * const content = readDoc('dw.catalog.ProductMgr');
- * console.log(content);
- * ```
+ * Bundled entries are read from disk. Entries whose content is published online
+ * (Developer Center guides) are fetched from their canonical URL; on network
+ * failure a readable fallback assembled from the indexed metadata is returned.
+ *
+ * @param id - The documentation id
+ * @returns The document content (markdown)
+ * @throws Error if the id is unknown
+ */
+export declare function readDoc(id: string): Promise<string>;
+/**
+ * Reads the content of a resolved {@link DocEntry}, choosing bundled-file vs.
+ * online fetch based on whether the entry ships its content on disk.
  */
-export declare function readDoc(id: string): string;
+export declare function readEntryContent(entry: DocEntry): Promise<string>;
 /**
  * Reads documentation by fuzzy-matching the query and returning the best match.
  *
  * @param query - The search query string
+ * @param options - Optional search constraints (e.g. category)
  * @returns The best matching entry and its content, or null if no match
  *
  * @example
  * ```typescript
- * const doc = readDocByQuery('ProductMgr');
- * if (doc) {
- *   console.log(`Found: ${doc.entry.title}`);
- *   console.log(doc.content);
- * }
+ * const doc = await readDocByQuery('ProductMgr');
+ * if (doc) console.log(doc.content);
  * ```
  */
-export declare function readDocByQuery(query: string): {
+export declare function readDocByQuery(query: string, options?: SearchDocsOptions): Promise<{
     entry: DocEntry;
     content: string;
-} | null;
+} | null>;
 /**
- * Lists all available documentation entries.
- *
- * @returns Array of all documentation entries in the index
- *
- * @example
- * ```typescript
- * const docs = listDocs();
- * console.log(`${docs.length} documentation files available`);
- * ```
+ * Resets the in-memory index/search caches. Intended for tests that swap the
+ * bundled data on disk between assertions.
  */
-export declare function listDocs(): DocEntry[];
+export declare function resetDocsCache(): void;