> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Olostep NodeJS SDK

> SDK officiel NodeJS pour rechercher, extraire et structurer des données du Web

**Package NPM**: [olostep](https://www.npmjs.com/package/olostep)

## Pour commencer

```bash theme={null}
npm install olostep
```

<CodeGroup>
  ```ts camelCase theme={null}
  import Olostep from 'olostep';

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

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

  ```ts snake_case theme={null}
  import Olostep from 'olostep';

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

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

<Note>
  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.
</Note>

## Utilisation

### Scraping

Scrape une URL unique avec diverses options :

<CodeGroup>
  ```ts camelCase theme={null}
  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 le scraping par ID
  const fetched = await client.scrapes.get(scrape.id);
  ```

  ```ts snake_case theme={null}
  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 le scraping par ID
  const fetched = await client.scrapes.get(scrape.id);
  ```
</CodeGroup>

### Traitement par lot

Traite plusieurs URLs dans un seul lot :

<CodeGroup>
  ```ts camelCase theme={null}
  // En utilisant des chaînes d'URL (IDs personnalisés auto-générés)
  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);
  }
  ```

  ```ts snake_case theme={null}
  // En utilisant des chaînes d'URL (IDs personnalisés auto-générés)
  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);
  }
  ```
</CodeGroup>

### Exploration

Explore un site web entier :

<CodeGroup>
  ```ts camelCase theme={null}
  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);
  }
  ```

  ```ts snake_case theme={null}
  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);
  }
  ```
</CodeGroup>

### Cartographie du site

Génère une carte des URLs d'un site web :

<CodeGroup>
  ```ts camelCase theme={null}
  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();
  ```

  ```ts snake_case theme={null}
  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();
  ```
</CodeGroup>

### Réponses alimentées par l'IA

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

<CodeGroup>
  ```ts camelCase theme={null}
  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);
  ```

  ```ts snake_case theme={null}
  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);
  ```
</CodeGroup>

### Récupération de contenu

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

```ts theme={null}
// Obtenir le contenu dans un format spécifique
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 :

```ts theme={null}
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 :

<CodeGroup>
  ```ts camelCase theme={null}
  import Olostep, {Country} from 'olostep';

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

  // En utilisant des 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 utilise tout code pays valide comme chaîne
  const scrape2 = await client.scrapes.create({
    url: 'https://example.com',
    country: 'jp'  // Japon
  });
  ```

  ```ts snake_case theme={null}
  import Olostep, {Country} from 'olostep';

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

  // En utilisant des 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 utilise tout code pays valide comme chaîne
  const scrape2 = await client.scrapes.create({
    url: 'https://example.com',
    country: 'jp'  // Japon
  });
  ```
</CodeGroup>

#### 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](/features/scrapes#caching) pour plus de détails.

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

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

#### Extraction LLM

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

<CodeGroup>
  ```ts camelCase theme={null}
  const scrape = await client.scrapes.create({
    url: 'https://example.com',
    llmExtract: {
      schema: {
        title: 'string',
        price: 'number',
        description: 'string'
      },
      prompt: 'Extraire les informations produit de cette page'
    }
  });
  ```

  ```ts snake_case theme={null}
  const scrape = await client.scrapes.create({
    url: 'https://example.com',
    llm_extract: {
      schema: {
        title: 'string',
        price: 'number',
        description: 'string'
      },
      prompt: 'Extraire les informations produit de cette page'
    }
  });
  ```
</CodeGroup>

### Configuration du client

<CodeGroup>
  ```ts camelCase theme={null}
  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
  });
  ```

  ```ts snake_case theme={null}
  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
  });
  ```
</CodeGroup>

### Points forts des fonctionnalités

* Client asynchrone avec prise en charge complète de TypeScript.
* Entrées sûres grâce à TypeScript avec des énumérations et interfaces (Formats, Pays, Actions, etc.).
* Espaces de noms riches en ressources avec des appels abrégés (`client.scrapes.create()`) et des méthodes explicites (`client.scrapes.get()`).
* Couche de transport partagée avec reprises, délais d'attente et décodage JSON.
* Hiérarchie d'erreurs complète