Olostep NodeJS SDK - Olostep Docs

Paquete NPM: olostep

Comenzando

npm install olostep

import Olostep from 'olostep';

const client = new Olostep({apiKey: process.env.OLOSTEP_API_KEY});

// Ejemplo mínimo de scraping
const result = await client.scrapes.create('https://example.com');
console.log(result.id, result.html_content);

import Olostep from 'olostep';

const client = new Olostep({api_key: process.env.OLOSTEP_API_KEY});

// Ejemplo mínimo de scraping
const result = await client.scrapes.create('https://example.com');
console.log(result.id, result.html_content);

El SDK de NodeJS acepta tanto camelCase como snake_case para todos los parámetros. Usa snake_case si estás desarrollando para agentes de IA, ya que coincide con los nombres de campo nativos de la API.

Uso

Scraping

Realiza scraping de una sola URL con varias opciones:

import Olostep, {Format} from 'olostep';

const client = new Olostep({apiKey: 'your_api_key'});

// Scraping simple
const scrape = await client.scrapes.create('https://example.com');

// Con múltiples formatos
const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: [Format.HTML, Format.MARKDOWN, Format.TEXT],
  waitBeforeScraping: 1000,
  removeImages: true
});

// Accede al contenido
console.log(scrape.html_content);
console.log(scrape.markdown_content);

// Obtén el scraping por ID
const fetched = await client.scrapes.get(scrape.id);

import Olostep, {Format} from 'olostep';

const client = new Olostep({api_key: 'your_api_key'});

// Scraping simple
const scrape = await client.scrapes.create('https://example.com');

// Con múltiples formatos
const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: [Format.HTML, Format.MARKDOWN, Format.TEXT],
  wait_before_scraping: 1000,
  remove_images: true
});

// Accede al contenido
console.log(scrape.html_content);
console.log(scrape.markdown_content);

// Obtén el scraping por ID
const fetched = await client.scrapes.get(scrape.id);

Procesamiento por Lotes

Procesa múltiples URLs en un solo lote:

// Usando cadenas de URL (IDs personalizados generados automáticamente)
const batch = await client.batches.create([
  'https://example.com',
  'https://example.org',
  'https://example.net'
]);

// O con IDs personalizados explícitos
const batch = await client.batches.create([
  {url: 'https://example.com', customId: 'site-1'},
  {url: 'https://example.org', customId: 'site-2'}
]);

console.log(`Batch ${batch.id} creado con ${batch.total_urls} URLs`);

// Espera a que se complete
await batch.waitTillDone({
  checkEveryNSecs: 5,
  timeoutSeconds: 120
});

// Obtén información del lote
const info = await batch.info();
console.log(info);

// Transmite resultados individuales
for await (const item of batch.items()) {
  console.log(item.custom_id);
}

// Usando cadenas de URL (IDs personalizados generados automáticamente)
const batch = await client.batches.create([
  'https://example.com',
  'https://example.org',
  'https://example.net'
]);

// O con IDs personalizados explícitos
const batch = await client.batches.create([
  {url: 'https://example.com', custom_id: 'site-1'},
  {url: 'https://example.org', custom_id: 'site-2'}
]);

console.log(`Batch ${batch.id} creado con ${batch.total_urls} URLs`);

// Espera a que se complete
await batch.waitTillDone({
  check_every_n_secs: 5,
  timeout_seconds: 120
});

// Obtén información del lote
const info = await batch.info();
console.log(info);

// Transmite resultados individuales
for await (const item of batch.items()) {
  console.log(item.custom_id);
}

Crawling

Rastrea un sitio web completo:

const crawl = await client.crawls.create({
  url: 'https://example.com',
  maxPages: 100,
  maxDepth: 3,
  includeUrls: ['*/blog/*'],
  excludeUrls: ['*/admin/*']
});

console.log(`Crawl ${crawl.id} iniciado`);

// Espera a que se complete
await crawl.waitTillDone({
  checkEveryNSecs: 10,
  timeoutSeconds: 300
});

