API: providers/types

providers/types#

Classes#

ProviderBlockedError#

A provider refused the request rather than finding nothing.

Rate limiting, a challenge page, or an auth failure all mean “we do not know what the results are”, which is a different fact from “there are no results”. Collapsing the two made a throttled search look like a query that matched nothing, which is how a working site: search appeared broken and how a rate-limited benchmark run produced a retention figure that read as real.

Extends#

Error

Constructors#

Constructor#

new ProviderBlockedError(provider, reason): ProviderBlockedError

Defined in: src/providers/types.ts:66

Parameters#

Parameter	Type
`provider`	`string`
`reason`	`string`

Returns#

ProviderBlockedError

Overrides#

Error.constructor

Properties#

Property	Modifier	Type	Description	Inherited from	Defined in
`cause?`	`public`	`unknown`	-	`Error.cause`	node_modules/typescript/lib/lib.es2022.error.d.ts:26
`message`	`public`	`string`	-	`Error.message`	node_modules/typescript/lib/lib.es5.d.ts:1077
`name`	`public`	`string`	-	`Error.name`	node_modules/typescript/lib/lib.es5.d.ts:1076
`provider`	`readonly`	`string`	The provider that refused.	-	src/providers/types.ts:64
`stack?`	`public`	`string`	-	`Error.stack`	node_modules/typescript/lib/lib.es5.d.ts:1078
`stackTraceLimit`	`static`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	`Error.stackTraceLimit`	node_modules/@types/node/globals.d.ts:68

Methods#

captureStackTrace()#

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters#

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns#

void

Inherited from#

Error.captureStackTrace

prepareStackTrace()#

static prepareStackTrace(err, stackTraces): any

Defined in: node_modules/@types/node/globals.d.ts:56

Parameters#

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns#

any

See#

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from#

Error.prepareStackTrace

Interfaces#

SearchOptions#

Defined in: src/providers/types.ts:27

Options controlling a single provider search.

Properties#

Property	Type	Description	Defined in
`count?`	`number`	Maximum number of results to request.	src/providers/types.ts:29
`extraSnippets?`	`boolean`	Request extra snippets from providers that support it (Brave).	src/providers/types.ts:35
`freshness?`	`string`	Provider-specific freshness filter (e.g. Brave “pd”/“pw”/“pm”/“py”).	src/providers/types.ts:31
`recency_days?`	`number`	Number of days back to restrict results to.	src/providers/types.ts:33

SearchProvider#

Defined in: src/providers/types.ts:39

A search provider that can be queried and returns normalized results.

Properties#

Property	Type	Description	Defined in
`name`	`string`	Stable provider identifier (e.g. “brave”, “tavily”, “duckduckgo”).	src/providers/types.ts:41

Methods#

search()#

search(query, opts): Promise<SearchResult[]>

Defined in: src/providers/types.ts:49

Run a search and return normalized results.

Implementations MUST NOT throw on provider errors (missing key, HTTP 401/429, timeout). They return an empty array and log a warning instead, so one failing provider never breaks the aggregate search.

Parameters#

Parameter	Type
`query`	`string`
`opts`	`SearchOptions`

Returns#

Promise<SearchResult[]>

SearchResult#

Defined in: src/providers/types.ts:11

A single normalized search result returned by any provider.

Extended by#

RankedResult

Properties#

Property	Type	Description	Defined in
`published?`	`string`	ISO date string of publication, when the provider exposes it.	src/providers/types.ts:19
`score?`	`number`	A 0-1 relevance/quality score assigned by the provider, when available.	src/providers/types.ts:21
`snippet`	`string`	A short text snippet / description of the result.	src/providers/types.ts:17
`source`	`string`	The name of the provider that produced this result.	src/providers/types.ts:23
`title`	`string`	The result title.	src/providers/types.ts:13
`url`	`string`	The canonical URL of the result.	src/providers/types.ts:15