@vertaaux/sdk

VertaaUX SDK

Official TypeScript SDK for VertaaUX.ai -- AI-powered UX and accessibility auditing.

Why VertaaUX?

Most UX auditing is manual, slow, and inconsistent. VertaaUX runs AI-powered audits that score your pages across accessibility, usability, information architecture, and performance -- then generates actionable remediation patches you can apply directly.

The SDK lets you integrate this into your workflow programmatically:

• CI/CD gates -- fail builds when accessibility scores drop below your threshold
• Scheduled monitoring -- track UX quality across deploys with recurring audits
• Automated remediation -- generate and verify code patches for detected issues
• Batch analysis -- audit hundreds of pages in parallel with auto-pagination

Zero runtime dependencies. Full TypeScript types. Stripe-style resource API.

Installation

npm install @vertaaux/sdk

Quick Start

import { VertaaUX } from '@vertaaux/sdk';

const client = new VertaaUX({ apiKey: process.env.VERTAAUX_API_KEY! });

// Create an audit
const audit = await client.audits.create({
  url: 'https://example.com',
  mode: 'standard',
});

// Poll for results
let result = await client.audits.retrieve(audit.job_id);
while (result.status === 'queued' || result.status === 'running') {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  result = await client.audits.retrieve(audit.job_id);
}

if (result.status === 'completed') {
  console.log('Overall score:', result.scores?.overall);
  console.log('Issues found:', result.issues?.length);
}

Configuration

const client = new VertaaUX({
  apiKey: 'vx_test_your_api_key',  // Required. Get yours at https://vertaaux.ai/dashboard/api-keys
  baseUrl: 'https://...',      // Optional. Defaults to https://vertaaux.ai/api/v1
  timeout: 120000,             // Optional. Request timeout in ms (default: 120000)
  maxRetries: 2,               // Optional. Auto-retry on 429/5xx (default: 2)
  fetch: customFetch,          // Optional. Custom fetch implementation
});

Cancellation and Per-Request Timeout

Every SDK method accepts an optional CallOptions final argument:

import { VertaaUX, ConnectionError, type CallOptions } from '@vertaaux/sdk';

const client = new VertaaUX({ apiKey: process.env.VERTAAUX_API_KEY! });

// Cancel mid-flight from the caller
const controller = new AbortController();
const audit = await client.audits.create(
  { url: 'https://example.com' },
  { signal: controller.signal, timeoutMs: 60_000 },
);

// Elsewhere:
controller.abort();  // throws ConnectionError on the in-flight call

The timeoutMs value overrides the global config.timeout for this call only. Each retry attempt gets a fresh budget; the overall envelope is timeoutMs * (maxRetries + 1) + sum(backoffs).

When the SDK wraps an underlying error, the original is preserved on err.cause:

try {
  await client.audits.retrieve('job_123', { timeoutMs: 100 });
} catch (err) {
  if (err instanceof ConnectionError && err.cause instanceof Error) {
    console.error('underlying:', err.cause.name);  // "AbortError" or TypeError
  }
}

Aborts are observed promptly even during the internal retry backoff wait. If you controller.abort() while the SDK is sleeping between retries (exponential backoff or honoring a Retry-After header), the in-flight call throws ConnectionError with the abort reason on err.cause; the SDK does not wait out the backoff before noticing the abort. (Added in 2.1.1.)

Resources

The SDK uses a Stripe-style resource architecture. All resources are accessed as properties on the client instance.

Resource	Methods	Description
client.audits	create, retrieve, get, list, createWithLLM, listAutoPaginate	Create, retrieve, and list UX audits
client.webhooks	create, list, delete	Manage webhook subscriptions for audit events
client.schedules	create, retrieve, list, update, delete	Create and manage scheduled recurring audits
client.quota	retrieve	Check API usage and plan limits
client.engines	list	List available audit engine versions
client.patches	generate	Generate remediation patches for issues
client.verification	run	Verify patch effectiveness before applying

Auto-Pagination

List endpoints support automatic pagination via listAutoPaginate():

// Iterate with for-await
for await (const audit of client.audits.listAutoPaginate({ status: 'completed' })) {
  console.log(audit.job_id, audit.scores?.overall);
}

// Collect into an array
const audits = await client.audits
  .listAutoPaginate({ status: 'completed' })
  .toArray({ maxItems: 100 });

Error Handling

All errors extend VertaaUXError and include type, statusCode, and requestId properties.

import {
  VertaaUX,
  VertaaUXError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError,
  APIError,
  IdempotencyError,
  ConnectionError,
  PermissionError,
  isVertaaUXError,
} from '@vertaaux/sdk';

try {
  const audit = await client.audits.create({ url: 'https://example.com' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401 - Invalid or missing API key
  } else if (error instanceof PermissionError) {
    // 403 - Insufficient permissions
  } else if (error instanceof NotFoundError) {
    // 404 - Resource not found
  } else if (error instanceof ValidationError) {
    // 400 - Invalid request parameters
    console.error(error.param, error.errors);
  } else if (error instanceof RateLimitError) {
    // 429 - Rate limit exceeded
    console.error('Retry after:', error.retryAfter, 'seconds');
  } else if (error instanceof IdempotencyError) {
    // 409 - Idempotency key conflict
  } else if (error instanceof ConnectionError) {
    // Network or timeout error
  } else if (error instanceof APIError) {
    // 5xx - Server error
  }

  // Type guard for any VertaaUX error
  if (isVertaaUXError(error)) {
    console.error(error.type, error.statusCode, error.requestId);
  }
}

Error Class	Status	When
AuthenticationError	401	Invalid or missing API key
PermissionError	403	Insufficient permissions for the resource
NotFoundError	404	Audit, webhook, or schedule not found
ValidationError	400	Invalid request parameters
RateLimitError	429	Too many requests (includes retryAfter)
IdempotencyError	409	Idempotency key conflict
ConnectionError	--	Network failure or request timeout
APIError	5xx	Internal server error
VertaaUXError	--	Base class for all SDK errors

CI Integration

GitHub Actions

name: Accessibility Check

on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install SDK
        run: npm install @vertaaux/sdk

      - name: Run VertaaUX Audit
        uses: actions/github-script@v7
        env:
          VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}
        with:
          script: |
            const { VertaaUX } = require('@vertaaux/sdk');
            const client = new VertaaUX({ apiKey: process.env.VERTAAUX_API_KEY });

            const audit = await client.audits.create({
              url: 'https://your-preview-url.com',
              mode: 'standard',
            });

            let result = await client.audits.retrieve(audit.job_id);
            while (result.status === 'queued' || result.status === 'running') {
              await new Promise(r => setTimeout(r, 3000));
              result = await client.audits.retrieve(audit.job_id);
            }

            if (result.status === 'failed') {
              core.setFailed(`Audit failed: ${result.error}`);
              return;
            }

            const score = result.scores?.overall ?? 0;
            console.log(`Score: ${score}/100`);

            if (score < 80) {
              core.setFailed(`Accessibility score ${score} is below threshold 80`);
            }

TypeScript

Full type definitions are included. All API types are exported from the package root:

import type {
  Audit,
  AuditCreateParams,
  AuditScores,
  Issue,
  Finding,
  Webhook,
  Schedule,
  Quota,
  Engine,
  Patch,
  VerificationResult,
} from '@vertaaux/sdk';

Examples

See /examples for complete integration patterns:

• basic-audit.ts -- Simple audit with polling
• ci-integration.ts -- CI/CD pipeline with score thresholds
• batch-audit.ts -- Audit multiple URLs in parallel

License

MIT (c) VertaaUX