@hyperserve/hyperserve-js 0.1.0

package/README.md

@@ -0,0 +1,291 @@
+# @hyperserve/hyperserve-js
+
+TypeScript SDK for the [Hyperserve](https://hyperserve.io) video infrastructure API. Works in Node.js, browsers, and React Native.
+
+## Installation
+
+```bash
+npm install @hyperserve/hyperserve-js
+```
+
+## How it works
+
+Hyperserve uploads are a three-step flow. Your **backend** handles steps 1 and 3 (API key stays on the server). Your **frontend or mobile app** handles step 2 (direct to storage, no API key needed).
+
+```
+1. Backend  →  POST /api/video       →  Hyperserve   (get presigned URL)
+2. Client   →  PUT file to uploadUrl →  Storage      (upload the bytes)
+3. Backend  →  POST complete-upload  →  Hyperserve   (verify + queue transcoding)
+```
+
+---
+
+## Quick start
+
+### 1. Backend — create the upload
+
+```typescript
+import { HyperserveClient } from '@hyperserve/hyperserve-js';
+
+const hyperserve = new HyperserveClient({ apiKey: process.env.HYPERSERVE_API_KEY });
+
+// In your API route or server action
+const upload = await hyperserve.createVideo({
+  filename: 'promo.mp4',
+  fileSizeBytes: 10_485_760,
+  resolutions: ['480p', '1080p'],
+  isPublic: true,
+});
+
+// Return to your client — uploadUrl and contentType are all it needs
+return { videoId: upload.id, uploadUrl: upload.uploadUrl, contentType: upload.contentType };
+```
+
+### 2a. Browser — upload the file
+
+```typescript
+import { putVideoToStorage } from '@hyperserve/hyperserve-js/browser';
+
+const { videoId, uploadUrl, contentType } = await fetch('/api/create-upload', {
+  method: 'POST',
+  body: JSON.stringify({ filename: file.name, fileSizeBytes: file.size }),
+}).then(r => r.json());
+
+await putVideoToStorage({
+  uploadUrl,
+  contentType,
+  file,                              // File from <input type="file">
+  onProgress: (percent) => console.log(`${percent}%`),
+});
+
+// Tell your backend the upload is done
+await fetch('/api/complete-upload', { method: 'POST', body: JSON.stringify({ videoId }) });
+```
+
+### 2b. React Native — upload the file
+
+```typescript
+import { putVideoToStorage } from '@hyperserve/hyperserve-js/react-native';
+
+// asset from expo-image-picker, react-native-image-picker, etc.
+const { videoId, uploadUrl, contentType } = await fetch('https://your-api.com/create-upload', {
+  method: 'POST',
+  body: JSON.stringify({ filename: asset.fileName, fileSizeBytes: asset.fileSize }),
+}).then(r => r.json());
+
+await putVideoToStorage({
+  uploadUrl,
+  contentType,
+  uri: asset.uri,                    // file:/// URI — SDK handles the rest
+  onProgress: (percent) => setProgress(percent),
+});
+
+await fetch('https://your-api.com/complete-upload', {
+  method: 'POST',
+  body: JSON.stringify({ videoId }),
+});
+```
+
+### 3. Backend — complete the upload
+
+```typescript
+const result = await hyperserve.completeUpload(videoId);
+// Hyperserve verifies the file and queues transcoding
+// result.resolutions — all statuses are now 'processing'
+```
+
+---
+
+## Server API
+
+### `new HyperserveClient(options)`
+
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `apiKey` | `string` | Yes | — | Your Hyperserve API key |
+| `baseUrl` | `string` | No | `https://api.hyperserve.io` | Override for local dev |
+| `timeoutMs` | `number` | No | `30000` | Timeout for API calls |
+| `retries` | `number` | No | `0` | Retry attempts on 5xx responses and network errors. Uses exponential backoff with full jitter. Does not retry on 4xx or timeouts. |
+
+---
+
+### `createVideo(options)`
+
+Creates a video record and returns a presigned upload URL.
+
+```typescript
+const upload = await hyperserve.createVideo({
+  filename: 'clip.mp4',          // required — extension determines content type
+  fileSizeBytes: 5_242_880,      // required
+  resolutions: ['720p', '1080p'],// required — at least one
+  isPublic: true,                // required
+  thumbnailTimestampsSeconds: [5, 30, 60], // optional
+  customMetadata: { campaignId: 'launch' }, // optional
+});
+
+upload.id          // video ID for subsequent calls
+upload.uploadUrl   // presigned PUT URL — expires shortly, pass to your client
+upload.contentType // exact Content-Type to use on the PUT
+```
+
+---
+
+### `completeUpload(videoId)`
+
+Notifies Hyperserve that the file has been uploaded. Verifies the object and queues transcoding.
+
+```typescript
+const result = await hyperserve.completeUpload(videoId);
+result.resolutions // Record<VideoResolution, { status: 'processing' }>
+```
+
+---
+
+### `getVideo(videoId, options?)`
+
+Retrieves video status and playback URLs.
+
+```typescript
+// Public video
+const video = await hyperserve.getVideo(videoId);
+
+// Private video — time-limited signed URLs
+const video = await hyperserve.getVideo(videoId, {
+  private: true,
+  expirationSeconds: 3600, // defaults to 3600
+});
+
+video.status                          // 'pending_upload' | 'processing' | 'ready' | 'fail'
+video.resolutions['1080p']?.videoUrl  // playback URL (set when status is 'ready')
+video.resolutions['1080p']?.thumbnailImageUrls // array of thumbnail URLs
+```
+
+---
+
+### `deleteVideo(videoId)`
+
+Deletes a video and all associated resolutions and thumbnails.
+
+```typescript
+await hyperserve.deleteVideo(videoId);
+```
+
+---
+
+### `deleteResolution(resolutionId)`
+
+Deletes a single resolution.
+
+```typescript
+await hyperserve.deleteResolution(resolutionId);
+```
+
+---
+
+### `uploadVideo(options)` — convenience
+
+Wraps `createVideo`, the storage PUT, and `completeUpload` into a single call. Intended for scripts and server-to-server use cases where the server holds the file. **Not suitable for the browser proxy pattern.**
+
+```typescript
+import { readFileSync, statSync } from 'fs';
+
+const buffer = readFileSync('./promo.mp4');
+const { size } = statSync('./promo.mp4');
+
+const result = await hyperserve.uploadVideo({
+  file: buffer,                  // Blob | Buffer | ReadableStream
+  filename: 'promo.mp4',
+  fileSizeBytes: size,           // required for ReadableStream, inferred for Blob/Buffer
+  resolutions: ['1080p'],
+  isPublic: false,
+});
+```
+
+---
+
+### `verifyWebhookSignature(options)`
+
+Verifies the `x-hyperserve-signature` header on incoming webhook requests. Returns `Promise<boolean>` — never throws.
+
+```typescript
+import { verifyWebhookSignature } from '@hyperserve/hyperserve-js';
+
+const isValid = await verifyWebhookSignature({
+  signature: req.headers['x-hyperserve-signature'] ?? '',
+  secret: process.env.HYPERSERVE_WEBHOOK_SECRET,
+});
+if (!isValid) return res.status(401).end();
+```
+
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `signature` | `string` | Yes | — | Value of the `x-hyperserve-signature` header |
+| `secret` | `string` | Yes | — | Webhook signing secret from the Hyperserve dashboard |
+| `toleranceMs` | `number` | No | `300000` | Max timestamp age in ms (default 5 min) |
+
+---
+
+## Error handling
+
+All errors extend `HyperserveError` and can be caught broadly or narrowly.
+
+```typescript
+import {
+  HyperserveClient,
+  HyperserveError,
+  HyperserveValidationError,
+  HyperserveNotFoundError,
+  HyperserveUploadError,
+  HyperserveTimeoutError,
+} from '@hyperserve/hyperserve-js';
+
+try {
+  await hyperserve.createVideo({ ... });
+} catch (err) {
+  if (err instanceof HyperserveValidationError) {
+    // 4xx — unsupported format, file too large, invalid resolutions, etc.
+    console.error(err.message, err.statusCode);
+  } else if (err instanceof HyperserveNotFoundError) {
+    // 404
+  } else if (err instanceof HyperserveTimeoutError) {
+    // request exceeded timeoutMs
+  } else if (err instanceof HyperserveError) {
+    // any other SDK error
+  }
+}
+```
+
+`HyperserveUploadError` and `HyperserveTimeoutError` are also exported from `@hyperserve/hyperserve-js/browser` and `@hyperserve/hyperserve-js/react-native`.
+
+---
+
+## Types
+
+```typescript
+import type {
+  VideoResolution,             // '144p' | '240p' | '360p' | '480p' | '720p' | '1080p' | '1440p' | '4k' | '8k'
+  VideoStatus,                 // 'pending_upload' | 'processing' | 'ready' | 'fail'
+  CreateVideoOptions,
+  CreateVideoResult,
+  CompleteUploadResult,
+  VideoResult,
+  VideoResolutionResult,
+  VerifyWebhookSignatureOptions,
+  PutVideoToStorageOptions,    // for @hyperserve/hyperserve-js/browser
+  PutVideoToStorageRNOptions,  // for @hyperserve/hyperserve-js/react-native
+} from 'hyperserve-js';
+```
+
+---
+
+## Requirements
+
+| Environment | Minimum version |
+|---|---|
+| Node.js | 18+ |
+| Modern browsers | Chrome 80+, Firefox 75+, Safari 14+ |
+| React Native | 0.60+ |
+| Expo | SDK 41+ |
+| Bun / Deno | Current stable |
+
+No polyfills required. The SDK uses native `fetch`, `Blob`, and `XMLHttpRequest` — all available in the supported environments without additional setup.

package/dist/browser.cjs

@@ -0,0 +1,91 @@
+'use strict';
+
+// src/errors.ts
+var HyperserveError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "HyperserveError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var HyperserveUploadError = class extends HyperserveError {
+  constructor(message, uploadStatus) {
+    super(message);
+    this.uploadStatus = uploadStatus;
+    this.name = "HyperserveUploadError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var HyperserveTimeoutError = class extends HyperserveError {
+  constructor(message = "Request timed out") {
+    super(message);
+    this.name = "HyperserveTimeoutError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/storage.ts
+async function putToStorage(uploadUrl, contentType, body, onProgress) {
+  if (onProgress !== void 0 && typeof XMLHttpRequest !== "undefined" && !(body instanceof ReadableStream)) {
+    return putWithXhr(uploadUrl, contentType, body, onProgress);
+  }
+  return putWithFetch(uploadUrl, contentType, body);
+}
+function putWithFetch(uploadUrl, contentType, body) {
+  return fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    // duplex is required for ReadableStream bodies in some runtimes (Node 18)
+    ...body instanceof ReadableStream ? { duplex: "half" } : {},
+    body
+  }).then((response) => {
+    if (!response.ok) {
+      throw new HyperserveUploadError(
+        `Storage PUT failed with status ${response.status}`,
+        response.status
+      );
+    }
+  });
+}
+function putWithXhr(uploadUrl, contentType, body, onProgress) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open("PUT", uploadUrl);
+    xhr.setRequestHeader("Content-Type", contentType);
+    xhr.upload.addEventListener("progress", (event) => {
+      if (event.lengthComputable) {
+        onProgress(Math.round(event.loaded / event.total * 100));
+      }
+    });
+    xhr.addEventListener("load", () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        onProgress(100);
+        resolve();
+      } else {
+        reject(
+          new HyperserveUploadError(`Storage PUT failed with status ${xhr.status}`, xhr.status)
+        );
+      }
+    });
+    xhr.addEventListener("timeout", () => {
+      reject(new HyperserveTimeoutError("Storage PUT timed out"));
+    });
+    xhr.addEventListener("error", () => {
+      reject(new HyperserveUploadError("Storage PUT failed due to a network error"));
+    });
+    xhr.send(body);
+  });
+}
+
+// src/browser.ts
+async function putVideoToStorage(options) {
+  return putToStorage(options.uploadUrl, options.contentType, options.file, options.onProgress);
+}
+
+exports.HyperserveError = HyperserveError;
+exports.HyperserveTimeoutError = HyperserveTimeoutError;
+exports.HyperserveUploadError = HyperserveUploadError;
+exports.putVideoToStorage = putVideoToStorage;
+//# sourceMappingURL=browser.cjs.map
+//# sourceMappingURL=browser.cjs.map

