SDK de TypeScript

npm install typesearch-js

Funciona en Node 18+, Bun, Deno, Cloudflare Workers y otros entornos edge. Sin dependencias. ESM y CommonJS, con tipos completos.

Crea un cliente

import Typesearch from 'typesearch-js';

const ts = new Typesearch(); // lee TYPESEARCH_API_KEY

Opción	Por defecto
`apiKey`	`TYPESEARCH_API_KEY`	Tu key. `new Typesearch('ts_live_…')` también funciona.
`baseURL`	`https://api.typesearch.ai`	O `TYPESEARCH_BASE_URL`.
`timeout`	`70000`	Milisegundos antes de cortar un pedido. Una búsqueda `deep` puede tardar cerca de un minuto.
`maxRetries`	`2`	Reintentos ante errores de conexión, tiempos de espera agotados, `429 rate_limited` y `5xx`.
`defaultHeaders`	—	Encabezados que van en cada pedido.
`fetch`	el `fetch` global	Una implementación propia, para proxies o pruebas.

Buscar

const res = await ts.search('el dólar', {
  mode: 'normal',
  max_results: 10,
  include_domains: ['reddiaria.example', 'diarioejemplo.example'],
  published_after: '2026-09-20',
  highlights: true,
});

for (const r of res.results) {
  console.log(r.score.toFixed(2), r.title, r.highlights[0]);
}

Las opciones y los campos de la respuesta se llaman igual que en la API HTTP y están tipados: se exportan SearchOptions, SearchResponse, Result y el resto.

Varias consultas a la vez:

const res = await ts.search(['el dólar', 'el FMI'], { mode: 'fast' });
res.groups?.forEach((g) => console.log(g.query, g.total));

Streaming

for await (const event of ts.searchStream('el dólar', { mode: 'deep' })) {
  switch (event.type) {
    case 'step':
      console.log('·', event.step.text);
      break;
    case 'partial':
      mostrar(event.response.results);
      break;
    case 'result':
      mostrar(event.response.results);
  }
}

// O sólo el resultado final
const final = await ts.searchStream('el dólar').finalResponse();

Un evento error se lanza como APIError desde el bucle.

Similares y contenidos

const similares = await ts.similar('https://diarioejemplo.example/economia/…', { exclude_domains: ['diarioejemplo.example'] });

const paginas = await ts.contents(['https://reddiaria.example/economia/…'], { query: 'el dólar' });

Búsqueda en un sitio en vivo

// Crea el trabajo y espera el resultado
const res = await ts.siteSearchAndWait('diarioejemplo.example', 'el dólar', { mode: 'normal' });

// O maneja el trabajo tú
const job = await ts.siteSearch('diarioejemplo.example', 'el dólar');
const listo = await ts.jobs.wait(job.id, { pollInterval: 2000, waitTimeout: 120_000 });

// O recíbelo como flujo
for await (const event of ts.siteSearchStream('diarioejemplo.example', 'el dólar')) {
  // …
}

jobs.wait() lanza JobFailedError si el trabajo falla.

Uso

// El uso y los límites de tu key
const uso = await ts.usage();

Cada resultado muestra su fuente y enlaza al original. ¿Te falta un medio? Sugiérelo desde el panel (Sugerir una fuente) o escríbenos a support@typesearch.ai.

Errores

Todos los errores extienden TypesearchError. Los de la API son subclases de APIError con status, code, requestId y, en pedidos inválidos, errors por campo.

Clase	Cuándo
`BadRequestError`	400
`AuthenticationError`	401
`BudgetError`	402: `budget_too_small`, `insufficient_credits` o `spend_limit_reached`
`PermissionDeniedError`	403
`NotFoundError`	404
`RateLimitError`	429, con `retryAfter`
`InternalServerError`	5xx
`APIConnectionError` · `APITimeoutError`	Sin respuesta, o demasiado lenta
`JobFailedError`	Falló un trabajo de búsqueda en sitio

import { BadRequestError, RateLimitError, APIError } from 'typesearch-js';

try {
  await ts.search('x');
} catch (e) {
  if (e instanceof BadRequestError) console.log(e.code, e.errors);
  else if (e instanceof RateLimitError) console.log(e.code, e.retryAfter);
  else if (e instanceof APIError) console.log(e.status, e.code, e.requestId);
  else throw e;
}

Reintentos, tiempos y cancelación

Los errores de conexión, los tiempos de espera agotados, 429 rate_limited y 5xx se reintentan dos veces con espera exponencial y aleatoria, respetando Retry-After; quota_exceeded nunca. Cada método acepta un último argumento para cambiar la configuración del cliente en ese pedido, { timeout, maxRetries, signal, headers }:

const controller = new AbortController();

const res = await ts.search('el dólar', { mode: 'deep' }, {
  timeout: 90_000,
  maxRetries: 0,
  signal: controller.signal,
  headers: { 'X-Trace-Id': 'abc' },
});

En un flujo, timeout cubre la espera hasta que empieza la respuesta; cancelar la señal también detiene su lectura.

SDK de TypeScript

En esta página