webseek 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,177 @@
+import { z } from "zod";
+
+//#region src/config/env.d.ts
+/**
+ * Resolves provider credentials and configuration from environment variables.
+ *
+ * API keys are read from the environment only (never from CLI flags/args) so
+ * they don't leak into shell history or process listings.
+ *
+ * Each provider's base URL can be overridden via an environment variable. This
+ * keeps the defaults pointed at the real services while letting tests (and
+ * proxies) redirect traffic to a local endpoint.
+ */
+interface Env {
+  [key: string]: string | undefined;
+}
+type GeminiBackend = "gemini-api" | "vertex-express";
+//#endregion
+//#region src/providers/provider.d.ts
+/**
+ * Shared types and the provider interface for the webseek CLI.
+ *
+ * Web search providers fall into two categories that this schema normalizes:
+ * - SERP-style providers (e.g. Google Custom Search) return a ranked list of
+ *   links in `results`.
+ * - LLM-grounded providers (e.g. OpenAI web search, Gemini grounding) return a
+ *   synthesized `answer` plus `citations` and the underlying `searchQueries`.
+ */
+type ProviderName = "openai" | "google" | "gemini";
+/** A single SERP-style result (one link). */
+interface SearchResultItem {
+  title: string;
+  url: string;
+  snippet: string;
+  displayLink?: string;
+}
+/** A single source citation backing a grounded answer. */
+interface Citation {
+  url: string;
+  title?: string;
+  /** Character offsets into `answer` that this citation supports, if known. */
+  startIndex?: number;
+  endIndex?: number;
+}
+/** The normalized result shape returned by every provider. */
+interface NormalizedSearchResult {
+  provider: ProviderName;
+  query: string;
+  /** SERP-style results (empty for grounded providers). */
+  results: SearchResultItem[];
+  /** Grounded answer text, if the provider synthesizes one. */
+  answer?: string;
+  /** Sources backing the answer (grounded providers). */
+  citations: Citation[];
+  /** Queries the provider actually ran (grounded providers). */
+  searchQueries: string[];
+  /** The provider's raw response, included only when requested. */
+  raw?: unknown;
+}
+/** Options shared by every provider's `search` call. */
+interface SearchParams {
+  query: string;
+  /** Desired number of results; best-effort for grounded providers. */
+  maxResults?: number;
+  /** Model override for LLM-backed providers. */
+  model?: string;
+  /** Include the provider's raw response in the result. */
+  includeRaw?: boolean;
+  /** Injectable fetch for testing; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+/** A web search provider. Implementations are stateless given their config. */
+interface SearchProvider {
+  readonly name: ProviderName;
+  search(params: SearchParams): Promise<NormalizedSearchResult>;
+}
+//#endregion
+//#region src/lib/search.d.ts
+declare const PROVIDER_NAMES: readonly ["openai", "google", "gemini"];
+declare const GEMINI_BACKENDS: readonly ["gemini-api", "vertex-express"];
+interface RunSearchParams {
+  provider: ProviderName;
+  query: string;
+  maxResults?: number;
+  model?: string;
+  includeRaw?: boolean;
+  geminiBackend?: GeminiBackend;
+  env?: Env;
+  fetchImpl?: typeof fetch;
+}
+declare function runSearch(params: RunSearchParams): Promise<NormalizedSearchResult>;
+//#endregion
+//#region src/utils/error.d.ts
+/**
+ * Consistent error formatting for the CLI.
+ *
+ * Provider calls fail in predictable ways (missing credentials, auth rejected,
+ * quota exhausted, malformed responses). `WebseekError` carries a stable
+ * `code` so the CLI can map failures to exit codes and a clear message, while
+ * `formatError` renders any thrown value into a single human-readable string.
+ */
+type WebseekErrorCode = "missing_config" | "auth_failed" | "rate_limited" | "provider_error" | "invalid_response" | "invalid_usage";
+interface WebseekErrorOptions {
+  code: WebseekErrorCode;
+  message: string;
+  cause?: unknown;
+}
+declare class WebseekError extends Error {
+  readonly code: WebseekErrorCode;
+  constructor(options: WebseekErrorOptions);
+}
+/**
+ * Map a thrown value to a process exit code: `2` for usage mistakes, `1` for
+ * any other failure.
+ */
+declare function errorExitCode(error: unknown): number;
+/** Render any thrown value into a single-line, user-facing message. */
+declare function formatError(error: unknown): string;
+//#endregion
+//#region src/mcp/tools.d.ts
+declare const webSearchInputShape: {
+  query: z.ZodString;
+  provider: z.ZodEnum<{
+    openai: "openai";
+    google: "google";
+    gemini: "gemini";
+  }>;
+  maxResults: z.ZodOptional<z.ZodNumber>;
+  model: z.ZodOptional<z.ZodString>;
+  geminiBackend: z.ZodOptional<z.ZodEnum<{
+    "gemini-api": "gemini-api";
+    "vertex-express": "vertex-express";
+  }>>;
+  includeRaw: z.ZodOptional<z.ZodBoolean>;
+};
+declare const webSearchArgsSchema: z.ZodObject<{
+  query: z.ZodString;
+  provider: z.ZodEnum<{
+    openai: "openai";
+    google: "google";
+    gemini: "gemini";
+  }>;
+  maxResults: z.ZodOptional<z.ZodNumber>;
+  model: z.ZodOptional<z.ZodString>;
+  geminiBackend: z.ZodOptional<z.ZodEnum<{
+    "gemini-api": "gemini-api";
+    "vertex-express": "vertex-express";
+  }>>;
+  includeRaw: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type WebSearchArgs = z.infer<typeof webSearchArgsSchema>;
+interface ToolResult {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  isError?: boolean;
+  [key: string]: unknown;
+}
+interface CreateWebSearchToolParams {
+  /** Injectable for tests; defaults to the process environment. */
+  env?: Env;
+  /** Injectable for tests; defaults to the global fetch. */
+  fetchImpl?: typeof fetch;
+}
+interface WebSearchTool {
+  name: string;
+  config: {
+    title: string;
+    description: string;
+    inputSchema: typeof webSearchInputShape;
+  };
+  handler: (args: WebSearchArgs) => Promise<ToolResult>;
+}
+declare function createWebSearchTool(params?: CreateWebSearchToolParams): WebSearchTool;
+//#endregion
+export { type Citation, type CreateWebSearchToolParams, type Env, GEMINI_BACKENDS, type GeminiBackend, type NormalizedSearchResult, PROVIDER_NAMES, type ProviderName, type RunSearchParams, type SearchParams, type SearchProvider, type SearchResultItem, type ToolResult, type WebSearchArgs, type WebSearchTool, WebseekError, type WebseekErrorCode, type WebseekErrorOptions, createWebSearchTool, errorExitCode, formatError, runSearch, webSearchInputShape };

package/dist/index.d.mts

@@ -0,0 +1,177 @@
+import { z } from "zod";
+
+//#region src/config/env.d.ts
+/**
+ * Resolves provider credentials and configuration from environment variables.
+ *
+ * API keys are read from the environment only (never from CLI flags/args) so
+ * they don't leak into shell history or process listings.
+ *
+ * Each provider's base URL can be overridden via an environment variable. This
+ * keeps the defaults pointed at the real services while letting tests (and
+ * proxies) redirect traffic to a local endpoint.
+ */
+interface Env {
+  [key: string]: string | undefined;
+}
+type GeminiBackend = "gemini-api" | "vertex-express";
+//#endregion
+//#region src/providers/provider.d.ts
+/**
+ * Shared types and the provider interface for the webseek CLI.
+ *
+ * Web search providers fall into two categories that this schema normalizes:
+ * - SERP-style providers (e.g. Google Custom Search) return a ranked list of
+ *   links in `results`.
+ * - LLM-grounded providers (e.g. OpenAI web search, Gemini grounding) return a
+ *   synthesized `answer` plus `citations` and the underlying `searchQueries`.
+ */
+type ProviderName = "openai" | "google" | "gemini";
+/** A single SERP-style result (one link). */
+interface SearchResultItem {
+  title: string;
+  url: string;
+  snippet: string;
+  displayLink?: string;
+}
+/** A single source citation backing a grounded answer. */
+interface Citation {
+  url: string;
+  title?: string;
+  /** Character offsets into `answer` that this citation supports, if known. */
+  startIndex?: number;
+  endIndex?: number;
+}
+/** The normalized result shape returned by every provider. */
+interface NormalizedSearchResult {
+  provider: ProviderName;
+  query: string;
+  /** SERP-style results (empty for grounded providers). */
+  results: SearchResultItem[];
+  /** Grounded answer text, if the provider synthesizes one. */
+  answer?: string;
+  /** Sources backing the answer (grounded providers). */
+  citations: Citation[];
+  /** Queries the provider actually ran (grounded providers). */
+  searchQueries: string[];
+  /** The provider's raw response, included only when requested. */
+  raw?: unknown;
+}
+/** Options shared by every provider's `search` call. */
+interface SearchParams {
+  query: string;
+  /** Desired number of results; best-effort for grounded providers. */
+  maxResults?: number;
+  /** Model override for LLM-backed providers. */
+  model?: string;
+  /** Include the provider's raw response in the result. */
+  includeRaw?: boolean;
+  /** Injectable fetch for testing; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+/** A web search provider. Implementations are stateless given their config. */
+interface SearchProvider {
+  readonly name: ProviderName;
+  search(params: SearchParams): Promise<NormalizedSearchResult>;
+}
+//#endregion
+//#region src/lib/search.d.ts
+declare const PROVIDER_NAMES: readonly ["openai", "google", "gemini"];
+declare const GEMINI_BACKENDS: readonly ["gemini-api", "vertex-express"];
+interface RunSearchParams {
+  provider: ProviderName;
+  query: string;
+  maxResults?: number;
+  model?: string;
+  includeRaw?: boolean;
+  geminiBackend?: GeminiBackend;
+  env?: Env;
+  fetchImpl?: typeof fetch;
+}
+declare function runSearch(params: RunSearchParams): Promise<NormalizedSearchResult>;
+//#endregion
+//#region src/utils/error.d.ts
+/**
+ * Consistent error formatting for the CLI.
+ *
+ * Provider calls fail in predictable ways (missing credentials, auth rejected,
+ * quota exhausted, malformed responses). `WebseekError` carries a stable
+ * `code` so the CLI can map failures to exit codes and a clear message, while
+ * `formatError` renders any thrown value into a single human-readable string.
+ */
+type WebseekErrorCode = "missing_config" | "auth_failed" | "rate_limited" | "provider_error" | "invalid_response" | "invalid_usage";
+interface WebseekErrorOptions {
+  code: WebseekErrorCode;
+  message: string;
+  cause?: unknown;
+}
+declare class WebseekError extends Error {
+  readonly code: WebseekErrorCode;
+  constructor(options: WebseekErrorOptions);
+}
+/**
+ * Map a thrown value to a process exit code: `2` for usage mistakes, `1` for
+ * any other failure.
+ */
+declare function errorExitCode(error: unknown): number;
+/** Render any thrown value into a single-line, user-facing message. */
+declare function formatError(error: unknown): string;
+//#endregion
+//#region src/mcp/tools.d.ts
+declare const webSearchInputShape: {
+  query: z.ZodString;
+  provider: z.ZodEnum<{
+    openai: "openai";
+    google: "google";
+    gemini: "gemini";
+  }>;
+  maxResults: z.ZodOptional<z.ZodNumber>;
+  model: z.ZodOptional<z.ZodString>;
+  geminiBackend: z.ZodOptional<z.ZodEnum<{
+    "gemini-api": "gemini-api";
+    "vertex-express": "vertex-express";
+  }>>;
+  includeRaw: z.ZodOptional<z.ZodBoolean>;
+};
+declare const webSearchArgsSchema: z.ZodObject<{
+  query: z.ZodString;
+  provider: z.ZodEnum<{
+    openai: "openai";
+    google: "google";
+    gemini: "gemini";
+  }>;
+  maxResults: z.ZodOptional<z.ZodNumber>;
+  model: z.ZodOptional<z.ZodString>;
+  geminiBackend: z.ZodOptional<z.ZodEnum<{
+    "gemini-api": "gemini-api";
+    "vertex-express": "vertex-express";
+  }>>;
+  includeRaw: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type WebSearchArgs = z.infer<typeof webSearchArgsSchema>;
+interface ToolResult {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  isError?: boolean;
+  [key: string]: unknown;
+}
+interface CreateWebSearchToolParams {
+  /** Injectable for tests; defaults to the process environment. */
+  env?: Env;
+  /** Injectable for tests; defaults to the global fetch. */
+  fetchImpl?: typeof fetch;
+}
+interface WebSearchTool {
+  name: string;
+  config: {
+    title: string;
+    description: string;
+    inputSchema: typeof webSearchInputShape;
+  };
+  handler: (args: WebSearchArgs) => Promise<ToolResult>;
+}
+declare function createWebSearchTool(params?: CreateWebSearchToolParams): WebSearchTool;
+//#endregion
+export { type Citation, type CreateWebSearchToolParams, type Env, GEMINI_BACKENDS, type GeminiBackend, type NormalizedSearchResult, PROVIDER_NAMES, type ProviderName, type RunSearchParams, type SearchParams, type SearchProvider, type SearchResultItem, type ToolResult, type WebSearchArgs, type WebSearchTool, WebseekError, type WebseekErrorCode, type WebseekErrorOptions, createWebSearchTool, errorExitCode, formatError, runSearch, webSearchInputShape };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { c as runSearch, d as formatError, i as PROVIDER_NAMES, l as WebseekError, n as webSearchInputShape, r as GEMINI_BACKENDS, t as createWebSearchTool, u as errorExitCode } from "./tools-CCqL3Phx.mjs";
+export { GEMINI_BACKENDS, PROVIDER_NAMES, WebseekError, createWebSearchTool, errorExitCode, formatError, runSearch, webSearchInputShape };