package/dist/browser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/storage.ts","../src/browser.ts"],"names":[],"mappings":"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","file":"browser.cjs","sourcesContent":["/**\n * Base class for all Hyperserve SDK errors.\n */\nexport class HyperserveError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly statusCode?: number,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"HyperserveError\";\n\t\t// Maintain proper prototype chain in transpiled environments\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * The Hyperserve API returned a 4xx response.\n * Typically indicates a validation problem: unsupported file format,\n * file too large, invalid resolutions, video not in expected state, etc.\n */\nexport class HyperserveValidationError extends HyperserveError {\n\tconstructor(\n\t\tmessage: string,\n\t\tstatusCode: number,\n\t\tpublic readonly detail?: unknown,\n\t) {\n\t\tsuper(message, statusCode);\n\t\tthis.name = \"HyperserveValidationError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * The Hyperserve API returned a 404 response.\n */\nexport class HyperserveNotFoundError extends HyperserveError {\n\tconstructor(message = \"Resource not found\") {\n\t\tsuper(message, 404);\n\t\tthis.name = \"HyperserveNotFoundError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * The Hyperserve API returned a 5xx response.\n */\nexport class HyperserveApiError extends HyperserveError {\n\tconstructor(message: string, statusCode: number) {\n\t\tsuper(message, statusCode);\n\t\tthis.name = \"HyperserveApiError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * The storage PUT request failed.\n */\nexport class HyperserveUploadError extends HyperserveError {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly uploadStatus?: number,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"HyperserveUploadError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * A request exceeded the configured timeoutMs.\n */\nexport class HyperserveTimeoutError extends HyperserveError {\n\tconstructor(message = \"Request timed out\") {\n\t\tsuper(message);\n\t\tthis.name = \"HyperserveTimeoutError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n","import { HyperserveTimeoutError, HyperserveUploadError } from \"./errors.js\";\n\n/**\n * PUT a file to a presigned S3 URL.\n * Used internally by uploadVideo (server) and exported as putVideoToStorage (browser).\n *\n * When onProgress is provided, uses XMLHttpRequest for upload progress events.\n * Falls back to fetch otherwise.\n */\nexport async function putToStorage(\n\tuploadUrl: string,\n\tcontentType: string,\n\tbody: Blob | ReadableStream,\n\tonProgress?: (percent: number) => void,\n): Promise<void> {\n\t// XHR is used for progress reporting but does not support ReadableStream bodies.\n\t// Fall back to fetch (no progress) when the body is a stream.\n\tif (\n\t\tonProgress !== undefined &&\n\t\ttypeof XMLHttpRequest !== \"undefined\" &&\n\t\t!(body instanceof ReadableStream)\n\t) {\n\t\treturn putWithXhr(uploadUrl, contentType, body, onProgress);\n\t}\n\treturn putWithFetch(uploadUrl, contentType, body);\n}\n\nfunction putWithFetch(\n\tuploadUrl: string,\n\tcontentType: string,\n\tbody: Blob | ReadableStream,\n): Promise<void> {\n\treturn fetch(uploadUrl, {\n\t\tmethod: \"PUT\",\n\t\theaders: { \"Content-Type\": contentType },\n\t\t// duplex is required for ReadableStream bodies in some runtimes (Node 18)\n\t\t...(body instanceof ReadableStream ? { duplex: \"half\" } : {}),\n\t\tbody: body as BodyInit,\n\t}).then((response) => {\n\t\tif (!response.ok) {\n\t\t\tthrow new HyperserveUploadError(\n\t\t\t\t`Storage PUT failed with status ${response.status}`,\n\t\t\t\tresponse.status,\n\t\t\t);\n\t\t}\n\t});\n}\n\nfunction putWithXhr(\n\tuploadUrl: string,\n\tcontentType: string,\n\tbody: Blob,\n\tonProgress: (percent: number) => void,\n): Promise<void> {\n\treturn new Promise((resolve, reject) => {\n\t\tconst xhr = new XMLHttpRequest();\n\n\t\txhr.open(\"PUT\", uploadUrl);\n\t\txhr.setRequestHeader(\"Content-Type\", contentType);\n\n\t\txhr.upload.addEventListener(\"progress\", (event) => {\n\t\t\tif (event.lengthComputable) {\n\t\t\t\tonProgress(Math.round((event.loaded / event.total) * 100));\n\t\t\t}\n\t\t});\n\n\t\txhr.addEventListener(\"load\", () => {\n\t\t\tif (xhr.status >= 200 && xhr.status < 300) {\n\t\t\t\tonProgress(100);\n\t\t\t\tresolve();\n\t\t\t} else {\n\t\t\t\treject(\n\t\t\t\t\tnew HyperserveUploadError(`Storage PUT failed with status ${xhr.status}`, xhr.status),\n\t\t\t\t);\n\t\t\t}\n\t\t});\n\n\t\txhr.addEventListener(\"timeout\", () => {\n\t\t\treject(new HyperserveTimeoutError(\"Storage PUT timed out\"));\n\t\t});\n\n\t\txhr.addEventListener(\"error\", () => {\n\t\t\treject(new HyperserveUploadError(\"Storage PUT failed due to a network error\"));\n\t\t});\n\n\t\txhr.send(body);\n\t});\n}\n","/**\n * Browser-only utilities for the Hyperserve SDK.\n *\n * Import from '@hyperserve/hyperserve-js/browser' — this entry point contains no API key\n * logic and is safe to bundle into client-side code.\n *\n * Usage:\n *   import { putVideoToStorage } from '@hyperserve/hyperserve-js/browser';\n *\n *   // uploadUrl and contentType come from your own backend\n *   await putVideoToStorage({ uploadUrl, contentType, file, onProgress });\n */\n\nexport { HyperserveError, HyperserveTimeoutError, HyperserveUploadError } from \"./errors.js\";\nexport type { PutVideoToStorageOptions, VideoResolution, VideoStatus } from \"./types.js\";\n\nimport { putToStorage } from \"./storage.js\";\nimport type { PutVideoToStorageOptions } from \"./types.js\";\n\n/**\n * PUT a video file to the presigned storage URL obtained from your backend.\n * No API key required — this call goes directly to storage, not to the Hyperserve API.\n *\n * @example\n * const { uploadUrl, contentType } = await fetch('/api/create-upload', { ... }).then(r => r.json());\n * await putVideoToStorage({ uploadUrl, contentType, file, onProgress: (p) => console.log(p) });\n * await fetch('/api/complete-upload', { method: 'POST', body: JSON.stringify({ videoId }) });\n */\nexport async function putVideoToStorage(options: PutVideoToStorageOptions): Promise<void> {\n\treturn putToStorage(options.uploadUrl, options.contentType, options.file, options.onProgress);\n}\n"]}

