SDK Overview

Install the official TypeScript SDK and start reading and writing data from your frontend or server.

The @urbackend/sdk package is the official TypeScript SDK for urBackend. It wraps the REST API with typed methods for auth, database, and storage — no manual fetch calls required.

Installation

npm install @urbackend/sdk

Initialize the client

Import the default export and call it with your API key:

import urBackend from '@urbackend/sdk';

const client = urBackend({ apiKey: 'YOUR_API_KEY' });

The factory accepts a UrBackendConfig object:

Option	Type	Required	Description
apiKey	string	Yes	Your project’s API key.
baseUrl	string	No	Override the default API base URL.
headers	Record<string, string>	No	Additional headers sent with every request.

Quick example

import urBackend from '@urbackend/sdk';

const client = urBackend({ apiKey: process.env.URBACKEND_API_KEY });

// Log in an existing user
const { accessToken } = await client.auth.login({
  email: '[e-mail]',
  password: 'secret123'
});

// Insert a document with RLS support (passing the user token)
const product = await client.db.insert('products', { name: 'Chair', price: 99 }, accessToken);

// Fetch documents with filtering and sorting
const products = await client.db.getAll('products', { 
  filter: { price_gt: 50 },
  sort: 'price:asc'
});

// In private RLS mode (with pk_live), pass token for reads too
const myPrivateProducts = await client.db.getAll('products', { limit: 20 }, accessToken);

// ⚠️ Server-side only — requires a secret key (sk_live_...).
// Do not use this initialization in browser/client code.
const serverClient = urBackend({ apiKey: process.env.URBACKEND_SECRET_KEY });

await serverClient.mail.send({
  to: '[e-mail]',
  templateName: 'welcome',
  variables: {
    name: 'Alice',
    projectName: 'Acme',
    appUrl: 'https://acme.com'
  }
});

TypeScript generics

Database methods accept a generic type parameter so returned documents are fully typed:

interface Product {
  _id: string;
  name: string;
  price: number;
}

const products = await client.db.getAll<Product>('products');
// products is Product[]

const product = await client.db.getOne<Product>('products', '507f1f77bcf86cd799439011');
// product is Product

Error handling

Import the error classes to handle specific failure modes:

import urBackend, { AuthError, NotFoundError, RateLimitError } from '@urbackend/sdk';

const client = urBackend({ apiKey: process.env.URBACKEND_API_KEY });

try {
  const product = await client.db.getOne('products', id);
} catch (e) {
  if (e instanceof NotFoundError) {
    console.error('Document not found');
  } else if (e instanceof AuthError) {
    console.error('Invalid or missing API key');
  } else if (e instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${e.retryAfter}s`);
  } else {
    throw e;
  }
}

Error class	HTTP status	When thrown
AuthError	401 / 403	Invalid API key or missing token
NotFoundError	404	Document or resource not found
RateLimitError	429	Too many requests (100 req / 15 min per IP)
ValidationError	400	Request body failed validation
StorageError	varies	Storage-specific failures
UrBackendError	varies	Base class for all SDK errors

API key security

Use pk_live_... (publishable key) in frontend/browser code.

• In public-read, reads work without a user token; writes require user token when RLS is enabled.
• In private, both reads and writes require a user token.

Use sk_live_... (secret key) in server-side code only. It allows full CRUD access. Never expose it in client-side bundles or public repositories.

The SDK logs a console warning if it detects you are using a Secret Key (sk_live_...) in a browser context.

Explore the SDK

Auth

Login, logout, profile updates, and social auth.

Database

CRUD operations, query building, and RLS support.

Storage

Upload files and get back a public CDN URL.

Schema

Inspect collection definitions and field types.

Mail

Send transactional emails from your server.