@scarletdb/sdk

Official TypeScript SDK for Scarlet DB - The modern Backend-as-a-Service platform.

Installation

npm install @scarletdb/sdk
# or
pnpm add @scarletdb/sdk
# or
yarn add @scarletdb/sdk
# or
bun add @scarletdb/sdk

Quick Start (Server)

import { createScarlet } from '@scarletdb/sdk'

const scarlet = createScarlet({
  projectId: 'YOUR_PROJECT_ID',
  apiKey: process.env.SCARLET_API_KEY!,
  url: 'https://api.scarletdb.space',
})

const { rows } = await scarlet.from('users').select().limit(10).execute()
console.log(rows)

Quick Start (Browser)

Do not ship secret API keys to the browser. Use a publishable key to mint short-lived tokens, and enable proof-of-possession.

import { createScarlet } from '@scarletdb/sdk'

const scarlet = createScarlet({
  projectId: 'YOUR_PROJECT_ID',
  url: 'https://api.scarletdb.space',
  publishableKey: 'pk_***************',
  enableDpop: true,
})

const { rows } = await scarlet.from('users').select().limit(10).execute()
console.log(rows)

Features

📊 Data API

Fluent query builder for CRUD operations on your database tables.

// Select with filters
const activeUsers = await scarlet
  .from('users')
  .select('id', 'name', 'email')
  .where({ active: true })
  .orderBy('created_at', 'desc')
  .limit(20)
  .execute();

// Insert single row
const { row: newUser } = await scarlet.from('users').insert({
  name: 'Jane',
  email: '[email protected]',
});

// Update with filters
await scarlet.from('users')
  .where({ id: userId })
  .update({ last_login: new Date() });

// Delete with filters
await scarlet.from('users').where({ id: userId }).delete();

📁 Storage

Upload, download, and manage files in cloud storage.

// Upload a file
const uploaded = await scarlet.storage.upload('avatars', file, { randomId: true });
console.log(uploaded.url);

// List files in bucket
const files = await scarlet.storage.list('avatars');

// Delete a file
await scarlet.storage.delete('avatars', 'old-avatar.png');

📧 Email

Send transactional emails with custom domains.

// Send an email
await scarlet.email.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Welcome to MyApp!',
  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
});

// List configured domains
const domains = await scarlet.email.listDomains();

🤖 AI Queries

Natural language to SQL conversion powered by AI.

// Query with natural language
const result = await scarlet.ai.query('Show me all users who signed up last week');

console.log(result.sql);    // Generated SQL
console.log(result.data);   // Query results

Configuration

const scarlet = createScarlet({
  projectId: 'YOUR_PROJECT_ID',
  url: 'https://api.scarletdb.space',
  apiKey: process.env.SCARLET_API_KEY!,
  timeout: 30000,
})

Error Handling

import { createScarlet, ScarletError } from '@scarletdb/sdk';

try {
  const scarlet = createScarlet({
    projectId: 'YOUR_PROJECT_ID',
    apiKey: process.env.SCARLET_API_KEY!,
  })
  await scarlet.from('users').insert({ email: 'invalid' });
} catch (error) {
  if (error instanceof ScarletError) {
    console.error('Scarlet Error:', error.message);
    console.error('Status:', error.status);
    console.error('Code:', error.code);
  }
}

TypeScript Support

Full TypeScript support with generics for type-safe queries:

interface User {
  id: number;
  name: string;
  email: string;
  created_at: Date;
}

// Type-safe queries
const { rows } = await scarlet.from<User>('users').select().execute()
// rows is typed as User[]

License

MIT