TypeScript SDK for the Wisprs Transcription API

Official TypeScript/JavaScript client for the Wisprs API. Type-safe, zero runtime dependencies, and works in Node.js, Bun, Deno, and browser environments.

The SDK wraps the REST API with typed request and response models, automatic retries, and convenience helpers like jobs.wait() that eliminate polling boilerplate.

Install

bash

npm install @wisprs/sdk
# or
yarn add @wisprs/sdk
# or
bun add @wisprs/sdk

Initialize

typescript

import { WisprsClient } from '@wisprs/sdk';

const client = new WisprsClient({
  apiKey: process.env.WISPRS_API_KEY!,
  // baseUrl: 'https://wisprs.co', // optional, defaults to production
});

Transcriptions

typescript

// Submit a job
const job = await client.transcriptions.create({
  source: { url: 'https://youtube.com/watch?v=...' },
  language: 'en',
  options: { sttQuality: 'balanced' }, // 'fast' | 'balanced' | 'accurate'
});

// Poll until done (2s interval, 2m timeout)
const result = await client.jobs.wait(job.id);
console.log(result.transcriptText);

// Fetch manually
const transcription = await client.transcriptions.get(result.transcriptionId!);

Exports

typescript

// Export as SRT
const srt = await client.transcriptions.export(transcriptionId, { format: 'srt' });

// Available: 'txt' | 'srt' | 'vtt' | 'json' | 'md' | 'docx'

Repurposing

typescript

const summary  = await client.transcriptions.summary(id);
const chapters = await client.transcriptions.chapters(id);
const quotes   = await client.transcriptions.quotes(id);

// Generic mode: 'summary' | 'chapters' | 'quotes' | 'show-notes' | 'thread' | 'blog'
const thread = await client.transcriptions.repurpose(id, 'thread');

Library search

typescript

const results = await client.library.search('launch day metrics', { limit: 5 });
for (const r of results) {
  console.log(r.score.toFixed(2), r.snippet);
}

Webhooks

typescript

// Register an endpoint
const endpoint = await client.webhooks.createEndpoint({
  url: 'https://your-app.com/webhooks/wisprs',
});

// List endpoints
const endpoints = await client.webhooks.listEndpoints();

// Check delivery history
const deliveries = await client.webhooks.listDeliveries();

// Retry a failed delivery
await client.webhooks.retryDelivery(deliveryId);

Usage & keys

typescript

// Usage stats for the current period
const usage = await client.usage.get();
console.log(usage.requestsThisMonth, usage.audioMinutesThisMonth);

Error handling

typescript

import { WisprsApiError } from '@wisprs/sdk';

try {
  const job = await client.transcriptions.create({ source: { url: '...' } });
} catch (err) {
  if (err instanceof WisprsApiError) {
    console.error(err.status, err.message); // e.g. 403, "Missing scope: media:ingest"
  }
}

TypeScript types

typescript

import type {
  WisprsJob,
  WisprsTranscription,
  WisprsTranscriptionSegment,
  WisprsExportFormat,
  WisprsRepurposeMode,
  WisprsSearchResult,
} from '@wisprs/sdk';

Requirements

Node.js ≥ 18 (uses native fetch)
TypeScript ≥ 5.0
No external runtime dependencies

FAQ

Does it work in the browser?

Yes, with a caveat: never expose your API key in client-side code. Use the SDK server-side and proxy requests through your own backend, or use short-lived scoped tokens if you need browser access.

Is it ESM or CommonJS?

The package ships both ESM and CJS builds. Your bundler or runtime picks the right one automatically.

How do I handle API errors?

All API errors throw a WisprsApiError with status (HTTP status code) and message (error string from the API). Wrap calls in a try/catch and check err instanceof WisprsApiError.