Node.js SDK

Descripción general

El SDK oficial de Scrapeless para Node.js proporciona acceso a automatización de navegadores, extracción de datos, rastreo, proxies, resultados de búsqueda y extracción de conversaciones con inteligencia artificial. Esta guía sigue el README del repositorio del SDK, con ejemplos ejecutables y detalles de configuración.

Requisitos

Use Node.js con npm, pnpm o Yarn. El manifiesto del paquete no declara una versión mínima de Node.js; el flujo de trabajo de publicación del repositorio utiliza Node.js 20. Se admiten JavaScript y TypeScript, con exportaciones de módulos ES y CommonJS.

Los ejemplos siguientes utilizan módulos ES. Guárdelos como .mjs archivos, o establezca "type": "module" en el package.json de su proyecto.

Instalación

npm install @scrapeless-ai/sdk

También puede usar pnpm add @scrapeless-ai/sdk o yarn add @scrapeless-ai/sdk.

Autenticación / Clave de API

Inicie sesión en el panel de control de Scrapeless y cree una clave de API. Exporte dicha clave antes de ejecutar los ejemplos:

export SCRAPELESS_API_KEY="YOUR_API_KEY"

Mantenga su clave de API en su entorno o gestor de secretos en lugar de incluirla en el control de versiones.

new Scrapeless() lee SCRAPELESS_API_KEY. También puede pasar una opción apiKey al construir el cliente.

Inicio rápido

Guarde esto como quickstart.mjs y ejecute node quickstart.mjs después de establecer su clave 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 productos

Ejemplos de uso

A menos que un ejemplo inicialice su propio cliente, reutilice const client = new Scrapeless() del inicio rápido.

Navegador

Instale Puppeteer para este ejemplo: npm install puppeteer-core. Para Playwright y los contenedores del SDK para navegadores, consulte los ejemplos de integración con navegadores.

Gestión avanzada de sesiones de navegador que admite los frameworks Playwright y Puppeteer, con capacidades anti-detección configurables (por ejemplo, suplantación de huellas digitales, resolución de CAPTCHA) y flujos de trabajo de automatización ampliables:

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

Perfil de navegador

Gestione perfiles de navegador para sesiones 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 directas para la extracción de datos de sitios web (por ejemplo, comercio electrónico, plataformas de viajes). Recupere información estructurada sobre productos, precios y reseñas mediante conectores predefinidos:

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

Web Unlocker

Extraiga datos de sitios web usando Web Unlocker (expuesto 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

Extraiga datos de páginas individuales o recorra dominios completos, exportando en formatos que incluyen Markdown, JSON, HTML, capturas de pantalla y enlaces.

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

Proxy

Genere una URL de proxy utilizando su puerta de enlace y configuración de sesión.

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

Crear una tarea: client.aiScraper.createTask(request)

Pase el actor requerido y los input específicos del actor. Un objeto opcional webhook acepta un callback url. La promesa se resuelve en la respuesta completa de la API, incluyendo task_id y status, y task_result cuando esté disponible.

Extraiga contenido de chat de IA en masa para monitorear menciones de marca, comparar respuestas y analizar inteligencia competitiva de los modelos más recientes. Recupere URLs, indicaciones, respuestas en Markdown, citas y más a través de una sola integración.

Los Actor compatibles incluyen scraper.chatgpt, scraper.perplexity, scraper.copilot, scraper.gemini, scraper.aimode, scraper.overview, scraper.grok, y scraper.alexa. El JSON de input depende del actor; consulte la documentación de AI Scraper para parámetros detallados. El JSON opcional de webhook contiene un callback url.

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

Obtener estado y resultado de la tarea: client.aiScraper.getTaskResult(taskId)

Pase el task_id obtenido al crearla. Continúe en el mismo script, o almacene el ID y recupere el resultado en una solicitud 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 métodos devuelven el JSON de la API sin cambios. La creación devuelve task_id, status, y, cuando está disponible, task_result. La recuperación de resultados devuelve status, task_result cuando está disponible, y message en caso de error. El estado es success, failed, o running; el SDK no realiza sondeos automáticamente.

La creación ya puede incluir un resultado. Inspeccione su estado antes de programar solicitudes adicionales. Si implementa sondeo, utilice un retraso y un tiempo de espera general.

Google Search API

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

Para integraciones más completas, explore el directorio ejemplos del repositorio.

Manejo de errores

Capture ScrapelessError para fallos en solicitudes de API. Verifique la status respuesta del AI Scraper por separado: una tarea puede devolver failed sin que la solicitud HTTP genere un error.

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

Configuración / Variables de entorno

Se requiere la clave de API. Las sustituciones de endpoint son opcionales; la tabla muestra sus valores predeterminados.

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

La configuración explícita tiene prioridad sobre las variables de entorno. El tiempo de espera predeterminado para solicitudes es de 30.000 milisegundos.

Soporte

• Código fuente del SDK y README
• Informar de un problema
• Documentación de Scrapeless
• Únase a la comunidad de Discord
• Soporte por correo electrónico

El SDK se publica bajo la licencia Licencia MIT.

Proyectos relacionados

• Documentación del SDK para Python · GitHub
• Documentación del SDK para Go · GitHub
• Descripción general del SDK