Skip to main content

SDK reference

The @hyperserve/hyperserve-js package provides a typed client for the Hyperserve API. It handles authentication, request formatting, and error parsing.

For a working app that uses all of this, see the Next.js starter.

Installation​

npm install @hyperserve/hyperserve-js

Initialization​

Create a client instance on your server. Never expose your API key in browser code.

import { HyperserveClient } from '@hyperserve/hyperserve-js';

const client = new HyperserveClient({
  apiKey: process.env.HYPERSERVE_API_KEY,  // Required
  baseUrl: 'https://api.hyperserve.io',     // Optional, this is the default
  timeoutMs: 30000,                         // Optional, default 30s
  retries: 0,                               // Optional, default 0
});

Methods​

createVideo()​

Initiates an upload. Returns a presigned URL the client can use to upload directly to storage without exposing your API key.

const { id, uploadUrl, contentType } = await client.createVideo({
  filename: 'my-video.mp4',          // Required
  resolutions: ['480p', '1080p'],     // Required, at least one
  isPublic: true,                     // Required
  thumbnailTimestampsSeconds: [5, 30], // Optional
  customMetadata: { userId: '123' },  // Optional
});

completeUpload()​

Notifies the API that the file upload is complete. Hyperserve will verify the file and begin transcoding.

await client.completeUpload(videoId);

getVideo()​

Retrieves video metadata and playback URLs. For private videos, returns time-limited signed URLs.

// Public video
const video = await client.getVideo(videoId);

// Private video with custom expiration
const video = await client.getVideo(videoId, {
  private: true,
  expirationSeconds: 3600, // Default: 3600
});

// Access URLs
const videoUrl = video.resolutions['1080p']?.videoUrl;
const thumbnails = video.resolutions['1080p']?.thumbnailImageUrls;

deleteVideo()​

Permanently deletes a video and all its resolutions.

await client.deleteVideo(videoId);

deleteResolution()​

Deletes a single resolution of a video.

await client.deleteResolution(resolutionId);

verifyWebhookSignature()​

A standalone function that validates the x-hyperserve-signature header on incoming webhook requests. Pass the raw request body string exactly as received — do not parse and re-serialize JSON, as any whitespace difference will invalidate the signature.

import { verifyWebhookSignature } from '@hyperserve/hyperserve-js';

const isValid = await verifyWebhookSignature({
  signature: req.headers['x-hyperserve-signature'] ?? '', // Required
  secret: process.env.HYPERSERVE_WEBHOOK_SECRET,          // Required
  body: req.body.toString(),                              // Required: raw body string
  toleranceMs: 300_000,                                   // Optional, default 5 minutes
});

if (!isValid) {
  return res.status(401).end();
}

Client-side uploads​

The browser and React Native packages expose putVideoToStorage() for uploading directly to cloud storage using the presigned URL from createVideo(). These packages do not require your API key.

Browser​

import { putVideoToStorage } from '@hyperserve/hyperserve-js/browser';

await putVideoToStorage({
  uploadUrl,    // From createVideo()
  contentType,  // From createVideo()
  file,         // File object from an <input type="file">
  onProgress: (percent) => console.log(`${percent}% uploaded`),
});

React Native​

import { putVideoToStorage } from '@hyperserve/hyperserve-js/react-native';

await putVideoToStorage({
  uploadUrl,    // From createVideo()
  contentType,  // From createVideo()
  uri: fileUri, // file:/// URI from the device
  onProgress: (percent) => console.log(`${percent}% uploaded`),
});

Error handling​

All SDK methods throw typed error classes that extend HyperserveError.

import {
  HyperserveValidationError,
  HyperserveNotFoundError,
  HyperserveUploadError,
  HyperserveTimeoutError,
  HyperserveError,
} from '@hyperserve/hyperserve-js';

try {
  await client.createVideo({ ... });
} catch (err) {
  if (err instanceof HyperserveValidationError) {
    // 4xx — bad request parameters
  } else if (err instanceof HyperserveNotFoundError) {
    // 404 — video not found
  } else if (err instanceof HyperserveTimeoutError) {
    // Request exceeded timeoutMs
  } else if (err instanceof HyperserveError) {
    // Catch-all for other API errors
  }
}

Types​

type VideoResolution =
  | '144p' | '240p' | '360p' | '480p' | '720p'
  | '1080p' | '1440p' | '4k' | '8k';

type VideoStatus = 'pending_upload' | 'processing' | 'ready' | 'fail';