@zyris/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zyris.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# Zyris Node.js SDK
+
+The official Node.js SDK for Zyris.
+
+## Documentation
+
+- [Node.js SDK reference](https://www.zyris.ai/build/sdks/nodejs) — install, quick start, every resource, response shapes, recipes.
+- [HTTP API reference](https://www.zyris.ai/build/api-docs) — wire protocol if you are calling the API without the SDK.
+
+## Install
+
+```bash
+npm install @zyris/sdk
+```
+
+Requires Node.js 18+.
+
+## Quick start
+
+```javascript
+import { Client } from '@zyris/sdk';
+
+const client = new Client({
+  apiKey: 'sk_...',
+  baseUrl: 'https://playground.zyris.ai',
+});
+
+const collections = await client.collections.list({ page: 1, pageSize: 10 });
+console.log(`${collections.total} collection(s)`);
+```
+
+For full usage — every resource, response shapes, and recipes — see the [Node.js SDK reference](https://www.zyris.ai/build/sdks/nodejs).

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@zyris/sdk",
+  "version": "0.1.0",
+  "description": "Node.js SDK for Zyris.",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mikshi-VLM/nodejs_sdk.git"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "video",
+    "sdk",
+    "api",
+    "zyris",
+    "vlm",
+    "collections",
+    "embeddings",
+    "search",
+    "chat"
+  ],
+  "dependencies": {
+    "axios": "^1.18.0"
+  },
+  "author": "zyris.ai <contact@zyris.ai>",
+  "license": "MIT",
+  "homepage": "https://www.zyris.ai/",
+  "bugs": {
+    "email": "contact@zyris.ai"
+  }
+}

package/src/_version.js

@@ -0,0 +1 @@
+export const VERSION = "0.1.0";

package/src/client.js

@@ -0,0 +1,195 @@
+import axios from 'axios';
+import { VERSION } from './_version.js';
+import {
+  APIError,
+  AuthenticationError,
+  BadGatewayError,
+  BadRequestError,
+  ConflictError,
+  InsufficientCreditsError,
+  InternalServerError,
+  NotFoundError,
+  PayloadTooLargeError,
+  PermissionDeniedError,
+  RateLimitError,
+  ServiceUnavailableError,
+  UnprocessableEntityError,
+} from './exceptions.js';
+import { ChatResource } from './resources/chat.js';
+import { CollectionsResource } from './resources/collections.js';
+import { EmbeddingsResource } from './resources/embeddings.js';
+import { SearchResource } from './resources/search.js';
+import { UploadsResource } from './resources/uploads.js';
+import { VideosResource } from './resources/videos.js';
+
+const DEFAULT_BASE_URL = "https://playground.zyris.ai";
+const DEFAULT_TIMEOUT = 30000;
+
+export class Client {
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, timeout = DEFAULT_TIMEOUT } = {}) {
+    if (!apiKey) throw new Error("apiKey is required");
+
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.timeout = timeout;
+
+    this.axios = axios.create({
+      baseURL: this.baseUrl,
+      timeout: this.timeout,
+      headers: {
+        "Accept": "application/json",
+        "X-API-Key": apiKey,
+        "User-Agent": `zyris-node/${VERSION}`,
+      },
+    });
+
+    this.collections = new CollectionsResource(this);
+    this.uploads = new UploadsResource(this);
+    this.videos = new VideosResource(this);
+    this.search = new SearchResource(this);
+    this.chat = new ChatResource(this);
+    this.embeddings = new EmbeddingsResource(this);
+  }
+
+  /**
+   * Release any underlying HTTP resources. Axios has no persistent client to
+   * close, so this is a no-op — provided for API parity with the Python SDK.
+   */
+  close() {
+    // no-op
+  }
+
+  async _request(method, path, { params, data, headers, ...config } = {}) {
+    try {
+      const response = await this.axios.request({
+        method,
+        url: path,
+        params,
+        data,
+        headers,
+        ...config,
+      });
+      return response.data;
+    } catch (error) {
+      this._handleError(error);
+    }
+  }
+
+  /**
+   * Stream Server-Sent Events from the API. Async-iterates `{ event, data }`
+   * pairs where `data` is the parsed JSON payload (or `{ raw }` on parse failure).
+   *
+   * On non-2xx the response body is read and routed through the standard
+   * error handler — same exception types as `_request`.
+   */
+  async *_streamSse(method, path, { data: body } = {}) {
+    let response;
+    try {
+      response = await this.axios.request({
+        method,
+        url: path,
+        data: body,
+        headers: { Accept: "text/event-stream" },
+        responseType: "stream",
+      });
+    } catch (error) {
+      // axios with responseType:'stream' may not have parsed the error body yet;
+      // try to materialize it before handing off to _handleError.
+      if (error.response && error.response.data && typeof error.response.data.on === "function") {
+        const chunks = [];
+        for await (const chunk of error.response.data) chunks.push(chunk);
+        const text = Buffer.concat(chunks).toString("utf8");
+        try {
+          error.response.data = JSON.parse(text);
+        } catch {
+          error.response.data = text;
+        }
+      }
+      this._handleError(error);
+      return;
+    }
+
+    const stream = response.data;
+    let buffer = "";
+    let eventName = "message";
+    let dataLines = [];
+
+    const flush = () => {
+      if (dataLines.length === 0) return null;
+      const raw = dataLines.join("\n");
+      let payload;
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        payload = { raw };
+      }
+      const ev = { event: eventName, data: payload };
+      eventName = "message";
+      dataLines = [];
+      return ev;
+    };
+
+    for await (const chunk of stream) {
+      buffer += chunk.toString("utf8");
+      let nlIndex;
+      while ((nlIndex = buffer.indexOf("\n")) !== -1) {
+        let line = buffer.slice(0, nlIndex);
+        buffer = buffer.slice(nlIndex + 1);
+        if (line.endsWith("\r")) line = line.slice(0, -1);
+        if (line === "") {
+          const ev = flush();
+          if (ev) yield ev;
+          continue;
+        }
+        if (line.startsWith(":")) continue;
+        if (line.startsWith("event:")) {
+          eventName = line.slice("event:".length).trim();
+        } else if (line.startsWith("data:")) {
+          dataLines.push(line.slice("data:".length).replace(/^\s/, ""));
+        }
+      }
+    }
+
+    if (buffer.length > 0) {
+      let line = buffer;
+      if (line.endsWith("\r")) line = line.slice(0, -1);
+      if (line !== "" && !line.startsWith(":")) {
+        if (line.startsWith("event:")) {
+          eventName = line.slice("event:".length).trim();
+        } else if (line.startsWith("data:")) {
+          dataLines.push(line.slice("data:".length).replace(/^\s/, ""));
+        }
+      }
+    }
+    const ev = flush();
+    if (ev) yield ev;
+  }
+
+  _handleError(error) {
+    if (!error.response) throw error;
+    const { status, statusText, data } = error.response;
+    const message = `${status} ${statusText}: ${typeof data === "string" ? data : JSON.stringify(data)}`;
+
+    if (status === 400) throw new BadRequestError(message, status, data);
+    if (status === 401) throw new AuthenticationError(message, status, data);
+    if (status === 402) throw new InsufficientCreditsError(message, status, data);
+    if (status === 403) throw new PermissionDeniedError(message, status, data);
+    if (status === 404) throw new NotFoundError(message, status, data);
+    if (status === 409) throw new ConflictError(message, status, data);
+    if (status === 413) throw new PayloadTooLargeError(message, status, data);
+    if (status === 422) throw new UnprocessableEntityError(message, status, data);
+    if (status === 429) {
+      const header = error.response.headers?.["retry-after"];
+      let retryAfter = null;
+      if (header != null) {
+        const parsed = Number(header);
+        retryAfter = Number.isFinite(parsed) ? parsed : null;
+      }
+      throw new RateLimitError(message, status, data, retryAfter);
+    }
+    if (status === 502) throw new BadGatewayError(message, status, data);
+    if (status === 503) throw new ServiceUnavailableError(message, status, data);
+    if (status >= 500) throw new InternalServerError(message, status, data);
+    throw new APIError(message, status, data);
+  }
+}

