Événements et SDK

SDK JavaScript

Un petit client typé pour Node.js 18+, Deno et Bun. Sans dépendance : il utilise le fetch intégré et Web Crypto.

@scanverra/sdk est en préversion et son interface peut encore changer. Chaque appel est une simple requête HTTP : les pages de l'API montrent comment faire sans lui.

Installer

Créez un client et réutilisez-le.

shell

npm install @scanverra/sdk

javascript

import { Scanverra } from "@scanverra/sdk";

const scanverra = new Scanverra({
  apiKey: process.env.SCANVERRA_API_KEY,
  // baseUrl: "https://www.scanverra.com",  // optional
  // timeoutMs: 300_000,                     // optional, per request
});

Lancer des analyses

scans.audit() et scans.repo() répondent avec le rapport terminé. Les autres répondent aussitôt avec un id ; wait() interroge jusqu'à ce que le rapport soit prêt et lève une erreur si l'analyse a échoué.

javascript

// Answers with the finished report
const audit = await scanverra.scans.audit({ url: "https://example.com" });

// Answer with an id; wait() polls until the report is ready
const { scanId } = await scanverra.scans.security({ url: "https://example.com" });
const security = await scanverra.wait("security", scanId);

const { testId } = await scanverra.scans.browser({ url: "https://example.com" });
const browser = await scanverra.wait("browser", testId, { intervalMs: 5000 });

// Repo scans: owner and repo of a connected account
const repo = await scanverra.scans.repo({ owner: "acme", repo: "storefront", async: true });
const repoReport = await scanverra.wait("repo", repo.scanId);

Lire les propriétés

Scores, problèmes fusionnés et prochaines étapes de chaque produit.

javascript

const { properties } = await scanverra.properties.list();
for (const p of properties) console.log(p.name, p.score, p.openTasks);

const detail = await scanverra.properties.get(properties[0].id);
const critical = detail.issues.filter((i) => i.severity === "critical");

S'abonner aux événements

Créez un REST hook pour n'importe quel événement, puis vérifiez la signature de chaque envoi avec verifyWebhook. Les envois de plus de cinq minutes sont refusés.

javascript

const hook = await scanverra.hooks.create({
  event: "remediation.task_created",
  url: "https://hooks.example.com/scanverra",
});
// Store hook.secret: it is shown only once.

// In your receiver, with the raw request body:
import { verifyWebhook } from "@scanverra/sdk";

const ok = await verifyWebhook({
  secret: process.env.SCANVERRA_HOOK_SECRET,
  body: rawBody,
  timestamp: req.headers["x-scanverra-timestamp"],
  signature: req.headers["x-scanverra-signature"],
});
if (!ok) return res.status(401).end();

Erreurs

Tout échec lève ScanverraError avec status, code, un message lisible et le body de la réponse. Sans réponse, status vaut 0 et code vaut network_error ou timeout.

javascript

import { ScanverraError } from "@scanverra/sdk";

try {
  await scanverra.scans.audit({ url: "https://example.com" });
} catch (err) {
  if (!(err instanceof ScanverraError)) throw err;
  if (err.code === "SCAN_COOLDOWN") console.log("Try again later:", err.message);
  else if (err.status === 0 || err.status >= 500) console.log("Retry with backoff:", err.code ?? err.status);
  else throw err; // 4xx: fix the request (see /docs/errors)
}

Référence

Champ	Description
`scans.audit(body)`Promise<report>Facultatif	Lance un audit de site et renvoie le rapport. Avec async: true, vous obtenez reportId aussitôt.
`scans.security(body)`Promise<{ scanId }>Facultatif	Lance une analyse de sécurité.
`scans.browser(body)`Promise<{ testId }>Facultatif	Lance un audit navigateur. Avec credentialId, testez des pages derrière une connexion.
`scans.seo(body)`Promise<{ scanId }>Facultatif	Lance une analyse SEO.
`scans.repo(body)`Promise<{ scanId }>Facultatif	Analyse un dépôt connecté.
`results.<tool>(id)`Promise<ScanResult>Facultatif	Lit une analyse par id : audit, security, browser, seo ou repo.
`wait(tool, id, options?)`Promise<ScanResult>Facultatif	Interroge la méthode results de l'outil jusqu'à la fin de l'analyse. Options : intervalMs (4000), timeoutMs (600000).
`properties.list() / get(id)`Promise<...>Facultatif	Liste les propriétés ou en lit une avec ses problèmes et prochaines étapes.
`hooks.list() / create() / delete(id) / sample(event)`Promise<...>Facultatif	Gère les REST hooks. create() renvoie le secret de signature une seule fois.
`verifyWebhook(input)`Promise<boolean>Facultatif	Vérifie X-Scanverra-Signature avec le corps brut et l'horodatage.