package/dist/browser.d.cts

@@ -0,0 +1,28 @@
+import { P as PutVideoToStorageOptions } from './errors-C89laaKB.cjs';
+export { e as HyperserveError, g as HyperserveTimeoutError, h as HyperserveUploadError, k as VideoResolution, m as VideoStatus } from './errors-C89laaKB.cjs';
+
+/**
+ * Browser-only utilities for the Hyperserve SDK.
+ *
+ * Import from '@hyperserve/hyperserve-js/browser' — this entry point contains no API key
+ * logic and is safe to bundle into client-side code.
+ *
+ * Usage:
+ *   import { putVideoToStorage } from '@hyperserve/hyperserve-js/browser';
+ *
+ *   // uploadUrl and contentType come from your own backend
+ *   await putVideoToStorage({ uploadUrl, contentType, file, onProgress });
+ */
+
+/**
+ * PUT a video file to the presigned storage URL obtained from your backend.
+ * No API key required — this call goes directly to storage, not to the Hyperserve API.
+ *
+ * @example
+ * const { uploadUrl, contentType } = await fetch('/api/create-upload', { ... }).then(r => r.json());
+ * await putVideoToStorage({ uploadUrl, contentType, file, onProgress: (p) => console.log(p) });
+ * await fetch('/api/complete-upload', { method: 'POST', body: JSON.stringify({ videoId }) });
+ */
+declare function putVideoToStorage(options: PutVideoToStorageOptions): Promise<void>;
+
+export { PutVideoToStorageOptions, putVideoToStorage };

