TypeScript SDK

Complete reference for @blobrouter/sdk — upload, get, delete, retries, and errors.

BlobRouter v0.1 · Last updated: August 2026 · Architecture version: 2.0

Server-side SDK for Node.js 18+. Not for browser use (API keys must stay on the server).

Install

npm install @blobrouter/sdk

Constructor

import { BlobRouter } from "@blobrouter/sdk";

const storage = new BlobRouter({
  apiKey: process.env.BLOBROUTER_API_KEY!, // required — br_live_… or br_test_…
  baseUrl: "https://api.blobrouter.com", // optional
  maxRetries: 3, // optional — control-plane retries (default 3)
});

Option	Type	Default	Description
apiKey	string	—	API key from the dashboard
baseUrl	string	https://api.blobrouter.com	API origin
maxRetries	number	3	Retries for BlobRouter API calls

upload(file, options)

Uploads via init → direct PUT to provider → complete. BlobRouter never sees file bytes.

import { readFileSync } from "fs";

const file = readFileSync("./report.pdf");

const result = await storage.upload(file, {
  fileName: "report.pdf",
  contentType: "application/pdf",
  fileSizeBytes: file.length,
  priority: "cold", // "hot" | "cold" | "archive"
  region: "us", // optional — e.g. "eu" for residency warnings
});

console.log(result.fileId);
console.log(result.provider);
console.log(result.savedVsAws);
console.log(result.url);
console.log(result.routingWarning); // optional

Parameters

Field	Type	Required	Notes
file	Buffer | Readable	yes	File body
fileName	string	yes	Object key / display name
contentType	string	yes	MIME type
fileSizeBytes	number	yes	Exact size in bytes
priority	"hot" | "cold" | "archive"	no	Default cold on API if omitted
region	routing region	no	e.g. "eu"

Returns UploadResult

Field	Type
fileId	string
url	string — BlobRouter file URL
provider	"aws-s3" | "cloudflare-r2" | "backblaze-b2"
savedVsAws	number — estimated USD savings vs S3
routingWarning	string | undefined

Retry behavior

• Retries control-plane calls (/v1/upload/init, /v1/upload/complete, get, delete) on network failures and 5xx / 408 / 429 with exponential backoff
• Does not retry other 4xx responses
• Does not retry the provider presigned PUT

get(fileId)

Returns a time-limited presigned download URL.

const { url, expiresAt } = await storage.get(fileId);
console.log(url, expiresAt);

delete(fileId)

Deletes the object on the provider and marks the file deleted in BlobRouter.

const { success } = await storage.delete(fileId);

Errors

import { BlobRouter, BlobRouterError } from "@blobrouter/sdk";

try {
  await storage.upload(file, options);
} catch (err) {
  if (err instanceof BlobRouterError) {
    console.error(err.message, err.code, err.statusCode);
  }
  throw err;
}

Common code values:

Code	Meaning
unauthorized	Invalid API key
plan_limit	Plan / quota gate
file_too_large	Exceeds max size (5GB)
no_providers / related	No providers configured
rate_limit_exceeded	Too many requests
network_error	Transport failure talking to API
upload_to_provider_failed	Provider PUT failed
api_error	Other API error

Local API

const storage = new BlobRouter({
  apiKey: "br_test_…",
  baseUrl: "http://127.0.0.1:8787",
});