TypeScript SDK

@wholisphere.ai/sdk is a typed client for the Wholisphere API. It runs in Node, Deno, Bun, browsers, and Cloudflare Workers — anywhere fetch exists.

Install

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

Authenticate

Create an API key in the dashboard (Settings → API keys). Keys start with whk_ and are shown once.

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

const client = new Wholisphere({
  apiKey: process.env.WHOLISPHERE_API_KEY!, // whk_…
  // baseUrl defaults to https://api.wholisphere.ai
});

The key is sent as the x-api-key header. For anonymous, per-device usage you can instead pass { installId } (a UUID) — but server capabilities and scans require an apiKey.

Live-assist capabilities

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

// Rewrite text at a chosen reading level
const easy = await client.simplify({ text: 'A long 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',
});

Findings, scans, and VPATs

// Submit accessibility findings (analyzer / custom scanner integration)
await client.findings.submit({ productId, findings: [/* … */] });

// Fetch the latest findings for a product
const latest = await client.findings.latest({ productId });

// Render a VPAT from a completed scan
const vpat = await client.scans.vpat({ scanId, format: 'html' });

// Diff two scans as markdown (great for release notes)
const diff = await client.scans.diffMarkdown({ scanId, baseScanId });

See the API reference and the OpenAPI 3.1 spec for the authoritative request/response schemas.

React

@wholisphere.ai/react wraps the SDK with a provider and hooks:

import { WholisphereProvider, useDescribe, useSummarize } from '@wholisphere.ai/react';

function App() {
  return (
    <WholisphereProvider apiKey={import.meta.env.VITE_WHOLISPHERE_KEY}>
      <ProductImage />
    </WholisphereProvider>
  );
}

function ProductImage() {
  const { describe, data, loading } = useDescribe();
  // …call describe({ image, url }) on demand
}

Available hooks: useDescribe, useSimplify, useSummarize, useReadPage, useIntent, useVoiceAction, useFindingsLatest, useFindingsSubmit, useVpatGenerate, useCacheInvalidate, and useWholisphere (the raw client).

Verify webhooks

The SDK ships a constant-time signature verifier for webhooks. It’s async (SubtleCrypto-based, so it runs everywhere from Node to Workers) — always await it:

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

const event = await verifyWebhook({
  secret: process.env.WHOLISPHERE_WEBHOOK_SECRET!,
  signature: req.headers['x-wholisphere-signature'], // t=…,v1=…
  payload: rawBody, // the exact bytes, before JSON.parse
});
// rejects with WebhookVerificationError on mismatch; resolves to the typed event on success