SDK Node.js

Visão geral

O SDK Node.js oficial da Scrapeless oferece acesso a automação de navegador, scraping, crawling, proxies, resultados de pesquisa e extração de chat de IA. Este guia segue o README do repositório do SDK, com exemplos executáveis e detalhes de configuração.

Requisitos

Use Node.js com npm, pnpm ou Yarn. O manifesto do pacote não declara uma versão mínima do Node.js; o fluxo de publicação do repositório usa Node.js 20. JavaScript e TypeScript são suportados, com exportações tanto em módulos ES quanto em CommonJS.

Os exemplos abaixo usam módulos ES. Salve-os como arquivos .mjs, ou defina "type": "module" no package.json do seu projeto.

Instalação

npm install @scrapeless-ai/sdk

Você também pode usar pnpm add @scrapeless-ai/sdk ou yarn add @scrapeless-ai/sdk.

Autenticação / Chave de API

Faça login no painel da Scrapeless e crie uma chave de API. Exporte-a antes de executar os exemplos:

export SCRAPELESS_API_KEY="YOUR_API_KEY"

Mantenha sua chave de API no seu ambiente ou gerenciador de segredos em vez de confirmá-la no controle de versão.

new Scrapeless() lê SCRAPELESS_API_KEY. Você também pode passar uma opção apiKey ao construir o cliente.

Início rápido

Salve isto como quickstart.mjs e execute node quickstart.mjs após definir sua chave de API.

import { Scrapeless } from '@scrapeless-ai/sdk';
 
const client = new Scrapeless();
const result = await client.universal.scrape({
  actor: 'unlocker.webunlocker',
  input: { url: 'https://example.com', method: 'GET', redirect: false }
});
console.log(result);

Matriz de cobertura de produtos

Exemplos de uso

A menos que um exemplo inicialize seu próprio cliente, reutilize const client = new Scrapeless() do Início rápido.

Browser

Instale o Puppeteer para este exemplo: npm install puppeteer-core. Para Playwright e os wrappers de navegador do SDK, consulte os exemplos de integração de navegador.

Gerenciamento avançado de sessões de navegador com suporte aos frameworks Playwright e Puppeteer, com recursos anti-detecção configuráveis (por exemplo, spoofing de fingerprint, resolução de CAPTCHA) e fluxos de automação extensíveis:

import { Scrapeless } from '@scrapeless-ai/sdk';
import puppeteer from 'puppeteer-core';
 
const client = new Scrapeless();
 
// Create a browser session
const { browserWSEndpoint } = await client.browser.create({
  sessionName: 'my-session',
  sessionTTL: 180,
  proxyCountry: 'US'
});
 
// Connect with Puppeteer
const browser = await puppeteer.connect({
  browserWSEndpoint: browserWSEndpoint
});
 
try {
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());
} finally {
  await browser.close();
}

Browser Profile

Gerencie perfis de navegador para sessões persistentes.

const createResponse = await client.profiles.create('My Profile');
console.log('Profile created:', createResponse);
 
const profiles = await client.profiles.list({ page: 1, pageSize: 10 });
console.log('Profiles:', profiles.docs);
 
const profile = await client.profiles.get(createResponse.profileId);
console.log('Profile details:', profile);
 
// Delete the profile when it is no longer needed.
await client.profiles.delete(createResponse.profileId);

Scraping API

APIs diretas de extração de dados para sites (por exemplo, e-commerce, plataformas de viagem). Recupere informações estruturadas de produtos, preços e avaliações com conectores pré-construídos:

const result = await client.scraping.scrape({
  actor: 'scraper.google.search',
  input: {
    'q': 'coffee',
    'hl': 'en',
    'gl': 'us'
  }
});
 
console.log(result.data);

Web Unlocker

Extraia dados de sites usando o Web Unlocker (exposto como client.universal).

const result = await client.universal.scrape({
  actor: 'unlocker.webunlocker',
  input: { url: 'https://example.com', method: 'GET', redirect: false }
});
console.log(result);

Crawl

Extraia dados de páginas individuais ou percorra domínios inteiros, exportando em formatos como Markdown, JSON, HTML, capturas de tela e links.

const result = await client.scrapingCrawl.scrapeUrl('https://example.com');
 
console.log(result);

Proxy

Gere uma URL de proxy usando seu gateway e configurações de sessão.

