lumiverse-spindle-types 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -1266,6 +1266,99 @@ export interface PermissionChangedDetail {
   allGranted: string[];
 }
 
+// ─── Web Search DTOs ────────────────────────────────────────────────────
+
+/** Identifies which provider backs the user's configured web search engine. */
+export type WebSearchProviderDTO = "searxng";
+
+/**
+ * Safe view of a user's web search configuration. The raw API key is never
+ * exposed — only `hasApiKey` indicates whether one is on file.
+ */
+export interface WebSearchSettingsDTO {
+  enabled: boolean;
+  provider: WebSearchProviderDTO;
+  apiUrl: string;
+  requestTimeoutMs: number;
+  defaultResultCount: number;
+  maxResultCount: number;
+  maxPagesToScrape: number;
+  maxCharsPerPage: number;
+  language: string;
+  safeSearch: 0 | 1 | 2;
+  engines: string[];
+  hasApiKey: boolean;
+}
+
+/** A single search result row, normalized across providers. */
+export interface WebSearchResultDTO {
+  title: string;
+  url: string;
+  snippet: string;
+  /** Provider-reported engine identifier when available (e.g. `"google"`, `"bing"`). */
+  engine?: string;
+  /** Provider-reported relevance score when available. */
+  score?: number;
+}
+
+/**
+ * A search result enriched with scraped page content. Only present when the
+ * query was run with `scrape: true` (the default).
+ */
+export interface WebSearchDocumentDTO {
+  title: string;
+  url: string;
+  snippet: string;
+  /** How the page content was extracted (e.g. `"html"`, `"pdf"`). */
+  sourceType?: string;
+  /** Extracted page text, clipped to `WebSearchSettingsDTO.maxCharsPerPage`. */
+  content?: string;
+  /** Length of the source page content before clipping. */
+  contentLength?: number;
+  /** Populated when scraping failed for this result; `content` is then absent. */
+  error?: string;
+}
+
+/** Options forwarded to `spindle.webSearch.query()`. */
+export interface WebSearchRequestDTO {
+  /** Free-text search query. Trimmed by the host; empty values are rejected. */
+  query: string;
+  /**
+   * Desired number of results. Clamped to `WebSearchSettingsDTO.maxResultCount`
+   * on the host; omit to use the user's `defaultResultCount`.
+   */
+  count?: number;
+  /**
+   * When `true` (default), the host scrapes the first
+   * `WebSearchSettingsDTO.maxPagesToScrape` results, fills in
+   * `documents[].content`, and assembles the `context` block. Set to `false`
+   * to skip scraping entirely — only `results` are returned, and
+   * `documents` / `context` are omitted from the response. Useful when the
+   * extension only needs titles, URLs, and snippets.
+   */
+  scrape?: boolean;
+  /** For operator-scoped extensions; ignored on user-scoped extensions. */
+  userId?: string;
+}
+
+/**
+ * Result of a successful `spindle.webSearch.query()` call. `documents` and
+ * `context` are omitted when the request was issued with `scrape: false`.
+ */
+export interface WebSearchResponseDTO {
+  /** The (trimmed) query that was executed. */
+  query: string;
+  /** Raw normalized results from the search provider. */
+  results: WebSearchResultDTO[];
+  /** Per-result scraped page content. Absent when `scrape: false`. */
+  documents?: WebSearchDocumentDTO[];
+  /**
+   * Pre-assembled, prompt-ready context block summarizing the query plus the
+   * scraped documents. Absent when `scrape: false`.
+   */
+  context?: string;
+}
+
 // ─── Theme DTOs ──────────────────────────────────────────────────────────
 
 /**
@@ -2448,7 +2541,17 @@ export type WorkerToHost =
       model?: string;
       modelSource?: TokenModelSourceDTO;
       userId?: string;
-    };
+    }
+  // ─── Web Search (gated: "web_search") ─────────────────────────────────
+  | {
+      type: "web_search_query";
+      requestId: string;
+      query: string;
+      count?: number;
+      scrape?: boolean;
+      userId?: string;
+    }
+  | { type: "web_search_get_settings"; requestId: string; userId?: string };
 
 // ─── Host → Worker messages ──────────────────────────────────────────────
 

package/src/index.ts

@@ -155,6 +155,12 @@ export type {
   MessageContentProcessorOrigin,
   MessageContentProcessorCtxDTO,
   MessageContentProcessorResultDTO,
+  WebSearchProviderDTO,
+  WebSearchSettingsDTO,
+  WebSearchResultDTO,
+  WebSearchDocumentDTO,
+  WebSearchRequestDTO,
+  WebSearchResponseDTO,
   WorkerToHost,
   HostToWorker,
 } from "./api";

package/src/permissions.ts

@@ -19,6 +19,9 @@
  *                            links, consolidations) and long-term chat memory (vectorized
  *                            chat-chunk retrieval, warmup, cache).
  * - "macro_interceptor"    — transform raw templates before macro parsing/dispatch
+ * - "web_search"           — execute searches via the user's configured web search
+ *                            provider (e.g. SearXNG) and read the safe view of their
+ *                            web search settings (never the API key).
  */
 export type SpindlePermission =
   | "generation"
