Olostep NodeJS SDK - Olostep Docs

Package NPM: olostep

Pour commencer

npm install olostep

import Olostep from 'olostep';

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

// Exemple minimal 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});

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

Le SDK NodeJS accepte à la fois camelCase et snake_case pour tous les paramètres. Utilise snake_case si tu développes pour des agents IA, cela correspond aux noms de champs natifs de l’API.

Utilisation

Scraping

Scrape une URL unique avec diverses options :

import Olostep, {Format} from 'olostep';

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

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

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

// Accéder au contenu
console.log(scrape.html_content);
console.log(scrape.markdown_content);

// Obtenir un scrape par 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');

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

// Accéder au contenu
console.log(scrape.html_content);
console.log(scrape.markdown_content);

// Obtenir un scrape par ID
const fetched = await client.scrapes.get(scrape.id);

Traitement par lots

Traite plusieurs URLs dans un seul lot :

// Utilisation de chaînes d'URL (IDs personnalisés générés automatiquement)
const batch = await client.batches.create([
  'https://example.com',
  'https://example.org',
  'https://example.net'
]);

// Ou avec des IDs personnalisés explicites
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} créé avec ${batch.total_urls} URLs`);

// Attendre la fin
await batch.waitTillDone({
  checkEveryNSecs: 5,
  timeoutSeconds: 120
});

// Obtenir les infos du lot
const info = await batch.info();
console.log(info);

// Diffuser les résultats individuels
for await (const item of batch.items()) {
  console.log(item.custom_id);
}

// Utilisation de chaînes d'URL (IDs personnalisés générés automatiquement)
const batch = await client.batches.create([
  'https://example.com',
  'https://example.org',
  'https://example.net'
]);

// Ou avec des IDs personnalisés explicites
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} créé avec ${batch.total_urls} URLs`);

// Attendre la fin
await batch.waitTillDone({
  check_every_n_secs: 5,
  timeout_seconds: 120
});

// Obtenir les infos du lot
const info = await batch.info();
console.log(info);

// Diffuser les résultats individuels
for await (const item of batch.items()) {
  console.log(item.custom_id);
}

Exploration

Explore un site web entier :

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

console.log(`Exploration ${crawl.id} commencée`);

// Attendre la fin
await crawl.waitTillDone({
  checkEveryNSecs: 10,
  timeoutSeconds: 300
});

// Obtenir les infos de l'exploration
const info = await crawl.info();
console.log(`Exploré ${info.pages_crawled} pages`);

// Diffuser les pages explorées
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(`Exploration ${crawl.id} commencée`);

// Attendre la fin
await crawl.waitTillDone({
  check_every_n_secs: 10,
  timeout_seconds: 300
});

// Obtenir les infos de l'exploration
const info = await crawl.info();
console.log(`Exploré ${info.pages_crawled} pages`);

// Diffuser les pages explorées
for await (const page of crawl.pages()) {
  console.log(page.url, page.status_code);
}

Cartographie du site

Génère un plan du site des URLs d’un site web :

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

console.log(`Carte ${map.id} créée`);

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

// Obtenir les infos de la carte
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(`Carte ${map.id} créée`);

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

// Obtenir les infos de la carte
const info = await map.info();

Réponses alimentées par l’IA

Obtiens des réponses à partir de pages web en utilisant l’IA :

import Olostep from 'olostep';

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

// Tâche simple : passer une chaîne directement
const answer = await client.answers.create(
  'Quel est le sujet principal de https://example.com?'
);
console.log(answer.answer);
console.log(answer.sources);

// Avec sortie JSON structurée
const structured = await client.answers.create({
  task: 'Extraire tous les noms de produits et prix de https://example.com',
  jsonFormat: {
    products: [{name: '', price: ''}]
  }
});
console.log(structured.json_content);

// Récupérer une réponse précédemment créée par 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'});

// Tâche simple : passer une chaîne directement
const answer = await client.answers.create(
  'Quel est le sujet principal de https://example.com?'
);
console.log(answer.answer);
console.log(answer.sources);

// Avec sortie JSON structurée
const structured = await client.answers.create({
  task: 'Extraire tous les noms de produits et prix de https://example.com',
  json_format: {
    products: [{name: '', price: ''}]
  }
});
console.log(structured.json_content);

