refactor!: use abstract provider classes

packages/pi/extensions/askweb.ts

@@ -206,7 +206,7 @@ export default function askwebExtension(pi: ExtensionAPI) {
 
       const resolvedProvider =
         providerName ?? (await askweb.resolveDefaultProviderAsync())
-      const provider = askweb.create(resolvedProvider)
+      const provider = askweb.createSearchProvider(resolvedProvider)
       const results = await provider.search(query, searchOptions)
       const header = buildHeader({
         mode: "single",
@@ -346,7 +346,7 @@ export default function askwebExtension(pi: ExtensionAPI) {
       let results: SearchResult[]
       try {
         results = await askweb
-          .create(providerName)
+          .createSearchProvider(providerName)
           .search(trimmed, { maxResults: DEFAULT_MAX_RESULTS })
       } catch (err) {
         if (ctx.hasUI) {

src/ai.ts

@@ -1,7 +1,7 @@
 import { tool } from 'ai'
 import { z } from 'zod'
 import { builtinProviders } from './core/providers.ts'
-import { create } from './core/registry.ts'
+import { createSearchProvider } from './core/registry.ts'
 import { searchAll } from './core/all.ts'
 import { readProviderNames, readUrl } from './core/read.ts'
 import { EmptyQueryError, EmptyUrlError } from './core/errors.ts'
@@ -34,7 +34,7 @@ export const searchTool = tool({
     }
 
     const name = providerName ?? resolveDefaultProvider()
-    return create(name).search(query, searchOptions)
+    return createSearchProvider(name).search(query, searchOptions)
   },
 })
 

src/commands/search.ts

@@ -28,9 +28,9 @@ export default defineCommand({
     },
   },
   async run({ args }) {
-    const { create } = await import('../core/registry.ts')
+    const { createSearchProvider } = await import('../core/registry.ts')
     const { resolveDefaultProvider } = await import('../core/resolve.ts')
-    const { AuthError, UnknownProviderError, NoProviderConfiguredError } = await import('../core/errors.ts')
+    const { AuthError, SearchNotSupportedError, UnknownProviderError, NoProviderConfiguredError } = await import('../core/errors.ts')
     let providerName = args.provider
 
     try {
@@ -47,7 +47,7 @@ export default defineCommand({
 
       providerName = args.provider || resolveDefaultProvider()
       await import('../providers/index.ts')
-      const provider = create(providerName, {})
+      const provider = createSearchProvider(providerName, {})
       const results = await provider.search(args.query, {
         maxResults: maxResults.value,
       })
@@ -81,6 +81,10 @@ export default defineCommand({
         consola.info(`Set the ${authProvider.toUpperCase()}_API_KEY environment variable.`)
         process.exit(1)
       }
+      if (error instanceof SearchNotSupportedError) {
+        consola.error(`Provider "${error.provider}" does not support web search.`)
+        process.exit(1)
+      }
       if (error instanceof UnknownProviderError) {
         const { providers } = await import('../core/registry.ts')
         consola.error(`Unknown provider: ${providerName}`)

src/core/all.ts

@@ -1,6 +1,6 @@
 import type { SearchResult, SearchOptions } from './types.ts'
 import { UnknownProviderError, NoProviderConfiguredError, NoProviderAvailableError, EmptyQueryError, validateDateFilters } from './errors.ts'
-import { create, has } from './registry.ts'
+import { createSearchProvider, has } from './registry.ts'
 import { detectAvailableProviders, detectAvailableProvidersAsync } from './resolve.ts'
 
 export interface SearchAllOptions extends SearchOptions {
@@ -67,7 +67,7 @@ export async function searchAllDetailed(query: string, options?: SearchAllOption
 
   const settled = await Promise.allSettled(
     providerNames.map(async (name) => {
-      const provider = create(name)
+      const provider = createSearchProvider(name)
       const results = await provider.search(query, searchOptions)
       return results.map(result => ({ ...result, provider: name }))
     }),
@@ -96,6 +96,7 @@ export async function searchAllDetailed(query: string, options?: SearchAllOption
 
 
 
+
 function deduplicateByUrl(results: SearchAllResult[]): SearchAllResult[] {
   const seen = new Map<string, SearchAllResult>()
 

src/core/errors.ts

@@ -82,6 +82,27 @@ export class EmptyUrlError extends AskwebError {
   }
 }
 
+export class InvalidProviderUrlError extends AskwebError {
+  readonly provider: string
+
+  constructor(provider: string) {
+    super(`Invalid base URL for provider "${provider}": expected an absolute http or https URL`)
+    this.name = 'InvalidProviderUrlError'
+    this.provider = provider
+  }
+}
+
+/** Thrown when a provider does not implement the search capability. */
+export class SearchNotSupportedError extends AskwebError {
+  readonly provider: string
+
+  constructor(provider: string) {
+    super(`Provider does not support search: ${provider}`)
+    this.name = 'SearchNotSupportedError'
+    this.provider = provider
+  }
+}
+
 /** Thrown when a provider does not implement the read capability. */
 export class ReadNotSupportedError extends AskwebError {
   readonly provider: string

src/core/provider.ts

@@ -0,0 +1,65 @@
+import { defaultClient, type Client } from './client.ts'
+import type { ProviderConfig, ReadOptions, ReadResult, SearchOptions, SearchResult } from './types.ts'
+import { InvalidProviderUrlError } from './errors.ts'
+
+export interface ProviderConstructor {
+  readonly providerName: string
+  readonly defaultBaseURL: string
+  new (config: ProviderConfig): Provider
+}
+
+export abstract class Provider {
+  readonly #name: string
+  protected readonly client: Client
+  protected readonly baseURL: string
+
+  get name(): string {
+    return this.#name
+  }
+
+  protected constructor(config: ProviderConfig, provider: Pick<ProviderConstructor, 'providerName' | 'defaultBaseURL'>) {
+    this.#name = provider.providerName
+    const baseURL = config.baseURL ?? provider.defaultBaseURL
+    assertProviderBaseURL(baseURL, this.name)
+    this.baseURL = baseURL.replace(/\/+$/, '')
+    this.client = defaultClient()
+  }
+}
+
+export function assertProviderBaseURL(baseURL: string, providerName: string): void {
+  let protocol: string
+  try {
+    protocol = new URL(baseURL).protocol
+  }
+  catch {
+    throw new InvalidProviderUrlError(providerName)
+  }
+
+  if (protocol !== 'http:' && protocol !== 'https:') {
+    throw new InvalidProviderUrlError(providerName)
+  }
+}
+
+export interface SearchProvider {
+  search(query: string, options?: SearchOptions): Promise<SearchResult[]>
+}
+
+export interface ReadProvider {
+  read(url: string, options?: ReadOptions): Promise<ReadResult>
+}
+
+export interface AvailabilityProvider {
+  isAvailable(): Promise<boolean>
+}
+
+export function isSearchProvider(provider: Provider): provider is Provider & SearchProvider {
+  return 'search' in provider && typeof provider.search === 'function'
+}
+
+export function isReadProvider(provider: Provider): provider is Provider & ReadProvider {
+  return 'read' in provider && typeof provider.read === 'function'
+}
+
+export function isAvailabilityProvider(provider: Provider): provider is Provider & AvailabilityProvider {
+  return 'isAvailable' in provider && typeof provider.isAvailable === 'function'
+}

src/core/read.ts

@@ -1,7 +1,7 @@
 import type { ReadOptions, ReadResult } from './types.ts'
 import { builtinProviders } from './providers.ts'
 import { EmptyUrlError, ReadNotSupportedError } from './errors.ts'
-import { create } from './registry.ts'
+import { createReadProvider } from './registry.ts'
 
 export const readProviderNames = ['jina', 'firecrawl'] as const
 export type ReadProviderName = typeof readProviderNames[number]
@@ -24,14 +24,11 @@ export async function readUrl(url: string, options?: ReadUrlOptions): Promise<Re
     throw new ReadNotSupportedError(providerName)
   }
 
-  const provider = create(providerName)
-  if (typeof provider.read !== 'function') {
-    throw new ReadNotSupportedError(providerName)
-  }
-
+  const provider = createReadProvider(providerName)
   return provider.read(trimmedUrl, readOptions)
 }
 
+
 function isBuiltinProvider(name: string): boolean {
   return (builtinProviders as readonly string[]).includes(name)
 }

src/core/registry.ts

@@ -1,55 +1,69 @@
-import type { SearchProvider, ProviderConfig, ProviderFactory } from './types'
-import { UnknownProviderError } from './errors'
+import type { ProviderConfig } from './types.ts'
+import {
+  Provider,
+  isReadProvider,
+  isSearchProvider,
+  type ProviderConstructor,
+  type ReadProvider,
+  type SearchProvider,
+} from './provider.ts'
+import {
+  ReadNotSupportedError,
+  SearchNotSupportedError,
+  UnknownProviderError,
+} from './errors.ts'
 
-const factories = new Map<string, ProviderFactory>()
-const defaultURLs = new Map<string, string>()
+const providerClasses = new Map<string, ProviderConstructor>()
 
 /**
- * Register a provider factory with the registry.
+ * Register a provider class.
  * Called by providers on import to self-register.
  */
-export function register(
-  name: string,
-  defaultURL: string,
-  factory: ProviderFactory
-): void {
-  factories.set(name, factory)
-  defaultURLs.set(name, defaultURL)
+export function register(provider: ProviderConstructor): void {
+  providerClasses.set(provider.providerName, provider)
 }
 
 /**
  * Create a provider instance by name.
  * Resolves apiKey from config or environment variable (PROVIDER_NAME_API_KEY).
  */
-export function create(name: string, config?: ProviderConfig): SearchProvider {
-  const factory = factories.get(name)
-  if (!factory) {
+export function create(name: string, config?: ProviderConfig): Provider {
+  const ProviderClass = providerClasses.get(name)
+  if (!ProviderClass) {
     throw new UnknownProviderError(name)
   }
 
   const apiKey =
     config?.apiKey ||
     process.env[`${name.toUpperCase()}_API_KEY`]
 
-  const resolvedConfig: ProviderConfig = {
+  return new ProviderClass({
     ...config,
     apiKey,
-    baseURL: config?.baseURL || defaultURLs.get(name),
+    baseURL: config?.baseURL || ProviderClass.defaultBaseURL,
+  })
+}
+
+export function createSearchProvider(name: string, config?: ProviderConfig): Provider & SearchProvider {
+  const provider = create(name, config)
+  if (!isSearchProvider(provider)) {
+    throw new SearchNotSupportedError(name)
   }
+  return provider
+}
 
-  return factory(resolvedConfig)
+export function createReadProvider(name: string, config?: ProviderConfig): Provider & ReadProvider {
+  const provider = create(name, config)
+  if (!isReadProvider(provider)) {
+    throw new ReadNotSupportedError(name)
+  }
+  return provider
 }
 
-/**
- * List all registered provider names.
- */
 export function providers(): string[] {
-  return Array.from(factories.keys())
+  return Array.from(providerClasses.keys())
 }
 
-/**
- * Check if a provider is registered.
- */
 export function has(name: string): boolean {
-  return factories.has(name)
+  return providerClasses.has(name)
 }

src/core/resolve.ts

@@ -1,6 +1,7 @@
 import { builtinProviders, type WebSearchProviderName } from './providers.ts'
 import { create, has } from './registry.ts'
 import { NoProviderAvailableError, NoProviderConfiguredError } from './errors.ts'
+import { isAvailabilityProvider } from './provider.ts'
 
 const envKeys: Record<string, WebSearchProviderName> = {
   EXA_API_KEY: 'exa',
@@ -52,9 +53,9 @@ export interface ProviderStatus {
   envVar: string | null
   /**
    * Set by {@link listProvidersAsync} when the provider implements
-   * {@link SearchProvider.isAvailable}. `true` = probe succeeded, `false` =
-   * probe failed (host down / unreachable / timeout), `undefined` = no probe
-   * was performed (sync caller) or provider has no probe (trust `configured`).
+   * {@link AvailabilityProvider.isAvailable}. `true` = probe succeeded,
+   * `false` = probe failed (host down / unreachable / timeout), `undefined` =
+   * no reachability probe was performed (trust `configured`).
    */
   reachable?: boolean
 }
@@ -126,7 +127,7 @@ export async function resolveDefaultProviderAsync(): Promise<WebSearchProviderNa
 async function probeConfiguredProvider(name: WebSearchProviderName): Promise<boolean | undefined> {
   try {
     const provider = create(name)
-    if (typeof provider.isAvailable !== 'function') return undefined
+    if (!isAvailabilityProvider(provider)) return undefined
     return await provider.isAvailable()
   }
   catch {

src/core/types.ts

@@ -45,28 +45,12 @@ export interface ReadOptions {
   noCache?: boolean
 }
 
-export interface SearchProvider {
-  name(): string
-  search(query: string, options?: SearchOptions): Promise<SearchResult[]>
-  read?(url: string, options?: ReadOptions): Promise<ReadResult>
-  /**
-   * Optional reachability probe. Used by {@link searchAll} and async detection
-   * helpers to skip self-hosted / optional providers whose endpoint is not
-   * responding, without failing the fan-out. Providers backed by paid APIs
-   * usually omit this and rely on env-var presence as the configured signal.
-   * Should resolve quickly (<= ~2s) and never throw.
-   */
-  isAvailable?(): Promise<boolean>
-}
-
 export interface ProviderConfig {
   apiKey?: string
   baseURL?: string
   readBaseURL?: string
 }
 
-export type ProviderFactory = (config: ProviderConfig) => SearchProvider
-
 export interface ClientOptions {
   maxRetries?: number
   baseDelay?: number

src/index.ts

@@ -4,13 +4,15 @@ export { version } from './version.ts'
 
 export { builtinProviders, type WebSearchProviderName } from './core/providers.ts'
 
-export type { SearchResult, SearchOptions, ReadResult, ReadOptions, SearchProvider, ProviderConfig, ProviderFactory, ClientOptions } from './core/types.ts'
+export type { SearchResult, SearchOptions, ReadResult, ReadOptions, ProviderConfig, ClientOptions } from './core/types.ts'
+export { Provider, isSearchProvider, isReadProvider, isAvailabilityProvider } from './core/provider.ts'
+export type { ProviderConstructor, SearchProvider, ReadProvider, AvailabilityProvider } from './core/provider.ts'
 
-export { AskwebError, HTTPError, AuthError, RateLimitError, UnknownProviderError, NoProviderConfiguredError, NoProviderAvailableError, EmptyQueryError, EmptyUrlError, ReadNotSupportedError, InvalidDateFilterError, normalizeError, validateDateFilters } from './core/errors.ts'
+export { AskwebError, HTTPError, AuthError, RateLimitError, UnknownProviderError, InvalidProviderUrlError, SearchNotSupportedError, NoProviderConfiguredError, NoProviderAvailableError, EmptyQueryError, EmptyUrlError, ReadNotSupportedError, InvalidDateFilterError, normalizeError, validateDateFilters } from './core/errors.ts'
 
 export { Client, defaultClient } from './core/client.ts'
 
-export { register, create, providers, has } from './core/registry.ts'
+export { register, create, createSearchProvider, createReadProvider, providers, has } from './core/registry.ts'
 
 export { searchAll, searchAllDetailed } from './core/all.ts'
 export type { SearchAllOptions, SearchAllResult, SearchAllResponse, ProviderError } from './core/all.ts'