@scarletdb/sdk 0.1.1 → 0.2.0

package/README.md

@@ -5,37 +5,46 @@ Official TypeScript SDK for [Scarlet DB](https://scarletdb.space) - The modern B
 ## Installation
 
 ```bash
-npm install @scarlet/sdk
+npm install @scarletdb/sdk
 # or
-pnpm add @scarlet/sdk
+pnpm add @scarletdb/sdk
 # or
-yarn add @scarlet/sdk
+yarn add @scarletdb/sdk
+# or
+bun add @scarletdb/sdk
 ```
 
-## Quick Start
+## Quick Start (Server)
 
-```typescript
-import { Scarlet } from '@scarlet/sdk';
+```ts
+import { createScarlet } from '@scarletdb/sdk'
 
-// Initialize with your project API key
-const db = new Scarlet({
-  apiKey: 'sk_live_your_api_key',
-});
+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)
+```
 
-// Query data
-const users = await db.from('users').select().limit(10);
+## Quick Start (Browser)
 
-// Insert data
-await db.from('users').insert({
-  name: 'John Doe',
-  email: 'john@example.com',
-});
+Do not ship secret API keys to the browser. Use a publishable key to mint short-lived tokens, and enable proof-of-possession.
 
-// Update data
-await db.from('users').update({ active: true }).where({ id: 1 });
+```ts
+import { createScarlet } from '@scarletdb/sdk'
 
-// Delete data
-await db.from('users').delete().where({ id: 1 });
+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
@@ -46,26 +55,27 @@ Fluent query builder for CRUD operations on your database tables.
 
 ```typescript
 // Select with filters
-const activeUsers = await db
+const activeUsers = await scarlet
   .from('users')
   .select('id', 'name', 'email')
   .where({ active: true })
   .orderBy('created_at', 'desc')
-  .limit(20);
+  .limit(20)
+  .execute();
 
 // Insert single row
-const newUser = await db.from('users').insert({
+const { row: newUser } = await scarlet.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 });
+await scarlet.from('users')
+  .where({ id: userId })
+  .update({ last_login: new Date() });
 
 // Delete with filters
-await db.from('users').delete().where({ id: userId });
+await scarlet.from('users').where({ id: userId }).delete();
 ```
 
 ### 📁 Storage
@@ -74,16 +84,14 @@ 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');
+const uploaded = await scarlet.storage.upload('avatars', file, { randomId: true });
+console.log(uploaded.url);
 
 // List files in bucket
-const files = await db.storage.list('avatars');
+const files = await scarlet.storage.list('avatars');
 
 // Delete a file
-await db.storage.delete('avatars', 'old-avatar.png');
+await scarlet.storage.delete('avatars', 'old-avatar.png');
 ```
 
 ### 📧 Email
@@ -92,7 +100,7 @@ Send transactional emails with custom domains.
 
 ```typescript
 // Send an email
