ubersearch 0.0.0-development

package/src/plugin/types.ts

@@ -0,0 +1,212 @@
+/**
+ * Plugin System Types
+ *
+ * Defines the interfaces and types for the allsearch plugin system.
+ * Plugins allow adding new search providers without modifying core code.
+ */
+
+import type { EngineConfigBase } from "../config/types";
+import type { Container } from "../core/container";
+import type { ILifecycleProvider, SearchProvider } from "../core/provider";
+
+/**
+ * Configuration schema for a plugin's engine configuration
+ * Used for validation and TypeScript type inference
+ */
+export interface PluginConfigSchema<T extends EngineConfigBase = EngineConfigBase> {
+  /** The type discriminator for this plugin */
+  readonly type: string;
+
+  /**
+   * Validate the configuration
+   * @param config - Raw configuration object
+   * @returns Validated config or throws on validation failure
+   */
+  validate(config: unknown): T;
+
+  /**
+   * Get default values for optional fields
+   */
+  getDefaults(): Partial<T>;
+}
+
+/**
+ * Factory function type for creating provider instances
+ */
+export type ProviderFactory<
+  TConfig extends EngineConfigBase = EngineConfigBase,
+  TProvider extends SearchProvider = SearchProvider,
+> = (config: TConfig, container?: Container) => TProvider;
+
+/**
+ * Plugin definition interface
+ *
+ * A plugin provides everything needed to integrate a new search provider:
+ * - Type identifier for config discrimination
+ * - Config schema for validation
+ * - Factory function for creating instances
+ * - Metadata about the plugin
+ *
+ * @example
+ * ```typescript
+ * const myPlugin: PluginDefinition<MyConfig, MyProvider> = {
+ *   type: 'my-provider',
+ *   displayName: 'My Search Provider',
+ *   description: 'A custom search provider',
+ *   configSchema: myConfigSchema,
+ *   factory: (config, container) => new MyProvider(config),
+ *   hasLifecycle: false,
+ * };
+ * ```
+ */
+export interface PluginDefinition<
+  TConfig extends EngineConfigBase = EngineConfigBase,
+  TProvider extends SearchProvider = SearchProvider,
+> {
+  /**
+   * Unique type identifier for this plugin
+   * Used as discriminator in config objects (config.type)
+   */
+  readonly type: string;
+
+  /**
+   * Human-readable name for display
+   */
+  readonly displayName: string;
+
+  /**
+   * Brief description of the plugin
+   */
+  readonly description?: string;
+
+  /**
+   * URL to documentation
+   */
+  readonly docsUrl?: string;
+
+  /**
+   * Version of the plugin
+   */
+  readonly version?: string;
+
+  /**
+   * Configuration schema for validation
+   */
+  readonly configSchema?: PluginConfigSchema<TConfig>;
+
+  /**
+   * Factory function to create provider instances
+   */
+  readonly factory: ProviderFactory<TConfig, TProvider>;
+
+  /**
+   * Whether this provider implements ILifecycleProvider
+   * If true, init/shutdown will be called
+   */
+  readonly hasLifecycle: boolean;
+
+  /**
+   * Optional initialization hook called when plugin is registered
+   */
+  onRegister?(): void | Promise<void>;
+
+  /**
+   * Optional cleanup hook called when plugin is unregistered
+   */
+  onUnregister?(): void | Promise<void>;
+}
+
+/**
+ * Helper type to extract config type from a plugin definition
+ */
+export type PluginConfig<T> = T extends PluginDefinition<infer C, unknown> ? C : never;
+
+/**
+ * Helper type to extract provider type from a plugin definition
+ */
+export type PluginProvider<T> = T extends PluginDefinition<unknown, infer P> ? P : never;
+
+/**
+ * Registration options when adding a plugin to the registry
+ */
+export interface PluginRegistrationOptions {
+  /**
+   * Whether to overwrite if plugin type already exists
+   * @default false
+   */
+  overwrite?: boolean;
+}
+
+/**
+ * Result of plugin registration
+ */
+export interface PluginRegistrationResult {
+  success: boolean;
+  type: string;
+  message?: string;
+  overwritten?: boolean;
+}
+
+/**
+ * Plugin metadata returned by registry queries
+ */
+export interface PluginInfo {
+  type: string;
+  displayName: string;
+  description?: string;
+  docsUrl?: string;
+  version?: string;
+  hasLifecycle: boolean;
+  isBuiltIn: boolean;
+}
+
+/**
+ * Options for creating a provider from a plugin
+ */
+export interface CreateProviderOptions {
+  /**
+   * DI container for dependency injection
+   */
+  container?: Container;
+
+  /**
+   * Whether to skip config validation
+   * @default false
+   */
+  skipValidation?: boolean;
+}
+
+/**
+ * Extended provider type that combines SearchProvider with optional lifecycle
+ */
+export type ManagedProvider = SearchProvider & Partial<ILifecycleProvider>;
+
+/**
+ * Type guard to check if a provider implements ILifecycleProvider
+ */
+export function isLifecycleProvider(
+  provider: SearchProvider,
+): provider is SearchProvider & ILifecycleProvider {
+  if (provider == null || typeof provider !== "object") {
+    return false;
+  }
+  const obj = provider as Record<string, unknown>;
+  return (
+    "init" in provider &&
+    "healthcheck" in provider &&
+    "shutdown" in provider &&
+    typeof obj.init === "function" &&
+    typeof obj.healthcheck === "function" &&
+    typeof obj.shutdown === "function"
+  );
+}
+
+/**
+ * Type guard to check if a provider has lifecycle management enabled
+ */
+export function hasLifecycleManagement(provider: SearchProvider): boolean {
+  if (isLifecycleProvider(provider)) {
+    return typeof provider.isLifecycleManaged === "function" ? provider.isLifecycleManaged() : true;
+  }
+  return false;
+}

