ubersearch 0.0.0-development

package/src/providers/utils.ts

@@ -0,0 +1,182 @@
+/**
+ * Shared Provider Utilities
+ *
+ * Common functionality extracted from search providers to reduce duplication
+ * and ensure consistent behavior across all providers.
+ */
+
+import type { EngineId } from "../core/types";
+import { SearchError } from "../core/types";
+
+/**
+ * Options for HTTP requests
+ */
+export interface FetchOptions {
+  /** Request method */
+  method: "GET" | "POST";
+  /** Request headers */
+  headers: Record<string, string>;
+  /** Request body (for POST requests) */
+  body?: string;
+  /** Request timeout in milliseconds */
+  timeoutMs?: number;
+}
+
+/**
+ * Result of a fetch operation
+ */
+export interface FetchResult<T> {
+  /** Parsed response data */
+  data: T;
+  /** Response status code */
+  status: number;
+  /** Time taken in milliseconds */
+  tookMs: number;
+}
+
+/**
+ * Get API key from environment variable
+ *
+ * @param engineId - Engine ID for error messages
+ * @param envVarName - Environment variable name
+ * @returns API key value
+ * @throws SearchError if environment variable is not set
+ */
+export function getApiKey(engineId: EngineId, envVarName: string): string {
+  const apiKey = process.env[envVarName];
+  if (!apiKey) {
+    throw new SearchError(engineId, "config_error", `Missing environment variable: ${envVarName}`);
+  }
+  return apiKey;
+}
+
+/**
+ * Perform an HTTP fetch with error handling and timeout support
+ *
+ * @param engineId - Engine ID for error messages
+ * @param url - URL to fetch
+ * @param options - Fetch options
+ * @param providerDisplayName - Optional provider display name for error messages
+ * @returns Parsed JSON response
+ * @throws SearchError on network errors, HTTP errors, or parse errors
+ */
+export async function fetchWithErrorHandling<T>(
+  engineId: EngineId,
+  url: string,
+  options: FetchOptions,
+  providerDisplayName?: string,
+): Promise<FetchResult<T>> {
+  const started = Date.now();
+  let response: Response;
+
+  // Set up abort controller for timeout
+  const controller = new AbortController();
+  const timeoutId = options.timeoutMs
+    ? setTimeout(() => controller.abort(), options.timeoutMs)
+    : undefined;
+
+  try {
+    response = await fetch(url, {
+      method: options.method,
+      headers: options.headers,
+      body: options.body,
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    // Handle abort/timeout
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new SearchError(
+        engineId,
+        "network_error",
+        `Request timeout after ${options.timeoutMs}ms`,
+      );
+    }
+
+    throw new SearchError(
+      engineId,
+      "network_error",
+      `Network error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  // Handle HTTP errors
+  if (!response.ok) {
+    let errorBody = "";
+    try {
+      errorBody = await response.text();
+    } catch {
+      // Ignore error body parsing failures
+    }
+
+    const errorPrefix = providerDisplayName ? `${providerDisplayName} API error` : "API error";
+    throw new SearchError(
+      engineId,
+      "api_error",
+      `${errorPrefix}: HTTP ${response.status} ${response.statusText}${errorBody ? ` - ${errorBody}` : ""}`,
+      response.status,
+    );
+  }
+
+  // Parse JSON response
+  let data: T;
+  try {
+    data = (await response.json()) as T;
+  } catch (error) {
+    const errorPrefix = providerDisplayName
+      ? `Invalid JSON response from ${providerDisplayName}`
+      : "Invalid JSON response";
+    throw new SearchError(
+      engineId,
+      "api_error",
+      `${errorPrefix}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  return {
+    data,
+    status: response.status,
+    tookMs: Date.now() - started,
+  };
+}
+
+/**
+ * Validate that a response contains results
+ *
+ * @param engineId - Engine ID for error messages
+ * @param results - Results array to validate
+ * @param providerName - Optional provider name for custom error message
+ * @throws SearchError if results are empty or invalid
+ */
+export function validateResults(
+  engineId: EngineId,
+  results: unknown,
+  providerName?: string,
+): asserts results is unknown[] {
+  if (!Array.isArray(results) || results.length === 0) {
+    const message = providerName ? `${providerName} returned no results` : "No results returned";
+    throw new SearchError(engineId, "no_results", message);
+  }
+}
+
+/**
+ * Build a URL with query parameters
+ *
+ * @param baseUrl - Base URL
+ * @param params - Query parameters
+ * @returns URL with query string
+ */
+export function buildUrl(baseUrl: string, params: Record<string, string | number>): string {
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    searchParams.append(key, String(value));
+  }
+  return `${baseUrl}?${searchParams.toString()}`;
+}

package/src/tool/allSearchTool.ts

@@ -0,0 +1,110 @@
+/**
+ * Main allsearch tool function
+ *
+ * This is the single public interface that orchestrates the entire search process
+ */
+
+import { bootstrapContainer } from "../bootstrap/container";
+import type { CreditManager } from "../core/credits";
+import type { AllSearchOrchestrator } from "../core/orchestrator";
+import { ServiceKeys } from "../core/serviceKeys";
+import type { AllSearchInput, AllSearchOutput } from "./interface";
+
+/**
+ * Options for multiSearch function
+ */
+export interface AllSearchOptions {
+  /** Explicit config file path */
+  configPath?: string;
+  /** Container override for testing (dependency injection) */
+  containerOverride?: {
+    get<T>(serviceId: string): T;
+  };
+}
+
+/**
+ * Execute a allsearch across configured providers
+ *
+ * This function:
+ * 1. Bootstraps the DI container (or uses provided override)
+ * 2. Resolves orchestrator from container
+ * 3. Executes search with chosen strategy
+ * 4. Returns normalized results
+ *
+ * @param input Search input parameters
+ * @param options Optional config path or options object
+ * @returns Search results with metadata
+ */
+export async function multiSearch(
+  input: AllSearchInput,
+  options?: string | AllSearchOptions,
+): Promise<AllSearchOutput> {
+  // Handle backwards compatibility: string arg is config path
+  const opts: AllSearchOptions =
+    typeof options === "string" ? { configPath: options } : (options ?? {});
+
+  // Bootstrap the DI container or use override
+  const container = opts.containerOverride ?? (await bootstrapContainer(opts.configPath));
+
+  // Resolve orchestrator from container
+  const orchestrator = container.get<AllSearchOrchestrator>(ServiceKeys.ORCHESTRATOR);
+
+  // Execute search
+  const result = await orchestrator.run(input.query, {
+    limit: input.limit,
+    engineOrderOverride: input.engines,
+    includeRaw: input.includeRaw,
+    strategy: input.strategy ?? "all",
+  });
+
+  // Format output
+  return {
+    query: result.query,
+    items: result.results.map((r) => ({
+      title: r.title,
+      url: r.url,
+      snippet: r.snippet,
+      score: r.score,
+      sourceEngine: r.sourceEngine,
+    })),
+    enginesTried: result.engineAttempts.map((a) => ({
+      engineId: a.engineId,
+      success: a.success,
+      reason: a.reason,
+    })),
+    credits: result.credits,
+  };
+}
+
+/**
+ * Options for getCreditStatus function
+ */
+export interface GetCreditStatusOptions {
+  /** Explicit config file path */
+  configPath?: string;
+  /** Container override for testing (dependency injection) */
+  containerOverride?: {
+    get<T>(serviceId: string): T;
+  };
+}
+
+/**
+ * Get current credit status for all engines
+ *
+ * Useful for checking credit availability before searching
+ *
+ * @param options Optional config path (string) or options object
+ */
+export async function getCreditStatus(
+  options?: string | GetCreditStatusOptions,
+): Promise<AllSearchOutput["credits"]> {
+  // Handle backwards compatibility: string arg is config path
+  const opts: GetCreditStatusOptions =
+    typeof options === "string" ? { configPath: options } : (options ?? {});
+
+  // Bootstrap the DI container or use override
+  const container = opts.containerOverride ?? (await bootstrapContainer(opts.configPath));
+  const creditManager = container.get<CreditManager>(ServiceKeys.CREDIT_MANAGER);
+
+  return creditManager.listSnapshots();
+}

package/src/tool/interface.ts

@@ -0,0 +1,71 @@
+/**
+ * Input and output interfaces for the allsearch tool
+ */
+
+export interface AllSearchInput {
+  /** Search query string */
+  query: string;
+
+  /** Maximum number of results to return per provider */
+  limit?: number;
+
+  /** Specific engines to use (overrides config default order) */
+  engines?: string[];
+
+  /** Include raw provider responses in output */
+  includeRaw?: boolean;
+
+  /** Search strategy: 'all' (query all) or 'first-success' (stop after first success) */
+  strategy?: "all" | "first-success";
+
+  /**
+   * Execute searches in parallel (only applies to 'all' strategy)
+   * When true, all providers are queried simultaneously
+   * When false (default), providers are queried sequentially
+   */
+  parallel?: boolean;
+}
+
+export interface AllSearchEngineAttempt {
+  /** Provider/engine ID that was attempted */
+  engineId: string;
+
+  /** Whether the attempt succeeded */
+  success: boolean;
+
+  /** Reason for failure (if success=false) */
+  reason?: string;
+}
+
+export interface AllSearchOutputItem {
+  /** Result title */
+  title: string;
+
+  /** Result URL */
+  url: string;
+
+  /** Snippet/excerpt */
+  snippet: string;
+
+  /** Relevance score (if provided by engine) */
+  score?: number;
+
+  /** Source engine that returned this result */
+  sourceEngine: string;
+}
+
+import type { CreditSnapshot } from "../core/credits";
+
+export interface AllSearchOutput {
+  /** Original query */
+  query: string;
+
+  /** Combined search results from all successful providers */
+  items: AllSearchOutputItem[];
+
+  /** Metadata about which engines were tried and their outcomes */
+  enginesTried: AllSearchEngineAttempt[];
+
+  /** Credit snapshots for each engine after the search */
+  credits?: CreditSnapshot[];
+}