-await db.email.send({
+await scarlet.email.send({
   from: 'hello@myapp.com',
   to: 'user@email.com',
   subject: 'Welcome to MyApp!',
@@ -100,7 +108,7 @@ await db.email.send({
 });
 
 // List configured domains
-const domains = await db.email.listDomains();
+const domains = await scarlet.email.listDomains();
 ```
 
 ### 🤖 AI Queries
@@ -109,50 +117,34 @@ 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');
+const result = await scarlet.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);
+console.log(result.data);   // Query results
 ```
 
 ## 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)
+const scarlet = createScarlet({
+  projectId: 'YOUR_PROJECT_ID',
+  url: 'https://api.scarletdb.space',
+  apiKey: process.env.SCARLET_API_KEY!,
   timeout: 30000,
-});
+})
 ```
 
 ## Error Handling
 
 ```typescript
-import { Scarlet, ScarletError } from '@scarlet/sdk';
+import { createScarlet, ScarletError } from '@scarletdb/sdk';
 
 try {
-  await db.from('users').insert({ email: 'invalid' });
+  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);
@@ -175,8 +167,8 @@ interface User {
 }
 
 // Type-safe queries
-const users = await db.from<User>('users').select();
-// users is typed as User[]
+const { rows } = await scarlet.from<User>('users').select().execute()
+// rows is typed as User[]
 ```
 
 ## License

package/dist/index.d.mts

@@ -2,10 +2,16 @@
  * Scarlet SDK - Type Definitions
  */
 interface ScarletConfig {
-    /** Project API key (required) */
-    apiKey: string;
-    /** Base URL for the API (defaults to production) */
-    baseUrl?: string;
+    projectId: string;
+    apiKey?: string;
+    publishableKey?: string;
+    token?: string;
+    getToken?: () => Promise<string>;
+    url?: string;
+    coreUrl?: string;
+    engineUrl?: string;
+    tokenEndpoint?: string;
+    enableDpop?: boolean;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
 }
@@ -99,19 +105,10 @@ interface EmailLog {
     error?: string;
 }
 interface AIQueryResult {
-    /** Generated SQL query */
+    success: boolean;
     sql: string;
-    /** Natural language explanation */
     explanation: string;
-    /** Query execution results */
-    result: {
-        rows: Record<string, unknown>[];
-        fields: {
-            name: string;
-            dataType: number;
-        }[];
-    };
-    /** Error if query failed */
+    data: Record<string, unknown>[];
     error?: string;
     details?: string;
 }
@@ -144,24 +141,24 @@ interface APIResponse<T> {
  */
 
 interface ClientConfig {
-    apiKey: string;
     baseUrl: string;
     timeout: number;
+    getAuthHeaders: (params: {
+        method: string;
+        url: string;
+    }) => Promise<Record<string, string>>;
 }
 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>;
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, headers?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    patch<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    put<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    delete<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    postForm<T>(path: string, form: FormData): Promise<T>;
 }
 
 /**
@@ -172,11 +169,11 @@ declare class HttpClient {
 declare class QueryBuilder<T = Record<string, unknown>> {
     private readonly client;
     private readonly table;
-    private _columns;
-    private _where;
-    private _orderBy?;
+    private _fields;
+    private _filters;
+    private _sort?;
+    private _page?;
     private _limit?;
-    private _offset?;
     constructor(client: HttpClient, table: string);
     /**
      * Select specific columns (default: all)
@@ -196,14 +193,12 @@ declare class QueryBuilder<T = Record<string, unknown>> {
      * Order results
      */
     orderBy(column: keyof T & string, direction?: OrderDirection): this;
+    page(page: number): this;
     /**
      * Limit results
      */
     limit(count: number): this;
-    /**
-     * Offset results (for pagination)
-     */
-    offset(count: number): this;
+    private buildQueryParams;
     /**
      * Execute SELECT query
      */
@@ -237,8 +232,8 @@ declare class QueryBuilder<T = Record<string, unknown>> {
 
 declare class StorageModule {
     private readonly client;
-    private readonly baseUrl;
-    constructor(client: HttpClient, baseUrl: string);
+    private readonly projectId;
+    constructor(client: HttpClient, projectId: string);
     /**
      * Create a new storage bucket
      */
@@ -252,7 +247,16 @@ declare class StorageModule {
     /**
      * Upload a file to a bucket
      */
-    upload(bucket: string, file: Blob | File, options?: UploadOptions): Promise<StorageFile>;
+    upload(bucket: string, file: Blob | File, options?: UploadOptions & {
+        randomId?: boolean;
+        cacheDuration?: number;
+    }): Promise<{
+        fileId: string;
+        url: string;
+        key: string;
+        bucket: string;
+        fileName: string;
+    }>;
     /**
      * List files in a bucket
      */
@@ -264,7 +268,6 @@ declare class StorageModule {
     /**
      * Get public URL for a file (bucket must be public)
      */
-    getPublicUrl(bucket: string, fileName: string): string;
     /**
      * Delete a file
      */
@@ -287,7 +290,9 @@ declare class StorageModule {
 
 declare class EmailModule {
     private readonly client;
-    constructor(client: HttpClient);
+    private readonly projectId;
+    constructor(client: HttpClient, projectId: string);
+    private headers;
     /**
      * Send a transactional email
      */
@@ -325,7 +330,8 @@ declare class EmailModule {
 
 declare class AIModule {
     private readonly client;
-    constructor(client: HttpClient);
+    private readonly projectId;
+    constructor(client: HttpClient, projectId: string);
     /**
      * Execute a natural language query
      * Converts natural language to SQL and executes it
@@ -336,40 +342,12 @@ declare class AIModule {
      * 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
  */
@@ -434,7 +412,8 @@ declare class RateLimitError extends ScarletError {
  * Main Scarlet SDK client
  */
 declare class Scarlet {
-    private readonly client;
+    private readonly engineClient;
+    private readonly coreClient;
     private readonly _data;
     /** Storage module for file operations */
     readonly storage: StorageModule;
@@ -442,10 +421,7 @@ declare class Scarlet {
     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>>;
-    };
+    readonly projectId: string;
     constructor(config: ScarletConfig);
     /**
      * Start a query on a table
@@ -455,5 +431,6 @@ declare class Scarlet {
      */
     from<T = Record<string, unknown>>(table: string): QueryBuilder<T>;
 }
+declare function createScarlet(config: ScarletConfig): Scarlet;
 
-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 };
+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, createScarlet };

package/dist/index.d.ts

@@ -2,10 +2,16 @@
  * Scarlet SDK - Type Definitions
  */
 interface ScarletConfig {
-    /** Project API key (required) */
-    apiKey: string;
-    /** Base URL for the API (defaults to production) */
-    baseUrl?: string;
+    projectId: string;
+    apiKey?: string;
+    publishableKey?: string;
+    token?: string;
+    getToken?: () => Promise<string>;
+    url?: string;
+    coreUrl?: string;
+    engineUrl?: string;
+    tokenEndpoint?: string;
+    enableDpop?: boolean;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
 }
@@ -99,19 +105,10 @@ interface EmailLog {
     error?: string;
 }
 interface AIQueryResult {
-    /** Generated SQL query */
+    success: boolean;
     sql: string;
-    /** Natural language explanation */
     explanation: string;
-    /** Query execution results */
-    result: {
-        rows: Record<string, unknown>[];
-        fields: {
-            name: string;
-            dataType: number;
-        }[];
-    };
-    /** Error if query failed */
+    data: Record<string, unknown>[];
     error?: string;
     details?: string;
 }
@@ -144,24 +141,24 @@ interface APIResponse<T> {
  */
 
 interface ClientConfig {
-    apiKey: string;
     baseUrl: string;
     timeout: number;
+    getAuthHeaders: (params: {
+        method: string;
+        url: string;
+    }) => Promise<Record<string, string>>;
 }
 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>;
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, headers?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    patch<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    put<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    delete<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    postForm<T>(path: string, form: FormData): Promise<T>;
 }
 
 /**
@@ -172,11 +169,11 @@ declare class HttpClient {
 declare class QueryBuilder<T = Record<string, unknown>> {
     private readonly client;
     private readonly table;
-    private _columns;
-    private _where;
-    private _orderBy?;
+    private _fields;
+    private _filters;
+    private _sort?;
+    private _page?;
     private _limit?;
-    private _offset?;
     constructor(client: HttpClient, table: string);
     /**
      * Select specific columns (default: all)
@@ -196,14 +193,12 @@ declare class QueryBuilder<T = Record<string, unknown>> {
      * Order results
      */
     orderBy(column: keyof T & string, direction?: OrderDirection): this;
+    page(page: number): this;
     /**
      * Limit results
      */
     limit(count: number): this;
-    /**
-     * Offset results (for pagination)
-     */
-    offset(count: number): this;
+    private buildQueryParams;
     /**
      * Execute SELECT query
      */
@@ -237,8 +232,8 @@ declare class QueryBuilder<T = Record<string, unknown>> {
 
 declare class StorageModule {
     private readonly client;
-    private readonly baseUrl;
-    constructor(client: HttpClient, baseUrl: string);
+    private readonly projectId;
+    constructor(client: HttpClient, projectId: string);
     /**
      * Create a new storage bucket
      */
@@ -252,7 +247,16 @@ declare class StorageModule {
     /**
      * Upload a file to a bucket
      */
-    upload(bucket: string, file: Blob | File, options?: UploadOptions): Promise<StorageFile>;
+    upload(bucket: string, file: Blob | File, options?: UploadOptions & {
+        randomId?: boolean;
+        cacheDuration?: number;
+    }): Promise<{
+        fileId: string;
+        url: string;
+        key: string;
+        bucket: string;
+        fileName: string;
+    }>;
     /**
      * List files in a bucket
      */
@@ -264,7 +268,6 @@ declare class StorageModule {
     /**
      * Get public URL for a file (bucket must be public)
      */
-    getPublicUrl(bucket: string, fileName: string): string;
     /**
      * Delete a file
      */
@@ -287,7 +290,9 @@ declare class StorageModule {
 
 declare class EmailModule {
     private readonly client;
-    constructor(client: HttpClient);
+    private readonly projectId;
+    constructor(client: HttpClient, projectId: string);
+    private headers;
     /**
      * Send a transactional email
      */
@@ -325,7 +330,8 @@ declare class EmailModule {
 
 declare class AIModule {
     private readonly client;
-    constructor(client: HttpClient);
+    private readonly projectId;
+    constructor(client: HttpClient, projectId: string);
     /**
      * Execute a natural language query
      * Converts natural language to SQL and executes it
@@ -336,40 +342,12 @@ declare class AIModule {
      * 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
  */
@@ -434,7 +412,8 @@ declare class RateLimitError extends ScarletError {
  * Main Scarlet SDK client
  */
 declare class Scarlet {
-    private readonly client;
+    private readonly engineClient;
+    private readonly coreClient;
     private readonly _data;
     /** Storage module for file operations */
     readonly storage: StorageModule;
@@ -442,10 +421,7 @@ declare class Scarlet {
     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>>;
-    };
+    readonly projectId: string;
     constructor(config: ScarletConfig);
     /**
      * Start a query on a table
@@ -455,5 +431,6 @@ declare class Scarlet {
      */
     from<T = Record<string, unknown>>(table: string): QueryBuilder<T>;
 }
+declare function createScarlet(config: ScarletConfig): Scarlet;
 
-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 };
+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, createScarlet };