package/src/providers/BaseProvider.ts

@@ -0,0 +1,49 @@
+/**
+ * Base Provider Class
+ *
+ * Shared functionality for all search providers to reduce duplication
+ */
+
+import type { EngineConfigBase } from "../config/types";
+import type { ProviderMetadata, SearchProvider } from "../core/provider";
+import type { SearchQuery, SearchResponse } from "../core/types";
+import { SearchError } from "../core/types";
+import { getApiKey, validateResults } from "./utils";
+
+export abstract class BaseProvider<T extends EngineConfigBase> implements SearchProvider {
+  readonly id: string;
+  protected config: T;
+
+  constructor(config: T) {
+    this.id = config.id;
+    this.config = config;
+  }
+
+  getMetadata(): ProviderMetadata {
+    return {
+      id: this.id,
+      displayName: this.config.displayName,
+      docsUrl: this.getDocsUrl(),
+    };
+  }
+
+  abstract search(query: SearchQuery): Promise<SearchResponse>;
+  protected abstract getDocsUrl(): string;
+  protected abstract getApiKeyEnv(): string;
+
+  protected getApiKey(): string {
+    return getApiKey(this.id, this.getApiKeyEnv());
+  }
+
+  protected validateResults(results: unknown, providerName: string): void {
+    validateResults(this.id, results, providerName);
+  }
+
+  protected throwSearchError(
+    type: "config_error" | "network_error" | "api_error" | "no_results" | "provider_unavailable",
+    message: string,
+    statusCode?: number,
+  ): never {
+    throw new SearchError(this.id, type, message, statusCode);
+  }
+}

package/src/providers/brave.ts