// Obtén información del crawl
const info = await crawl.info();
console.log(`Se rastrearon ${info.pages_crawled} páginas`);

// Transmite páginas rastreadas
for await (const page of crawl.pages()) {
  console.log(page.url, page.status_code);
}

const crawl = await client.crawls.create({
  url: 'https://example.com',
  max_pages: 100,
  max_depth: 3,
  include_urls: ['*/blog/*'],
  exclude_urls: ['*/admin/*']
});

console.log(`Crawl ${crawl.id} iniciado`);

// Espera a que se complete
await crawl.waitTillDone({
  check_every_n_secs: 10,
  timeout_seconds: 300
});

// Obtén información del crawl
const info = await crawl.info();
console.log(`Se rastrearon ${info.pages_crawled} páginas`);

// Transmite páginas rastreadas
for await (const page of crawl.pages()) {
  console.log(page.url, page.status_code);
}

Mapeo del Sitio

Genera un mapa del sitio de URLs de un sitio web:

const map = await client.maps.create({
  url: 'https://example.com',
  topN: 100,
  includeSubdomain: true,
  searchQuery: 'blog posts'
});

console.log(`Mapa ${map.id} creado`);

// Transmite URLs
for await (const url of map.urls()) {
  console.log(url);
}

// Obtén información del mapa
const info = await map.info();

const map = await client.maps.create({
  url: 'https://example.com',
  top_n: 100,
  include_subdomain: true,
  search_query: 'blog posts'
});

console.log(`Mapa ${map.id} creado`);

// Transmite URLs
for await (const url of map.urls()) {
  console.log(url);
}

// Obtén información del mapa
const info = await map.info();

Respuestas Potenciadas por IA

Obtén respuestas de páginas web usando IA:

import Olostep from 'olostep';

const client = new Olostep({apiKey: 'your_api_key'});

// Tarea simple: pasa una cadena directamente
const answer = await client.answers.create(
  'What is the main topic of https://example.com?'
);
console.log(answer.answer);
console.log(answer.sources);

// Con salida JSON estructurada
const structured = await client.answers.create({
  task: 'Extract all product names and prices from https://example.com',
  jsonFormat: {
    products: [{name: '', price: ''}]
  }
});
console.log(structured.json_content);

// Recupera una respuesta previamente creada por ID
const fetched = await client.answers.get(answer.id);
console.log(fetched.answer);

import Olostep from 'olostep';

const client = new Olostep({api_key: 'your_api_key'});

// Tarea simple: pasa una cadena directamente
const answer = await client.answers.create(
  'What is the main topic of https://example.com?'
);
console.log(answer.answer);
console.log(answer.sources);

// Con salida JSON estructurada
const structured = await client.answers.create({
  task: 'Extract all product names and prices from https://example.com',
  json_format: {
    products: [{name: '', price: ''}]
  }
});
console.log(structured.json_content);

// Recupera una respuesta previamente creada por ID
const fetched = await client.answers.get(answer.id);
console.log(fetched.answer);

Recuperación de Contenido

Recupera contenido previamente extraído:

// Obtén contenido en formato(s) específico(s)
const content = await client.retrieve(retrieveId, Format.MARKDOWN);
console.log(content.markdown_content);

// Múltiples formatos
const content = await client.retrieve(retrieveId, [
  Format.HTML,
  Format.MARKDOWN
]);

Opciones Avanzadas

Acciones Personalizadas

Realiza acciones en el navegador antes de hacer scraping:

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  actions: [
    {type: 'wait', milliseconds: 2000},
    {type: 'click', selector: '#load-more'},
    {type: 'scroll', distance: 1000},
    {type: 'fill_input', selector: '#search', value: 'query'}
  ]
});

Ubicación Geográfica

Realiza scraping desde diferentes países usando códigos de país predefinidos o cualquier cadena de código de país válida:

import Olostep, {Country} from 'olostep';

const client = new Olostep({apiKey: 'your_api_key'});

// Usando valores de enumeración predefinidos (US, DE, FR, GB, SG)
const scrape = await client.scrapes.create({
  url: 'https://example.com',
  country: Country.DE  // Alemania
});

