ubersearch 0.0.0-development

package/src/core/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Core search types and error handling
+ */
+
+export type EngineId = string;
+
+export interface SearchQuery {
+  query: string;
+  limit?: number;
+  includeRaw?: boolean;
+}
+
+export interface SearchResultItem {
+  title: string;
+  url: string;
+  snippet: string;
+  score?: number;
+  sourceEngine: EngineId;
+}
+
+export interface SearchResponse {
+  engineId: EngineId;
+  items: SearchResultItem[];
+  raw?: unknown;
+  tookMs: number;
+}
+
+export type SearchFailureReason =
+  | "network_error"
+  | "api_error"
+  | "no_results"
+  | "low_credit"
+  | "config_error"
+  | "no_provider"
+  | "provider_unavailable"
+  | "unknown";
+
+/**
+ * Error thrown when a search provider fails
+ */
+export class SearchError extends Error {
+  engineId: EngineId;
+  reason: SearchFailureReason;
+  statusCode?: number;
+
+  constructor(
+    engineId: EngineId,
+    reason: SearchFailureReason,
+    message: string,
+    statusCode?: number,
+  ) {
+    super(message);
+    this.name = "SearchError";
+    this.engineId = engineId;
+    this.reason = reason;
+    this.statusCode = statusCode;
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./app/index";

package/src/plugin/PluginRegistry.ts

@@ -0,0 +1,336 @@
+/**
+ * Plugin Registry
+ *
+ * Central registry for managing search provider plugins.
+ * Handles plugin registration, lookup, and provider creation.
+ */
+
+import type { EngineConfigBase } from "../config/types";
+import type {
+  CreateProviderOptions,
+  ManagedProvider,
+  PluginDefinition,
+  PluginInfo,
+  PluginRegistrationOptions,
+  PluginRegistrationResult,
+} from "./types";
+
+/**
+ * Central registry for search provider plugins
+ *
+ * The PluginRegistry provides:
+ * - Plugin registration with optional overwrite
+ * - Plugin lookup by type
+ * - Provider creation from registered plugins
+ * - Plugin metadata queries
+ *
+ * @example
+ * ```typescript
+ * // Get singleton instance
+ * const registry = PluginRegistry.getInstance();
+ *
+ * // Register a plugin
+ * registry.register(myPlugin);
+ *
+ * // Create a provider
+ * const provider = registry.createProvider('my-provider', config);
+ *
+ * // Check if plugin exists
+ * if (registry.has('my-provider')) { ... }
+ * ```
+ */
+export class PluginRegistry {
+  private static instance: PluginRegistry | null = null;
+
+  /** Registered plugins by type */
+  private plugins = new Map<string, PluginDefinition>();
+
+  /** Track which plugins are built-in */
+  private builtInTypes = new Set<string>();
+
+  /**
+   * Get the singleton instance of PluginRegistry
+   */
+  static getInstance(): PluginRegistry {
+    if (!PluginRegistry.instance) {
+      PluginRegistry.instance = new PluginRegistry();
+    }
+    return PluginRegistry.instance;
+  }
+
+  /**
+   * Reset the singleton instance (useful for testing)
+   */
+  static resetInstance(): void {
+    PluginRegistry.instance = null;
+  }
+
+  /**
+   * Private constructor - use getInstance()
+   */
+  private constructor() {}
+
+  /**
+   * Register a plugin
+   *
+   * @param plugin - Plugin definition to register
+   * @param options - Registration options
+   * @returns Registration result
+   *
+   * @example
+   * ```typescript
+   * const result = registry.register(myPlugin);
+   * if (!result.success) {
+   *   console.error(result.message);
+   * }
+   * ```
+   */
+  async register(
+    plugin: PluginDefinition,
+    options: PluginRegistrationOptions = {},
+  ): Promise<PluginRegistrationResult> {
+    const { overwrite = false } = options;
+
+    // Check for existing registration
+    if (this.plugins.has(plugin.type)) {
+      if (!overwrite) {
+        return {
+          success: false,
+          type: plugin.type,
+          message: `Plugin type '${plugin.type}' is already registered. Use overwrite option to replace.`,
+        };
+      }
+
+      // Call onUnregister for existing plugin if it exists
+      const existing = this.plugins.get(plugin.type);
+      if (existing?.onUnregister) {
+        try {
+          await existing.onUnregister();
+        } catch (error) {
+          // Log but don't fail - we still want to register the new plugin
+          console.warn(`Error during onUnregister for plugin '${plugin.type}':`, error);
+        }
+      }
+    }
+
+    // Register the plugin
+    this.plugins.set(plugin.type, plugin);
+
+    // Call onRegister if provided
+    if (plugin.onRegister) {
+      try {
+        await plugin.onRegister();
+      } catch (error) {
+        // Rollback registration on error
+        this.plugins.delete(plugin.type);
+        return {
+          success: false,
+          type: plugin.type,
+          message: `Plugin onRegister failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+    }
+
+    return {
+      success: true,
+      type: plugin.type,
+      overwritten: overwrite && this.plugins.has(plugin.type),
+    };
+  }
+
+  /**
+   * Register a plugin synchronously (no lifecycle hooks called)
+   */
+  registerSync(
+    plugin: PluginDefinition,
+    options: PluginRegistrationOptions = {},
+  ): PluginRegistrationResult {
+    const { overwrite = false } = options;
+
+    if (this.plugins.has(plugin.type) && !overwrite) {
+      return {
+        success: false,
+        type: plugin.type,
+        message: `Plugin type '${plugin.type}' is already registered.`,
+      };
+    }
+
+    this.plugins.set(plugin.type, plugin);
+
+    return {
+      success: true,
+      type: plugin.type,
+      overwritten: overwrite && this.plugins.has(plugin.type),
+    };
+  }
+
+  /**
+   * Mark a plugin type as built-in
+   * Built-in plugins are identified in metadata
+   */
+  markBuiltIn(type: string): void {
+    this.builtInTypes.add(type);
+  }
+
+  /**
+   * Unregister a plugin
+   *
+   * @param type - Plugin type to unregister
+   * @returns true if plugin was removed, false if not found
+   */
+  async unregister(type: string): Promise<boolean> {
+    const plugin = this.plugins.get(type);
+    if (!plugin) {
+      return false;
+    }
+
+    // Call onUnregister if provided
+    if (plugin.onUnregister) {
+      await plugin.onUnregister();
+    }
+
+    this.plugins.delete(type);
+    this.builtInTypes.delete(type);
+    return true;
+  }
+
+  /**
+   * Check if a plugin type is registered
+   */
+  has(type: string): boolean {
+    return this.plugins.has(type);
+  }
+
+  /**
+   * Get a plugin by type
+   */
+  get(type: string): PluginDefinition | undefined {
+    return this.plugins.get(type);
+  }
+
+  /**
+   * Get all registered plugin types
+   */
+  getTypes(): string[] {
+    return Array.from(this.plugins.keys());
+  }
+
+  /**
+   * Get metadata for all registered plugins
+   */
+  listPlugins(): PluginInfo[] {
+    return Array.from(this.plugins.values()).map((plugin) => ({
+      type: plugin.type,
+      displayName: plugin.displayName,
+      description: plugin.description,
+      docsUrl: plugin.docsUrl,
+      version: plugin.version,
+      hasLifecycle: plugin.hasLifecycle,
+      isBuiltIn: this.builtInTypes.has(plugin.type),
+    }));
+  }
+
+  /**
+   * Get metadata for a specific plugin
+   */
+  getPluginInfo(type: string): PluginInfo | undefined {
+    const plugin = this.plugins.get(type);
+    if (!plugin) {
+      return undefined;
+    }
+
+    return {
+      type: plugin.type,
+      displayName: plugin.displayName,
+      description: plugin.description,
+      docsUrl: plugin.docsUrl,
+      version: plugin.version,
+      hasLifecycle: plugin.hasLifecycle,
+      isBuiltIn: this.builtInTypes.has(type),
+    };
+  }
+
+  /**
+   * Create a provider instance from a plugin
+   *
+   * @param config - Engine configuration (must include 'type' field)
+   * @param options - Creation options
+   * @returns Provider instance
+   * @throws Error if plugin not found or config validation fails
+   *
+   * @example
+   * ```typescript
+   * const config = { type: 'tavily', id: 'tavily', ... };
+   * const provider = registry.createProvider(config);
+   * ```
+   */
+  createProvider<T extends EngineConfigBase>(
+    config: T & { type: string },
+    options: CreateProviderOptions = {},
+  ): ManagedProvider {
+    const { container, skipValidation = false } = options;
+
+    const plugin = this.plugins.get(config.type);
+    if (!plugin) {
+      throw new Error(
+        `No plugin registered for type '${config.type}'. ` +
+          `Available types: ${this.getTypes().join(", ") || "none"}`,
+      );
+    }
+
+    // Validate config if schema provided and validation not skipped
+    let validatedConfig = config;
+    if (plugin.configSchema && !skipValidation) {
+      try {
+        validatedConfig = plugin.configSchema.validate(config) as T & { type: string };
+      } catch (error) {
+        throw new Error(
+          `Config validation failed for plugin '${config.type}': ` +
+            `${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+
+    // Create provider using factory
+    return plugin.factory(validatedConfig, container) as ManagedProvider;
+  }
+
+  /**
+   * Create multiple providers from configs
+   */
+  createProviders(
+    configs: Array<EngineConfigBase & { type: string }>,
+    options: CreateProviderOptions = {},
+  ): ManagedProvider[] {
+    return configs.map((config) => this.createProvider(config, options));
+  }
+
+  /**
+   * Clear all registered plugins
+   */
+  async clear(): Promise<void> {
+    // Call onUnregister for all plugins
+    for (const plugin of this.plugins.values()) {
+      if (plugin.onUnregister) {
+        try {
+          await plugin.onUnregister();
+        } catch (error) {
+          console.warn(`Error during onUnregister for plugin '${plugin.type}':`, error);
+        }
+      }
+    }
+
+    this.plugins.clear();
+    this.builtInTypes.clear();
+  }
+
+  /**
+   * Get count of registered plugins
+   */
+  get size(): number {
+    return this.plugins.size;
+  }
+}
+
+// Export singleton getter as convenience
+export const getPluginRegistry = (): PluginRegistry => PluginRegistry.getInstance();

package/src/plugin/builtin.ts

@@ -0,0 +1,130 @@
+/**
+ * Built-in Plugin Definitions
+ *
+ * Registers the core search providers as plugins:
+ * - Tavily
+ * - Brave
+ * - Linkup
+ * - SearchXNG
+ */
+
+import type {
+  BraveConfig,
+  EngineConfigBase,
+  LinkupConfig,
+  SearchxngConfig,
+  TavilyConfig,
+} from "../config/types";
+import type { SearchProvider } from "../core/provider";
+import { BraveProvider } from "../providers/brave";
+import { LinkupProvider } from "../providers/linkup";
+import { SearchxngProvider } from "../providers/searchxng";
+import { TavilyProvider } from "../providers/tavily";
+import { PluginRegistry } from "./PluginRegistry";
+import type { PluginDefinition } from "./types";
+
+/**
+ * Tavily plugin definition
+ */
+export const tavilyPlugin: PluginDefinition<TavilyConfig, TavilyProvider> = {
+  type: "tavily",
+  displayName: "Tavily",
+  description: "AI-powered search API with high-quality results",
+  docsUrl: "https://docs.tavily.com/",
+  version: "1.0.0",
+  hasLifecycle: false,
+  factory: (config) => new TavilyProvider(config),
+};
+
+/**
+ * Brave plugin definition
+ */
+export const bravePlugin: PluginDefinition<BraveConfig, BraveProvider> = {
+  type: "brave",
+  displayName: "Brave Search",
+  description: "Privacy-focused search engine API",
+  docsUrl: "https://api.search.brave.com/app/documentation",
+  version: "1.0.0",
+  hasLifecycle: false,
+  factory: (config) => new BraveProvider(config),
+};
+
+/**
+ * Linkup plugin definition
+ */
+export const linkupPlugin: PluginDefinition<LinkupConfig, LinkupProvider> = {
+  type: "linkup",
+  displayName: "Linkup",
+  description: "Web search API with Docker support",
+  docsUrl: "https://docs.linkup.ai/",
+  version: "1.0.0",
+  hasLifecycle: true,
+  factory: (config) => new LinkupProvider(config),
+};
+
+/**
+ * SearchXNG plugin definition
+ */
+export const searchxngPlugin: PluginDefinition<SearchxngConfig, SearchxngProvider> = {
+  type: "searchxng",
+  displayName: "SearXNG (Local)",
+  description: "Self-hosted meta search engine with Docker auto-start",
+  docsUrl: "https://docs.searxng.org/",
+  version: "1.0.0",
+  hasLifecycle: true,
+  factory: (config) => new SearchxngProvider(config),
+};
+
+/**
+ * All built-in plugins
+ * Using base types since specific configs/providers extend them
+ */
+export const builtInPlugins: PluginDefinition<EngineConfigBase, SearchProvider>[] = [
+  tavilyPlugin,
+  bravePlugin,
+  linkupPlugin,
+  searchxngPlugin,
+];
+
+/**
+ * Register all built-in plugins with the registry
+ *
+ * @param registry - Plugin registry instance (defaults to singleton)
+ * @returns Array of registration results
+ *
+ * @example
+ * ```typescript
+ * // Register with default singleton
+ * await registerBuiltInPlugins();
+ *
+ * // Or with custom registry
+ * const registry = new PluginRegistry();
+ * await registerBuiltInPlugins(registry);
+ * ```
+ */
+export async function registerBuiltInPlugins(
+  registry: PluginRegistry = PluginRegistry.getInstance(),
+): Promise<void> {
+  for (const plugin of builtInPlugins) {
+    const result = registry.registerSync(plugin);
+    if (result.success) {
+      registry.markBuiltIn(plugin.type);
+    }
+  }
+}
+
+/**
+ * Check if built-in plugins are registered
+ */
+export function areBuiltInPluginsRegistered(
+  registry: PluginRegistry = PluginRegistry.getInstance(),
+): boolean {
+  return builtInPlugins.every((plugin) => registry.has(plugin.type));
+}
+
+/**
+ * Get list of built-in plugin types
+ */
+export function getBuiltInPluginTypes(): string[] {
+  return builtInPlugins.map((p) => p.type);
+}

package/src/plugin/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Plugin System
+ *
+ * Exports all plugin-related types, classes, and utilities.
+ */
+
+// Built-in plugins
+export {
+  areBuiltInPluginsRegistered,
+  bravePlugin,
+  builtInPlugins,
+  getBuiltInPluginTypes,
+  linkupPlugin,
+  registerBuiltInPlugins,
+  searchxngPlugin,
+  tavilyPlugin,
+} from "./builtin";
+// Registry
+export { getPluginRegistry, PluginRegistry } from "./PluginRegistry";
+// Types
+export type {
+  CreateProviderOptions,
+  ManagedProvider,
+  PluginConfig,
+  PluginConfigSchema,
+  PluginDefinition,
+  PluginInfo,
+  PluginProvider,
+  PluginRegistrationOptions,
+  PluginRegistrationResult,
+  ProviderFactory,
+} from "./types";
+export { hasLifecycleManagement, isLifecycleProvider } from "./types";