@urbackend/sdk 0.1.1 → 0.2.1

package/README.md

@@ -1,9 +1,11 @@
 # urbackend-sdk
 
-Official TypeScript SDK for [urBackend](https://urbackend.bitbros.in) — the instant Backend-as-a-Service for frontend developers.
+Official TypeScript SDK for [urBackend](https://urbackend.bitbros.in) — the instant Backend-as-a-Service for MongoDB.
 
 ## Installation
+```bash
 npm install @urbackend/sdk
+```
 
 ## Quick Start
 ```javascript
@@ -12,49 +14,80 @@ import urBackend from '@urbackend/sdk';
 const client = urBackend({ apiKey: 'YOUR_API_KEY' });
 
 // Auth
-await client.auth.signUp({ email, password, name });
-await client.auth.login({ email, password });
-await client.auth.me();
+const { accessToken } = await client.auth.login({ email, password });
+const user = await client.auth.me();
 
-// Database — collections are auto-created on first insert
-await client.db.insert('products', { name: 'Chair', price: 99 });
-await client.db.getAll('products');
-await client.db.getOne('products', id);
-await client.db.update('products', id, { price: 79 });
-await client.db.delete('products', id);
+// Database — collections are managed via the urBackend Dashboard
+await client.db.insert('posts', { title: 'Hello World' }, client.auth.getToken());
+await client.db.getAll('posts', { sort: 'createdAt:desc', limit: 10 });
 
 // Storage
-await client.storage.upload(file);
-await client.storage.deleteFile(path);
+const { url } = await client.storage.upload(file);
+
+// Mail (Requires Secret Key)
+await client.mail.send({ 
+  to: 'user@example.com', 
+  subject: 'Welcome!', 
+  text: 'Glad to have you.' 
+});
 ```
 
 ## API Reference
 
-### Client initialization
+### Client Initialization
 `urBackend({ apiKey: string, baseUrl?: string })`
 
-### Auth
+---
+
+### Auth (`client.auth`)
 | Method | Params | Returns |
 |--------|--------|---------|
-| signUp | { email, password, name? } | AuthUser |
-| login  | { email, password } | { token, user } |
-| me     | token? | AuthUser |
-| logout | — | void |
+| `signUp` | `{ email, password, username?, name?, ... }` | `AuthUser` |
+| `login` | `{ email, password }` | `AuthResponse` |
+| `me` | `token?` | `AuthUser` |
+| `logout` | `token?` | `{ success: boolean }` |
+| `refreshToken` | `refreshToken?` | `AuthResponse` |
+| `updateProfile`| `payload, token?` | `{ message: string }` |
+| `changePassword`| `payload, token?` | `{ message: string }` |
+| `verifyEmail` | `{ email, otp }` | `{ message: string }` |
+| `publicProfile`| `username` | `AuthUser` |
+| `socialStart` | `provider ('github'\|'google')` | `string` (Redirect URL) |
+| `socialExchange`| `{ token, rtCode }` | `SocialExchangeResponse` |
+
+---
+
+### Database (`client.db`)
+Support for **Row-Level Security (RLS)** is built-in. Pass the user's `accessToken` as the final parameter to write routes if RLS is enabled for the collection.
 
-### Database
 | Method | Params | Returns |
 |--------|--------|---------|
-| getAll<T> | collection | T[] |
-| getOne<T> | collection, id | T |
-| insert<T> | collection, data | T |
-| update<T> | collection, id, data | T |
-| delete | collection, id | { deleted: boolean } |
-
-### Storage
+| `getAll<T>` | `collection, params?` | `T[]` |
+| `getOne<T>` | `collection, id, options?` | `T` |
+| `insert<T>` | `collection, data, token?` | `T` |
+| `update<T>` | `collection, id, data, token?` | `T` (Full Replace) |
+| `patch<T>` | `collection, id, data, token?` | `T` (Partial Update) |
+| `delete` | `collection, id, token?` | `{ deleted: boolean }` |
+
+**Query Parameters (`params`):**
+- `filter`: `{ price_gt: 100 }`
+- `sort`: `"createdAt:desc"`
+- `limit`: `50`
+- `page`: `1`
+- `populate`: `"author"` (Expand Reference fields)
+
+---
+
+### Storage (`client.storage`)
 | Method | Params | Returns |
 |--------|--------|---------|
-| upload | file, filename? | { url, path } |
-| deleteFile | path | { deleted: boolean } |
+| `upload` | `file (Buffer\|Blob), filename?` | `{ url, path, provider }` |
+| `deleteFile` | `path` | `{ deleted: boolean }` |
+
+---
+
+### New Modules
+- **`client.schema`**: Use `getSchema(collection)` to fetch visual field definitions.
+- **`client.mail`**: Use `send(payload)` to send emails via Resend (Requires Secret Key).
 
 ## Error Handling
 ```javascript
@@ -63,23 +96,13 @@ import { AuthError, NotFoundError, RateLimitError } from '@urbackend/sdk';
 try {
   await client.db.getOne('products', id);
 } catch (e) {
-  if (e instanceof NotFoundError) console.log('Not found');
-  if (e instanceof RateLimitError) console.log('Slow down');
+  if (e instanceof AuthError) console.error('Invalid token or insufficient RLS permissions');
+  if (e instanceof NotFoundError) console.error('Resource not found');
+  if (e instanceof RateLimitError) console.error('Too many requests');
 }
 ```
 
-## TypeScript Support
-```typescript
-interface Product { _id: string; name: string; price: number; }
-const products = await client.db.getAll<Product>('products');
-```
-
-## Limits
-- Rate limit: 100 requests / 15 mins per IP
-- Database: 50 MB per project
-- Storage: 100 MB per project
-- File upload: 5 MB per file
-
 ## Security
-⚠️ Never expose your API key in client-side/browser code.
-Use environment variables: `process.env.URBACKEND_API_KEY`
+- **Never expose your Secret Key (`sk_live_...`)** in frontend/browser code.
+- Use **Publishable Keys (`pk_live_...`)** for client-side applications.
+- Enable **RLS** in the urBackend Dashboard to allow secure writes from the frontend using the user's access token.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbackend/sdk",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Official TypeScript SDK for urBackend BaaS",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",

package/src/client.ts

@@ -3,6 +3,8 @@ import { UrBackendError, parseApiError } from './errors';
 import { AuthModule } from './modules/auth';
 import { DatabaseModule } from './modules/database';
 import { StorageModule } from './modules/storage';
+import { SchemaModule } from './modules/schema';
+import { MailModule } from './modules/mail';
 
 export class UrBackendClient {
   private apiKey: string;
@@ -10,6 +12,8 @@ export class UrBackendClient {
   private _auth?: AuthModule;
   private _db?: DatabaseModule;
   private _storage?: StorageModule;
+  private _schema?: SchemaModule;
+  private _mail?: MailModule;
   private headers: Record<string, string>;
 
   constructor(config: UrBackendConfig) {
@@ -17,9 +21,9 @@ export class UrBackendClient {
     this.baseUrl = config.baseUrl || 'https://api.ub.bitbros.in';
     this.headers = config.headers || {};
 
-    if (typeof window !== 'undefined') {
+    if (typeof window !== 'undefined' && this.apiKey.startsWith('sk_live_')) {
       console.warn(
-        '⚠️ urbackend-sdk: Avoid exposing your SK-API key in client-side code(instead use pk_live key). This can lead to unauthorized access to your account and data.',
+        '⚠️ urbackend-sdk: Avoid exposing your Secret Key (sk_live_...) in client-side code. This can lead to unauthorized access to your account and data. Use your Publishable Key (pk_live_...) instead.',
       );
     }
   }
@@ -45,6 +49,28 @@ export class UrBackendClient {
     return this._storage;
   }
 
+  get schema(): SchemaModule {
+    if (!this._schema) {
+      this._schema = new SchemaModule(this);
+    }
+    return this._schema;
+  }
+
+  get mail(): MailModule {
+    if (!this._mail) {
+      this._mail = new MailModule(this);
+    }
+    return this._mail;
+  }
+
+  public getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  public getApiKey(): string {
+    return this.apiKey;
+  }
+
   /**
    * Internal request handler
    */
@@ -56,7 +82,7 @@ export class UrBackendClient {
     const url = `${this.baseUrl}${path}`;
     const headers: Record<string, string> = {
       'x-api-key': this.apiKey,
-      'User-Agent': `urbackend-sdk-js/0.1.1`,
+      'User-Agent': `urbackend-sdk-js/0.2.0`,
       ...this.headers,
     };
 
@@ -64,6 +90,11 @@ export class UrBackendClient {
       headers['Authorization'] = `Bearer ${options.token}`;
     }
 
+    // Merge custom headers from options if provided
+    if (options.headers) {
+      Object.assign(headers, options.headers);
+    }
+
     let requestBody: BodyInit | undefined;
 
     if (options.isMultipart) {
@@ -79,6 +110,7 @@ export class UrBackendClient {
         method,
         headers,
         body: requestBody,
+        credentials: options.credentials,
       });
 
       if (!response.ok) {
@@ -89,7 +121,11 @@ export class UrBackendClient {
       if (contentType && contentType.includes('application/json')) {
         const json = await response.json();
         // The API returns { data, success, message }
-        return json.data !== undefined ? json.data : json;
+        // If data is present, return it. If success/message are present but no data, return the whole object (for exchange/logout etc)
+        if (json.data !== undefined) {
+          return json.data;
+        }
+        return json;
       }
 
       return (await response.text()) as unknown as T;

package/src/index.ts

@@ -1,9 +1,14 @@
 import { UrBackendClient } from './client';
 import { UrBackendConfig } from './types';
+import { AuthModule } from './modules/auth';
+import { DatabaseModule } from './modules/database';
+import { StorageModule } from './modules/storage';
+import { SchemaModule } from './modules/schema';
+import { MailModule } from './modules/mail';
 
 export * from './types';
 export * from './errors';
-export { UrBackendClient };
+export { UrBackendClient, AuthModule, DatabaseModule, StorageModule, SchemaModule, MailModule };
 
 /**
  * Factory function to create a new urBackend client

package/src/modules/auth.ts

@@ -1,5 +1,19 @@
 import { UrBackendClient } from '../client';
-import { AuthUser, AuthResponse, SignUpPayload, LoginPayload } from '../types';
+import {
+  AuthUser,
+  AuthResponse,
+  SignUpPayload,
+  LoginPayload,
+  UpdateProfilePayload,
+  ChangePasswordPayload,
+  VerifyEmailPayload,
+  ResendOtpPayload,
+  RequestPasswordResetPayload,
+  ResetPasswordPayload,
+  SocialExchangePayload,
+  SocialExchangeResponse,
+  RequestOptions,
+} from '../types';
 import { AuthError } from '../errors';
 
 export class AuthModule {
@@ -21,7 +35,15 @@ export class AuthModule {
     const response = await this.client.request<AuthResponse>('POST', '/api/userAuth/login', {
       body: payload,
     });
-    this.sessionToken = response.token;
+
+    this.sessionToken = response.accessToken || response.token;
+
+    if (!response.accessToken && response.token) {
+      console.warn(
+        'urbackend-sdk: The server returned "token" which is deprecated. Please update your backend to return "accessToken".',
+      );
+    }
+
     return response;
   }
 
@@ -32,16 +54,156 @@ export class AuthModule {
     const activeToken = token || this.sessionToken;
 
     if (!activeToken) {
-      throw new AuthError('Authentication token is required for /me endpoint', 401, '/api/userAuth/me');
+      throw new AuthError(
+        'Authentication token is required for /me endpoint',
+        401,
+        '/api/userAuth/me',
+      );
     }
 
     return this.client.request<AuthUser>('GET', '/api/userAuth/me', { token: activeToken });
   }
 
   /**
-   * Clear the local session token
+   * Update the current authenticated user's profile
+   */
+  public async updateProfile(payload: UpdateProfilePayload, token?: string): Promise<{ message: string }> {
+    const activeToken = token || this.sessionToken;
+    if (!activeToken) {
+      throw new AuthError('Authentication token is required to update profile', 401, '/api/userAuth/update-profile');
+    }
+    return this.client.request<{ message: string }>('PUT', '/api/userAuth/update-profile', {
+      body: payload,
+      token: activeToken,
+    });
+  }
+
+  /**
+   * Change the current authenticated user's password
+   */
+  public async changePassword(payload: ChangePasswordPayload, token?: string): Promise<{ message: string }> {
+    const activeToken = token || this.sessionToken;
+    if (!activeToken) {
+      throw new AuthError('Authentication token is required to change password', 401, '/api/userAuth/change-password');
+    }
+    return this.client.request<{ message: string }>('PUT', '/api/userAuth/change-password', {
+      body: payload,
+      token: activeToken,
+    });
+  }
+
+  /**
+   * Verify user email with OTP
+   */
+  public async verifyEmail(payload: VerifyEmailPayload): Promise<{ message: string }> {
+    return this.client.request<{ message: string }>('POST', '/api/userAuth/verify-email', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Resend verification OTP
+   */
+  public async resendVerificationOtp(payload: ResendOtpPayload): Promise<{ message: string }> {
+    return this.client.request<{ message: string }>('POST', '/api/userAuth/resend-verification-otp', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Request password reset OTP
+   */
+  public async requestPasswordReset(payload: RequestPasswordResetPayload): Promise<{ message: string }> {
+    return this.client.request<{ message: string }>('POST', '/api/userAuth/request-password-reset', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Reset user password with OTP
    */
-  public logout(): void {
+  public async resetPassword(payload: ResetPasswordPayload): Promise<{ message: string }> {
+    return this.client.request<{ message: string }>('POST', '/api/userAuth/reset-password', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Get public-safe profile by username
+   */
+  public async publicProfile(username: string): Promise<AuthUser> {
+    return this.client.request<AuthUser>('GET', `/api/userAuth/public/${username}`);
+  }
+
+  /**
+   * Refresh the access token
+   * @param refreshToken Optional refresh token for header mode. If omitted, uses cookie mode.
+   */
+  public async refreshToken(refreshToken?: string): Promise<AuthResponse> {
+    const options: RequestOptions = {};
+    if (refreshToken) {
+      options.headers = { 'x-refresh-token': refreshToken, 'x-refresh-token-mode': 'header' };
+    } else {
+      options.credentials = 'include';
+    }
+
+    const response = await this.client.request<AuthResponse>('POST', '/api/userAuth/refresh-token', options);
+    this.sessionToken = response.accessToken || response.token;
+    return response;
+  }
+
+  /**
+   * Returns the start URL for social authentication.
+   * Redirect the user's browser to this URL to begin the flow.
+   */
+  public socialStart(provider: 'github' | 'google'): string {
+    return `${this.client.getBaseUrl()}/api/userAuth/social/${provider}/start?key=${this.client.getApiKey()}`;
+  }
+
+  /**
+   * Exchange social auth rtCode for a refresh token
+   */
+  public async socialExchange(payload: SocialExchangePayload): Promise<SocialExchangeResponse> {
+    return this.client.request<SocialExchangeResponse>('POST', '/api/userAuth/social/exchange', {
+      body: payload,
+    });
+  }
+
+  /**
+   * Revoke the current session and clear local state
+   */
+  public async logout(token?: string): Promise<{ success: boolean; message: string }> {
+    const activeToken = token || this.sessionToken;
+    let result = { success: true, message: 'Logged out locally' };
+
+    if (activeToken) {
+      try {
+        result = await this.client.request<{ success: boolean; message: string }>(
+          'POST',
+          '/api/userAuth/logout',
+          { token: activeToken, credentials: 'include' },
+        );
+      } catch (e) {
+        // Silently fail if server logout fails, we still want to clear local state
+        console.warn('urbackend-sdk: Server logout failed', e);
+      }
+    }
+
     this.sessionToken = undefined;
+    return result;
+  }
+
+  /**
+   * Manually set the session token (e.g. after social auth exchange)
+   */
+  public setToken(token: string): void {
+    this.sessionToken = token;
+  }
+
+  /**
+   * Get the current stored session token
+   */
+  public getToken(): string | undefined {
+    return this.sessionToken;
   }
 }

package/src/modules/database.ts

@@ -1,16 +1,19 @@
 import { UrBackendClient } from '../client';
-import { DocumentData, InsertPayload, UpdatePayload } from '../types';
+import { DocumentData, InsertPayload, UpdatePayload, PatchPayload, QueryParams } from '../types';
 import { NotFoundError } from '../errors';
 
 export class DatabaseModule {
   constructor(private client: UrBackendClient) {}
 
   /**
-   * Fetch all documents from a collection
+   * Fetch all documents from a collection with optional query parameters
    */
-  public async getAll<T extends DocumentData>(collection: string): Promise<T[]> {
+  public async getAll<T extends DocumentData>(collection: string, params: QueryParams = {}): Promise<T[]> {
+    const queryString = this.buildQueryString(params);
+    const path = `/api/data/${collection}${queryString}`;
+    
     try {
-      return await this.client.request<T[]>('GET', `/api/data/${collection}`);
+      return await this.client.request<T[]>('GET', path);
     } catch (e) {
       if (e instanceof NotFoundError) {
         return [] as T[];
@@ -22,32 +25,100 @@ export class DatabaseModule {
   /**
    * Fetch a single document by its ID
    */
-  public async getOne<T extends DocumentData>(collection: string, id: string): Promise<T> {
-    return this.client.request<T>('GET', `/api/data/${collection}/${id}`);
+  public async getOne<T extends DocumentData>(
+    collection: string, 
+    id: string, 
+    options: { populate?: string | string[]; expand?: string | string[] } = {}
+  ): Promise<T> {
+    const queryString = this.buildQueryString(options);
+    return this.client.request<T>('GET', `/api/data/${collection}/${id}${queryString}`);
   }
 
   /**
    * Insert a new document into a collection
    */
-  public async insert<T extends DocumentData>(collection: string, data: InsertPayload): Promise<T> {
-    return this.client.request<T>('POST', `/api/data/${collection}`, { body: data });
+  public async insert<T extends DocumentData>(
+    collection: string, 
+    data: InsertPayload, 
+    token?: string
+  ): Promise<T> {
+    return this.client.request<T>('POST', `/api/data/${collection}`, { 
+      body: data,
+      token 
+    });
   }
 
   /**
-   * Update an existing document by its ID
+   * Update an existing document by its ID (Full replacement)
    */
   public async update<T extends DocumentData>(
     collection: string,
     id: string,
     data: UpdatePayload,
+    token?: string
+  ): Promise<T> {
+    return this.client.request<T>('PUT', `/api/data/${collection}/${id}`, { 
+      body: data,
+      token
+    });
+  }
+
+  /**
+   * Partially update an existing document by its ID
+   */
+  public async patch<T extends DocumentData>(
+    collection: string,
+    id: string,
+    data: PatchPayload,
+    token?: string
   ): Promise<T> {
-    return this.client.request<T>('PUT', `/api/data/${collection}/${id}`, { body: data });
+    return this.client.request<T>('PATCH', `/api/data/${collection}/${id}`, { 
+      body: data,
+      token
+    });
   }
 
   /**
    * Delete a document by its ID
    */
-  public async delete(collection: string, id: string): Promise<{ deleted: boolean }> {
-    return this.client.request<{ deleted: boolean }>('DELETE', `/api/data/${collection}/${id}`);
+  public async delete(collection: string, id: string, token?: string): Promise<{ deleted: boolean }> {
+    const result = await this.client.request<{ message?: string; id?: string } | null>(
+      'DELETE',
+      `/api/data/${collection}/${id}`,
+      { token },
+    );
+
+    const deleted =
+      typeof result === 'object' &&
+      result !== null &&
+      (result.id === id || result.message === 'Document deleted');
+
+    return { deleted };
+  }
+
+  /**
+   * Internal helper to build query string from QueryParams
+   */
+  private buildQueryString(params: QueryParams): string {
+    const searchParams = new URLSearchParams();
+
+    Object.entries(params).forEach(([key, value]) => {
+      if (value === undefined || value === null) return;
+
+      if (key === 'filter' && typeof value === 'object') {
+        Object.entries(value as Record<string, unknown>).forEach(([fKey, fValue]) => {
+          if (fValue !== undefined && fValue !== null) {
+            searchParams.append(fKey, String(fValue));
+          }
+        });
+      } else if ((key === 'populate' || key === 'expand') && Array.isArray(value)) {
+        searchParams.append(key, value.join(','));
+      } else {
+        searchParams.append(key, String(value));
+      }
+    });
+
+    const str = searchParams.toString();
+    return str ? `?${str}` : '';
   }
 }

package/src/modules/mail.ts

@@ -0,0 +1,16 @@
+import { UrBackendClient } from '../client';
+import { SendMailPayload, SendMailResponse } from '../types';
+
+export class MailModule {
+  constructor(private client: UrBackendClient) {}
+
+  /**
+   * Send an email using the urBackend mail service.
+   * Note: This requires a Secret Key (sk_live_...) and should be called from a server environment.
+   */
+  public async send(payload: SendMailPayload): Promise<SendMailResponse> {
+    return this.client.request<SendMailResponse>('POST', '/api/mail/send', {
+      body: payload,
+    });
+  }
+}

package/src/modules/schema.ts

@@ -0,0 +1,24 @@
+import { UrBackendClient } from '../client';
+import { CollectionSchema } from '../types';
+
+export class SchemaModule {
+  constructor(private client: UrBackendClient) {}
+
+  /**
+   * Fetch the schema definition for a collection
+   */
+  public async getSchema(collection: string): Promise<CollectionSchema> {
+    const trimmedCollection = collection.trim();
+    if (trimmedCollection === '') {
+      throw new Error('Collection name cannot be empty or whitespace-only');
+    }
+
+    const encodedCollection = encodeURIComponent(trimmedCollection);
+    const response = await this.client.request<{
+      message: string;
+      collection: CollectionSchema;
+    }>('GET', `/api/schemas/${encodedCollection}`);
+
+    return response.collection;
+  }
+}

package/src/types/index.ts

@@ -8,12 +8,26 @@ export interface RequestOptions {
   body?: unknown;
   token?: string;
   isMultipart?: boolean;
+  credentials?: RequestCredentials;
+  headers?: Record<string, string>;
+}
+
+export interface QueryParams {
+  page?: number;
+  limit?: number;
+  sort?: string;
+  populate?: string | string[];
+  expand?: string | string[];
+  filter?: Record<string, unknown>;
+  [key: string]: unknown;
 }
 
 export interface SignUpPayload {
   email: string;
   password: string;
+  username?: string;
   name?: string;
+  [key: string]: unknown;
 }
 
 export interface LoginPayload {
@@ -21,16 +35,60 @@ export interface LoginPayload {
   password: string;
 }
 
+export interface UpdateProfilePayload {
+  username?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+export interface ChangePasswordPayload {
+  currentPassword: string;
+  newPassword: string;
+}
+
+export interface VerifyEmailPayload {
+  email: string;
+  otp: string;
+}
+
+export interface ResendOtpPayload {
+  email: string;
+}
+
+export interface RequestPasswordResetPayload {
+  email: string;
+}
+
+export interface ResetPasswordPayload {
+  email: string;
+  otp: string;
+  newPassword: string;
+}
+
+export interface SocialExchangePayload {
+  token: string;
+  rtCode: string;
+}
+
+export interface SocialExchangeResponse {
+  refreshToken: string;
+}
+
 export interface AuthUser {
   _id: string;
   email: string;
+  username?: string;
   name?: string;
   [key: string]: unknown;
 }
 
 export interface AuthResponse {
-  token: string;
-  user: AuthUser;
+  accessToken?: string;
+  /** @deprecated use accessToken instead */
+  token?: string;
+  expiresIn?: string;
+  userId?: string;
+  user?: AuthUser;
 }
 
 export interface DocumentData {
@@ -46,9 +104,47 @@ export interface UpdatePayload {
   [key: string]: unknown;
 }
 
+export interface PatchPayload {
+  [key: string]: unknown;
+}
+
+export interface SchemaField {
+  key: string;
+  type: string;
+  required: boolean;
+  unique?: boolean;
+  ref?: string;
+  items?: {
+    type: string;
+    fields?: SchemaField[];
+  };
+  fields?: SchemaField[];
+}
+
+export interface CollectionSchema {
+  name: string;
+  model: SchemaField[];
+}
+
+export interface SendMailPayload {
+  to: string | string[];
+  subject: string;
+  text?: string;
+  html?: string;
+}
+
+export interface SendMailResponse {
+  id: string | null;
+  provider: 'byok' | 'default';
+  monthlyUsage: number;
+  monthlyLimit: number;
+}
+
 export interface UploadResponse {
   url: string;
   path: string;
+  provider: 'internal' | 'external';
+  message?: string;
 }
 
 export interface ApiResponse<T> {

package/tests/auth.test.ts

@@ -1,8 +1,13 @@
-import { expect, test, vi } from 'vitest';
+import { expect, test, vi, beforeEach } from 'vitest';
 import urBackend from '../src/index';
 
-const mockApiKey = 'test-api-key';
-const client = urBackend({ apiKey: mockApiKey });
+const mockApiKey = 'pk_live_test';
+let client: ReturnType<typeof urBackend>;
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  client = urBackend({ apiKey: mockApiKey });
+});
 
 test('signUp returns user object on success', async () => {
   const mockUser = { _id: '123', email: 'test@example.com' };
@@ -19,8 +24,8 @@ test('signUp returns user object on success', async () => {
   expect(user).toEqual(mockUser);
 });
 
-test('login stores session token', async () => {
-  const mockToken = 'mock-token';
+test('login stores accessToken', async () => {
+  const mockAccessToken = 'mock-access-token';
   vi.stubGlobal(
     'fetch',
     vi.fn().mockResolvedValue({
@@ -29,13 +34,14 @@ test('login stores session token', async () => {
       json: () =>
         Promise.resolve({
           success: true,
-          data: { token: mockToken, user: { _id: '123', email: 'test@example.com' } },
+          data: { accessToken: mockAccessToken, user: { _id: '123', email: 'test@example.com' } },
         }),
     }),
   );
 
   const response = await client.auth.login({ email: 'test@example.com', password: 'password' });
-  expect(response.token).toBe(mockToken);
+  expect(response.accessToken).toBe(mockAccessToken);
+  expect(client.auth.getToken()).toBe(mockAccessToken);
 });
 
 test('me() uses stored token from login', async () => {
@@ -51,7 +57,7 @@ test('me() uses stored token from login', async () => {
       json: () =>
         Promise.resolve({
           success: true,
-          data: { token: mockToken, user: mockUser },
+          data: { accessToken: mockToken, user: mockUser },
         }),
     }),
   );
@@ -77,32 +83,87 @@ test('me() uses stored token from login', async () => {
   );
 });
 
-test('me() throws AuthError when no token present', async () => {
-  client.auth.logout();
-  await expect(client.auth.me()).rejects.toThrow('Authentication token is required');
-});
+test('logout() calls server and clears local token', async () => {
+  client.auth.setToken('test-token');
+  const logoutFetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, message: 'Logged out' }),
+  });
+  vi.stubGlobal('fetch', logoutFetchMock);
 
-test('login throws AuthError on 401', async () => {
-  vi.stubGlobal(
-    'fetch',
-    vi.fn().mockResolvedValue({
-      ok: false,
-      status: 401,
-      url: 'https://api.urbackend.bitbros.in/api/userAuth/login',
-      statusText: 'Unauthorized',
-      json: () => Promise.resolve({ success: false, message: 'Invalid credentials' }),
+  await client.auth.logout();
+
+  expect(logoutFetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/userAuth/logout'),
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer test-token',
+      }),
     }),
   );
+  expect(client.auth.getToken()).toBeUndefined();
+});
+
+test('refreshToken() uses credentials: include by default', async () => {
+  const refreshFetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { accessToken: 'new-token' } }),
+  });
+  vi.stubGlobal('fetch', refreshFetchMock);
+
+  await client.auth.refreshToken();
 
-  await expect(client.auth.login({ email: 'a', password: 'b' })).rejects.toThrow(
-    'Invalid credentials',
+  expect(refreshFetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/userAuth/refresh-token'),
+    expect.objectContaining({
+      method: 'POST',
+      credentials: 'include',
+    }),
   );
 });
 
-test('handles network failure', async () => {
-  vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('DNS failure')));
+test('refreshToken(token) uses header mode', async () => {
+  const refreshFetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { accessToken: 'new-token' } }),
+  });
+  vi.stubGlobal('fetch', refreshFetchMock);
+
+  await client.auth.refreshToken('manual-refresh-token');
 
-  await expect(client.auth.login({ email: 'a', password: 'b' })).rejects.toThrow(
-    'DNS failure',
+  expect(refreshFetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/userAuth/refresh-token'),
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({
+        'x-refresh-token': 'manual-refresh-token',
+        'x-refresh-token-mode': 'header',
+      }),
+    }),
   );
 });
+
+test('socialStart returns correct URL', () => {
+  const url = client.auth.socialStart('github');
+  expect(url).toBe('https://api.ub.bitbros.in/api/userAuth/social/github/start?key=pk_live_test');
+});
+
+test('publicProfile calls correct endpoint', async () => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { username: 'yash' } }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  await client.auth.publicProfile('yash');
+
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/userAuth/public/yash'),
+    expect.any(Object),
+  );
+});

package/tests/database.test.ts

@@ -1,9 +1,13 @@
-import { expect, test, vi } from 'vitest';
+import { expect, test, vi, beforeEach } from 'vitest';
 import urBackend from '../src/index';
 
-const mockApiKey = 'test-api-key';
+const mockApiKey = 'pk_live_test';
 const client = urBackend({ apiKey: mockApiKey });
 
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
 test('getAll returns array of typed documents', async () => {
   const mockData = [
     { _id: '1', name: 'Product 1' },
@@ -20,99 +24,111 @@ test('getAll returns array of typed documents', async () => {
 
   const items = await client.db.getAll<{ _id: string; name: string }>('products');
   expect(items).toEqual(mockData);
-  expect(items[0].name).toBe('Product 1');
 });
 
-test('getOne throws NotFoundError on 404', async () => {
-  vi.stubGlobal(
-    'fetch',
-    vi.fn().mockResolvedValue({
-      ok: false,
-      status: 404,
-      url: 'https://api.urbackend.bitbros.in/api/data/products/999',
-      json: () => Promise.resolve({ success: false, message: 'Not Found' }),
-    }),
-  );
+test('getAll with query params builds correct query string', async () => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: [] }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  await client.db.getAll('products', {
+    page: 2,
+    limit: 10,
+    sort: 'price:asc',
+    populate: 'category',
+    filter: { price_gt: 100 }
+  });
 
-  await expect(client.db.getOne('products', '999')).rejects.toThrow('Not Found');
+  const url = fetchMock.mock.calls[0][0] as string;
+  const searchParams = new URL(url).searchParams;
+  
+  expect(searchParams.get('page')).toBe('2');
+  expect(searchParams.get('limit')).toBe('10');
+  expect(searchParams.get('sort')).toBe('price:asc');
+  expect(searchParams.get('populate')).toBe('category');
+  expect(searchParams.get('price_gt')).toBe('100');
 });
 
-test('insert returns created document with _id', async () => {
+test('insert returns created document and handles optional token', async () => {
   const payload = { name: 'New Item' };
   const mockCreated = { _id: 'new-id', ...payload };
-  vi.stubGlobal(
-    'fetch',
-    vi.fn().mockResolvedValue({
-      ok: true,
-      headers: new Headers({ 'content-type': 'application/json' }),
-      json: () => Promise.resolve({ success: true, data: mockCreated }),
-    }),
-  );
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: mockCreated }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
 
-  const result = await client.db.insert<{ _id: string; name: string }>('products', payload);
+  const result = await client.db.insert<{ _id: string; name: string }>('products', payload, 'user-token');
+  
   expect(result._id).toBe('new-id');
-});
-
-test('update returns updated document', async () => {
-  const payload = { name: 'Updated' };
-  const mockUpdated = { _id: 'id-1', ...payload };
-  vi.stubGlobal(
-    'fetch',
-    vi.fn().mockResolvedValue({
-      ok: true,
-      headers: new Headers({ 'content-type': 'application/json' }),
-      json: () => Promise.resolve({ success: true, data: mockUpdated }),
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/data/products'),
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer user-token',
+      }),
     }),
   );
-
-  const result = await client.db.update<{ _id: string; name: string }>('products', 'id-1', payload);
-  expect(result.name).toBe('Updated');
 });
 
-test('delete returns { deleted: true }', async () => {
-  vi.stubGlobal(
-    'fetch',
-    vi.fn().mockResolvedValue({
-      ok: true,
-      headers: new Headers({ 'content-type': 'application/json' }),
-      json: () => Promise.resolve({ success: true, data: { deleted: true } }),
-    }),
-  );
+test('patch sends PATCH request', async () => {
+  const payload = { price: 50 };
+  const mockUpdated = { _id: '1', name: 'Original', price: 50 };
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: mockUpdated }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
 
-  const result = await client.db.delete('products', 'id-1');
-  expect(result.deleted).toBe(true);
-});
+  await client.db.patch('products', '1', payload);
 
-test('RateLimitError thrown on 429', async () => {
-  vi.stubGlobal(
-    'fetch',
-    vi.fn().mockResolvedValue({
-      ok: false,
-      status: 429,
-      url: 'https://api.urbackend.bitbros.in/api/data/products',
-      headers: new Headers({ 'Retry-After': '60' }),
-      json: () => Promise.resolve({ success: false, message: 'Too Many Requests' }),
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/data/products/1'),
+    expect.objectContaining({
+      method: 'PATCH',
+      body: JSON.stringify(payload),
     }),
   );
+});
 
-  try {
-    await client.db.getAll('products');
-  } catch (error: any) {
-    expect(error.name).toBe('RateLimitError');
-    expect(error.retryAfter).toBe(60);
-  }
+test('getOne with populate builds correct query string', async () => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { _id: '1' } }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  await client.db.getOne('products', '1', { populate: 'category' });
+
+  const url = fetchMock.mock.calls[0][0] as string;
+  expect(url).toContain('?populate=category');
 });
 
-test('ValidationError thrown on 400', async () => {
-  vi.stubGlobal(
-    'fetch',
-    vi.fn().mockResolvedValue({
-      ok: false,
-      status: 400,
-      url: 'https://api.urbackend.bitbros.in/api/data/products',
-      json: () => Promise.resolve({ success: false, message: 'Invalid data format' }),
+test('delete returns { deleted: true } and handles token', async () => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve({ success: true, data: { message: 'Document deleted', id: 'id-1' } }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  const result = await client.db.delete('products', 'id-1', 'admin-token');
+  
+  expect(result.deleted).toBe(true);
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/data/products/id-1'),
+    expect.objectContaining({
+      method: 'DELETE',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer admin-token',
+      }),
     }),
   );
-
-  await expect(client.db.insert('products', {})).rejects.toThrow('Invalid data format');
 });

package/tests/mail.test.ts

@@ -0,0 +1,41 @@
+import { expect, test, vi, beforeEach } from 'vitest';
+import urBackend from '../src/index';
+
+const mockApiKey = 'sk_live_test';
+const client = urBackend({ apiKey: mockApiKey });
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+test('send() sends POST request to mail endpoint', async () => {
+  const payload = {
+    to: 'user@example.com',
+    subject: 'Hello',
+    text: 'Test mail'
+  };
+  
+  const mockResponse = {
+    success: true,
+    data: { id: 'msg_1', provider: 'default', monthlyUsage: 1, monthlyLimit: 100 },
+    message: 'Sent'
+  };
+
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    headers: new Headers({ 'content-type': 'application/json' }),
+    json: () => Promise.resolve(mockResponse),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  const result = await client.mail.send(payload);
+  
+  expect(result).toEqual(mockResponse.data);
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/mail/send'),
+    expect.objectContaining({
+      method: 'POST',
+      body: JSON.stringify(payload),
+    }),
+  );
+});

package/tests/schema.test.ts

@@ -0,0 +1,32 @@
+import { expect, test, vi, beforeEach } from 'vitest';
+import urBackend from '../src/index';
+
+const mockApiKey = 'pk_live_test';
+const client = urBackend({ apiKey: mockApiKey });
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+test('getSchema returns collection schema', async () => {
+  const mockSchema = {
+    name: 'products',
+    model: [
+      { key: 'name', type: 'String', required: true },
+      { key: 'price', type: 'Number', required: true }
+    ]
+  };
+  
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue({
+      ok: true,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      json: () => Promise.resolve({ message: 'Schema exists', collection: mockSchema }),
+    }),
+  );
+
+  const schema = await client.schema.getSchema('products');
+  expect(schema).toEqual(mockSchema);
+  expect(schema.name).toBe('products');
+});