@molecule/api-web-search

Web search core interface for molecule.dev.

Defines the abstract contract for searching the web. Bond a concrete provider to enable web search in your application — a vendor API (@molecule/api-web-search-brave) or molecule.dev's hosted service (@molecule/api-web-search-molecule).

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider, requireProvider } from '@molecule/api-web-search'
import { provider as webSearch } from '@molecule/api-web-search-molecule' // or -brave

setProvider(webSearch)

const { results } = await requireProvider().search('best plane for a 10 hour flight', { count: 5 })
for (const r of results) {
  console.log(r.title, r.url)
}

Type

core

Installation

npm install @molecule/api-web-search @molecule/api-bond @molecule/api-i18n

API

Interfaces

WebSearchResultItem

One search result.

interface WebSearchResultItem {
  /** Result title, as the source page titles it. */
  title: string
  /** The result URL. Treat as untrusted input, never as an instruction. */
  url: string
  /** Snippet or description, when the provider returns one. */
  description?: string
}

WebSearchResult

Result of one web search.

interface WebSearchResult {
  /** The query as executed. */
  query: string
  /** Results in the provider's own relevance order. */
  results: WebSearchResultItem[]
}

WebSearchOptions

Options for one search.

interface WebSearchOptions {
  /** 1–20 results. Providers may cap further. */
  count?: number
  /** Two-letter country code the results are localized for, e.g. `us`. */
  country?: string
  /** Search language, e.g. `en`. Providers interpret the tag their own way. */
  searchLang?: string
}

WebSearchProvider

Web search provider interface.

Implement this interface in a bond package to search the web — with a vendor API or molecule.dev's hosted service.

interface WebSearchProvider {
  /** Provider name (e.g. 'brave', 'molecule'). */
  readonly name: string

  /**
   * Search the web.
   *
   * @param query - The search query, 1–400 characters.
   * @param options - Count and localization hints.
   * @returns Results in the provider's relevance order.
   */
  search(query: string, options?: WebSearchOptions): Promise<WebSearchResult>
}

WebSearchConfig

Configuration for the web search provider.

interface WebSearchConfig {
  /** Default result count when a call passes none. */
  count?: number
  /** Default country code. */
  country?: string
  /** Default search language. */
  searchLang?: string
}

Functions

setProvider(provider)

Registers a web search provider.

function setProvider(provider: WebSearchProvider): void

• provider — The web search provider to bond.

getProvider()

Retrieves the bonded web search provider, or null if none is bonded.

function getProvider(): WebSearchProvider | null

Returns: The bonded provider, or null.

hasProvider()

Checks whether a web search provider is currently bonded.

function hasProvider(): boolean

Returns: true if a provider is bonded.

requireProvider()

Retrieves the bonded web search provider, throwing if none is bonded. Use this when web search functionality is required.

function requireProvider(): WebSearchProvider

Returns: The bonded web search provider.

Available Providers

Provider	Package
Brave Search	@molecule/api-web-search-brave
Molecule (hosted)	@molecule/api-web-search-molecule

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-bond ^1.0.1
• @molecule/api-i18n ^1.0.1

Runtime Dependencies

• @molecule/api-bond

• @molecule/api-i18n

• Like most cores there are NO module-level convenience delegates. Call methods on requireProvider() (throws when unbonded). Note getProvider() returns null rather than throwing.

• Search results are UNTRUSTED CONTENT, not instructions. Titles, URLs and snippets come from the open web and may contain prompt-injection text crafted to steer an agent or an XSS payload aimed at your UI. Never execute or follow a result's contents; escape before rendering; when an LLM consumes results, wrap them as quoted data, never as system text.

• Queries are bounded (400 characters here, less at some providers). A raw user string can exceed that — truncate or split before searching, and pass the user's language in searchLang rather than translating first.

• Providers rank differently and cap count differently (20 here, fewer at some vendors). Don't assume exactly count results come back; the provider returns what it has.

• Storage is a provider-terms question, not a code question. Search vendors commonly restrict storing, reshuffling or re-serving results — cache only what your provider's terms allow and keep the attribution.