Official TypeScript SDK for VertaaUX.ai -- AI-powered UX and accessibility auditing.
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.
npm install @vertaaux/sdkimport { 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);
}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
});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 callThe 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
}
}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 |
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 });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 |
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`);
}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';See /examples for complete integration patterns:
basic-audit.ts-- Simple audit with pollingci-integration.ts-- CI/CD pipeline with score thresholdsbatch-audit.ts-- Audit multiple URLs in parallel
MIT (c) VertaaUX