Olostep NodeJS SDK - Olostep Docs

Pacchetto NPM: olostep

Introduzione

npm install olostep

import Olostep from 'olostep';

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

// Esempio minimo di 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});

// Esempio minimo di scraping
const result = await client.scrapes.create('https://example.com');
console.log(result.id, result.html_content);

Il SDK NodeJS accetta sia camelCase che snake_case per tutti i parametri. Usa snake_case se stai sviluppando per agenti AI, corrisponde ai nomi dei campi nativi dell’API.

Utilizzo

Scraping

Esegui lo scraping di un singolo URL con varie opzioni:

import Olostep, {Format} from 'olostep';

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

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

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

// Accedi al contenuto
console.log(scrape.html_content);
console.log(scrape.markdown_content);

// Ottieni scraping per ID
const fetched = await client.scrapes.get(scrape.id);

import Olostep, {Format} from 'olostep';

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

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

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

// Accedi al contenuto
console.log(scrape.html_content);
console.log(scrape.markdown_content);

// Ottieni scraping per ID
const fetched = await client.scrapes.get(scrape.id);

Elaborazione in batch

Elabora più URL in un singolo batch:

// Usando stringhe URL (ID personalizzati generati automaticamente)
const batch = await client.batches.create([
  'https://example.com',
  'https://example.org',
  'https://example.net'
]);

// Oppure con ID personalizzati espliciti
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} creato con ${batch.total_urls} URL`);

// Attendi il completamento
await batch.waitTillDone({
  checkEveryNSecs: 5,
  timeoutSeconds: 120
});

// Ottieni informazioni sul batch
const info = await batch.info();
console.log(info);

// Stream dei risultati individuali
for await (const item of batch.items()) {
  console.log(item.custom_id);
}

// Usando stringhe URL (ID personalizzati generati automaticamente)
const batch = await client.batches.create([
  'https://example.com',
  'https://example.org',
  'https://example.net'
]);

// Oppure con ID personalizzati espliciti
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} creato con ${batch.total_urls} URL`);

// Attendi il completamento
await batch.waitTillDone({
  check_every_n_secs: 5,
  timeout_seconds: 120
});

// Ottieni informazioni sul batch
const info = await batch.info();
console.log(info);

// Stream dei risultati individuali
for await (const item of batch.items()) {
  console.log(item.custom_id);
}

Crawling

Esegui il crawling di un intero sito web:

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

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

// Attendi il completamento
await crawl.waitTillDone({
  checkEveryNSecs: 10,
  timeoutSeconds: 300
});

// Ottieni informazioni sul crawl
const info = await crawl.info();
console.log(`Crawled ${info.pages_crawled} pagine`);

