CaptionHub Node SDK

Node TypeScript SDK for the CaptionHub API with methods to call CaptionHub API endpoints, response types, webhook types and Timbra WebSocket API.

Installation

You can install the SDK via npm:

npm install @captionhub/captionhub-node-sdk

or

yarn add @captionhub/captionhub-node-sdk

Interact with the API

Here's a simple example of how to use the CaptionHub SDK:

import { CaptionHub } from '@captionhub/captionhub-node-sdk';

const client = new CaptionHub('YOUR_API_KEY');

const projects = await client.projects.getProjects();

console.log('Projects:', projects);

👉 View all available methods

If the API returns a unsuccesful response (i.e., 4xx or 5xx response), a subclass of CaptionHub.APIError will be thrown:

try {
  await client.projects.getProject('i-404');
} catch (err) {
  if (err instanceof CaptionHub.APIError.NotFoundError) {
    console.error(`API Error: ${err.status} - ${err.message}`);
    console.error('Response data:', err.data);
  } else if (err instanceof CaptionHub.APIError) {
    console.error(`API Error: ${err.status} - ${err.message}`);
    console.error('Response data:', err.data);
  } else {
    console.error('Unexpected error:', err);
  }
}

API response types

If you only want to use the types defined in the SDK, you can import them directly:

import { type APITypes } from '@captionhub/captionhub-node-sdk';

async function main() {
  const project: Partial<APITypes.Project> = {
    name: 'Your project',
  };

  console.log('Project:', project);
}

👉 View all available types

Webhook types

Use the WebhookEvent type to strongly type your webhook handlers:

import { type WebhookEvent } from '@captionhub/captionhub-node-sdk';

function handleWebhook(event: WebhookEvent) {
  if (event.type === 'project.created') {
    // Now `event.data.project` is strongly typed as `APITypes.Project`
    console.log('Project created with ID:', event.data.project.id);
  }
}

👉 View all webhook event types

Timbra WebSocket API

Use Timbra's WebSocket API to receive captions over a WebSocket connection.

const captionhub = new CaptionHub("YOUR_API_KEY", "http://localhost");

captionhub.timbra.startFlow("example-timbra-project");

const connectionDetails = await captionhub.timbra.getConnectionDetails("example-timbra-project");

captionhub.timbra.subscribe({
  connection: connectionDetails,
  onCaption: (event: CaptionsEvent) => {
    console.log("Received captions:", event);
  }
});

See CaptionsEvent for the payload.

Support and feedback

Raise a support ticket at CaptionHub Support.

License

CaptionHub user terms and license