@scarletdb/sdk 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# @scarlet/sdk
+
+Official TypeScript SDK for [Scarlet DB](https://scarletdb.space) - The modern Backend-as-a-Service platform.
+
+## Installation
+
+```bash
+npm install @scarlet/sdk
+# or
+pnpm add @scarlet/sdk
+# or
+yarn add @scarlet/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Scarlet } from '@scarlet/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: 'john@example.com',
+});
+
+// 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.
+
+```typescript
+// 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: 'jane@example.com',
+}).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.
+
+```typescript
+// 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.
+
+```typescript
+// Send an email
+await db.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 db.email.listDomains();
+```
+
+### 🤖 AI Queries
+
+Natural language to SQL conversion powered by AI.
+
+```typescript
+// 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.
+
+```typescript
+// 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
+
+```typescript
+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
+
+```typescript
+import { Scarlet, ScarletError } from '@scarlet/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:
+
+```typescript
+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

package/dist/index.d.mts

@@ -0,0 +1,459 @@
+/**
+ * Scarlet SDK - Type Definitions
+ */
+interface ScarletConfig {
+    /** Project API key (required) */
+    apiKey: string;
+    /** Base URL for the API (defaults to production) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'in' | 'nin' | 'is' | 'isnot';
+type FilterValue = string | number | boolean | null | (string | number)[];
+interface WhereCondition {
+    [column: string]: FilterValue | {
+        [op in FilterOperator]?: FilterValue;
+    };
+}
+type OrderDirection = 'asc' | 'desc';
+interface QueryResult<T = Record<string, unknown>> {
+    rows: T[];
+    total?: number;
+    limit?: number;
+    offset?: number;
+    hasMore?: boolean;
+}
+interface InsertResult<T = Record<string, unknown>> {
+    success: boolean;
+    row?: T;
+    rows?: T[];
+}
+interface UpdateResult {
+    success: boolean;
+    count: number;
+}
+interface DeleteResult {
+    success: boolean;
+    count: number;
+}
+interface StorageBucket {
+    id: string;
+    name: string;
+    publicAccess: boolean;
+    createdAt: string;
+}
+interface StorageFile {
+    id: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    url?: string;
+    createdAt: string;
+}
+interface UploadOptions {
+    /** Custom file name (defaults to original) */
+    fileName?: string;
+    /** Content type override */
+    contentType?: string;
+    /** Make file publicly accessible */
+    public?: boolean;
+}
+interface ListFilesOptions {
+    /** Maximum files to return */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+    /** Filter by prefix/folder */
+    prefix?: string;
+}
+interface SendEmailOptions {
+    /** Sender email address */
+    from: string;
+    /** Recipient email address */
+    to: string;
+    /** Email subject */
+    subject: string;
+    /** HTML content */
+    html: string;
+    /** Plain text content (optional) */
+    text?: string;
+    /** Reply-to address */
+    replyTo?: string;
+}
+interface EmailDomain {
+    id: string;
+    domain: string;
+    status: 'pending' | 'verified' | 'failed';
+    dkimSelector: string;
+    dkimPublicKey: string;
+    verifiedAt?: string;
+}
+interface EmailLog {
+    id: string;
+    from: string;
+    to: string;
+    subject: string;
+    status: 'sent' | 'failed' | 'bounced';
+    sentAt: string;
+    error?: string;
+}
+interface AIQueryResult {
+    /** Generated SQL query */
+    sql: string;
+    /** Natural language explanation */
+    explanation: string;
+    /** Query execution results */
+    result: {
+        rows: Record<string, unknown>[];
+        fields: {
+            name: string;
+            dataType: number;
+        }[];
+    };
+    /** Error if query failed */
+    error?: string;
+    details?: string;
+}
+interface SQLResult<T = Record<string, unknown>> {
+    rows: T[];
+    rowCount: number;
+    fields: {
+        name: string;
+        dataType: number;
+    }[];
+    command?: string;
+    executionTime?: number;
+}
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    params?: Record<string, string | number | boolean | undefined>;
+}
+interface APIResponse<T> {
+    data: T;
+    status: number;
+    headers: Headers;
+}
+
+/**
+ * Scarlet SDK - HTTP Client
+ * Fetch-based HTTP client with error handling
+ */
+
+interface ClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    request<T>(options: RequestOptions): Promise<APIResponse<T>>;
+    private handleErrorResponse;
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Upload file using multipart/form-data
+     */
+    upload<T>(path: string, file: Blob, fileName?: string): Promise<T>;
+}
+
+/**
+ * Scarlet SDK - Data API Module
+ * Fluent query builder for CRUD operations
+ */
+
+declare class QueryBuilder<T = Record<string, unknown>> {
+    private readonly client;
+    private readonly table;
+    private _columns;
+    private _where;
+    private _orderBy?;
+    private _limit?;
+    private _offset?;
+    constructor(client: HttpClient, table: string);
+    /**
+     * Select specific columns (default: all)
+     */
+    select(...columns: (keyof T & string)[]): this;
+    /**
+     * Add where conditions
+     */
+    where(conditions: Partial<{
+        [K in keyof T]: T[K] | WhereCondition[string];
+    }>): this;
+    /**
+     * Add equality condition
+     */
+    eq<K extends keyof T & string>(column: K, value: T[K]): this;
+    /**
+     * Order results
+     */
+    orderBy(column: keyof T & string, direction?: OrderDirection): this;
+    /**
+     * Limit results
+     */
+    limit(count: number): this;
+    /**
+     * Offset results (for pagination)
+     */
+    offset(count: number): this;
+    /**
+     * Execute SELECT query
+     */
+    execute(): Promise<QueryResult<T>>;
+    /**
+     * Execute and return all rows
+     */
+    then<TResult = T[]>(resolve?: (value: T[]) => TResult | PromiseLike<TResult>): Promise<TResult>;
+    /**
+     * Get single result (or null)
+     */
+    single(): Promise<T | null>;
+    /**
+     * Insert data
+     */
+    insert(data: Partial<T> | Partial<T>[]): Promise<InsertResult<T>>;
+    /**
+     * Update data (requires where clause)
+     */
+    update(data: Partial<T>): Promise<UpdateResult>;
+    /**
+     * Delete data (requires where clause)
+     */
+    delete(): Promise<DeleteResult>;
+}
+
+/**
+ * Scarlet SDK - Storage Module
+ * File storage operations
+ */
+
+declare class StorageModule {
+    private readonly client;
+    private readonly baseUrl;
+    constructor(client: HttpClient, baseUrl: string);
+    /**
+     * Create a new storage bucket
+     */
+    createBucket(name: string, options?: {
+        publicAccess?: boolean;
+    }): Promise<StorageBucket>;
+    /**
+     * List all buckets
+     */
+    listBuckets(): Promise<StorageBucket[]>;
+    /**
+     * Upload a file to a bucket
+     */
+    upload(bucket: string, file: Blob | File, options?: UploadOptions): Promise<StorageFile>;
+    /**
+     * List files in a bucket
+     */
+    list(bucket: string, options?: ListFilesOptions): Promise<StorageFile[]>;
+    /**
+     * Get a signed URL for private file access
+     */
+    getSignedUrl(bucket: string, fileName: string): Promise<string>;
+    /**
+     * Get public URL for a file (bucket must be public)
+     */
+    getPublicUrl(bucket: string, fileName: string): string;
+    /**
+     * Delete a file
+     */
+    delete(bucket: string, fileName: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get storage statistics
+     */
+    getStats(): Promise<{
+        size_bytes: number;
+        object_count: number;
+    }>;
+}
+
+/**
+ * Scarlet SDK - Email Module
+ * Transactional email sending
+ */
+
+declare class EmailModule {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Send a transactional email
+     */
+    send(options: SendEmailOptions): Promise<{
+        success: boolean;
+        messageId?: string;
+    }>;
+    /**
+     * Add a custom email domain
+     */
+    addDomain(domain: string): Promise<EmailDomain>;
+    /**
+     * List configured email domains
+     */
+    listDomains(): Promise<EmailDomain[]>;
+    /**
+     * Verify domain DNS records
+     */
+    verifyDomain(domainId: string): Promise<{
+        verified: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get email send logs
+     */
+    getLogs(options?: {
+        limit?: number;
+    }): Promise<EmailLog[]>;
+}
+
+/**
+ * Scarlet SDK - AI Module
+ * Natural language query processing
+ */
+
+declare class AIModule {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Execute a natural language query
+     * Converts natural language to SQL and executes it
+     *
+     * @example
+     * 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
+     */
+    query(prompt: string): Promise<AIQueryResult>;
+    /**
+     * Generate SQL from natural language without executing
+     */
+    generateSQL(prompt: string): Promise<{
+        sql: string;
+        explanation: string;
+    }>;
+}
+
+/**
+ * Scarlet SDK - SQL Module
+ * Raw SQL query execution
+ */
+
+declare class SQLModule {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Execute a parameterized SQL query
+     *
+     * @example
+     * const result = await db.sql.query(
+     *   'SELECT * FROM users WHERE created_at > $1',
+     *   [new Date('2024-01-01')]
+     * );
+     */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<SQLResult<T>>;
+    /**
+     * Execute raw SQL without parameter binding
+     * ⚠️ Use with caution - ensure input is sanitized
+     */
+    unsafe<T = Record<string, unknown>>(sql: string): Promise<SQLResult<T>>;
+}
+
+/**
+ * Scarlet SDK - Error Classes
+ */
+declare class ScarletError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(message: string, status: number, code: string, details?: unknown);
+    toJSON(): {
+        name: string;
+        message: string;
+        status: number;
+        code: string;
+        details: unknown;
+    };
+}
+declare class NetworkError extends ScarletError {
+    constructor(message: string, details?: unknown);
+}
+declare class AuthenticationError extends ScarletError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends ScarletError {
+    constructor(resource: string);
+}
+declare class ValidationError extends ScarletError {
+    constructor(message: string, details?: unknown);
+}
+declare class RateLimitError extends ScarletError {
+    readonly retryAfter?: number;
+    constructor(retryAfter?: number);
+}
+
+/**
+ * @scarlet/sdk
+ * Official TypeScript SDK for Scarlet DB
+ *
+ * @example
+ * ```typescript
+ * import { Scarlet } from '@scarlet/sdk';
+ *
+ * const db = new Scarlet({ apiKey: 'sk_live_...' });
+ *
+ * // Query data
+ * const users = await db.from('users').select().limit(10);
+ *
+ * // Storage
+ * await db.storage.upload('avatars', file);
+ *
+ * // Email
+ * await db.email.send({ from: '...', to: '...', subject: '...', html: '...' });
+ *
+ * // AI Query
+ * const result = await db.ai.query('Show me active users');
+ *
+ * // Raw SQL
+ * const result = await db.sql.query('SELECT * FROM users WHERE id = $1', [1]);
+ * ```
+ */
+
+/**
+ * Main Scarlet SDK client
+ */
+declare class Scarlet {
+    private readonly client;
+    private readonly _data;
+    /** Storage module for file operations */
+    readonly storage: StorageModule;
+    /** Email module for sending transactional emails */
+    readonly email: EmailModule;
+    /** AI module for natural language queries */
+    readonly ai: AIModule;
+    /** SQL module for raw queries */
+    readonly sql: SQLModule & {
+        <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<SQLResult<T>>;
+    };
+    constructor(config: ScarletConfig);
+    /**
+     * Start a query on a table
+     *
+     * @example
+     * const users = await db.from('users').select().where({ active: true }).limit(10);
+     */
+    from<T = Record<string, unknown>>(table: string): QueryBuilder<T>;
+}
+
+export { type AIQueryResult, type APIResponse, AuthenticationError, type DeleteResult, type EmailDomain, type EmailLog, type FilterOperator, type FilterValue, type InsertResult, type ListFilesOptions, NetworkError, NotFoundError, type OrderDirection, QueryBuilder, type QueryResult, RateLimitError, type RequestOptions, type SQLResult, Scarlet, type ScarletConfig, ScarletError, type SendEmailOptions, type StorageBucket, type StorageFile, type UpdateResult, type UploadOptions, ValidationError, type WhereCondition };