package/dist/browser.d.ts

@@ -0,0 +1,28 @@
+import { P as PutVideoToStorageOptions } from './errors-C89laaKB.js';
+export { e as HyperserveError, g as HyperserveTimeoutError, h as HyperserveUploadError, k as VideoResolution, m as VideoStatus } from './errors-C89laaKB.js';
+
+/**
+ * Browser-only utilities for the Hyperserve SDK.
+ *
+ * Import from '@hyperserve/hyperserve-js/browser' — this entry point contains no API key
+ * logic and is safe to bundle into client-side code.
+ *
+ * Usage:
+ *   import { putVideoToStorage } from '@hyperserve/hyperserve-js/browser';
+ *
+ *   // uploadUrl and contentType come from your own backend
+ *   await putVideoToStorage({ uploadUrl, contentType, file, onProgress });
+ */
+
+/**
+ * PUT a video file to the presigned storage URL obtained from your backend.
+ * No API key required — this call goes directly to storage, not to the Hyperserve API.
+ *
+ * @example
+ * const { uploadUrl, contentType } = await fetch('/api/create-upload', { ... }).then(r => r.json());
+ * await putVideoToStorage({ uploadUrl, contentType, file, onProgress: (p) => console.log(p) });
+ * await fetch('/api/complete-upload', { method: 'POST', body: JSON.stringify({ videoId }) });
+ */
+declare function putVideoToStorage(options: PutVideoToStorageOptions): Promise<void>;
+
+export { PutVideoToStorageOptions, putVideoToStorage };