const proxyUrl = client.proxies.proxy({
  type: 'residential',
  country: 'US',
  sessionDuration: 30,
  sessionId: client.proxies.generateSessionId(),
  gateway: 'your-proxy-gateway:port'
});
console.log(proxyUrl);

AI Scraper

Criar uma tarefa: client.aiScraper.createTask(request)

Passe o actor obrigatório e o input específico do actor. Um objeto webhook opcional aceita uma url de callback. A promise é resolvida com a resposta completa da API, incluindo task_id e status, e task_result quando disponível.

Extraia conteúdo de chat de IA em massa para monitorar menções à marca, comparar respostas e analisar inteligência competitiva a partir dos modelos mais recentes. Recupere URLs, prompts, respostas em Markdown, citações e muito mais por meio de uma única integração.

Os actors suportados incluem scraper.chatgpt, scraper.perplexity, scraper.copilot, scraper.gemini, scraper.aimode, scraper.overview, scraper.grok e scraper.alexa. O JSON de input depende do actor; consulte a documentação do AI Scraper para parâmetros detalhados. O JSON opcional de webhook contém uma url de callback.

import { Scrapeless } from '@scrapeless-ai/sdk';
 
const client = new Scrapeless(); // Uses SCRAPELESS_API_KEY
 
const task = await client.aiScraper.createTask({
  actor: 'scraper.chatgpt',
  input: {
    prompt: 'Most reliable proxy service for data extraction',
    country: 'US',
    web_search: true
  },
  // Optional: webhook: { url: 'https://your-webhook.example.com' }
});
console.log('Created task:', task);

Obter status e resultado da tarefa: client.aiScraper.getTaskResult(taskId)

Passe o task_id obtido na criação. Continue no mesmo script, ou armazene o ID e recupere o resultado em uma requisição posterior.

const result = await client.aiScraper.getTaskResult(task.task_id);
 
switch (result.status) {
  case 'success':
    console.log('Task result:', result.task_result);
    break;
  case 'failed':
    console.error('Task failed:', result.message);
    break;
  case 'running':
    console.log('Task is running. Retrieve the result again later.');
    break;
}

Ambos os métodos retornam o JSON da API inalterado. A criação retorna task_id, status e, quando disponível, task_result. A recuperação do resultado retorna status, task_result quando disponível e message em caso de falha. O status é success, failed ou running; o SDK não faz polling automaticamente.

A criação já pode incluir um resultado. Inspecione seu status antes de agendar novas requisições. Se você implementar polling, use um atraso e um tempo limite geral.

Google Search API

const result = await client.deepserp.scrape({
  actor: 'scraper.google.search',
  input: { q: 'nike site:www.nike.com' }
});
console.log(result);

Para integrações mais completas, navegue pelo diretório de exemplos do repositório.

Tratamento de erros

Capture ScrapelessError para falhas de requisições à API. Verifique o status de uma resposta do AI Scraper separadamente: uma tarefa pode retornar failed sem que a requisição HTTP lance um erro.

import { Scrapeless, ScrapelessError } from '@scrapeless-ai/sdk';
 
try {
  const client = new Scrapeless();
  const result = await client.universal.scrape({
    actor: 'unlocker.webunlocker',
    input: { url: 'https://example.com', method: 'GET' }
  });
  console.log(result);
} catch (error) {
  if (error instanceof ScrapelessError) {
    console.error('Scrapeless error:', error.message);
    console.error('Status code:', error.statusCode);
  } else {
    throw error;
  }
}

Configuração / Variáveis de ambiente

A chave de API é obrigatória. As substituições de endpoint são opcionais; a tabela mostra seus valores padrão.

import { Scrapeless } from '@scrapeless-ai/sdk';
 
const client = new Scrapeless({
  apiKey: process.env.SCRAPELESS_API_KEY,
  timeout: 30000, // Request timeout in milliseconds
  baseApiUrl: 'https://api.scrapeless.com',
  browserApiUrl: 'https://browser.scrapeless.com',
  scrapingCrawlApiUrl: 'https://api.scrapeless.com'
});

A configuração explícita tem precedência sobre as variáveis de ambiente. O tempo limite padrão de requisição é de 30.000 milissegundos.

Suporte

• Código-fonte e README do SDK
• Reportar um problema
• Documentação da Scrapeless
• Entre na comunidade do Discord
• Suporte por e-mail

O SDK é distribuído sob a Licença MIT.

Projetos relacionados

• Documentação do SDK Python · GitHub
• Documentação do SDK Go · GitHub
• Visão geral do SDK