// Stream delle pagine scansionate
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} avviato`);

// Attendi il completamento
await crawl.waitTillDone({
  check_every_n_secs: 10,
  timeout_seconds: 300
});

// Ottieni informazioni sul crawl
const info = await crawl.info();
console.log(`Crawled ${info.pages_crawled} pagine`);

// Stream delle pagine scansionate
for await (const page of crawl.pages()) {
  console.log(page.url, page.status_code);
}

Mappatura del sito

Genera una sitemap degli URL da un sito web:

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

console.log(`Mappa ${map.id} creata`);

// Stream degli URL
for await (const url of map.urls()) {
  console.log(url);
}

// Ottieni informazioni sulla mappa
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(`Mappa ${map.id} creata`);

// Stream degli URL
for await (const url of map.urls()) {
  console.log(url);
}

// Ottieni informazioni sulla mappa
const info = await map.info();

Risposte potenziate dall’AI

Ottieni risposte dalle pagine web usando l’AI:

import Olostep from 'olostep';

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

// Compito semplice: passa una stringa direttamente
const answer = await client.answers.create(
  'Qual è l'argomento principale di https://example.com?'
);
console.log(answer.answer);
console.log(answer.sources);

// Con output JSON strutturato
const structured = await client.answers.create({
  task: 'Estrai tutti i nomi dei prodotti e i prezzi da https://example.com',
  jsonFormat: {
    products: [{name: '', price: ''}]
  }
});
console.log(structured.json_content);

// Recupera una risposta precedentemente creata per 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'});

// Compito semplice: passa una stringa direttamente
const answer = await client.answers.create(
  'Qual è l'argomento principale di https://example.com?'
);
console.log(answer.answer);
console.log(answer.sources);

// Con output JSON strutturato
const structured = await client.answers.create({
  task: 'Estrai tutti i nomi dei prodotti e i prezzi da https://example.com',
  json_format: {
    products: [{name: '', price: ''}]
  }
});
console.log(structured.json_content);

// Recupera una risposta precedentemente creata per ID
const fetched = await client.answers.get(answer.id);
console.log(fetched.answer);

Recupero del contenuto

Recupera contenuti precedentemente estratti:

// Ottieni contenuto in formato specifico
const content = await client.retrieve(retrieveId, Format.MARKDOWN);
console.log(content.markdown_content);

// Più formati
const content = await client.retrieve(retrieveId, [
  Format.HTML,
  Format.MARKDOWN
]);

Opzioni avanzate

Azioni personalizzate

Esegui azioni del browser prima dello 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'}
  ]
});

Posizione geografica

Esegui lo scraping da diversi paesi utilizzando codici paese predefiniti o qualsiasi stringa di codice paese valida:

import Olostep, {Country} from 'olostep';

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

// Usando valori enum predefiniti (US, DE, FR, GB, SG)
const scrape = await client.scrapes.create({
  url: 'https://example.com',
  country: Country.DE  // Germania
});

// Oppure usa qualsiasi codice paese valido come stringa
const scrape2 = await client.scrapes.create({
  url: 'https://example.com',
  country: 'jp'  // Giappone
});

import Olostep, {Country} from 'olostep';

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

// Usando valori enum predefiniti (US, DE, FR, GB, SG)
const scrape = await client.scrapes.create({
  url: 'https://example.com',
  country: Country.DE  // Germania
});

// Oppure usa qualsiasi codice paese valido come stringa
const scrape2 = await client.scrapes.create({
  url: 'https://example.com',
  country: 'jp'  // Giappone
});

Caching

Per impostazione predefinita, ogni richiesta di scraping recupera la pagina fresca (max_age: 0). Passa maxAge per riutilizzare un risultato recente con gli stessi parametri e migliorare il tempo di risposta. Il valore è in secondi; il massimo è 7 giorni (604800). Vedi Caching per i dettagli.

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: ['markdown'],
  maxAge: 86400 // Accetta risultati fino a 1 giorno di vecchiaia
});

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: ['markdown'],
  max_age: 86400 // Accetta risultati fino a 1 giorno di vecchiaia
});

Storage

Per impostazione predefinita, un risultato di scraping viene conservato per circa 7 giorni. Passa storage.expires_in come 10d, 30d, 60d, 90d, 180d, 365d, o never per conservarlo più a lungo. Vedi Storage per i dettagli.

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

Estrazione LLM

Estrai dati strutturati usando LLM:

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  llmExtract: {
    schema: {
      title: 'string',
      price: 'number',
      description: 'string'
    },
    prompt: 'Estrai informazioni sul prodotto da questa pagina'
  }
});

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  llm_extract: {
    schema: {
      title: 'string',
      price: 'number',
      description: 'string'
    },
    prompt: 'Estrai informazioni sul prodotto da questa pagina'
  }
});

Configurazione del client

import Olostep from 'olostep';

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

import Olostep from 'olostep';

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

Caratteristiche principali

Client orientato agli async con supporto completo per TypeScript.
Input sicuri tramite tipi usando enum e interfacce TypeScript (Formats, Countries, Actions, ecc.).
Namespace delle risorse ricchi con chiamate abbreviate (client.scrapes.create()) e metodi espliciti (client.scrapes.get()).
Livello di trasporto condiviso con retry, timeout e decodifica JSON.
Gerarchia degli errori completa.

​Introduzione

​Utilizzo

​Scraping

​Elaborazione in batch

​Crawling

​Mappatura del sito

​Risposte potenziate dall’AI

​Recupero del contenuto

​Opzioni avanzate

​Azioni personalizzate

​Posizione geografica

​Caching

​Storage

​Estrazione LLM

​Configurazione del client

​Caratteristiche principali

Introduzione

Utilizzo

Scraping

Elaborazione in batch

Crawling

Mappatura del sito

Risposte potenziate dall’AI

Recupero del contenuto

Opzioni avanzate

Azioni personalizzate

Posizione geografica

Caching

Storage

Estrazione LLM

Configurazione del client

Caratteristiche principali