SDK

Instalação

npm i @scrapa/sdk

Ler uma página

import { Scrapa } from "@scrapa/sdk";

const scrapa = new Scrapa(process.env.SCRAPA_API_KEY!);

const page = await scrapa.scrape({
  url: "https://example.com",
  formats: ["markdown", "links"],
});

console.log(page.engine, page.markdown);

O que o seu editor completa é o que o servidor aceita: os tipos dos parâmetros saem dos mesmos schemas que validam a requisição.

Quanto custou

const page = await scrapa.scrape(
  { url: "https://example.com" },
  { onUsage: ({ cost, creditsRemaining }) => log(cost, creditsRemaining) },
);

// …or before you spend anything:
const { cost, maxCost } = await scrapa.quote({ url: "https://example.com" });

O método devolve a página em si, então o medidor chega por callback, uma vez por chamada, e não num campo mutável que duas extrações simultâneas disputariam.

Quando alguém diz não

import { ScrapaError } from "@scrapa/sdk";

try {
  await scrapa.scrape({ url });
} catch (error) {
  if (!(error instanceof ScrapaError)) throw error;
  switch (error.outcome) {
    case "blocked":
      // time ran out, nobody said no: give the page more time
      if (error.code === "NAV_TIMEOUT") return scrapa.scrape({ url, timeoutMs: 60_000 });
      // the site said no: try another pool, country or engine
      return scrapa.scrape({ url, engine: "browser" });
    case "denied": // our policy said no, so retrying cannot help
      return null;
    case "broken": // ours, already refunded: worth one retry
      return scrapa.scrape({ url });
  }
  throw error; // a bad field, a missing key, a spent quota
}

outcome diz o que fazer a seguir: blocked, denied ou broken. Um código foge à regra: o NAV_TIMEOUT vem como blocked, mas ninguém disse não. O tempo acabou, então aumente o timeoutMs em vez de trocar de engine ou de país. cost vem no erro também, e é zero nos três, a não ser que um script seu de browser.actions tenha rodado na página antes: aí blocked e denied são cobrados pelo preço do navegador e pelo tráfego. Broken é sempre estornado.

O que ele repete

Só o que repetir resolve. Um 429, 408 ou 425 quer dizer que a chamada nem rodou, então o cliente manda de novo e espera o tempo que a resposta pede, quando são até 10 segundos. Uma consulta, um quote ou um cancelamento também vai de novo depois de um 5xx ou de ficar sem resposta. Um scrape, uma busca, um lote novo e uma sessão nova não: se um deles estourou o tempo do seu lado, ele pode já ter lido a página, e uma segunda tentativa seria cobrada pela mesma página duas vezes. Você recebe o erro e decide.