@@ -0,0 +1,66 @@
+/**
+ * Brave Search Provider Implementation
+ */
+
+import type { BraveConfig } from "../config/types";
+import type { SearchQuery, SearchResponse } from "../core/types";
+import { BaseProvider } from "./BaseProvider";
+import { PROVIDER_DEFAULTS } from "./constants";
+import type { BraveApiResponse, BraveWebResult } from "./types";
+import { buildUrl, fetchWithErrorHandling } from "./utils";
+
+export class BraveProvider extends BaseProvider<BraveConfig> {
+  protected getDocsUrl(): string {
+    return "https://api.search.brave.com/app/documentation";
+  }
+
+  protected getApiKeyEnv(): string {
+    return this.config.apiKeyEnv;
+  }
+
+  async search(query: SearchQuery): Promise<SearchResponse> {
+    const apiKey = this.getApiKey();
+
+    const limit = query.limit ?? this.config.defaultLimit ?? 10;
+    const url = buildUrl(this.config.endpoint, {
+      q: query.query,
+      count: limit,
+    });
+
+    // Make request with error handling
+    const { data: json, tookMs } = await fetchWithErrorHandling<BraveApiResponse>(
+      this.id,
+      url,
+      {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          "X-Subscription-Token": apiKey,
+        },
+        timeoutMs: PROVIDER_DEFAULTS.DEFAULT_TIMEOUT_MS,
+      },
+      "Brave",
+    );
+
+    // Extract web results (handle both response formats)
+    const webResults: BraveWebResult[] = json.web?.results ?? json.results ?? [];
+
+    this.validateResults(webResults, "Brave");
+
+    // Map to normalized format
+    const items = webResults.map((r: BraveWebResult) => ({
+      title: r.title ?? r.url,
+      url: r.url,
+      snippet: r.description ?? r.snippet ?? r.abstract ?? "",
+      score: r.rank ?? r.score,
+      sourceEngine: this.id,
+    }));
+
+    return {
+      engineId: this.id,
+      items,
+      raw: query.includeRaw ? json : undefined,
+      tookMs,
+    };
+  }
+}

package/src/providers/constants.ts

@@ -0,0 +1,13 @@
+/**
+ * Provider Constants
+ *
+ * Shared constants for provider configuration and behavior
+ */
+
+export const PROVIDER_DEFAULTS = {
+  SEARXNG_INIT_TIMEOUT_MS: 60000,
+  SEARXNG_STARTUP_DELAY_MS: 3000,
+  LINKUP_INIT_TIMEOUT_MS: 30000,
+  DEFAULT_TIMEOUT_MS: 30000,
+  DEFAULT_RESULT_LIMIT: 10,
+} as const;

package/src/providers/helpers/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Provider Helper Functions
+ *
+ * Reusable utilities for building search providers with less boilerplate.
+ */
+
+// Lifecycle helpers for Docker-managed providers
+export {
+  addLifecycleMethods,
+  createDockerLifecycle,
+  createLifecycleMethods,
+  type DockerConfigurable,
+  type DockerDefaults,
+} from "./lifecycleHelpers";
+
+// Result mapping helpers
+export {
+  DEFAULT_FIELD_MAPPINGS,
+  type FieldMappings,
+  getFirstMatch,
+  mapSearchResult,
+  mapSearchResults,
+  PROVIDER_MAPPINGS,
+} from "./resultMappers";

package/src/providers/helpers/lifecycleHelpers.ts

