@vertaaux/sdk-js

VertaaUX JS/TS SDK (beta)

Thin fetch-based client generated from docs/vertaaux-api.yaml. Includes retries/backoff, idempotency key helper, webhook signature verification, and a pagination helper.

Install

npm install @vertaaux/sdk-js

Usage

import {
  createVertaauxClient,
  generateIdempotencyKey,
  verifyWebhookSignature,
  paginate,
} from "@vertaaux/sdk-js";

const client = createVertaauxClient({
  apiKey: process.env.VERTAAUX_API_KEY!,
  baseUrl: "https://vertaaux.ai/v1", // or staging
  idempotencyKey: generateIdempotencyKey(), // optional for POSTs
  retry: { retries: 2, baseDelayMs: 300 },
});

async function run() {
  const audit = await client.createAudit({
    url: "https://example.com",
    mode: "basic",
  });
  console.log("job", audit.job_id, "ruleset", audit.ruleset_version);

  const status = await client.getAudit(audit.job_id);
  console.log("status", status.status, status.progress);
}
run().catch(console.error);

Webhook verification

const isValid = await verifyWebhookSignature({
  secret: process.env.VERTAAUX_WEBHOOK_SECRET!,
  payload: rawBodyString,
  signature: req.headers["x-vertaaux-signature"] as string,
  timestamp: req.headers["x-vertaaux-signature-timestamp"] as string,
  toleranceSeconds: 300,
});

Pagination helper

paginate walks an API endpoint that exposes page and limit query parameters. Your fetchPage callback signature is (page: number, limit: number) => Promise<T[]>, and MUST thread the supplied (page, limit) arguments into the underlying request; paginate increments page itself and relies on the response shrinking below limit to stop.

maxPages (default 100) caps the loop so a fetcher that ignores its arguments throws loudly instead of spinning until the host runs out of memory.

import { paginate } from "@vertaaux/sdk-js";

// Example against a hypothetical endpoint that accepts ?page=&limit=
const items = await paginate({
  limit: 50,
  maxPages: 100, // optional; caps the loop at 5000 items by default
  fetchPage: async (page, limit) => {
    const res = await fetch(
      `https://vertaaux.ai/api/v1/audits?page=${page}&limit=${limit}`,
      { headers: { "X-API-Key": process.env.VERTAAUX_API_KEY! } },
    );
    if (!res.ok) throw new Error(`paginate fetch failed: ${res.status}`);
    const json = (await res.json()) as { items: unknown[] };
    return json.items;
  },
});

Note: at the time of writing, none of the typed client.* methods on createVertaauxClient() accept (page, limit) arguments. Use paginate with a hand-rolled fetcher against endpoints whose contract documents page + limit query params, or wait for the typed list methods to gain pagination support.

Publish (npm)

• Update version in sdk/js/package.json.
• If the OpenAPI spec changed: regenerate types via scripts/generate-sdk-types.sh, then sync the in-package copy: cp sdk/types/index.d.ts sdk/js/types.d.ts (re-add the Phase 136 header comment at the top — see sdk/js/types.d.ts).
• npm publish --access public. prepublishOnly runs npm run build && npm run smoke automatically; both must pass before the tarball is uploaded.

Notes

• Base URL defaults to production; override for staging/test mode.
• Retries cover 429/5xx with exponential backoff or Retry-After.
• Add endpoint-specific list wrappers as new API endpoints ship.