Node.js SDK

@videohati/node is the official server SDK. It is ESM, ships zero runtime dependencies, and is typed against the public OpenAPI 3.1 spec at https://api.videohati.com/openapi.json. Version 1.0.0-rc.0.

Install

Node.js 18 or newer. The package is ESM only — use import, not require.

npm install @videohati/node

Create a client

Create one client and reuse it. The mode (live or test) always follows the key prefix — a vh_test_ key runs against test data.

import { Videohati } from "@videohati/node";

const videohati = new Videohati({
  apiKey: process.env.VIDEOHATI_API_KEY, // vh_live_... or vh_test_...
});

VideohatiOptions:

Authentication

The client authenticates with a project API key sent as a bearer token. Use a vh_live_ key in production and a vh_test_ key against test data — the SDK derives the mode from the prefix. You create and manage keys in the dashboard.

Videos

The videos resource covers the whole lifecycle: create, upload, read, and manage thumbnails.

One-call upload

videos.upload(file, options) runs the full multipart flow in a single call. file is a path, a Buffer/Uint8Array, or a Blob/File.

const uploaded = await videohati.videos.upload("./lecture-01.mp4", {
  onProgress: (p) => console.log(`${p.uploadedBytes}/${p.totalBytes} bytes`),
});

// Poll until the video is playable end to end:
const video = await videohati.videos.waitForState(uploaded.videoId);
console.log(video.state); // "ready"

UploadOptions:

waitForState defaults to targetStates: ["ready", "failed"], intervalMs: 3000, and timeoutMs: 900000 (15 minutes); it rejects with a VideohatiError on timeout.

Read and delete

const { data } = await videohati.videos.list({ state: "ready" });

const detail = await videohati.videos.get(videoId);
console.log(detail.state); // uploading | uploaded | encoding | ready | failed

await videohati.videos.delete(videoId); // soft delete; aborts any active upload

Playback

Create the session on your server and hand only sessionToken to the page (embed it with @videohati/player or @videohati/react).

Your app calls only createSession; the player performs the other playback calls itself with the session token.

createSession parameters:

const session = await videohati.playback.createSession({
  videoId,
  viewerDisplayText: "Ahmed K.",
});
console.log(session.sessionToken);

Webhooks

Register endpoints, inspect deliveries, and verify signatures. Full flow in the webhooks guide.

Verify a signature

verifyWebhookSignature is also exported standalone. Pass the raw request body — not re-serialized JSON.

import { verifyWebhookSignature, SIGNATURE_HEADER } from "@videohati/node";

app.post("/webhooks/videohati", (req, res) => {
  const { valid, event } = verifyWebhookSignature({
    payload: req.rawBody, // string or Uint8Array, exactly as received
    header: req.headers[SIGNATURE_HEADER], // "videohati-signature"
    secret: process.env.VIDEOHATI_WEBHOOK_SECRET,
  });
  if (!valid) return res.status(400).end();
  if (event?.type === "video.encoding.ready") {
    // The video is ready — create a playback session, notify a user, etc.
  }
  res.status(200).end();
});

The header is Videohati-Signature: t=<unix_ts>,v1=<hex_sha256> (HMAC-SHA256 over <unix_ts>.<raw_body>); verification is constant-time and rejects timestamps more than 300 seconds old (tune with toleranceSeconds).

Projects and API keys

You create and manage projects and API keys in the dashboard, not through the SDK. See Concepts for how accounts, projects, and keys relate.

Errors

Every non-2xx response throws a typed subclass of VideohatiError, which carries status and code (the API's machine code, for example video_not_found). Errors never contain your API key.

import {
  VideohatiError,
  VideohatiNotFoundError,
  VideohatiRateLimitError,
} from "@videohati/node";

try {
  await videohati.videos.get(videoId);
} catch (error) {
  if (error instanceof VideohatiNotFoundError) {
    // 404 — error.code === "video_not_found"
  } else if (error instanceof VideohatiRateLimitError) {
    await sleep((error.retryAfterSeconds ?? 1) * 1000);
  } else if (error instanceof VideohatiError) {
    console.error(error.status, error.code, error.message);
  }
}

GET and DELETE requests, 429s, and 5xxs retry with exponential backoff capped at 8 seconds — 2 retries by default. A 429 honors the Retry-After header. Tune the behavior with maxRetries and timeoutMs.