package/src/duration.js

@@ -0,0 +1,125 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+// ISO-BMFF top-level box types we accept as a signal the file is MP4/MOV.
+const BMFF_TOP_TYPES = new Set(['ftyp', 'moov', 'free', 'skip', 'mdat', 'wide', 'pnot']);
+
+/**
+ * Best-effort detection of a local video's duration in seconds.
+ *
+ * Tries two dependency-free strategies, in order:
+ *   1. Parse the MP4/MOV `moov` → `mvhd` header directly (covers `.mp4`,
+ *      `.m4v`, `.mov` — no external tools).
+ *   2. Shell out to `ffprobe` if it is on PATH (mkv, webm, avi, …).
+ *
+ * Throws if neither yields a positive duration — catch it and pass
+ * `videoDurationSeconds` explicitly. Used automatically by
+ * `uploads.uploadFile` / `uploads.direct` when the caller omits the duration.
+ * (Not used for YouTube imports — those are probed server-side.)
+ */
+export function probeDuration(filePath) {
+  const fromMp4 = _durationFromMp4(filePath);
+  if (fromMp4 != null && fromMp4 > 0) return fromMp4;
+  const fromFfprobe = _durationFromFfprobe(filePath);
+  if (fromFfprobe != null) return fromFfprobe;
+  throw new Error(
+    `Could not determine the duration of ${filePath}. ` +
+    'Pass videoDurationSeconds explicitly (e.g. measured via ffprobe).',
+  );
+}
+
+function _readAt(fd, position, length) {
+  const buf = Buffer.alloc(length);
+  const n = fs.readSync(fd, buf, 0, length, position);
+  return n === length ? buf : buf.subarray(0, n);
+}
+
+function _durationFromMp4(filePath) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, 'r');
+    const head = _readAt(fd, 0, 8);
+    if (head.length < 8 || !BMFF_TOP_TYPES.has(head.toString('latin1', 4, 8))) {
+      return null;
+    }
+    return _findMvhd(fd, 0, fs.fstatSync(fd).size);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch { /* ignore */ }
+    }
+  }
+}
+
+// Walk the boxes in [start, end); invoke cb(type, contentStart, contentSize)
+// for each. The first cb result that isn't `undefined` is returned.
+function _iterBoxes(fd, start, end, cb) {
+  let pos = start;
+  while (pos + 8 <= end) {
+    const header = _readAt(fd, pos, 8);
+    if (header.length < 8) break;
+    let size = header.readUInt32BE(0);
+    const type = header.toString('latin1', 4, 8);
+    let headerSize = 8;
+    if (size === 1) { // 64-bit largesize follows the 8-byte header
+      const ext = _readAt(fd, pos + 8, 8);
+      if (ext.length < 8) break;
+      size = Number(ext.readBigUInt64BE(0));
+      headerSize = 16;
+    } else if (size === 0) { // box extends to end of range
+      size = end - pos;
+    }
+    if (size < headerSize) break;
+    const result = cb(type, pos + headerSize, size - headerSize);
+    if (result !== undefined) return result;
+    pos += size;
+  }
+  return undefined;
+}
+
+function _findMvhd(fd, start, end) {
+  const found = _iterBoxes(fd, start, end, (type, cStart, cSize) => {
+    if (type !== 'moov') return undefined;
+    const dur = _iterBoxes(fd, cStart, cStart + cSize, (t2, c2Start, c2Size) => {
+      if (t2 === 'mvhd') return _parseMvhd(_readAt(fd, c2Start, Math.min(c2Size, 32)));
+      return undefined;
+    });
+    return dur == null ? undefined : dur;
+  });
+  return found == null ? null : found;
+}
+
+function _parseMvhd(buf) {
+  if (buf.length < 20) return null;
+  const version = buf[0];
+  let timescale;
+  let duration;
+  if (version === 1) {
+    if (buf.length < 32) return null;
+    timescale = buf.readUInt32BE(20);
+    duration = Number(buf.readBigUInt64BE(24));
+  } else {
+    timescale = buf.readUInt32BE(12);
+    duration = buf.readUInt32BE(16);
+  }
+  if (!timescale) return null;
+  return duration / timescale;
+}
+
+function _durationFromFfprobe(filePath) {
+  let res;
+  try {
+    res = spawnSync(
+      'ffprobe',
+      ['-v', 'error', '-show_entries', 'format=duration',
+        '-of', 'default=noprint_wrappers=1:nokey=1', filePath],
+      { encoding: 'utf8', timeout: 30000 },
+    );
+  } catch {
+    return null;
+  }
+  if (res.error || res.status !== 0) return null;
+  const value = parseFloat((res.stdout || '').trim());
+  return Number.isFinite(value) && value > 0 ? value : null;
+}