// Récupérer une réponse précédemment créée par ID
const fetched = await client.answers.get(answer.id);
console.log(fetched.answer);

Récupération de contenu

Récupère le contenu précédemment scrappé :

// Obtenir le contenu dans un ou plusieurs formats spécifiques
const content = await client.retrieve(retrieveId, Format.MARKDOWN);
console.log(content.markdown_content);

// Plusieurs formats
const content = await client.retrieve(retrieveId, [
  Format.HTML,
  Format.MARKDOWN
]);

Options avancées

Actions personnalisées

Effectue des actions de navigateur avant le 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'}
  ]
});

Localisation géographique

Scrape depuis différents pays en utilisant des codes pays prédéfinis ou tout code pays valide :

import Olostep, {Country} from 'olostep';

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

// Utilisation de valeurs d'énumération prédéfinies (US, DE, FR, GB, SG)
const scrape = await client.scrapes.create({
  url: 'https://example.com',
  country: Country.DE  // Allemagne
});

// Ou utiliser tout code pays valide en tant que chaîne
const scrape2 = await client.scrapes.create({
  url: 'https://example.com',
  country: 'jp'  // Japon
});

import Olostep, {Country} from 'olostep';

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

// Utilisation de valeurs d'énumération prédéfinies (US, DE, FR, GB, SG)
const scrape = await client.scrapes.create({
  url: 'https://example.com',
  country: Country.DE  // Allemagne
});

// Ou utiliser tout code pays valide en tant que chaîne
const scrape2 = await client.scrapes.create({
  url: 'https://example.com',
  country: 'jp'  // Japon
});

Mise en cache

Par défaut, chaque requête de scraping récupère la page fraîche (max_age: 0). Passe maxAge pour réutiliser un résultat récent avec les mêmes paramètres et améliorer le temps de réponse. La valeur est en secondes ; le maximum est de 7 jours (604800). Voir Mise en cache pour plus de détails.

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: ['markdown'],
  maxAge: 86400 // Accepter les résultats jusqu'à 1 jour
});

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  formats: ['markdown'],
  max_age: 86400 // Accepter les résultats jusqu'à 1 jour
});

Stockage

Par défaut, un résultat de scraping est conservé environ 7 jours. Passe storage.expires_in comme 10d, 30d, 60d, 90d, 180d, 365d, ou never pour le conserver plus longtemps. Voir Stockage pour plus de détails.

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

Extraction LLM

Extrait des données structurées en utilisant des LLMs :

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  llmExtract: {
    schema: {
      title: 'string',
      price: 'number',
      description: 'string'
    },
    prompt: 'Extraire les informations sur le produit de cette page'
  }
});

const scrape = await client.scrapes.create({
  url: 'https://example.com',
  llm_extract: {
    schema: {
      title: 'string',
      price: 'number',
      description: 'string'
    },
    prompt: 'Extraire les informations sur le produit de cette page'
  }
});

Configuration du client

import Olostep from 'olostep';

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

import Olostep from 'olostep';

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

Points forts des fonctionnalités

Client orienté asynchrone avec prise en charge complète de TypeScript.
Entrées de type sécurisé utilisant des énumérations et interfaces TypeScript (Formats, Pays, Actions, etc.).
Espaces de noms de ressources riches avec des appels abrégés (client.scrapes.create()) et des méthodes explicites (client.scrapes.get()).
Couche de transport partagée avec des réessais, des délais d’attente et un décodage JSON.
Hiérarchie d’erreurs complète

​Pour commencer

​Utilisation

​Scraping

​Traitement par lots

​Exploration

​Cartographie du site

​Réponses alimentées par l’IA

​Récupération de contenu

​Options avancées

​Actions personnalisées

​Localisation géographique

​Mise en cache

​Stockage

​Extraction LLM

​Configuration du client

​Points forts des fonctionnalités

Pour commencer

Utilisation

Scraping

Traitement par lots

Exploration

Cartographie du site

Réponses alimentées par l’IA

Récupération de contenu

Options avancées

Actions personnalisées

Localisation géographique

Mise en cache

Stockage

Extraction LLM

Configuration du client

Points forts des fonctionnalités