@@ -0,0 +1,110 @@
+/**
+ * Lifecycle Helper Functions for Docker-Managed Providers
+ *
+ * Provides reusable functions for creating Docker lifecycle managers
+ * and implementing ILifecycleProvider methods via composition.
+ */
+
+import type { DockerConfigurable } from "../../config/types";
+import { DockerLifecycleManager } from "../../core/docker/dockerLifecycleManager";
+import type { ILifecycleProvider } from "../../core/provider";
+
+// Re-export for convenience
+export type { DockerConfigurable };
+
+/**
+ * Default values for Docker lifecycle configuration
+ */
+export interface DockerDefaults {
+  /** Default for autoStart (default: false) */
+  autoStart?: boolean;
+  /** Default for autoStop (default: false) */
+  autoStop?: boolean;
+  /** Default initialization timeout in ms (default: 30000) */
+  initTimeoutMs?: number;
+  /** Optional project root directory for Docker commands */
+  projectRoot?: string;
+}
+
+/**
+ * Create a DockerLifecycleManager from config with sensible defaults
+ *
+ * @param config - Engine config containing Docker settings
+ * @param defaults - Default values to use when config values are undefined
+ * @returns Configured DockerLifecycleManager instance
+ *
+ * @example
+ * ```typescript
+ * const manager = createDockerLifecycle(config, {
+ *   autoStart: true,
+ *   autoStop: true,
+ *   initTimeoutMs: 60000,
+ * });
+ * ```
+ */
+export function createDockerLifecycle(
+  config: DockerConfigurable,
+  defaults: DockerDefaults = {},
+): DockerLifecycleManager {
+  return new DockerLifecycleManager({
+    containerName: config.containerName,
+    composeFile: config.composeFile,
+    healthEndpoint: config.healthEndpoint,
+    autoStart: config.autoStart ?? defaults.autoStart ?? false,
+    autoStop: config.autoStop ?? defaults.autoStop ?? false,
+    initTimeoutMs: config.initTimeoutMs ?? defaults.initTimeoutMs ?? 30000,
+    projectRoot: defaults.projectRoot,
+  });
+}
+
+/**
+ * Create ILifecycleProvider methods that delegate to a DockerLifecycleManager
+ *
+ * This implements the composition pattern - rather than inheritance,
+ * we create an object with lifecycle methods that delegate to the manager.
+ *
+ * @param manager - The DockerLifecycleManager to delegate to
+ * @returns Object implementing ILifecycleProvider interface
+ *
+ * @example
+ * ```typescript
+ * const lifecycleMethods = createLifecycleMethods(this.lifecycleManager);
+ * // Now spread or assign these methods to your provider
+ * ```
+ */
+export function createLifecycleMethods(manager: DockerLifecycleManager): ILifecycleProvider {
+  return {
+    init: () => manager.init(),
+    healthcheck: () => manager.healthcheck(),
+    shutdown: () => manager.shutdown(),
+    validateConfig: () => manager.validateDockerConfig(),
+    isLifecycleManaged: () => true,
+  };
+}
+
+/**
+ * Mixin function to add lifecycle methods to a provider class instance
+ *
+ * @param target - The provider instance to add methods to
+ * @param manager - The DockerLifecycleManager to delegate to
+ * @returns The target with lifecycle methods added
+ *
+ * @example
+ * ```typescript
+ * class MyProvider {
+ *   private lifecycleManager: DockerLifecycleManager;
+ *
+ *   constructor(config: MyConfig) {
+ *     this.lifecycleManager = createDockerLifecycle(config, { autoStart: true });
+ *     addLifecycleMethods(this, this.lifecycleManager);
+ *   }
+ * }
+ * ```
+ */
+export function addLifecycleMethods<T extends object>(
+  target: T,
+  manager: DockerLifecycleManager,
+): T & ILifecycleProvider {
+  const methods = createLifecycleMethods(manager);
+  return Object.assign(target, methods);
+}

package/src/providers/helpers/resultMappers.ts

