npm package: @scarletdb/sdk
Description: Official TypeScript SDK for Scarlet DB - The modern Backend-as-a-Service platform
Author: Scarlet Team
Latest version: 0.2.0

# @scarletdb/sdk

Official TypeScript SDK for [Scarlet DB](https://scarletdb.space) - The modern Backend-as-a-Service platform.

## Installation

```bash
npm install @scarletdb/sdk
# or
pnpm add @scarletdb/sdk
# or
yarn add @scarletdb/sdk
# or
bun add @scarletdb/sdk
```

## Quick Start (Server)

```ts
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.

```ts
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.

```typescript
// 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: 'jane@example.com',
});

// 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.

```typescript
// 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.

```typescript
// Send an email
await scarlet.email.send({
  from: 'hello@myapp.com',
  to: 'user@email.com',
  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.

```typescript
// 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

```typescript
const scarlet = createScarlet({
  projectId: 'YOUR_PROJECT_ID',
  url: 'https://api.scarletdb.space',
  apiKey: process.env.SCARLET_API_KEY!,
  timeout: 30000,
})
```

## Error Handling

```typescript
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:

```typescript
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