@imperial-host/sdk

Official TypeScript SDK for the Imperial media API.

@imperial-host/sdk gives you a small, typed client for uploading files, listing media, managing folders, changing privacy, and working with private access links from Node.js or modern browser environments.

Why use it

• Typed request and response models
• One client for both upload keys and full API keys
• Works in Node.js 18+ and browser runtimes with fetch, FormData, and Blob
• Built-in error classes for common API failures
• Rate-limit and usage metadata available after requests

Installation

npm install @imperial-host/sdk

pnpm add @imperial-host/sdk

yarn add @imperial-host/sdk

bun add @imperial-host/sdk

Quick start

import { ImperialClient } from "@imperial-host/sdk";
import { readFile } from "node:fs/promises";

const client = new ImperialClient({
  apiKey: process.env.IMPERIAL_API_KEY!,
});

const file = await readFile("./cat.png");

const upload = await client.upload({
  file,
  filename: "cat.png",
  mimeType: "image/png",
});

console.log(upload.url);

Authentication

The SDK supports two key types:

• imperial_live_* Full API keys for listing, deleting, folder management, privacy changes, and private access links.
• imperial_upload_* Upload-only keys. These can upload files, but the SDK will intentionally block management methods like list(), delete(), setPrivacy(), and folder operations.

Supported operations

Uploads

await client.upload({
  file: new Uint8Array([1, 2, 3]),
  filename: "tiny.bin",
  mimeType: "application/octet-stream",
});

await client.uploadBatch([
  { file: fileA, filename: "a.png", mimeType: "image/png" },
  { file: fileB, filename: "b.png", mimeType: "image/png" },
]);

Accepted upload payloads:

• Blob
• File
• ArrayBuffer
• Uint8Array
• Node.js Buffer values also work because they are Uint8Array

Listing and reading media

const media = await client.list({
  page: 1,
  limit: 50,
  q: "invoice",
  mimePrefix: "image/",
  tags: ["receipts"],
});

const item = await client.get(media.images[0]._id);
console.log(item.url);

Deleting and bulk actions

await client.delete("67d8f9a1b2c3d4e5f6789012");

await client.deleteBatch([
  "67d8f9a1b2c3d4e5f6789012",
  "67d8f9a1b2c3d4e5f6789013",
]);

await client.bulkTrash(["67d8f9a1b2c3d4e5f6789012"]);
await client.bulkRestore(["67d8f9a1b2c3d4e5f6789012"]);

await client.bulkMetadata({
  ids: ["67d8f9a1b2c3d4e5f6789012"],
  tags: ["reference", "archive"],
  mode: "replace",
});

Privacy and private access links

await client.setPrivacy("67d8f9a1b2c3d4e5f6789012", "private");

const link = await client.getAccessUrl("67d8f9a1b2c3d4e5f6789012");
console.log(link.accessUrl, link.expiresAt);

Metadata helpers

await client.moveUpload("67d8f9a1b2c3d4e5f6789012", "folder_id");
await client.addTags("67d8f9a1b2c3d4e5f6789012", ["client", "invoice"]);
await client.removeTags("67d8f9a1b2c3d4e5f6789012", ["invoice"]);
await client.setExpiry("67d8f9a1b2c3d4e5f6789012", 7);
await client.clearExpiry("67d8f9a1b2c3d4e5f6789012");

Folders

const folders = await client.listFolders();

const folder = await client.createFolder({
  name: "Receipts",
});

await client.updateFolder(folder.id, {
  name: "Archived Receipts",
});

await client.pinFolder(folder.id);
const pinned = await client.listPinnedFolders();
await client.unpinFolder(folder.id);

Browser example

import { ImperialClient } from "@imperial-host/sdk";

const client = new ImperialClient({
  apiKey: "imperial_upload_xxxxxxxxxxxxx",
});

const input = document.querySelector<HTMLInputElement>("#file-input");
const file = input?.files?.[0];

if (file) {
  const result = await client.upload({
    file,
    filename: file.name,
    mimeType: file.type,
  });

  console.log(result.url);
}

Error handling

The SDK throws typed errors for common failure modes:

• AuthenticationError
• PermissionError
• NotFoundError
• StorageLimitError
• UnsupportedMediaError
• RateLimitError
• ValidationError
• ServerError
• NetworkError

import {
  ImperialClient,
  AuthenticationError,
  PermissionError,
  RateLimitError,
} from "@imperial-host/sdk";

try {
  await client.list();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Your API key is invalid.");
  } else if (error instanceof PermissionError) {
    console.error("This key does not have permission for that action.");
  } else if (error instanceof RateLimitError) {
    console.error("Slow down and retry later.", error.retryAfter);
  } else {
    console.error(error);
  }
}

Rate limits and usage

After a request, you can inspect the latest rate-limit and usage headers:

await client.upload({
  file,
  filename: "cat.png",
  mimeType: "image/png",
});

console.log(client.getRateLimitInfo());
console.log(client.getUsageInfo());

API surface

Main exports:

• ImperialClient
• ImperialError and specialized error classes
• Type exports including ImperialConfig, UploadOptions, UploadResult, MediaItem, ListMediaResult, FolderItem, RateLimitInfo, and UsageInfo

Development

From packages/sdk:

npm run build
npm run test

Repository

This package is maintained in the Imperial monorepo by @spoodyz.