@scanverra/sdk 0.1.0 → 0.1.2

package/README.md

@@ -30,7 +30,29 @@ const ok = await verifyWebhook({
 });
 ```
 
-Errors throw `ScanverraError` with `status`, `code` and the response `body`. A scan refused for quota answers 402 with `code` set.
+## 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.
 

package/dist/index.d.ts

@@ -7,11 +7,18 @@ export interface ScanverraOptions {
     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);
+    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 {

package/dist/index.js

@@ -1,18 +1,24 @@
 // @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) {
-        super(message);
+    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;
@@ -25,13 +31,25 @@ export class Scanverra {
         this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
     }
     async request(method, path, body) {
-        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
-            method,
-            headers: { Authorization: `Bearer ${this.options.apiKey}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
-            body: body === undefined ? undefined : JSON.stringify(body),
-            signal: AbortSignal.timeout(this.options.timeoutMs ?? 300_000),
-        });
-        const text = await res.text();
+        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;
@@ -40,8 +58,10 @@ export class Scanverra {
             data = text;
         }
         if (!res.ok) {
-            const err = (data ?? {});
-            throw new ScanverraError(res.status, err.code, err.error ?? `Scanverra answered ${res.status}`, data);
+            // 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;
     }

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "@scanverra/sdk",
-  "version": "0.1.0",
+  "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" },
+  "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"