@@ -44,7 +47,8 @@ export type SpindlePermission =
   | "image_gen"
   | "images"
   | "generation_parameters"
-  | "macro_interceptor";
+  | "macro_interceptor"
+  | "web_search";
 
 export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "generation",
@@ -71,6 +75,7 @@ export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "images",
   "generation_parameters",
   "macro_interceptor",
+  "web_search",
 ] as const;
 
 export function isValidPermission(p: string): p is SpindlePermission {

package/src/spindle-api.ts

@@ -103,6 +103,9 @@ import type {
   MessageContentProcessorResultDTO,
   SharedRpcRequestContextDTO,
   SharedRpcEndpointPolicyDTO,
+  WebSearchRequestDTO,
+  WebSearchResponseDTO,
+  WebSearchSettingsDTO,
 } from "./api";
 import type {
   ChatChunkDTO,
@@ -1370,6 +1373,74 @@ export interface SpindleAPI {
     }>;
   };
 
+  /**
+   * Web search (permission: `"web_search"`).
+   *
+   * Execute searches via the user's configured web search provider
+   * (currently SearXNG; additional providers will be added over time) and
+   * read the safe view of their web search settings. The host enforces all
+   * upstream limits (engine list, max result count, max pages to scrape,
+   * timeouts) — extensions cannot supply their own endpoint or API key.
+   *
+   * For user-scoped extensions, `userId` is inferred from the extension
+   * owner. Operator-scoped extensions should pass the `userId` of the user
+   * whose search engine should run the query.
+   *
+   * @example
+   * ```ts
+   * // Pre-flight: confirm web search is configured before issuing a query.
+   * const settings = await spindle.webSearch.getSettings()
+   * if (!settings.enabled) {
+   *   spindle.toast.warning('Configure a web search provider in Settings → Web Search first.')
+   *   return
+   * }
+   *
+   * // Full enriched query — scrapes the top-N pages and returns a
+   * // ready-to-inject context block.
+   * const enriched = await spindle.webSearch.query({
+   *   query: 'latest LLM benchmark results',
+   *   count: 5,
+   * })
+   * await spindle.chat.appendMessage(chatId, {
+   *   role: 'system',
+   *   content: enriched.context ?? '',
+   * })
+   *
+   * // Lightweight query — titles, URLs, snippets only.
+   * const quick = await spindle.webSearch.query({
+   *   query: 'who won the 2026 world cup',
+   *   scrape: false,
+   * })
+   * for (const row of quick.results) {
+   *   spindle.log.info(`${row.title} — ${row.url}`)
+   * }
+   * ```
+   */
+  webSearch: {
+    /**
+     * Run a search against the user's configured provider.
+     *
+     * Rejects with `"Web search is disabled"` when the user has not
+     * configured a provider, and with `"Web search API URL is not configured"`
+     * when the upstream endpoint is missing. Other upstream errors surface
+     * as `Error("SearXNG returned HTTP NNN")` (or equivalent for future
+     * providers).
+     *
+     * When `input.scrape` is `false`, `documents` and `context` are omitted
+     * from the response. Otherwise the host scrapes up to
+     * `WebSearchSettingsDTO.maxPagesToScrape` results, fills in
+     * `documents[].content`, and assembles a prompt-ready `context` block.
+     */
+    query(input: WebSearchRequestDTO): Promise<WebSearchResponseDTO>;
+    /**
+     * Read the safe view of the user's web search configuration. The raw
+     * API key is never exposed — only `hasApiKey` indicates whether one is
+     * on file. Useful for branching on `enabled` / `provider` /
+     * `maxResultCount` before issuing a query.
+     */
+    getSettings(userId?: string): Promise<WebSearchSettingsDTO>;
+  };
+
   /**
    * Text editor (free tier — no permission needed).
    * Opens the native Lumiverse expanded text editor modal on the user's