package/src/exceptions.js

@@ -0,0 +1,56 @@
+export const YOUTUBE_FATAL_CODES = new Set([
+  "YOUTUBE_VIDEO_TOO_LONG",
+  "YOUTUBE_VIDEO_UNAVAILABLE",
+  "YOUTUBE_VIDEO_PRIVATE",
+  "YOUTUBE_VIDEO_AGE_RESTRICTED",
+  "YOUTUBE_VIDEO_GEO_BLOCKED",
+  "YOUTUBE_VIDEO_BLOCKED",
+  "YOUTUBE_AUTH_REQUIRED",
+  "YOUTUBE_AUTH_EXPIRED",
+  "YOUTUBE_AUTH_MISSING",
+  "YOUTUBE_AUTH_INVALID",
+  "YOUTUBE_IMPORT_FAILED",
+]);
+
+export class ZyrisError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+export class APIError extends ZyrisError {
+  constructor(message, statusCode = null, responseBody = null) {
+    super(message);
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+  }
+}
+
+export class BadRequestError extends APIError {}
+
+export class YouTubeImportError extends BadRequestError {
+  constructor(message, statusCode = null, responseBody = null, code = null) {
+    super(message, statusCode, responseBody);
+    this.code = code;
+  }
+}
+
+export class AuthenticationError extends APIError {}
+export class InsufficientCreditsError extends APIError {}
+export class PermissionDeniedError extends APIError {}
+export class NotFoundError extends APIError {}
+export class ConflictError extends APIError {}
+export class PayloadTooLargeError extends APIError {}
+export class UnprocessableEntityError extends APIError {}
+
+export class RateLimitError extends APIError {
+  constructor(message, statusCode = null, responseBody = null, retryAfter = null) {
+    super(message, statusCode, responseBody);
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class InternalServerError extends APIError {}
+export class BadGatewayError extends APIError {}
+export class ServiceUnavailableError extends APIError {}

package/src/index.js

@@ -0,0 +1,12 @@
+export { Client } from './client.js';
+export { VERSION } from './_version.js';
+export { probeDuration } from './duration.js';
+export {
+  UPLOAD_BYTES_PER_CREDIT,
+  estimateUploadCredits,
+  derivedUploadStatus,
+  isPipelineDone,
+  isPipelineFailed,
+  isPipelineTerminal,
+} from './models.js';
+export * from './exceptions.js';

package/src/models.js

@@ -0,0 +1,48 @@
+export const UPLOAD_BYTES_PER_CREDIT = 25 * 1024 * 1024;
+
+const PIPELINE_DONE_STATES = new Set(["done", "success", "completed"]);
+const PIPELINE_FAILED_STATES = new Set(["failed", "error"]);
+
+/**
+ * Estimate the storage credits that will be charged for an upload of
+ * `sizeBytes`. Mirrors the server-side formula: 1 credit per 25 MiB,
+ * rounded up, minimum 1.
+ */
+export function estimateUploadCredits(sizeBytes) {
+  if (sizeBytes <= 0) return 0;
+  return Math.max(1, Math.ceil(sizeBytes / UPLOAD_BYTES_PER_CREDIT));
+}
+
+/**
+ * Roll the three upload-pipeline statuses into one of
+ * `pending` / `in_progress` / `completed` / `failed`.
+ *
+ * Accepts the raw object returned by `client.uploads.getStatus()`.
+ */
+export function derivedUploadStatus(uploadStatus) {
+  const pipelines = [
+    uploadStatus?.thumbnail_generation_status,
+    uploadStatus?.transcoding_status,
+    uploadStatus?.hls_generation_status,
+  ];
+  const statuses = pipelines
+    .filter((p) => p != null)
+    .map((p) => p.status);
+  if (statuses.length === 0) return "pending";
+  if (statuses.some((s) => s === "failed")) return "failed";
+  if (statuses.every((s) => s === "completed")) return "completed";
+  if (statuses.some((s) => s === "in_progress" || s === "completed")) return "in_progress";
+  return "pending";
+}
+
+export function isPipelineDone(pipelineStatus) {
+  return PIPELINE_DONE_STATES.has(pipelineStatus?.status);
+}
+
+export function isPipelineFailed(pipelineStatus) {
+  return PIPELINE_FAILED_STATES.has(pipelineStatus?.status);
+}
+
+export function isPipelineTerminal(pipelineStatus) {
+  return isPipelineDone(pipelineStatus) || isPipelineFailed(pipelineStatus);
+}

package/src/resources/chat.js

@@ -0,0 +1,68 @@
+function serializeHistory(history) {
+  if (history == null) return null;
+  return history.map((msg) => ({ role: msg.role, content: msg.content }));
+}
+
+function buildPayload(question, videoId, topK, history, stream) {
+  const payload = {
+    question,
+    video_id: videoId.toString(),
+  };
+  if (topK != null) payload.top_k = topK;
+  const serialized = serializeHistory(history);
+  if (serialized != null) payload.history = serialized;
+  if (stream) payload.stream = true;
+  return payload;
+}
+
+export class ChatResource {
+  constructor(client) {
+    this._client = client;
+  }
+
+  /**
+   * Ask a question about a video (stateless, video-only RAG).
+   *
+   * The server is stateless — to maintain a multi-turn conversation,
+   * resend prior turns each call as
+   *   `history: [{ role: "user", content: "..." }, { role: "assistant", content: "..." }, ...]`.
+   *
+   * Costs 1 credit per call. Refunded automatically on 5xx.
+   *
+   * POST /chat-service/v1/developer/chat/ask
+   */
+  async ask(question, { videoId, topK = null, history = null } = {}) {
+    if (videoId == null) throw new Error("videoId is required");
+    const payload = buildPayload(question, videoId, topK, history, false);
+    return await this._client._request("POST", "/chat-service/v1/developer/chat/ask", {
+      data: payload,
+    });
+  }
+
+  /**
+   * Stream an answer as Server-Sent Events. Returns an async iterator that
+   * yields `{ event, data }` objects.
+   *
+   *   - `{ event: "token", data: { content } }` per LLM chunk
+   *   - terminates with one of:
+   *     - `{ event: "done", data: { answer } }` (success)
+   *     - `{ event: "error", data: { detail } }` (mid-stream failure; credit refunded)
+   *
+   * POST /chat-service/v1/developer/chat/ask (stream=true)
+   */
+  async *askStream(question, { videoId, topK = null, history = null } = {}) {
+    if (videoId == null) throw new Error("videoId is required");
+    const payload = buildPayload(question, videoId, topK, history, true);
+    for await (const ev of this._client._streamSse("POST", "/chat-service/v1/developer/chat/ask", { data: payload })) {
+      if (ev.event === "token") {
+        yield ev;
+      } else if (ev.event === "done") {
+        yield ev;
+        return;
+      } else if (ev.event === "error") {
+        yield ev;
+        return;
+      }
+    }
+  }
+}

package/src/resources/collections.js

@@ -0,0 +1,117 @@
+export class CollectionsResource {
+  constructor(client) {
+    this._client = client;
+  }
+
+  /**
+   * Create a new collection.
+   *
+   * POST /backend-service/v1/developer/collections/create
+   */
+  async create(name, description = null) {
+    const data = { name };
+    if (description != null) data.description = description;
+    return await this._client._request(
+      "POST",
+      "/backend-service/v1/developer/collections/create",
+      { data },
+    );
+  }
+
+  /**
+   * Update a collection's name and/or description. Fields left as `undefined`
+   * are not sent. Server rejects with 400 if nothing is provided.
+   *
+   * PATCH /backend-service/v1/developer/collections/update/{collection_id}
+   */
+  async update(collectionId, { name, description } = {}) {
+    const data = {};
+    if (name !== undefined) data.name = name;
+    if (description !== undefined) data.description = description;
+    return await this._client._request(
+      "PATCH",
+      `/backend-service/v1/developer/collections/update/${collectionId}`,
+      { data },
+    );
+  }
+
+  /**
+   * Delete a collection. Videos linked to it are unaffected.
+   *
+   * DELETE /backend-service/v1/developer/collections/delete/{collection_id}
+   */
+  async delete(collectionId) {
+    return await this._client._request(
+      "DELETE",
+      `/backend-service/v1/developer/collections/delete/${collectionId}`,
+    );
+  }
+
+  /**
+   * List the calling user's collections.
+   *
+   * `page` >= 1, `pageSize` 1-100. Response carries `data`, `page`,
+   * `page_size`, `total`.
+   *
+   * GET /backend-service/v1/developer/collections/list
+   */
+  async list({ page = 1, pageSize = 10 } = {}) {
+    return await this._client._request(
+      "GET",
+      "/backend-service/v1/developer/collections/list",
+      { params: { page, page_size: pageSize } },
+    );
+  }
+
+  /**
+   * List videos in a collection (paginated, sortable).
+   *
+   * GET /backend-service/v1/developer/collections/{collection_id}/videos
+   */
+  async listVideos(collectionId, {
+    page = 1,
+    pageSize = 10,
+    sortBy = "created_at",
+    sortOrder = "desc",
+  } = {}) {
+    return await this._client._request(
+      "GET",
+      `/backend-service/v1/developer/collections/${collectionId}/videos`,
+      {
+        params: {
+          page,
+          page_size: pageSize,
+          sort_by: sortBy,
+          sort_order: sortOrder,
+        },
+      },
+    );
+  }
+
+  /**
+   * Add a fully-processed video to a collection. Throws `ConflictError`
+   * (409) if the video is already in the collection.
+   *
+   * POST /backend-service/v1/developer/collections/{collection_id}/videos
+   */
+  async addVideo(collectionId, videoId) {
+    return await this._client._request(
+      "POST",
+      `/backend-service/v1/developer/collections/${collectionId}/videos`,
+      { data: { video_id: videoId.toString() } },
+    );
+  }
+
+  /**
+   * Remove a video from a collection. Removes only the link — the video
+   * record stays intact.
+   *
+   * DELETE /backend-service/v1/developer/collections/{collection_id}/videos/{video_id}
+   */
+  async removeVideo(collectionId, videoId) {
+    return await this._client._request(
+      "DELETE",
+      `/backend-service/v1/developer/collections/${collectionId}/videos/${videoId}`,
+    );
+  }
+}

package/src/resources/embeddings.js

@@ -0,0 +1,38 @@
+export class EmbeddingsResource {
+  constructor(client) {
+    this._client = client;
+  }
+
+  /**
+   * Return stored per-segment embedding vectors for a video.
+   *
+   * Reads directly from the vector store; no recompute. Costs 1 credit per
+   * call (refunded on 404/408/502/5xx). Throws `ConflictError` (409) if the
+   * video's search-process pipeline hasn't finished yet — wait and retry
+   * once `search_process_status === "done"`.
+   *
+   * GET /chat-service/v1/developer/embeddings/video/{video_id}
+   */
+  async video(videoId) {
+    return await this._client._request(
+      "GET",
+      `/chat-service/v1/developer/embeddings/video/${videoId}`,
+    );
+  }
+
+  /**
+   * Embed an arbitrary text string with the active backend.
+   *
+   * `text` must be 1–4096 characters. Costs 1 credit per call (refunded on
+   * 408/502/5xx).
+   *
+   * POST /chat-service/v1/developer/embeddings/text
+   */
+  async text(text) {
+    return await this._client._request(
+      "POST",
+      "/chat-service/v1/developer/embeddings/text",
+      { data: { text } },
+    );
+  }
+}

package/src/resources/search.js

@@ -0,0 +1,50 @@
+export class SearchResource {
+  constructor(client) {
+    this._client = client;
+  }
+
+  /**
+   * Vector-search across the developer's videos.
+   *
+   * Provide at least one of `videoIds` or `collectionId`. Costs 1 credit per
+   * call (refunded on failure). Returns the array of hits from `results`.
+   *
+   * POST /chat-service/v1/developer/search
+   */
+  async search(query, { videoIds = null, collectionId = null, topK = 5 } = {}) {
+    const payload = {
+      query,
+      video_ids: (videoIds || []).map((v) => v.toString()),
+      top_k: topK,
+    };
+    if (collectionId != null) payload.collection_id = collectionId.toString();
+
+    const data = await this._client._request(
+      "POST",
+      "/chat-service/v1/developer/search",
+      { data: payload },
+    );
+    return data.results;
+  }
+
+  /**
+   * Return a 2-D UMAP projection of every segment across the selection.
+   *
+   * Provide at least one of `videoIds` or `collectionId`. Free; no credit
+   * deduction.
+   *
+   * POST /chat-service/v1/developer/visualize
+   */
+  async visualize({ videoIds = null, collectionId = null } = {}) {
+    const payload = {
+      video_ids: (videoIds || []).map((v) => v.toString()),
+    };
+    if (collectionId != null) payload.collection_id = collectionId.toString();
+
+    return await this._client._request(
+      "POST",
+      "/chat-service/v1/developer/visualize",
+      { data: payload },
+    );
+  }
+}

package/src/resources/uploads.js

@@ -0,0 +1,316 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import axios from 'axios';
+import {
+  BadRequestError,
+  InsufficientCreditsError,
+  YOUTUBE_FATAL_CODES,
+  YouTubeImportError,
+} from '../exceptions.js';
+import { probeDuration } from '../duration.js';
+
+const DEFAULT_CHUNK_SIZE = 10 * 1024 * 1024;
+const S3_PART_PUT_TIMEOUT = 300000;
+
+// Minimal extension → MIME map for common video types. Falls back to
+// application/octet-stream when unknown.
+const MIME_BY_EXT = {
+  '.mp4': 'video/mp4',
+  '.m4v': 'video/x-m4v',
+  '.mov': 'video/quicktime',
+  '.mkv': 'video/x-matroska',
+  '.webm': 'video/webm',
+  '.avi': 'video/x-msvideo',
+  '.wmv': 'video/x-ms-wmv',
+  '.flv': 'video/x-flv',
+  '.ogv': 'video/ogg',
+  '.3gp': 'video/3gpp',
+};
+
+function guessContentType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return MIME_BY_EXT[ext] || 'application/octet-stream';
+}
+
+export class UploadsResource {
+  constructor(client) {
+    this._client = client;
+  }
+
+  // --- Multipart ---------------------------------------------------------
+
+  /**
+   * Start an S3 multipart upload.
+   *
+   * `videoDurationSeconds` (required, > 0) is the client-measured video
+   * length. The server rejects values that exceed `MAX_VIDEO_DURATION_SECONDS`
+   * with a 400 `BadRequestError`.
+   *
+   * POST /backend-service/v1/developer/uploads/multipart/initiate
+   */
+  async initiateMultipart(filename, contentType, videoDurationSeconds) {
+    return await this._client._request(
+      "POST",
+      "/backend-service/v1/developer/uploads/multipart/initiate",
+      {
+        data: {
+          filename,
+          content_type: contentType,
+          video_duration_seconds: videoDurationSeconds,
+        },
+      },
+    );
+  }
+
+  /**
+   * Get a pre-signed URL for one chunk. `partNumber` must be 1-10000.
+   *
+   * POST /backend-service/v1/developer/uploads/multipart/part-url
+   */
+  async getPartUrl(s3ObjectName, uploadId, partNumber) {
+    return await this._client._request(
+      "POST",
+      "/backend-service/v1/developer/uploads/multipart/part-url",
+      {
+        data: {
+          s3_object_name: s3ObjectName,
+          upload_id: uploadId,
+          part_number: partNumber,
+        },
+      },
+    );
+  }
+
+  /**
+   * List parts already uploaded for an in-progress multipart upload.
+   *
+   * POST /backend-service/v1/developer/uploads/multipart/list-parts
+   */
+  async listParts(s3ObjectName, uploadId) {
+    const data = await this._client._request(
+      "POST",
+      "/backend-service/v1/developer/uploads/multipart/list-parts",
+      { data: { s3_object_name: s3ObjectName, upload_id: uploadId } },
+    );
+    return data.parts;
+  }
+
+  /**
+   * Finalize a multipart upload. `parts` is an array of
+   * `{ part_number, etag }`.
+   *
+   * Storage credits (1 per 25 MiB rounded up) are deducted here based on the
+   * actual S3 object size. Throws `InsufficientCreditsError` (402) when the
+   * user can't cover the charge — in that case the server has already
+   * aborted the S3 upload, so do not call `abortMultipart`.
+   *
+   * POST /backend-service/v1/developer/uploads/multipart/complete
+   */
+  async completeMultipart(s3ObjectName, uploadId, parts) {
+    return await this._client._request(
+      "POST",
+      "/backend-service/v1/developer/uploads/multipart/complete",
+      {
+        data: {
+          s3_object_name: s3ObjectName,
+          upload_id: uploadId,
+          parts,
+        },
+      },
+    );
+  }
+
+  /**
+   * Abort an in-progress multipart upload.
+   *
+   * POST /backend-service/v1/developer/uploads/multipart/abort
+   */
+  async abortMultipart(s3ObjectName, uploadId) {
+    return await this._client._request(
+      "POST",
+      "/backend-service/v1/developer/uploads/multipart/abort",
+      { data: { s3_object_name: s3ObjectName, upload_id: uploadId } },
+    );
+  }
+
+  // --- Finalization -----------------------------------------------------
+
+  /**
+   * Create the video record and enqueue processing after multipart completes.
+   *
+   * POST /backend-service/v1/developer/uploads/preprocess
+   */
+  async preprocess(s3ObjectName, videoId, name, useDynamicHls = false) {
+    return await this._client._request(
+      "POST",
+      "/backend-service/v1/developer/uploads/preprocess",
+      {
+        data: {
+          s3_object_name: s3ObjectName,
+          video_id: videoId.toString(),
+          name,
+          use_dynamic_hls: useDynamicHls,
+        },
+      },
+    );
+  }
+
+  /**
+   * Upload a small file (<= 100 MB) in a single request. Throws
+   * `PayloadTooLargeError` on 413 — use the multipart flow for larger files.
+   *
+   * `videoDurationSeconds` (> 0) is the client-measured video length. When
+   * omitted it's auto-detected from the file via `probeDuration` (MP4/MOV
+   * header, or ffprobe if installed). The server rejects values that exceed
+   * `MAX_VIDEO_DURATION_SECONDS` with a 400 `BadRequestError`.
+   *
+   * Storage credits (1 per 25 MiB rounded up) are deducted server-side after
+   * the file body is received but before S3 upload begins. Throws
+   * `InsufficientCreditsError` (402) when the user can't cover the charge.
+   *
+   * POST /backend-service/v1/developer/uploads/direct
+   */
+  async direct(filePath, { name, videoDurationSeconds, useDynamicHls = false, contentType = null, filename = null } = {}) {
+    if (videoDurationSeconds == null) videoDurationSeconds = probeDuration(filePath);
+    const resolvedName = filename || path.basename(filePath);
+    const resolvedType = contentType || guessContentType(filePath);
+    const fileBuffer = fs.readFileSync(filePath);
+
+    const form = new FormData();
+    const blob = new Blob([fileBuffer], { type: resolvedType });
+    form.append('file', blob, resolvedName);
+    form.append('name', name);
+    form.append('video_duration_seconds', String(videoDurationSeconds));
+    form.append('use_dynamic_hls', useDynamicHls ? 'true' : 'false');
+
+    return await this._client._request(
+      "POST",
+      "/backend-service/v1/developer/uploads/direct",
+      { data: form },
+    );
+  }
+
+  /**
+   * Import a YouTube video.
+   *
+   * Throws `YouTubeImportError` (a subclass of `BadRequestError`) on 400
+   * responses carrying a known YouTube error code — inspect `.code`
+   * (e.g. `"YOUTUBE_VIDEO_PRIVATE"`) to branch. The full set of known
+   * codes is exported as `YOUTUBE_FATAL_CODES`.
+   *
+   * POST /backend-service/v1/developer/uploads/youtube
+   */
+  async importYoutube(url, name = null) {
+    const payload = { url };
+    if (name != null) payload.name = name;
+    try {
+      return await this._client._request(
+        "POST",
+        "/backend-service/v1/developer/uploads/youtube",
+        { data: payload },
+      );
+    } catch (e) {
+      if (e instanceof BadRequestError) {
+        const body = e.responseBody && typeof e.responseBody === 'object' ? e.responseBody : {};
+        const code = body.message || body.detail;
+        if (code && YOUTUBE_FATAL_CODES.has(code)) {
+          throw new YouTubeImportError(e.message, e.statusCode, e.responseBody, code);
+        }
+      }
+      throw e;
+    }
+  }
+
+  // --- Status -----------------------------------------------------------
+
+  /**
+   * Poll per-pipeline processing status for a video. Use `derivedUploadStatus`
+   * from `models.js` to collapse the three pipelines into a single state.
+   *
+   * GET /backend-service/v1/developer/uploads/status/{video_id}
+   */
+  async getStatus(videoId) {
+    return await this._client._request(
+      "GET",
+      `/backend-service/v1/developer/uploads/status/${videoId}`,
+    );
+  }
+
+  // --- high-level helper ------------------------------------------------
+
+  /**
+   * Upload a local file via the multipart flow and kick off processing.
+   *
+   * `videoDurationSeconds` (> 0) is the client-measured video length, forwarded
+   * to `initiateMultipart`. When omitted it's auto-detected from `filePath` via
+   * `probeDuration`. The server rejects values that exceed
+   * `MAX_VIDEO_DURATION_SECONDS` with a 400 `BadRequestError` before any chunk
+   * is uploaded.
+   *
+   * Sequential chunks, no retry. On any failure before `completeMultipart`
+   * succeeds, calls `abortMultipart` so the partial S3 object isn't left
+   * behind. Preprocess failures propagate without aborting (the upload is
+   * already durable at that point — retry `preprocess` separately if you
+   * stash `s3_object_name`).
+   *
+   * Charges 1 storage credit per 25 MiB (rounded up) at `completeMultipart`.
+   * On `InsufficientCreditsError` from that step the server has already
+   * aborted the S3 upload, so this helper skips the redundant client-side
+   * abort.
+   */
+  async uploadFile(filePath, {
+    name,
+    videoDurationSeconds,
+    useDynamicHls = false,
+    chunkSize = DEFAULT_CHUNK_SIZE,
+    contentType = null,
+    onProgress = null,
+  } = {}) {
+    if (videoDurationSeconds == null) videoDurationSeconds = probeDuration(filePath);
+    const stats = fs.statSync(filePath);
+    const totalBytes = stats.size;
+    const resolvedType = contentType || guessContentType(filePath);
+
+    const init = await this.initiateMultipart(path.basename(filePath), resolvedType, videoDurationSeconds);
+
+    const parts = [];
+    let fd = null;
+    try {
+      fd = fs.openSync(filePath, 'r');
+      let uploaded = 0;
+      let partNumber = 1;
+      const buffer = Buffer.alloc(chunkSize);
+      while (uploaded < totalBytes) {
+        const bytesRead = fs.readSync(fd, buffer, 0, chunkSize, uploaded);
+        if (bytesRead === 0) break;
+        const chunk = bytesRead === chunkSize ? buffer : buffer.subarray(0, bytesRead);
+        const presigned = await this.getPartUrl(init.s3_object_name, init.upload_id, partNumber);
+        const response = await axios.put(presigned.url, chunk, { timeout: S3_PART_PUT_TIMEOUT });
+        parts.push({
+          part_number: partNumber,
+          etag: response.headers.etag.replace(/"/g, ''),
+        });
+        uploaded += bytesRead;
+        if (onProgress) onProgress(uploaded, totalBytes);
+        partNumber++;
+      }
+
+      await this.completeMultipart(init.s3_object_name, init.upload_id, parts);
+    } catch (error) {
+      if (!(error instanceof InsufficientCreditsError)) {
+        try {
+          await this.abortMultipart(init.s3_object_name, init.upload_id);
+        } catch {
+          // swallow — best-effort cleanup
+        }
+      }
+      throw error;
+    } finally {
+      if (fd != null) {
+        try { fs.closeSync(fd); } catch { /* ignore */ }
+      }
+    }
+
+    return await this.preprocess(init.s3_object_name, init.video_id, name, useDynamicHls);
+  }
+}

package/src/resources/videos.js

@@ -0,0 +1,100 @@
+export class VideosResource {
+  constructor(client) {
+    this._client = client;
+  }
+
+  // --- list / get / delete ---------------------------------------------
+
+  /**
+   * List videos owned by the calling developer user.
+   *
+   * `status` is one of `uploaded`, `analysed`, `search_processed`,
+   * `processed`. `processed` requires both pipelines done; the middle two
+   * filter on a single pipeline.
+   *
+   * GET /backend-service/v1/developer/videos/list
+   */
+  async list({
+    status,
+    startTime,
+    endTime,
+    notInCollection,
+    skip,
+    limit,
+    sortBy,
+    sortOrder,
+  } = {}) {
+    const params = {
+      status,
+      start_time: startTime instanceof Date ? startTime.toISOString() : startTime,
+      end_time: endTime instanceof Date ? endTime.toISOString() : endTime,
+      not_in_collection: notInCollection,
+      skip,
+      limit,
+      sort_by: sortBy,
+      sort_order: sortOrder,
+    };
+    const cleanParams = Object.fromEntries(
+      Object.entries(params).filter(([, v]) => v != null),
+    );
+    return await this._client._request(
+      "GET",
+      "/backend-service/v1/developer/videos/list",
+      { params: cleanParams },
+    );
+  }
+
+  /**
+   * Fetch a single video with metadata.
+   *
+   * GET /backend-service/v1/developer/videos/get-video-details
+   */
+  async get(videoId) {
+    return await this._client._request(
+      "GET",
+      "/backend-service/v1/developer/videos/get-video-details",
+      { params: { video_id: videoId.toString() } },
+    );
+  }
+
+  /**
+   * Permanently delete a video and all derived assets.
+   *
+   * DELETE /backend-service/v1/developer/videos/delete
+   */
+  async delete(videoId) {
+    return await this._client._request(
+      "DELETE",
+      "/backend-service/v1/developer/videos/delete",
+      { params: { video_id: videoId.toString() } },
+    );
+  }
+
+  // --- Pipelines: search-process / analyse ----------------------------
+
+  /** POST /backend-service/v1/developer/videos/search-process/initiate */
+  async initiateSearchProcess(videoId) { return await this._initiate("search-process", videoId); }
+  /** GET /backend-service/v1/developer/videos/search-process/status/{video_id} */
+  async getSearchProcessStatus(videoId) { return await this._pipelineStatus("search-process", videoId); }
+  /** POST /backend-service/v1/developer/videos/analyse/initiate */
+  async initiateAnalyse(videoId) { return await this._initiate("analyse", videoId); }
+  /** GET /backend-service/v1/developer/videos/analyse/status/{video_id} */
+  async getAnalyseStatus(videoId) { return await this._pipelineStatus("analyse", videoId); }
+
+  // --- internals --------------------------------------------------------
+
+  async _initiate(pipeline, videoId) {
+    return await this._client._request(
+      "POST",
+      `/backend-service/v1/developer/videos/${pipeline}/initiate`,
+      { data: { video_id: videoId.toString() } },
+    );
+  }
+
+  async _pipelineStatus(pipeline, videoId) {
+    return await this._client._request(
+      "GET",
+      `/backend-service/v1/developer/videos/${pipeline}/status/${videoId}`,
+    );
+  }
+}