@wholisphere.ai/sdk

Official TypeScript / JavaScript SDK for the Wholisphere API. Works in Node, Deno, Bun, browsers, Cloudflare Workers — anywhere with a global fetch.

Install

npm install @wholisphere.ai/sdk
# or
pnpm add @wholisphere.ai/sdk

Quick start

import { Wholisphere } from '@wholisphere.ai/sdk';

const client = new Wholisphere({
  apiKey: process.env.WHOLISPHERE_API_KEY!, // whk_…
});

// Describe an image for a screen reader
const desc = await client.describe({
  image: { mimeType: 'image/png', data: '<base64>' },
  url: 'https://example.com/product/123',
});
console.log(desc.description);

// Rewrite text at a chosen reading level
const easy = await client.simplify({
  text: 'A long technical paragraph…',
  level: 'grade-8',
});

// Summarize a page
const summary = await client.summarize({ text: pageText, maxBullets: 5 });

// Map a voice command into an action plan
const action = await client.voiceAction({
  url: 'https://example.com/checkout',
  transcript: 'click checkout',
  domSummary: '#cta|button|Checkout\n#cancel|button|Cancel',
});

// Submit accessibility findings (analyzer integration)
await client.findings.submit({
  productName: 'Acme App',
  productVersion: '4.2.0',
  buildRef: process.env.GITHUB_SHA,
  findings: [
    { criterion: '1.1.1', conformance: 'Supports', remarks: 'All images have alt text.' },
  ],
});

// Invalidate the build-time cache after a deploy
await client.cache.invalidate({
  urls: ['https://example.com/*'],
  reason: `release ${process.env.GIT_TAG}`,
});

// Generate a VPAT
const { markdown } = await client.vpat.generate({
  product: { /* … */ },
  findings: [ /* … */ ],
});
fs.writeFileSync('vpat.md', markdown);

Errors

All errors descend from WholisphereError and carry { code, status, traceId, retryable }. Specialized subclasses give you better matching:

import {
  WholisphereError,
  WholisphereAuthError,
  WholisphereRateLimitError,
  WholisphereNetworkError,
} from '@wholisphere.ai/sdk';

try {
  await client.describe({ image });
} catch (e) {
  if (e instanceof WholisphereAuthError) {
    // 401 — bad key, key revoked, or permission denied
  } else if (e instanceof WholisphereRateLimitError) {
    // 429 — back off `e.retryAfterSeconds`
  } else if (e instanceof WholisphereNetworkError) {
    // network failure — already retried automatically
  } else if (e instanceof WholisphereError) {
    console.error('API error:', e.code, '·', e.message, '·', e.traceId);
  }
}

Retries + backoff

By default the client retries up to 2 times on retryable errors (network, 429, 5xx) with exponential backoff (250 ms → 500 ms) plus jitter. Disable with { retries: 0 } or raise with { retries: 5 }. Retry-After headers are honored.

Configuration

new Wholisphere({
  apiKey: 'whk_…',         // OR installId: '<uuid>' for legacy clients
  baseUrl: 'https://api.wholisphere.ai',  // default
  timeoutMs: 30_000,       // default
  retries: 2,              // default
  fetchImpl: customFetch,  // for testing or proxying
  userAgent: 'my-app/1.0', // appended to the default UA
});

Why direct fetch (no axios / undici)?

So the SDK works on every modern runtime — Node 20+, Deno, Bun, Cloudflare Workers, Vercel Edge, browsers — without bringing transport dependencies.

OpenAPI

The full machine-readable API spec lives at https://api.wholisphere.ai/openapi.json.