Backend Client API

Complete API reference for the backend Zapdos client. Only available in Node.js environments.

Client Creation

import { createClient } from "zapdos-js";

const client = createClient({
  apiKey: "your-api-key", // Required
  baseUrl: "https://api.zapdoslabs.com", // Optional, defaults to this
  verbose: false, // Optional, enables debug logging
});

File Upload Methods

upload(filePath, callbacks?)

Upload a single file:

const result = await client.upload("./video.mp4", {
  onProgress: ({ file_index, value }) => {},
  onCompleted: ({ object_id, file_index }) => {},
  // ... other callbacks
});

uploadBatch(filePaths, callbacks?)

Upload multiple files:

const results = await client.uploadBatch(
  ["./video1.mp4", "./video2.mkv"],
  callbacks
);

File Download Methods

download(objectId, destination)

Download a single file:

const result = await client.download("object-id", "./video.mp4");
// Returns: { data: { file: "./video.mp4" }, error?: undefined }

downloadBatch(objectIds, directory)

Download multiple files:

const result = await client.downloadBatch(
  ["object-id-1", "object-id-2"],
  "./downloads/"
);
// Returns: { data: { files: ["./downloads/object-id-1", ...] }, error?: undefined }

getDownloadUrl(objectId)

Get signed download URL for a single file:

const result = await client.getDownloadUrl("object-id");
// Returns: { data: { url: "signed-url", expires_at: "timestamp" }, error?: undefined }

getDownloadUrls(objectIds)

Get signed download URLs for multiple files:

const result = await client.getDownloadUrls(["id1", "id2"]);
// Returns: { data: { urls: { "id1": "url1", "id2": "url2" }, expires_at: "timestamp" }, error?: undefined }

Upload URL Methods

getUploadUrl()

Get a single signed upload URL:

const result = await client.getUploadUrl();
// Returns: { data: "signed-url", error?: undefined }

getUploadUrls(quantity)

Get multiple signed upload URLs:

const result = await client.getUploadUrls(3);
// Returns: { data: ["url1", "url2", "url3"], error?: undefined }

Query Methods

from(resource)

Start a query builder:

const query = client.from("object_storage");
// Returns: UnselectedQueryBuilder

Convenience Methods

Pre-configured queries for common use cases:

// Get all videos
const videos = client.videos(); // Returns: QueryBuilder<VideoObject>

// Get all images
const images = client.images(); // Returns: QueryBuilder<ObjectStorageItem>

// Get all jobs
const jobs = client.jobs(); // Returns: QueryBuilder<JobItem>

// Get scenes for a video
const scenes = client.scenes("video-id"); // Returns: QueryBuilder<ObjectStorageItem>

Query Builder Methods

select(...columns)

Select specific columns:

.select("id", "metadata", "created_at")
.select() // Select all columns

where(field, operator, value)

Add filter conditions:

.where("metadata->>'content_type'", "=", "video/mp4")
.where("metadata->>'size'", ">", "1000000")
.where("status", "=", "completed")

limit(count)

Limit results:

.limit(10)

sort(direction)

Sort results:

.sort("desc") // or "asc"

cursor(cursor)

Pagination cursor:

.cursor("pagination-cursor-string")

fetch()

Execute query:

const result = await query.fetch();
// Returns: { data: T[], error?: undefined } | { error: { message: string }, data?: undefined }

single()

Get exactly one result:

const result = await query.single();
// Returns: { data: T, error?: undefined } | { error: { message: string }, data?: undefined }

Search Methods

search(text, options?)

Search for content:

const result = await client.search("cats playing", {
  limit: 10, // Optional
  object_ids: ["id1", "id2"], // Optional: search specific videos
  video_id: "single-video-id", // Optional: search single video
});
// Returns: { data: { items: SearchResultItem[] }, error?: undefined }

WebSocket Methods

listen(options)

Connect to WebSocket:

const ws = client.listen({
  onOpen: (event) => {},
  onMessage: (data) => {},
  onError: (error) => {},
  onClose: (event) => {},
});
// Returns: WebSocket instance

Error Handling

All methods return result objects with consistent error handling:

const result = await client.someMethod();

if (result.error) {
  console.error("Operation failed:", result.error.message);
} else {
  console.log("Success:", result.data);
}