package/dist/browser.js

@@ -0,0 +1,86 @@
+// src/errors.ts
+var HyperserveError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "HyperserveError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var HyperserveUploadError = class extends HyperserveError {
+  constructor(message, uploadStatus) {
+    super(message);
+    this.uploadStatus = uploadStatus;
+    this.name = "HyperserveUploadError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var HyperserveTimeoutError = class extends HyperserveError {
+  constructor(message = "Request timed out") {
+    super(message);
+    this.name = "HyperserveTimeoutError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/storage.ts
+async function putToStorage(uploadUrl, contentType, body, onProgress) {
+  if (onProgress !== void 0 && typeof XMLHttpRequest !== "undefined" && !(body instanceof ReadableStream)) {
+    return putWithXhr(uploadUrl, contentType, body, onProgress);
+  }
+  return putWithFetch(uploadUrl, contentType, body);
+}
+function putWithFetch(uploadUrl, contentType, body) {
+  return fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    // duplex is required for ReadableStream bodies in some runtimes (Node 18)
+    ...body instanceof ReadableStream ? { duplex: "half" } : {},
+    body
+  }).then((response) => {
+    if (!response.ok) {
+      throw new HyperserveUploadError(
+        `Storage PUT failed with status ${response.status}`,
+        response.status
+      );
+    }
+  });
+}
+function putWithXhr(uploadUrl, contentType, body, onProgress) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open("PUT", uploadUrl);
+    xhr.setRequestHeader("Content-Type", contentType);
+    xhr.upload.addEventListener("progress", (event) => {
+      if (event.lengthComputable) {
+        onProgress(Math.round(event.loaded / event.total * 100));
+      }
+    });
+    xhr.addEventListener("load", () => {
+      if (xhr.status >= 200 && xhr.status < 300) {
+        onProgress(100);
+        resolve();
+      } else {
+        reject(
+          new HyperserveUploadError(`Storage PUT failed with status ${xhr.status}`, xhr.status)
+        );
+      }
+    });
+    xhr.addEventListener("timeout", () => {
+      reject(new HyperserveTimeoutError("Storage PUT timed out"));
+    });
+    xhr.addEventListener("error", () => {
+      reject(new HyperserveUploadError("Storage PUT failed due to a network error"));
+    });
+    xhr.send(body);
+  });
+}
+
+// src/browser.ts
+async function putVideoToStorage(options) {
+  return putToStorage(options.uploadUrl, options.contentType, options.file, options.onProgress);
+}
+
+export { HyperserveError, HyperserveTimeoutError, HyperserveUploadError, putVideoToStorage };
+//# sourceMappingURL=browser.js.map
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/storage.ts","../src/browser.ts"],"names":[],"mappings":"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","file":"browser.js","sourcesContent":["/**\n * Base class for all Hyperserve SDK errors.\n */\nexport class HyperserveError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly statusCode?: number,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"HyperserveError\";\n\t\t// Maintain proper prototype chain in transpiled environments\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * The Hyperserve API returned a 4xx response.\n * Typically indicates a validation problem: unsupported file format,\n * file too large, invalid resolutions, video not in expected state, etc.\n */\nexport class HyperserveValidationError extends HyperserveError {\n\tconstructor(\n\t\tmessage: string,\n\t\tstatusCode: number,\n\t\tpublic readonly detail?: unknown,\n\t) {\n\t\tsuper(message, statusCode);\n\t\tthis.name = \"HyperserveValidationError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * The Hyperserve API returned a 404 response.\n */\nexport class HyperserveNotFoundError extends HyperserveError {\n\tconstructor(message = \"Resource not found\") {\n\t\tsuper(message, 404);\n\t\tthis.name = \"HyperserveNotFoundError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * The Hyperserve API returned a 5xx response.\n */\nexport class HyperserveApiError extends HyperserveError {\n\tconstructor(message: string, statusCode: number) {\n\t\tsuper(message, statusCode);\n\t\tthis.name = \"HyperserveApiError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * The storage PUT request failed.\n */\nexport class HyperserveUploadError extends HyperserveError {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly uploadStatus?: number,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"HyperserveUploadError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n\n/**\n * A request exceeded the configured timeoutMs.\n */\nexport class HyperserveTimeoutError extends HyperserveError {\n\tconstructor(message = \"Request timed out\") {\n\t\tsuper(message);\n\t\tthis.name = \"HyperserveTimeoutError\";\n\t\tObject.setPrototypeOf(this, new.target.prototype);\n\t}\n}\n","import { HyperserveTimeoutError, HyperserveUploadError } from \"./errors.js\";\n\n/**\n * PUT a file to a presigned S3 URL.\n * Used internally by uploadVideo (server) and exported as putVideoToStorage (browser).\n *\n * When onProgress is provided, uses XMLHttpRequest for upload progress events.\n * Falls back to fetch otherwise.\n */\nexport async function putToStorage(\n\tuploadUrl: string,\n\tcontentType: string,\n\tbody: Blob | ReadableStream,\n\tonProgress?: (percent: number) => void,\n): Promise<void> {\n\t// XHR is used for progress reporting but does not support ReadableStream bodies.\n\t// Fall back to fetch (no progress) when the body is a stream.\n\tif (\n\t\tonProgress !== undefined &&\n\t\ttypeof XMLHttpRequest !== \"undefined\" &&\n\t\t!(body instanceof ReadableStream)\n\t) {\n\t\treturn putWithXhr(uploadUrl, contentType, body, onProgress);\n\t}\n\treturn putWithFetch(uploadUrl, contentType, body);\n}\n\nfunction putWithFetch(\n\tuploadUrl: string,\n\tcontentType: string,\n\tbody: Blob | ReadableStream,\n): Promise<void> {\n\treturn fetch(uploadUrl, {\n\t\tmethod: \"PUT\",\n\t\theaders: { \"Content-Type\": contentType },\n\t\t// duplex is required for ReadableStream bodies in some runtimes (Node 18)\n\t\t...(body instanceof ReadableStream ? { duplex: \"half\" } : {}),\n\t\tbody: body as BodyInit,\n\t}).then((response) => {\n\t\tif (!response.ok) {\n\t\t\tthrow new HyperserveUploadError(\n\t\t\t\t`Storage PUT failed with status ${response.status}`,\n\t\t\t\tresponse.status,\n\t\t\t);\n\t\t}\n\t});\n}\n\nfunction putWithXhr(\n\tuploadUrl: string,\n\tcontentType: string,\n\tbody: Blob,\n\tonProgress: (percent: number) => void,\n): Promise<void> {\n\treturn new Promise((resolve, reject) => {\n\t\tconst xhr = new XMLHttpRequest();\n\n\t\txhr.open(\"PUT\", uploadUrl);\n\t\txhr.setRequestHeader(\"Content-Type\", contentType);\n\n\t\txhr.upload.addEventListener(\"progress\", (event) => {\n\t\t\tif (event.lengthComputable) {\n\t\t\t\tonProgress(Math.round((event.loaded / event.total) * 100));\n\t\t\t}\n\t\t});\n\n\t\txhr.addEventListener(\"load\", () => {\n\t\t\tif (xhr.status >= 200 && xhr.status < 300) {\n\t\t\t\tonProgress(100);\n\t\t\t\tresolve();\n\t\t\t} else {\n\t\t\t\treject(\n\t\t\t\t\tnew HyperserveUploadError(`Storage PUT failed with status ${xhr.status}`, xhr.status),\n\t\t\t\t);\n\t\t\t}\n\t\t});\n\n\t\txhr.addEventListener(\"timeout\", () => {\n\t\t\treject(new HyperserveTimeoutError(\"Storage PUT timed out\"));\n\t\t});\n\n\t\txhr.addEventListener(\"error\", () => {\n\t\t\treject(new HyperserveUploadError(\"Storage PUT failed due to a network error\"));\n\t\t});\n\n\t\txhr.send(body);\n\t});\n}\n","/**\n * Browser-only utilities for the Hyperserve SDK.\n *\n * Import from '@hyperserve/hyperserve-js/browser' — this entry point contains no API key\n * logic and is safe to bundle into client-side code.\n *\n * Usage:\n *   import { putVideoToStorage } from '@hyperserve/hyperserve-js/browser';\n *\n *   // uploadUrl and contentType come from your own backend\n *   await putVideoToStorage({ uploadUrl, contentType, file, onProgress });\n */\n\nexport { HyperserveError, HyperserveTimeoutError, HyperserveUploadError } from \"./errors.js\";\nexport type { PutVideoToStorageOptions, VideoResolution, VideoStatus } from \"./types.js\";\n\nimport { putToStorage } from \"./storage.js\";\nimport type { PutVideoToStorageOptions } from \"./types.js\";\n\n/**\n * PUT a video file to the presigned storage URL obtained from your backend.\n * No API key required — this call goes directly to storage, not to the Hyperserve API.\n *\n * @example\n * const { uploadUrl, contentType } = await fetch('/api/create-upload', { ... }).then(r => r.json());\n * await putVideoToStorage({ uploadUrl, contentType, file, onProgress: (p) => console.log(p) });\n * await fetch('/api/complete-upload', { method: 'POST', body: JSON.stringify({ videoId }) });\n */\nexport async function putVideoToStorage(options: PutVideoToStorageOptions): Promise<void> {\n\treturn putToStorage(options.uploadUrl, options.contentType, options.file, options.onProgress);\n}\n"]}