@@ -0,0 +1,168 @@
+/**
+ * Result Mapping Helper Functions
+ *
+ * Provides utilities for mapping API responses to normalized SearchResultItem format.
+ * Uses a configuration-based approach to handle different field names across providers.
+ */
+
+import type { SearchResultItem } from "../../core/types";
+
+/**
+ * Configuration for mapping fields from raw API response to SearchResultItem
+ *
+ * Each property is an array of field names to try, in order of preference.
+ * The first non-null/undefined value found will be used.
+ */
+export interface FieldMappings {
+  /** Fields to try for the title (default: ['title', 'name', 'url']) */
+  title?: string[];
+  /** Fields to try for the URL (default: ['url', 'link', 'href']) */
+  url?: string[];
+  /** Fields to try for the snippet (default: ['content', 'description', 'snippet']) */
+  snippet?: string[];
+  /** Fields to try for the score (default: ['score', 'rank', 'relevance']) */
+  score?: string[];
+  /** Field to use for source engine (default: none, uses provided engineId) */
+  sourceEngine?: string;
+}
+
+/**
+ * Default field mappings that work for most providers
+ */
+export const DEFAULT_FIELD_MAPPINGS: Required<Omit<FieldMappings, "sourceEngine">> = {
+  title: ["title", "name", "url"],
+  url: ["url", "link", "href"],
+  snippet: ["content", "description", "snippet", "excerpt"],
+  score: ["score", "rank", "relevance", "priority"],
+};
+
+/**
+ * Get the first non-null/undefined value from an object by trying multiple keys
+ *
+ * @param obj - Object to extract value from
+ * @param keys - Array of keys to try, in order of preference
+ * @returns The first found value, or undefined if none found
+ */
+export function getFirstMatch<T = unknown>(
+  obj: Record<string, unknown>,
+  keys: string[],
+): T | undefined {
+  for (const key of keys) {
+    const value = obj[key];
+    if (value !== null && value !== undefined) {
+      return value as T;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Map a single raw result object to a SearchResultItem
+ *
+ * @param raw - Raw result object from API
+ * @param engineId - Engine ID to use for sourceEngine
+ * @param mappings - Optional custom field mappings (merged with defaults)
+ * @returns Normalized SearchResultItem
+ *
+ * @example
+ * ```typescript
+ * // Using default mappings
+ * const item = mapSearchResult(rawResult, 'tavily');
+ *
+ * // Using custom mappings
+ * const item = mapSearchResult(rawResult, 'custom-engine', {
+ *   title: ['headline', 'title', 'name'],
+ *   snippet: ['body', 'text', 'content'],
+ * });
+ * ```
+ */
+export function mapSearchResult(
+  raw: unknown,
+  engineId: string,
+  mappings: FieldMappings = {},
+): SearchResultItem {
+  const r = raw as Record<string, unknown>;
+
+  // Merge with defaults
+  const titleKeys = mappings.title ?? DEFAULT_FIELD_MAPPINGS.title;
+  const urlKeys = mappings.url ?? DEFAULT_FIELD_MAPPINGS.url;
+  const snippetKeys = mappings.snippet ?? DEFAULT_FIELD_MAPPINGS.snippet;
+  const scoreKeys = mappings.score ?? DEFAULT_FIELD_MAPPINGS.score;
+
+  return {
+    title: String(getFirstMatch(r, titleKeys) ?? "Untitled"),
+    url: String(getFirstMatch(r, urlKeys) ?? ""),
+    snippet: String(getFirstMatch(r, snippetKeys) ?? ""),
+    score: getFirstMatch<number>(r, scoreKeys),
+    sourceEngine: mappings.sourceEngine ? String(r[mappings.sourceEngine] ?? engineId) : engineId,
+  };
+}
+
+/**
+ * Map an array of raw results to SearchResultItems
+ *
+ * @param results - Array of raw result objects
+ * @param engineId - Engine ID to use for sourceEngine
+ * @param mappings - Optional custom field mappings
+ * @param filter - Optional filter function to exclude invalid results
+ * @returns Array of normalized SearchResultItems
+ *
+ * @example
+ * ```typescript
+ * const items = mapSearchResults(
+ *   json.results,
+ *   'brave',
+ *   { title: ['title', 'name'] },
+ *   (r) => r.url != null  // Filter out results without URL
+ * );
+ * ```
+ */
+export function mapSearchResults(
+  results: unknown[],
+  engineId: string,
+  mappings: FieldMappings = {},
+  filter?: (raw: Record<string, unknown>) => boolean,
+): SearchResultItem[] {
+  return results
+    .filter((r): r is Record<string, unknown> => {
+      if (r == null || typeof r !== "object") {
+        return false;
+      }
+      if (filter) {
+        return filter(r as Record<string, unknown>);
+      }
+      return true;
+    })
+    .map((r) => mapSearchResult(r, engineId, mappings));
+}
+
+/**
+ * Pre-configured field mappings for known providers
+ */
+export const PROVIDER_MAPPINGS = {
+  tavily: {
+    title: ["title", "url"],
+    url: ["url"],
+    snippet: ["content", "snippet"],
+    score: ["score"],
+  },
+  brave: {
+    title: ["title", "url"],
+    url: ["url"],
+    snippet: ["description", "snippet"],
+    score: ["score"],
+  },
+  linkup: {
+    title: ["name", "title", "url"],
+    url: ["url"],
+    snippet: ["content", "snippet", "description"],
+    score: ["score", "relevance"],
+  },
+  searchxng: {
+    title: ["title", "url"],
+    url: ["url"],
+    snippet: ["content", "description"],
+    score: ["score", "rank"],
+    sourceEngine: "engine",
+  },
+} as const satisfies Record<string, FieldMappings>;

package/src/providers/index.ts

@@ -0,0 +1,6 @@
+export { BraveProvider } from "./brave";
+export * as providerHelpers from "./helpers";
+export { LinkupProvider } from "./linkup";
+export { SearchxngProvider } from "./searchxng";
+export { TavilyProvider } from "./tavily";
+export * from "./types";