@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

import { Scarlet } from '@scarletdb/sdk';

// Initialize with your project API key
const db = new Scarlet({
  apiKey: 'sk_live_your_api_key',
});

// Query data
const users = await db.from('users').select().limit(10);

// Insert data
await db.from('users').insert({
  name: 'John Doe',
  email: '[email protected]',
});

// Update data
await db.from('users').update({ active: true }).where({ id: 1 });

// Delete data
await db.from('users').delete().where({ id: 1 });

Features

📊 Data API

Fluent query builder for CRUD operations on your database tables.

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

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

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

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

📁 Storage

Upload, download, and manage files in cloud storage.

// Upload a file
await db.storage.upload('avatars', file);

// Get public URL
const url = db.storage.getPublicUrl('avatars', 'avatar.png');

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

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

📧 Email

Send transactional emails with custom domains.

// Send an email
await db.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 db.email.listDomains();

🤖 AI Queries

Natural language to SQL conversion powered by AI.

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

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

🔧 Raw SQL

Execute raw SQL queries when you need full control.

// Parameterized query (safe)
const result = await db.sql(
  'SELECT * FROM users WHERE created_at > $1 AND status = $2',
  [lastWeek, 'active']
);

// Access results
console.log(result.rows);
console.log(result.rowCount);

Configuration

const db = new Scarlet({
  // Required: Your project API key
  apiKey: 'sk_live_...',
  
  // Optional: Custom API URL (defaults to production)
  baseUrl: 'https://api.scarletdb.space',
  
  // Optional: Request timeout in ms (default: 30000)
  timeout: 30000,
});

Error Handling

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

try {
  await db.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 users = await db.from<User>('users').select();
// users is typed as User[]

License

MIT