SEO report API in Node.js: audit a site and read the findings

// Audit one site with the SEOReport API and print its top three fixes.
// Usage: SEOREPORT_API_KEY=... node recipe.mjs [https://example.com]
// Node.js 18 or later: global fetch, ES modules, no dependencies.
import { writeFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";

const API = "https://seoreport.dev/api/v1/reports";
const MAX_WAIT_MS = 300_000; // stop waiting after five minutes
const DEFAULT_POLL_MS = 5_000; // used only when the API sends no pollAfterMs

class ApiRefusal extends Error {}

const key = (process.env.SEOREPORT_API_KEY ?? "").trim();
if (!key) {
  console.error("Set SEOREPORT_API_KEY to an API key from your SEOReport plan.");
  process.exit(2);
}
const target = process.argv[2] ?? "https://example.com";

/** Send one request; return { status, headers, text } for any HTTP status. */
async function request(method, url, body) {
  const headers = {
    Authorization: `Bearer ${key}`,
    Accept: "application/json",
    "User-Agent": "seoreport-recipe-node/1",
  };
  if (body !== undefined) headers["Content-Type"] = "application/json";
  const res = await fetch(url, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(60_000),
  });
  return { status: res.status, headers: res.headers, text: await res.text() };
}

function parse({ status, text }) {
  try {
    return JSON.parse(text);
  } catch {
    throw new ApiRefusal(`HTTP ${status}: not JSON: ${text.slice(0, 200)}`);
  }
}

/** Turn an error response into one line that names the API's own code. */
function refuse({ status, headers }, payload) {
  const code = payload.code ?? payload.errorCode ?? `HTTP_${status}`;
  let line = `${code} (HTTP ${status}): ${payload.error ?? "no message"}`;
  if (payload.ctaUrl) line += ` -> https://seoreport.dev${payload.ctaUrl}`;
  const retryAfter = headers.get("retry-after");
  if (retryAfter) line += ` [retry after ${retryAfter}s]`;
  throw new ApiRefusal(line);
}

async function main() {
  // 1. Create the report (or reuse the one this account already has).
  let res = await request("POST", API, { url: target });
  const created = parse(res);
  if (res.status >= 400 || !created.success) refuse(res, created);
  const jobId = created.report.jobId;
  let state = created.report.status;
  let pollMs = created.pollAfterMs || DEFAULT_POLL_MS;
  console.log(`job ${jobId}: ${state}`);

  // 2. Poll politely until the job leaves queued/running, with a hard cap.
  const deadline = Date.now() + MAX_WAIT_MS;
  let job = created;
  while (state === "queued" || state === "running") {
    if (Date.now() + pollMs > deadline) {
      throw new ApiRefusal(`gave up after ${MAX_WAIT_MS / 1000}s; job ${jobId} is still ${state}`);
    }
    await sleep(pollMs);
    res = await request("GET", `${API}/${jobId}`);
    job = parse(res);
    if (res.status >= 400 || !job.success) refuse(res, job);
    state = job.report.status;
    if (job.stuck) throw new ApiRefusal(`job ${jobId} stopped making progress; start a new report`);
    pollMs = job.pollAfterMs || DEFAULT_POLL_MS;
  }

  if (state !== "completed") {
    const err = job.error ?? {};
    const retry = err.retryable ? " (retryable)" : "";
    throw new ApiRefusal(`report ${state}: ${err.code ?? state}: ${err.message ?? ""}${retry}`);
  }

  // 3. Download the JSON diagnosis and keep a copy.
  res = await request("GET", `${API}/${jobId}/download?format=json`);
  const report = parse(res);
  if (res.status >= 400) refuse(res, report);
  const path = `seoreport-${jobId}.json`;
  await writeFile(path, res.text);

  // 4. Print the score, the band and the first three open findings.
  console.log(`${report.targetUrl}: ${report.score.overall}/100 (${report.score.band})`);
  console.log(`open issues: ${report.openIssues.total}, pages analysed: ${report.pagesAnalyzed}`);
  const openFindings = report.findings.filter((f) => f.status === "fail" || f.status === "warn");
  for (const finding of openFindings.slice(0, 3)) {
    const severity = finding.severity ?? finding.status;
    console.log(`\n#${finding.rank} [${severity}] ${finding.title} (${finding.area.name})`);
    console.log(`   Fix: ${finding.fix}`);
  }
  if (report.message) console.log(report.message);
  console.log(`\nfull diagnosis saved to ${path}`);
}

try {
  await main();
} catch (error) {
  console.error(error instanceof ApiRefusal ? `SEOReport: ${error.message}` : `error: ${error.cause?.message ?? error.message}`);
  process.exit(1);
}

job 3f6c2a1e-8d4b-4c7a-9e21-5b0d7f4a6c18: queued
https://example.com: 64/100 (mixed)
open issues: 9, pages analysed: 24

#1 [high] Canonical tag missing (URLs & Redirects)
   Fix: Add a canonical link element or Link HTTP header pointing to the preferred URL for this page. This is a strong canonicalization signal that helps search systems understand which version represents duplicate or very similar content; the declared URL remains a preference, not a guarantee.

#2 [high] Meta description missing (On-Page SEO)
   Fix: Add a concise, page-specific meta description that accurately describes the visible content. Search systems may use it for a result snippet when it is more helpful than text taken from the page.

#3 [high] Render parity mismatch (Crawl & Index)
   Fix: Ensure raw HTML and rendered DOM contain the same critical SEO elements (title, H1, canonical, meta description, structured data). If content is injected by JavaScript, move it to server-side rendering so crawlers see it immediately.

full diagnosis saved to seoreport-3f6c2a1e-8d4b-4c7a-9e21-5b0d7f4a6c18.json