@scanverra/sdk 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @scanverra/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, dependency-free client for the [Scanverra API](https://www.scanverra.com/docs). Node 18+, Deno and Bun.
+
+```ts
+import { Scanverra, verifyWebhook } from "@scanverra/sdk";
+
+const scanverra = new Scanverra({ apiKey: process.env.SCANVERRA_API_KEY! });
+
+// The Website Audit answers with the finished report.
+const audit = await scanverra.scans.audit({ url: "https://example.com" });
+
+// Security, Browser and SEO scans answer with an id; wait() polls until the report is ready.
+const { scanId } = await scanverra.scans.security({ url: "https://example.com" });
+const report = await scanverra.wait("security", scanId);
+
+// Properties: each product's sites and repos, scored together.
+const { properties } = await scanverra.properties.list();
+const detail = await scanverra.properties.get(properties[0].id);
+
+// Subscribe to events (REST hooks). Keep the secret to verify deliveries.
+const hook = await scanverra.hooks.create({ event: "remediation.task_created", url: "https://example.com/hooks/scanverra" });
+
+// In your receiver, with the raw request body:
+const ok = await verifyWebhook({
+  secret: hook.secret,
+  body: rawBody,
+  timestamp: req.headers["x-scanverra-timestamp"],
+  signature: req.headers["x-scanverra-signature"],
+});
+```
+
+## Errors
+
+Every failure throws `ScanverraError`:
+
+- `status`: the HTTP status, or `0` when no answer arrived.
+- `code`: a stable value to branch on, such as `free_limit_reached` (402), `SCAN_COOLDOWN` (429), `network_error` or `timeout`. The full list is at https://www.scanverra.com/docs/errors.
+- `message`: a sentence you can show to people.
+- `body`: the response as sent; `cause`: the original error for `network_error` and `timeout`.
+
+```ts
+import { ScanverraError } from "@scanverra/sdk";
+
+try {
+  await scanverra.scans.audit({ url: "https://example.com" });
+} catch (e) {
+  if (!(e instanceof ScanverraError)) throw e;
+  if (e.code === "SCAN_COOLDOWN") console.log("Try again later:", e.message);
+  else if (e.status === 0 || e.status >= 500) console.log("Retry with backoff:", e.code ?? e.status);
+  else throw e;
+}
+```
+
+The key is sent in the `X-API-Key` header. Requests time out after `timeoutMs` (default 300000, since the Website Audit answers when the scan is done).
+
+Events: `scan.score_dropped`, `scan.policy_failed`, `scan.completed`, `payment_page.scripts_changed`, `attack_surface.changed`, `remediation.task_created`, `remediation.task_resolved`, `property.score_changed`. Payloads are described at https://www.scanverra.com/docs/integrations.
+
+Build: `npm run build` (writes `dist/`).

package/dist/index.d.ts

@@ -0,0 +1,193 @@
+export type ScanverraEvent = "scan.score_dropped" | "scan.policy_failed" | "scan.completed" | "payment_page.scripts_changed" | "attack_surface.changed" | "remediation.task_created" | "remediation.task_resolved" | "property.score_changed";
+export interface ScanverraOptions {
+    apiKey: string;
+    /** Defaults to https://www.scanverra.com */
+    baseUrl?: string;
+    /** Per-request timeout; scans run synchronously and can take a few minutes. Default 300000. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/**
+ * Every failure the client raises. `status` is the HTTP status, or 0 when no
+ * answer arrived: then `code` is "network_error" or "timeout" and `cause`
+ * holds the original error. API codes are listed at /docs/errors.
+ */
+export declare class ScanverraError extends Error {
+    status: number;
+    code: string | undefined;
+    body: unknown;
+    constructor(status: number, code: string | undefined, message: string, body: unknown, options?: {
+        cause?: unknown;
+    });
+}
+/** A scan as the result endpoints return it; fields differ per tool (see /docs/api). */
+export interface ScanResult {
+    id?: string;
+    status: "pending" | "running" | "done" | "completed" | "failed" | string;
+    errorMessage?: string | null;
+    [field: string]: unknown;
+}
+export interface PropertyToolScore {
+    tool: string;
+    score: number;
+    change: number | null;
+    scanned: number;
+    of: number;
+    at: string;
+}
+export interface PropertySummary {
+    id: string;
+    name: string;
+    category: string;
+    client: string | null;
+    score: number | null;
+    lastScannedAt: string | null;
+    openTasks: number;
+    targets: {
+        target: string;
+        kind: "site" | "repo";
+    }[];
+    tools: PropertyToolScore[];
+}
+export interface PropertyDetail extends Omit<PropertySummary, "openTasks"> {
+    trend: {
+        day: string;
+        score: number;
+    }[];
+    issues: {
+        title: string;
+        severity: string;
+        tools: string[];
+        targets: string[];
+        places: number;
+        task: {
+            id: string;
+            status: string;
+            assignee: string | null;
+        } | null;
+        url: string;
+    }[];
+    nextSteps: {
+        kind: string;
+        tool: string;
+        target: string | null;
+        url: string | null;
+    }[];
+}
+export interface Hook {
+    id: string;
+    event: ScanverraEvent;
+    url: string;
+    source: string;
+    lastDeliveryAt: string | null;
+    lastStatus: number | null;
+    createdAt: string;
+}
+export interface Delivery<T = Record<string, unknown>> {
+    event: ScanverraEvent | "test";
+    sentAt: string;
+    summary: string;
+    data: T;
+    hookId?: string;
+}
+export declare class Scanverra {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: ScanverraOptions);
+    request<T>(method: "GET" | "POST" | "DELETE", path: string, body?: unknown): Promise<T>;
+    /**
+     * Start a scan. The Website Audit and Repo Scanner answer with the finished
+     * report (pass `async: true` to get an id at once instead). The Security
+     * Scan, Browser Audit and SEO Optimizer always answer with an id straight
+     * away: read the report with `results.*` or wait for it with `wait()`.
+     */
+    readonly scans: {
+        audit: (body: {
+            url: string;
+            budget?: Record<string, unknown>;
+            async?: boolean;
+        }) => Promise<Record<string, unknown>>;
+        security: (body: {
+            url: string;
+        }) => Promise<{
+            scanId: string;
+        }>;
+        browser: (body: {
+            url: string;
+            credentialId?: string;
+        }) => Promise<{
+            testId: string;
+        }>;
+        seo: (body: {
+            url: string;
+            keyword?: string;
+            competitorUrl?: string;
+            renderJs?: boolean;
+            checkPerformance?: boolean;
+        }) => Promise<{
+            scanId: string;
+        }>;
+        repo: (body: {
+            owner: string;
+            repo: string;
+            branch?: string;
+            provider?: "github" | "gitlab" | "bitbucket" | "azure";
+            async?: boolean;
+        }) => Promise<{
+            scanId: string;
+        }>;
+    };
+    /** Read a scan by id. `status` is "running" until it is "done"/"completed" or "failed". */
+    readonly results: {
+        audit: (id: string) => Promise<ScanResult>;
+        security: (id: string) => Promise<ScanResult>;
+        browser: (id: string) => Promise<ScanResult>;
+        seo: (id: string) => Promise<ScanResult>;
+        repo: (id: string) => Promise<ScanResult>;
+    };
+    /**
+     * Polls a scan until it finishes and returns the report. Throws a
+     * ScanverraError with code "scan_failed" when the scan failed, or
+     * "timeout" after `timeoutMs` (default 10 minutes).
+     */
+    wait(tool: keyof Scanverra["results"], id: string, { intervalMs, timeoutMs }?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<ScanResult>;
+    readonly properties: {
+        list: () => Promise<{
+            properties: PropertySummary[];
+        }>;
+        get: (id: string) => Promise<PropertyDetail>;
+    };
+    readonly hooks: {
+        list: () => Promise<{
+            hooks: Hook[];
+        }>;
+        /** The returned secret signs every delivery; it is shown only once. */
+        create: (body: {
+            event: ScanverraEvent;
+            url: string;
+            source?: "zapier" | "make" | "n8n" | "api";
+        }) => Promise<{
+            id: string;
+            secret: string;
+        }>;
+        delete: (id: string) => Promise<{
+            ok: true;
+        }>;
+        sample: (event: ScanverraEvent) => Promise<Delivery<Record<string, unknown>>[]>;
+    };
+}
+/**
+ * Checks a delivery's X-Scanverra-Signature against the raw body and its
+ * X-Scanverra-Timestamp (rejects anything older than `toleranceSeconds`).
+ */
+export declare function verifyWebhook(input: {
+    secret: string;
+    body: string;
+    timestamp: string | null;
+    signature: string | null;
+    toleranceSeconds?: number;
+}): Promise<boolean>;

package/dist/index.js

@@ -0,0 +1,139 @@
+// @scanverra/sdk: a small typed client for the Scanverra API. No dependencies:
+// it uses the global fetch (Node 18+, Deno, Bun, browsers for public calls)
+// and Web Crypto for webhook signatures.
+/**
+ * Every failure the client raises. `status` is the HTTP status, or 0 when no
+ * answer arrived: then `code` is "network_error" or "timeout" and `cause`
+ * holds the original error. API codes are listed at /docs/errors.
+ */
+export class ScanverraError extends Error {
+    status;
+    code;
+    body;
+    constructor(status, code, message, body, options) {
+        super(message, options);
+        this.status = status;
+        this.code = code;
+        this.body = body;
+        this.name = "ScanverraError";
+    }
+}
+const isTimeout = (e) => e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError");
+export class Scanverra {
+    options;
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        if (!options.apiKey)
+            throw new Error("Scanverra: apiKey is required");
+        this.baseUrl = (options.baseUrl ?? "https://www.scanverra.com").replace(/\/+$/, "");
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async request(method, path, body) {
+        const timeoutMs = this.options.timeoutMs ?? 300_000;
+        let res;
+        let text;
+        try {
+            // X-API-Key, not Authorization: clients drop Authorization when following
+            // the scanverra.com -> www.scanverra.com redirect.
+            res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers: { "X-API-Key": this.options.apiKey, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            text = await res.text();
+        }
+        catch (e) {
+            if (isTimeout(e))
+                throw new ScanverraError(0, "timeout", `No answer from Scanverra within ${timeoutMs} ms`, null, { cause: e });
+            throw new ScanverraError(0, "network_error", `Could not reach Scanverra: ${e instanceof Error ? e.message : String(e)}`, null, { cause: e });
+        }
+        let data = null;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = text;
+        }
+        if (!res.ok) {
+            // Most errors: { error: sentence, code }. Scan-access errors (402): { error: code, message: sentence }.
+            const err = (data && typeof data === "object" ? data : {});
+            const code = err.code ?? (err.message ? err.error : undefined);
+            throw new ScanverraError(res.status, code, err.message ?? err.error ?? `Scanverra answered ${res.status}`, data);
+        }
+        return data;
+    }
+    /**
+     * Start a scan. The Website Audit and Repo Scanner answer with the finished
+     * report (pass `async: true` to get an id at once instead). The Security
+     * Scan, Browser Audit and SEO Optimizer always answer with an id straight
+     * away: read the report with `results.*` or wait for it with `wait()`.
+     */
+    scans = {
+        audit: (body) => this.request("POST", "/api/audit", body),
+        security: (body) => this.request("POST", "/api/security-scan", body),
+        browser: (body) => this.request("POST", "/api/browser-test", body),
+        seo: (body) => this.request("POST", "/api/seo-optimizer", body),
+        repo: (body) => this.request("POST", "/api/repo/scan", body),
+    };
+    /** Read a scan by id. `status` is "running" until it is "done"/"completed" or "failed". */
+    results = {
+        audit: (id) => this.request("GET", `/api/reports/${encodeURIComponent(id)}`),
+        security: (id) => this.request("GET", `/api/security-scan?id=${encodeURIComponent(id)}`),
+        browser: (id) => this.request("GET", `/api/browser-test?id=${encodeURIComponent(id)}`),
+        seo: (id) => this.request("GET", `/api/seo-optimizer?id=${encodeURIComponent(id)}`),
+        repo: (id) => this.request("GET", `/api/repo/result?id=${encodeURIComponent(id)}`),
+    };
+    /**
+     * Polls a scan until it finishes and returns the report. Throws a
+     * ScanverraError with code "scan_failed" when the scan failed, or
+     * "timeout" after `timeoutMs` (default 10 minutes).
+     */
+    async wait(tool, id, { intervalMs = 4000, timeoutMs = 600_000 } = {}) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const result = await this.results[tool](id);
+            if (result.status === "failed")
+                throw new ScanverraError(200, "scan_failed", String(result.errorMessage ?? "The scan failed"), result);
+            if (result.status !== "running" && result.status !== "pending")
+                return result;
+            if (Date.now() > deadline)
+                throw new ScanverraError(0, "timeout", "The scan didn't finish in time", result);
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+    }
+    properties = {
+        list: () => this.request("GET", "/api/v1/properties"),
+        get: (id) => this.request("GET", `/api/v1/properties/${encodeURIComponent(id)}`),
+    };
+    hooks = {
+        list: () => this.request("GET", "/api/hooks"),
+        /** The returned secret signs every delivery; it is shown only once. */
+        create: (body) => this.request("POST", "/api/hooks", body),
+        delete: (id) => this.request("DELETE", `/api/hooks/${encodeURIComponent(id)}`),
+        sample: (event) => this.request("GET", `/api/hooks/sample?event=${encodeURIComponent(event)}`),
+    };
+}
+const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+/**
+ * Checks a delivery's X-Scanverra-Signature against the raw body and its
+ * X-Scanverra-Timestamp (rejects anything older than `toleranceSeconds`).
+ */
+export async function verifyWebhook(input) {
+    const { secret, body, timestamp, signature } = input;
+    if (!timestamp || !signature?.startsWith("sha256="))
+        return false;
+    if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > (input.toleranceSeconds ?? 300))
+        return false;
+    const enc = new TextEncoder();
+    const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const expected = `sha256=${hex(await crypto.subtle.sign("HMAC", key, enc.encode(`${timestamp}.${body}`)))}`;
+    if (expected.length !== signature.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++)
+        diff |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+    return diff === 0;
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@scanverra/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Typed client for the Scanverra API: run scans, read properties and subscribe to events.",
+  "license": "UNLICENSED",
+  "homepage": "https://www.scanverra.com/docs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}