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 rastreo
const info = await crawl.info();
console.log(`Rastreado ${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 rastreo
const info = await crawl.info();
console.log(`Rastreado ${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 desde 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(
  '¿Cuál es el tema principal de https://example.com?'
);
console.log(answer.answer);
console.log(answer.sources);

// Con salida JSON estructurada
const structured = await client.answers.create({
  task: 'Extrae todos los nombres de productos y precios de 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(
  '¿Cuál es el tema principal de https://example.com?'
);
console.log(answer.answer);
console.log(answer.sources);

// Con salida JSON estructurada
const structured = await client.answers.create({
  task: 'Extrae todos los nombres de productos y precios de 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 del 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

Haz 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
});

Caché

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 de 7 días (604800). Consulta Caché 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
});

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: 'Extrae información del producto de esta página'
  }
});

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  llm_extract: {
    schema: {
      title: 'string',
      price: 'number',
      description: 'string'
    },
    prompt: 'Extrae información del producto de esta página'
  }
});

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
});

Características Destacadas

Cliente orientado a async con soporte completo para TypeScript.
Entradas seguras con TypeScript usando enums e interfaces (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

​Caché

​Extracción LLM

​Configuración del Cliente

​Características Destacadas

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

Caché

Extracción LLM

Configuración del Cliente

Características Destacadas