// O usa cualquier código de país válido como cadena
const scrape2 = await client.scrapes.create({
  url: 'https://example.com',
  country: 'jp'  // Japón
});

import Olostep, {Country} from 'olostep';

const client = new Olostep({api_key: 'your_api_key'});

// Usando valores de enumeración predefinidos (US, DE, FR, GB, SG)
const scrape = await client.scrapes.create({
  url: 'https://example.com',
  country: Country.DE  // Alemania
});

// O usa cualquier código de país válido como cadena
const scrape2 = await client.scrapes.create({
  url: 'https://example.com',
  country: 'jp'  // Japón
});

Caching

Por defecto, cada solicitud de scraping obtiene la página fresca (max_age: 0). Pasa maxAge para reutilizar un resultado reciente con los mismos parámetros y mejorar el tiempo de respuesta. El valor está en segundos; el máximo es 7 días (604800). Consulta Caching para más detalles.

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: ['markdown'],
  maxAge: 86400 // Acepta resultados de hasta 1 día de antigüedad
});

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: ['markdown'],
  max_age: 86400 // Acepta resultados de hasta 1 día de antigüedad
});

Almacenamiento

Por defecto, un resultado de scraping se mantiene por aproximadamente 7 días. Pasa storage.expires_in como 10d, 30d, 60d, 90d, 180d, 365d, o never para mantenerlo por más tiempo. Consulta Storage para más detalles.

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: ['markdown'],
  storage: { expires_in: '90d' }
});

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: ['markdown'],
  storage: { expires_in: '90d' }
});

Extracción LLM

Extrae datos estructurados usando LLMs:

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  llmExtract: {
    schema: {
      title: 'string',
      price: 'number',
      description: 'string'
    },
    prompt: 'Extract product information from this page'
  }
});

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  llm_extract: {
    schema: {
      title: 'string',
      price: 'number',
      description: 'string'
    },
    prompt: 'Extract product information from this page'
  }
});

Configuración del Cliente

import Olostep from 'olostep';

const client = new Olostep({
  apiKey: 'your_api_key',
  apiBaseUrl: 'https://api.olostep.com/v1',  // opcional
  timeoutMs: 150000,  // 150 segundos (opcional)
  retry: {
    maxRetries: 3,
    initialDelayMs: 1000
  },
  userAgent: 'MyApp/1.0'  // opcional
});

import Olostep from 'olostep';

const client = new Olostep({
  api_key: 'your_api_key',
  api_base_url: 'https://api.olostep.com/v1',  // opcional
  timeout_ms: 150000,  // 150 segundos (opcional)
  retry: {
    max_retries: 3,
    initial_delay_ms: 1000
  },
  user_agent: 'MyApp/1.0'  // opcional
});

Destacados de la Funcionalidad

Cliente orientado a async con soporte completo para TypeScript.
Entradas seguras de tipo usando enumeraciones e interfaces de TypeScript (Formats, Countries, Actions, etc.).
Ricos espacios de nombres de recursos con llamadas abreviadas (client.scrapes.create()) y métodos explícitos (client.scrapes.get()).
Capa de transporte compartida con reintentos, tiempos de espera y decodificación JSON.
Jerarquía de errores completa

​Comenzando

​Uso

​Scraping

​Procesamiento por Lotes

​Crawling

​Mapeo del Sitio

​Respuestas Potenciadas por IA

​Recuperación de Contenido

​Opciones Avanzadas

​Acciones Personalizadas

​Ubicación Geográfica

​Caching

​Almacenamiento

​Extracción LLM

​Configuración del Cliente

​Destacados de la Funcionalidad

Comenzando

Uso

Scraping

Procesamiento por Lotes

Crawling

Mapeo del Sitio

Respuestas Potenciadas por IA

Recuperación de Contenido

Opciones Avanzadas

Acciones Personalizadas

Ubicación Geográfica

Caching

Almacenamiento

Extracción LLM

Configuración del Cliente

Destacados de la Funcionalidad