# @vibecodeapp/backend-sdk

> Backend SDK for Vibecode services - Storage and Email APIs

## Installation

```bash
bun add @vibecodeapp/backend-sdk
```

## Quick Start

```typescript
import { createVibecodeSDK } from '@vibecodeapp/backend-sdk';

const vibecode = createVibecodeSDK();
```

## API Reference

### Storage

The storage module handles file operations with Vibecode storage buckets.

#### `storage.upload(file: File | Blob): Promise<StorageFile>`

Upload a file to storage. Maximum file size is 500MB.

```typescript
const file = new File(['content'], 'example.txt', { type: 'text/plain' });
const result = await vibecode.storage.upload(file);
// Returns: { id, url, contentType, sizeBytes, originalFilename, ... }
```

#### `storage.delete(id: string): Promise<void>`

Delete a file by its ID.

```typescript
await vibecode.storage.delete('file-id-here');
```

#### `storage.list(options?: ListFilesOptions): Promise<ListFilesResponse>`

List files with optional filtering and pagination.

```typescript
const { files, totalCount } = await vibecode.storage.list({
  limit: 10,      // 1-100, default: 50
  offset: 0,      // default: 0
  prefix: 'img/', // filter by path prefix
});
```

### Email

The email module sends transactional emails via Vibecode's SMTP service.

#### `email.sendOTP(options: SendOTPOptions): Promise<void>`

Send a one-time password verification email.

```typescript
await vibecode.email.sendOTP({
  to: 'user@example.com',           // required, max 254 chars
  code: 'ABC123',                   // required, 6-12 alphanumeric chars
  fromName: 'MyApp',                // optional, max 50 chars, default: "Notifications"
  lang: 'en',                       // optional, default: 'en'
});
```

#### `email.sendWelcome(options: SendWelcomeOptions): Promise<void>`

Send a welcome email to new users.

```typescript
await vibecode.email.sendWelcome({
  to: 'user@example.com',           // required, max 254 chars
  name: 'John',                     // required, max 50 chars
  appName: 'MyApp',                 // required, max 50 chars
  fromName: 'Welcome Team',         // optional, max 50 chars
  lang: 'en',                       // optional, default: 'en'
});
```

Supported languages: `en`, `es`, `fr`, `de`, `pt`, `zh`, `ja`

## Types

```typescript
interface StorageFile {
  id: string;
  projectId: string;
  environment: string;
  originalFilename: string;
  storagePath: string;
  contentType: string;
  sizeBytes: number;
  url: string;
  created: string;
  updated: string;
}

interface ListFilesOptions {
  limit?: number;   // 1-100, default: 50
  offset?: number;  // default: 0
  prefix?: string;  // filter by path/filename prefix
}

interface ListFilesResponse {
  files: StorageFile[];
  totalCount: number;
  limit: number;
  offset: number;
}

interface SendOTPOptions {
  to: string;
  code: string;
  fromName?: string;
  lang?: EmailLanguage;
}

interface SendWelcomeOptions {
  to: string;
  name: string;
  appName: string;
  fromName?: string;
  lang?: EmailLanguage;
}

type EmailLanguage = 'en' | 'es' | 'fr' | 'de' | 'pt' | 'zh' | 'ja';
```

## Error Handling

The SDK exports specific error classes:

```typescript
import {
  VibecodeError,    // Base error class
  StorageError,     // Storage operation failures
  EmailError,       // Email operation failures
  RateLimitError,   // Daily email limit exceeded (100/day)
} from '@vibecodeapp/backend-sdk';
```

All errors extend `VibecodeError` and include a `statusCode` property.

```typescript
try {
  await vibecode.storage.upload(file);
} catch (error) {
  if (error instanceof StorageError) {
    console.error(`Storage error (${error.statusCode}): ${error.message}`);
  }
}

try {
  await vibecode.email.sendOTP({ to: 'user@example.com', code: '123456' });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Handle rate limit - 100 emails/day limit reached
  } else if (error instanceof EmailError) {
    // Handle other email errors
  }
}
```

## Direct Module Access

You can also import modules directly:

```typescript
import { Storage, Email } from '@vibecodeapp/backend-sdk';

const storage = new Storage();
const email = new Email();
```

## Backend Services

- Storage API: https://storage.vibecodeapp.com
- Email API: https://smtp.vibecodeapp.com

## Notes

- Storage uploads are limited to 500MB per file
- Email sending is rate-limited to 100 emails per day
- The `to` field in emails supports both `email@example.com` and `Name <email@example.com>` formats