@urbackend/sdk 0.3.1 → 0.4.1

package/dist/index.d.ts

@@ -0,0 +1,1264 @@
+interface UrBackendConfig {
+    apiKey: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+}
+interface RequestOptions {
+    body?: unknown;
+    token?: string;
+    isMultipart?: boolean;
+    credentials?: RequestCredentials;
+    headers?: Record<string, string>;
+}
+interface QueryParams {
+    page?: number;
+    limit?: number;
+    sort?: string;
+    populate?: string | string[];
+    expand?: string | string[];
+    filter?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface SignUpPayload {
+    email: string;
+    password: string;
+    username?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface LoginPayload {
+    email: string;
+    password: string;
+}
+interface UpdateProfilePayload {
+    username?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface ChangePasswordPayload {
+    currentPassword: string;
+    newPassword: string;
+}
+interface VerifyEmailPayload {
+    email: string;
+    otp: string;
+}
+interface ResendOtpPayload {
+    email: string;
+}
+interface RequestPasswordResetPayload {
+    email: string;
+}
+interface ResetPasswordPayload {
+    email: string;
+    otp: string;
+    newPassword: string;
+}
+interface SocialExchangePayload {
+    token: string;
+    rtCode: string;
+}
+interface SocialExchangeResponse {
+    refreshToken: string;
+}
+interface AuthUser {
+    _id: string;
+    email: string;
+    username?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface AuthResponse {
+    accessToken?: string;
+    /** @deprecated use accessToken instead */
+    token?: string;
+    expiresIn?: string;
+    userId?: string;
+    user?: AuthUser;
+}
+interface DocumentData {
+    _id: string;
+    [key: string]: unknown;
+}
+interface InsertPayload {
+    [key: string]: unknown;
+}
+interface UpdatePayload {
+    [key: string]: unknown;
+}
+interface PatchPayload {
+    [key: string]: unknown;
+}
+interface SchemaField {
+    key: string;
+    type: string;
+    required: boolean;
+    unique?: boolean;
+    ref?: string;
+    items?: {
+        type: string;
+        fields?: SchemaField[];
+    };
+    fields?: SchemaField[];
+}
+interface CollectionSchema {
+    name: string;
+    model: SchemaField[];
+}
+/**
+ * Mail payload contract:
+ * - Template mode: provide `templateId` or `templateName` (with optional `variables`).
+ * - Direct mode: provide `subject` and at least one of `text` or `html`.
+ */
+interface SendMailPayload {
+    to: string | string[];
+    variables?: Record<string, unknown>;
+    templateId?: string;
+    templateName?: string;
+    subject?: string;
+    text?: string;
+    html?: string;
+}
+interface SendMailResponse {
+    id: string | null;
+    provider: 'byok' | 'default';
+    monthlyUsage: number;
+    monthlyLimit: number;
+}
+interface UploadResponse {
+    url: string;
+    path: string;
+    provider: 'internal' | 'external';
+    message?: string;
+}
+interface ApiResponse<T> {
+    data: T;
+    success: boolean;
+    message?: string;
+}
+
+/**
+ * Module for authentication and user management in urBackend
+ *
+ * @class AuthModule
+ * @description Provides complete authentication functionality including signup, login,
+ * profile management, password operations, email verification, social authentication,
+ * and session management. Manages session tokens automatically.
+ *
+ * @example
+ * // Initialize the auth module
+ * const client = new UrBackendClient({ apiKey: 'pk_live_xxx', secretKey: 'sk_live_xxx' });
+ * const auth = new AuthModule(client);
+ *
+ * // Sign up a new user
+ * const user = await auth.signUp({
+ *   email: 'user@example.com',
+ *   password: 'securePassword123',
+ *   name: 'John Doe'
+ * });
+ *
+ * @example
+ * // Log in and manage session
+ * const session = await auth.login({
+ *   email: 'user@example.com',
+ *   password: 'securePassword123'
+ * });
+ * console.log('Access token:', session.accessToken);
+ *
+ * // Get current user profile
+ * const profile = await auth.me();
+ * console.log('Welcome:', profile.name);
+ */
+declare class AuthModule {
+    private client;
+    private sessionToken?;
+    /**
+     * Creates an instance of AuthModule
+     *
+     * @param {UrBackendClient} client - The urBackend client instance
+     *
+     * @example
+     * const client = new UrBackendClient({ apiKey: 'pk_live_xxx' });
+     * const auth = new AuthModule(client);
+     */
+    constructor(client: UrBackendClient);
+    /**
+     * Creates a new user account
+     *
+     * @param {SignUpPayload} payload - User registration data
+     * @param {string} payload.email - User's email address
+     * @param {string} payload.password - User's password
+     * @param {string} payload.name - User's full name
+     * @returns {Promise<AuthUser>} Promise resolving to the created user object
+     *
+     * @throws {AuthError} If email already exists
+     * @throws {AuthError} If password does not meet requirements
+     * @throws {AuthError} If validation fails
+     *
+     * @example
+     * // Sign up a new user
+     * const user = await auth.signUp({
+     *   email: 'john@example.com',
+     *   password: 'StrongP@ss123',
+     *   name: 'John Doe'
+     * });
+     * console.log('User created:', user._id);
+     *
+     * @example
+     * // Sign up with error handling
+     * try {
+     *   const user = await auth.signUp({
+     *     email: 'existing@email.com',
+     *     password: 'weak',
+     *     name: 'Test'
+     *   });
+     * } catch (error) {
+     *   if (error.message.includes('email')) {
+     *     console.log('Email already registered');
+     *   } else if (error.message.includes('password')) {
+     *     console.log('Password too weak');
+     *   }
+     * }
+     */
+    signUp(payload: SignUpPayload): Promise<AuthUser>;
+    /**
+     * Authenticates an existing user and stores the session token
+     *
+     * @param {LoginPayload} payload - User login credentials
+     * @param {string} payload.email - User's email address
+     * @param {string} payload.password - User's password
+     * @returns {Promise<AuthResponse>} Promise resolving to authentication response with tokens
+     *
+     * @throws {AuthError} If credentials are invalid
+     * @throws {AuthError} If account is locked or not verified
+     *
+     * @example
+     * // Log in a user
+     * const response = await auth.login({
+     *   email: 'john@example.com',
+     *   password: 'StrongP@ss123'
+     * });
+     * console.log('Access token:', response.accessToken);
+     *
+     * @example
+     * // Login with error handling
+     * try {
+     *   const { accessToken, user } = await auth.login({
+     *     email: 'user@example.com',
+     *     password: 'wrongpassword'
+     *   });
+     * } catch (error) {
+     *   if (error.status === 401) {
+     *     console.log('Invalid email or password');
+     *   }
+     * }
+     */
+    login(payload: LoginPayload): Promise<AuthResponse>;
+    /**
+     * Retrieves the current authenticated user's profile
+     *
+     * @param {string} [token] - Optional authentication token (overrides stored token)
+     * @returns {Promise<AuthUser>} Promise resolving to the authenticated user's profile
+     *
+     * @throws {AuthError} If no authentication token is provided
+     * @throws {AuthError} If token is invalid or expired
+     *
+     * @example
+     * // Get current user profile (uses stored token from login)
+     * const user = await auth.me();
+     * console.log(`Hello ${user.name}, your email is ${user.email}`);
+     *
+     * @example
+     * // Get profile with custom token
+     * const user = await auth.me(customToken);
+     *
+     * @example
+     * // Get profile with error handling
+     * try {
+     *   const user = await auth.me();
+     *   console.log('Authenticated as:', user.email);
+     * } catch (error) {
+     *   if (error.status === 401) {
+     *     console.log('Please log in again');
+     *   }
+     * }
+     */
+    me(token?: string): Promise<AuthUser>;
+    /**
+     * Updates the current authenticated user's profile
+     *
+     * @param {UpdateProfilePayload} payload - Profile data to update
+     * @param {string} [payload.name] - Updated name
+     * @param {string} [payload.email] - Updated email (may require re-verification)
+     * @param {string} [token] - Optional authentication token (overrides stored token)
+     * @returns {Promise<{ message: string }>} Promise resolving to success message
+     *
+     * @throws {AuthError} If no authentication token is provided
+     * @throws {AuthError} If token is invalid or expired
+     * @throws {AuthError} If email is already taken
+     *
+     * @example
+     * // Update user's name
+     * const result = await auth.updateProfile({ name: 'Jane Smith' });
+     * console.log(result.message);
+     *
+     * @example
+     * // Update multiple fields
+     * const result = await auth.updateProfile({
+     *   name: 'Jane Doe',
+     *   email: 'jane@newemail.com'
+     * });
+     *
+     * @example
+     * // Update with error handling
+     * try {
+     *   await auth.updateProfile({ email: 'taken@email.com' });
+     * } catch (error) {
+     *   console.log('Email already in use');
+     * }
+     */
+    updateProfile(payload: UpdateProfilePayload, token?: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Changes the current authenticated user's password
+     *
+     * @param {ChangePasswordPayload} payload - Password change data
+     * @param {string} payload.currentPassword - User's current password
+     * @param {string} payload.newPassword - Desired new password
+     * @param {string} [token] - Optional authentication token (overrides stored token)
+     * @returns {Promise<{ message: string }>} Promise resolving to success message
+     *
+     * @throws {AuthError} If no authentication token is provided
+     * @throws {AuthError} If current password is incorrect
+     * @throws {AuthError} If new password does not meet requirements
+     *
+     * @example
+     * // Change password
+     * const result = await auth.changePassword({
+     *   currentPassword: 'oldPassword123',
+     *   newPassword: 'newStrongP@ss456'
+     * });
+     * console.log(result.message);
+     *
+     * @example
+     * // Change password with error handling
+     * try {
+     *   await auth.changePassword({
+     *     currentPassword: 'wrong',
+     *     newPassword: 'newPassword123'
+     *   });
+     * } catch (error) {
+     *   if (error.message.includes('current password')) {
+     *     console.log('Current password is incorrect');
+     *   }
+     * }
+     */
+    changePassword(payload: ChangePasswordPayload, token?: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Verifies user's email address using OTP
+     *
+     * @param {VerifyEmailPayload} payload - Email verification data
+     * @param {string} payload.email - User's email address
+     * @param {string} payload.otp - One-time password sent to email
+     * @returns {Promise<{ message: string }>} Promise resolving to success message
+     *
+     * @throws {AuthError} If OTP is invalid or expired
+     * @throws {AuthError} If email is not found
+     *
+     * @example
+     * // Verify email with OTP
+     * const result = await auth.verifyEmail({
+     *   email: 'user@example.com',
+     *   otp: '123456'
+     * });
+     * console.log('Email verified:', result.message);
+     *
+     * @example
+     * // Verify with error handling
+     * try {
+     *   await auth.verifyEmail({ email: 'user@example.com', otp: '000000' });
+     * } catch (error) {
+     *   console.log('Invalid OTP. Please try again.');
+     * }
+     */
+    verifyEmail(payload: VerifyEmailPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Resends verification OTP to user's email
+     *
+     * @param {ResendOtpPayload} payload - Resend OTP request data
+     * @param {string} payload.email - User's email address
+     * @returns {Promise<{ message: string }>} Promise resolving to success message
+     *
+     * @throws {AuthError} If email is not found
+     * @throws {AuthError} If too many attempts
+     *
+     * @example
+     * // Resend verification OTP
+     * const result = await auth.resendVerificationOtp({
+     *   email: 'user@example.com'
+     * });
+     * console.log('OTP resent:', result.message);
+     */
+    resendVerificationOtp(payload: ResendOtpPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Requests a password reset OTP to be sent to user's email
+     *
+     * @param {RequestPasswordResetPayload} payload - Password reset request data
+     * @param {string} payload.email - User's email address
+     * @returns {Promise<{ message: string }>} Promise resolving to success message
+     *
+     * @throws {AuthError} If email is not found
+     * @throws {AuthError} If too many attempts
+     *
+     * @example
+     * // Request password reset
+     * const result = await auth.requestPasswordReset({
+     *   email: 'user@example.com'
+     * });
+     * console.log('Reset OTP sent:', result.message);
+     */
+    requestPasswordReset(payload: RequestPasswordResetPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Resets user's password using OTP
+     *
+     * @param {ResetPasswordPayload} payload - Password reset data
+     * @param {string} payload.email - User's email address
+     * @param {string} payload.otp - One-time password sent via email
+     * @param {string} payload.newPassword - Desired new password
+     * @returns {Promise<{ message: string }>} Promise resolving to success message
+     *
+     * @throws {AuthError} If OTP is invalid or expired
+     * @throws {AuthError} If email is not found
+     * @throws {AuthError} If new password does not meet requirements
+     *
+     * @example
+     * // Reset password with OTP
+     * const result = await auth.resetPassword({
+     *   email: 'user@example.com',
+     *   otp: '123456',
+     *   newPassword: 'NewStrongP@ss789'
+     * });
+     * console.log('Password reset:', result.message);
+     *
+     * @example
+     * // Reset password with error handling
+     * try {
+     *   await auth.resetPassword({
+     *     email: 'user@example.com',
+     *     otp: 'wrong',
+     *     newPassword: 'newPass123'
+     *   });
+     * } catch (error) {
+     *   console.log('Invalid OTP. Please request a new one.');
+     * }
+     */
+    resetPassword(payload: ResetPasswordPayload): Promise<{
+        message: string;
+    }>;
+    /**
+     * Retrieves a public-safe user profile by username
+     *
+     * @param {string} username - Username of the user to fetch
+     * @returns {Promise<AuthUser>} Promise resolving to public user profile (sensitive fields omitted)
+     *
+     * @throws {AuthError} If user with given username does not exist
+     *
+     * @example
+     * // Get public profile
+     * const profile = await auth.publicProfile('john_doe');
+     * console.log(`${profile.name} joined on ${profile.createdAt}`);
+     *
+     * @example
+     * // Display user profile on a public page
+     * try {
+     *   const user = await auth.publicProfile('username');
+     *   // Show user info (no email or private data)
+     * } catch (error) {
+     *   console.log('User not found');
+     * }
+     */
+    publicProfile(username: string): Promise<AuthUser>;
+    /**
+     * Refreshes the access token using refresh token or cookie
+     *
+     * @param {string} [refreshToken] - Optional refresh token for header mode. If omitted, uses cookie mode.
+     * @returns {Promise<AuthResponse>} Promise resolving to new authentication response with fresh tokens
+     *
+     * @throws {AuthError} If refresh token is invalid or expired
+     *
+     * @example
+     * // Refresh token using cookie (if configured)
+     * const newTokens = await auth.refreshToken();
+     * console.log('New access token:', newTokens.accessToken);
+     *
+     * @example
+     * // Refresh token using explicit refresh token
+     * const newTokens = await auth.refreshToken(storedRefreshToken);
+     *
+     * @example
+     * // Auto-refresh before API calls
+     * try {
+     *   await auth.me();
+     * } catch (error) {
+     *   if (error.status === 401) {
+     *     await auth.refreshToken();
+     *     // Retry the original request
+     *   }
+     * }
+     */
+    refreshToken(refreshToken?: string): Promise<AuthResponse>;
+    /**
+     * Returns the start URL for social authentication
+     *
+     * @param {('github' | 'google')} provider - The social authentication provider
+     * @returns {string} URL to redirect the user's browser to begin the OAuth flow
+     *
+     * @example
+     * // Redirect user to social login page
+     * const githubUrl = auth.socialStart('github');
+     * window.location.href = githubUrl;
+     *
+     * @example
+     * // For Node.js backend
+     * const googleUrl = auth.socialStart('google');
+     * res.redirect(googleUrl);
+     */
+    socialStart(provider: 'github' | 'google'): string;
+    /**
+     * Exchanges social authentication rtCode for a refresh token
+     *
+     * @param {SocialExchangePayload} payload - Social exchange data
+     * @param {string} payload.rtCode - Return code from social provider
+     * @param {string} payload.provider - Social provider ('github' or 'google')
+     * @returns {Promise<SocialExchangeResponse>} Promise resolving to authentication response
+     *
+     * @throws {AuthError} If rtCode is invalid or expired
+     * @throws {AuthError} If social provider fails
+     *
+     * @example
+     * // After user returns from social login
+     * const rtCode = new URLSearchParams(window.location.search).get('rtCode');
+     * if (rtCode) {
+     *   const response = await auth.socialExchange({
+     *     rtCode: rtCode,
+     *     provider: 'github'
+     *   });
+     *   console.log('Social login successful:', response.accessToken);
+     * }
+     */
+    socialExchange(payload: SocialExchangePayload): Promise<SocialExchangeResponse>;
+    /**
+     * Revokes the current session and clears local state
+     *
+     * @param {string} [token] - Optional authentication token (overrides stored token)
+     * @returns {Promise<{ success: boolean; message: string }>} Promise resolving to logout status
+     *
+     * @example
+     * // Log out current user
+     * const result = await auth.logout();
+     * console.log(result.message);
+     * // User is now logged out, session token is cleared
+     *
+     * @example
+     * // Log out with custom token
+     * const result = await auth.logout(customToken);
+     *
+     * @example
+     * // Logout after API calls
+     * try {
+     *   await auth.logout();
+     *   // Redirect to login page
+     *   window.location.href = '/login';
+     * } catch (error) {
+     *   console.log('Logout failed, but local session cleared');
+     * }
+     */
+    logout(token?: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Manually sets the session token (e.g., after social authentication exchange)
+     *
+     * @param {string} token - The session/access token to store
+     *
+     * @example
+     * // After successful social exchange
+     * const response = await auth.socialExchange({ rtCode, provider: 'github' });
+     * auth.setToken(response.accessToken);
+     *
+     * @example
+     * // Restore session from localStorage
+     * const savedToken = localStorage.getItem('authToken');
+     * if (savedToken) {
+     *   auth.setToken(savedToken);
+     *   const user = await auth.me();
+     * }
+     */
+    setToken(token: string): void;
+    /**
+     * Gets the current stored session token
+     *
+     * @returns {string | undefined} The current session token, if any
+     *
+     * @example
+     * // Get token for custom API calls
+     * const token = auth.getToken();
+     * if (token) {
+     *   // Use token in custom API request
+     *   fetch('/api/custom', { headers: { Authorization: `Bearer ${token}` } });
+     * }
+     *
+     * @example
+     * // Save token to localStorage for persistence
+     * const token = auth.getToken();
+     * if (token) {
+     *   localStorage.setItem('authToken', token);
+     * }
+     */
+    getToken(): string | undefined;
+}
+
+/**
+ * Module for database operations in urBackend
+ *
+ * @class DatabaseModule
+ * @description Provides CRUD (Create, Read, Update, Delete) operations for collections.
+ * Supports filtering, pagination, sorting, population, and expansion of related data.
+ *
+ * @example
+ * // Initialize the database module
+ * const client = new UrBackendClient({ secretKey: 'sk_live_xxx' });
+ * const db = new DatabaseModule(client);
+ *
+ * // Get all users
+ * const users = await db.getAll('users');
+ * console.log(users);
+ *
+ * @example
+ * // Insert a new document
+ * const newUser = await db.insert('users', {
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * });
+ * console.log('Created:', newUser._id);
+ */
+declare class DatabaseModule {
+    private client;
+    /**
+     * Creates an instance of DatabaseModule
+     *
+     * @param {UrBackendClient} client - The authenticated urBackend client instance
+     *
+     * @example
+     * const client = new UrBackendClient({ secretKey: 'sk_live_xxx' });
+     * const db = new DatabaseModule(client);
+     */
+    constructor(client: UrBackendClient);
+    /**
+     * Fetches all documents from a collection with optional query parameters
+     *
+     * @template T - The document type (extends DocumentData)
+     * @param {string} collection - Name of the collection to query
+     * @param {QueryParams} [params={}] - Optional query parameters for filtering, sorting, pagination
+     * @param {string} [token] - Optional authentication token (required for private-mode reads with publishable keys)
+     * @returns {Promise<T[]>} Promise resolving to an array of documents (empty array if none found)
+     *
+     * @throws {Error} If collection name is invalid
+     * @throws {Error} If authentication fails
+     * @throws {Error} If query parameters are malformed
+     *
+     * @example
+     * // Get all users
+     * const users = await db.getAll('users');
+     *
+     * @example
+     * // Get users with filters and pagination
+     * const activeUsers = await db.getAll('users', {
+     *   filter: { status: 'active' },
+     *   limit: 10,
+     *   skip: 0,
+     *   sort: '-createdAt'
+     * });
+     *
+     * @example
+     * // Get users with populated relations
+     * const usersWithPosts = await db.getAll('users', {
+     *   populate: ['posts'],
+     *   expand: ['profile']
+     * });
+     */
+    getAll<T extends DocumentData>(collection: string, params?: QueryParams, token?: string): Promise<T[]>;
+    /**
+     * Counts documents in a collection with optional filters
+     *
+     * @param {string} collection - Name of the collection to count
+     * @param {Omit<QueryParams, 'count'>} [params={}] - Optional filter parameters
+     * @param {string} [token] - Optional authentication token (required for private-mode reads with publishable keys)
+     * @returns {Promise<number>} Promise resolving to the total count of matching documents
+     *
+     * @throws {Error} If collection name is invalid
+     * @throws {Error} If authentication fails
+     *
+     * @example
+     * // Count all users
+     * const totalUsers = await db.count('users');
+     * console.log(`Total users: ${totalUsers}`);
+     *
+     * @example
+     * // Count users with filter
+     * const activeUsers = await db.count('users', {
+     *   filter: { status: 'active' }
+     * });
+     *
+     * @example
+     * // Count for pagination
+     * const total = await db.count('products', {
+     *   filter: { category: 'electronics' }
+     * });
+     * const totalPages = Math.ceil(total / 10);
+     */
+    count(collection: string, params?: Omit<QueryParams, 'count'>, token?: string): Promise<number>;
+    /**
+     * Fetches a single document by its ID
+     *
+     * @template T - The document type (extends DocumentData)
+     * @param {string} collection - Name of the collection
+     * @param {string} id - Unique identifier of the document
+     * @param {Object} [options={}] - Optional parameters
+     * @param {string|string[]} [options.populate] - Fields to populate with related data
+     * @param {string|string[]} [options.expand] - Fields to expand with nested data
+     * @param {string} [token] - Optional authentication token (required for private-mode reads with publishable keys)
+     * @returns {Promise<T>} Promise resolving to the document
+     *
+     * @throws {NotFoundError} If document with given ID does not exist
+     * @throws {Error} If collection name or ID is invalid
+     * @throws {Error} If authentication fails
+     *
+     * @example
+     * // Get user by ID
+     * const user = await db.getOne('users', 'user_123');
+     * console.log(user.name);
+     *
+     * @example
+     * // Get user with populated posts
+     * const userWithPosts = await db.getOne('users', 'user_123', {
+     *   populate: ['posts', 'comments']
+     * });
+     *
+     * @example
+     * // Get with error handling
+     * try {
+     *   const user = await db.getOne('users', 'non_existent_id');
+     * } catch (error) {
+     *   if (error instanceof NotFoundError) {
+     *     console.log('User not found');
+     *   }
+     * }
+     */
+    getOne<T extends DocumentData>(collection: string, id: string, options?: {
+        populate?: string | string[];
+        expand?: string | string[];
+    }, token?: string): Promise<T>;
+    /**
+     * Inserts a new document into a collection
+     *
+     * @template T - The document type (extends DocumentData)
+     * @param {string} collection - Name of the collection
+     * @param {InsertPayload} data - Document data to insert
+     * @param {string} [token] - Optional authentication token (overrides client default)
+     * @returns {Promise<T>} Promise resolving to the created document with generated ID
+     *
+     * @throws {Error} If collection name is invalid
+     * @throws {Error} If data validation fails
+     * @throws {Error} If authentication fails
+     * @throws {Error} If unique constraint violation occurs
+     *
+     * @example
+     * // Insert a new user
+     * const newUser = await db.insert('users', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     *   age: 25
+     * });
+     * console.log('User created:', newUser._id);
+     *
+     * @example
+     * // Insert with custom token
+     * const result = await db.insert('posts', {
+     *   title: 'My Post',
+     *   content: 'Hello World'
+     * }, customAuthToken);
+     *
+     * @example
+     * // Insert with error handling
+     * try {
+     *   const user = await db.insert('users', { email: 'existing@email.com' });
+     * } catch (error) {
+     *   if (error.message.includes('duplicate')) {
+     *     console.log('Email already exists');
+     *   }
+     * }
+     */
+    insert<T extends DocumentData>(collection: string, data: InsertPayload, token?: string): Promise<T>;
+    /**
+     * Updates an existing document by its ID (full replacement)
+     *
+     * @template T - The document type (extends DocumentData)
+     * @param {string} collection - Name of the collection
+     * @param {string} id - Unique identifier of the document
+     * @param {UpdatePayload} data - Complete document data for replacement
+     * @param {string} [token] - Optional authentication token (overrides client default)
+     * @returns {Promise<T>} Promise resolving to the updated document
+     *
+     * @throws {NotFoundError} If document with given ID does not exist
+     * @throws {Error} If collection name or ID is invalid
+     * @throws {Error} If data validation fails
+     * @throws {Error} If authentication fails
+     *
+     * @example
+     * // Full update of a user
+     * const updatedUser = await db.update('users', 'user_123', {
+     *   name: 'Jane Doe',
+     *   email: 'jane@example.com',
+     *   age: 26
+     * });
+     *
+     * @example
+     * // Update with error handling
+     * try {
+     *   const result = await db.update('users', 'user_123', updatedData);
+     *   console.log('Update successful:', result);
+     * } catch (error) {
+     *   if (error instanceof NotFoundError) {
+     *     console.log('User not found');
+     *   }
+     * }
+     */
+    update<T extends DocumentData>(collection: string, id: string, data: UpdatePayload, token?: string): Promise<T>;
+    /**
+     * Partially updates an existing document by its ID (only provided fields)
+     *
+     * @template T - The document type (extends DocumentData)
+     * @param {string} collection - Name of the collection
+     * @param {string} id - Unique identifier of the document
+     * @param {PatchPayload} data - Partial data to update
+     * @param {string} [token] - Optional authentication token (overrides client default)
+     * @returns {Promise<T>} Promise resolving to the updated document
+     *
+     * @throws {NotFoundError} If document with given ID does not exist
+     * @throws {Error} If collection name or ID is invalid
+     * @throws {Error} If data validation fails
+     * @throws {Error} If authentication fails
+     *
+     * @example
+     * // Partial update - only update age
+     * const updatedUser = await db.patch('users', 'user_123', {
+     *   age: 26
+     * });
+     *
+     * @example
+     * // Add a new field to document
+     * const result = await db.patch('users', 'user_123', {
+     *   lastLogin: new Date().toISOString()
+     * });
+     *
+     * @example
+     * // Partial update with error handling
+     * try {
+     *   const result = await db.patch('products', 'prod_123', {
+     *     price: 29.99
+     *   });
+     *   console.log('Price updated:', result);
+     * } catch (error) {
+     *   console.error('Update failed:', error.message);
+     * }
+     */
+    patch<T extends DocumentData>(collection: string, id: string, data: PatchPayload, token?: string): Promise<T>;
+    /**
+     * Deletes a document by its ID
+     *
+     * @param {string} collection - Name of the collection
+     * @param {string} id - Unique identifier of the document to delete
+     * @param {string} [token] - Optional authentication token (overrides client default)
+     * @returns {Promise<{ deleted: boolean }>} Promise resolving to deletion status
+     *
+     * @throws {Error} If collection name or ID is invalid
+     * @throws {Error} If authentication fails
+     * @throws {Error} If user lacks permission to delete
+     *
+     * @example
+     * // Delete a user
+     * const result = await db.delete('users', 'user_123');
+     * if (result.deleted) {
+     *   console.log('User deleted successfully');
+     * }
+     *
+     * @example
+     * // Delete with error handling
+     * try {
+     *   const { deleted } = await db.delete('posts', 'post_456');
+     *   if (deleted) {
+     *     console.log('Post removed');
+     *   }
+     * } catch (error) {
+     *   console.error('Deletion failed:', error.message);
+     * }
+     *
+     * @example
+     * // Delete after checking existence
+     * const exists = await db.getOne('users', 'user_123').catch(() => null);
+     * if (exists) {
+     *   await db.delete('users', 'user_123');
+     *   console.log('User deleted');
+     * }
+     */
+    delete(collection: string, id: string, token?: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Internal helper to build query string from QueryParams
+     *
+     * @param {QueryParams} params - Query parameters to convert
+     * @returns {string} URL query string (starting with '?' if parameters exist, otherwise empty)
+     *
+     * @internal
+     * @private
+     *
+     * @example
+     * // Returns "?limit=10&sort=-createdAt"
+     * buildQueryString({ limit: 10, sort: '-createdAt' })
+     *
+     * @example
+     * // Returns "?status=active&age=25"
+     * buildQueryString({ filter: { status: 'active', age: 25 } })
+     */
+    private buildQueryString;
+}
+
+/**
+ * Module for handling file storage operations in urBackend
+ *
+ * @class StorageModule
+ * @description Provides methods to upload and delete files in the urBackend storage system.
+ * Supports both browser (File/Blob) and Node.js (Buffer) environments.
+ *
+ * @example
+ * // Initialize the storage module
+ * const client = new UrBackendClient({ secretKey: 'sk_live_xxx' });
+ * const storage = new StorageModule(client);
+ *
+ * // Upload a file (Browser)
+ * const fileInput = document.getElementById('fileInput');
+ * const result = await storage.upload(fileInput.files[0], 'my-file.pdf');
+ * console.log(result.url);
+ *
+ * @example
+ * // Upload a file (Node.js)
+ * const fs = require('fs');
+ * const buffer = fs.readFileSync('./document.pdf');
+ * const result = await storage.upload(buffer, 'document.pdf');
+ */
+declare class StorageModule {
+    private client;
+    /**
+     * Creates an instance of StorageModule
+     *
+     * @param {UrBackendClient} client - The authenticated urBackend client instance
+     *
+     * @example
+     * const client = new UrBackendClient({ secretKey: 'sk_live_xxx' });
+     * const storage = new StorageModule(client);
+     */
+    constructor(client: UrBackendClient);
+    /**
+     * Uploads a file to the urBackend storage
+     *
+     * @param {unknown} file - The file to upload. Supports:
+     *   - Browser: File, Blob
+     *   - Node.js: Buffer
+     * @param {string} [filename] - Optional custom filename for the uploaded file
+     * @returns {Promise<UploadResponse>} Promise resolving to upload details including URL and file ID
+     *
+     * @throws {Error} If file is invalid or missing
+     * @throws {Error} If file size exceeds limits
+     * @throws {Error} If authentication fails
+     * @throws {Error} If storage quota is exceeded
+     *
+     * @example
+     * // Browser: Upload from file input
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0];
+     * const result = await storage.upload(file, 'custom-name.pdf');
+     * console.log('File URL:', result.url);
+     *
+     * @example
+     * // Node.js: Upload Buffer
+     * const fs = require('fs');
+     * const buffer = fs.readFileSync('./image.png');
+     * const result = await storage.upload(buffer, 'image.png');
+     * console.log('Uploaded:', result.fileId);
+     *
+     * @example
+     * // Upload without custom filename (uses original name)
+     * const result = await storage.upload(file);
+     *
+     * @example
+     * // Upload with error handling
+     * try {
+     *   const result = await storage.upload(file, 'document.pdf');
+     *   console.log('Upload successful:', result.url);
+     * } catch (error) {
+     *   console.error('Upload failed:', error.message);
+     *   // Handle error: retry, show user message, etc.
+     * }
+     */
+    upload(file: unknown, filename?: string): Promise<UploadResponse>;
+    /**
+     * Deletes a file from storage by its path
+     *
+     * @param {string} path - The file path or URL of the file to delete
+     * @returns {Promise<{ deleted: boolean }>} Promise resolving to deletion status
+     *
+     * @throws {Error} If path is empty or invalid
+     * @throws {Error} If file does not exist
+     * @throws {Error} If authentication fails
+     * @throws {Error} If user lacks permission to delete the file
+     *
+     * @example
+     * // Delete a file by path
+     * const result = await storage.deleteFile('uploads/document.pdf');
+     * if (result.deleted) {
+     *   console.log('File deleted successfully');
+     * }
+     *
+     * @example
+     * // Delete with error handling
+     * try {
+     *   const result = await storage.deleteFile('uploads/old-file.jpg');
+     *   console.log('Deleted:', result.deleted);
+     * } catch (error) {
+     *   console.error('Deletion failed:', error.message);
+     * }
+     *
+     * @example
+     * // Delete after upload
+     * const uploadResult = await storage.upload(file, 'temp-file.pdf');
+     * console.log('Uploaded:', uploadResult.url);
+     *
+     * // Later, delete the file
+     * await storage.deleteFile('temp-file.pdf');
+     * console.log('File cleaned up');
+     */
+    deleteFile(path: string): Promise<{
+        deleted: boolean;
+    }>;
+}
+
+/**
+ * Module for managing database schemas in urBackend
+ *
+ * @class SchemaModule
+ * @description Provides methods to fetch and manage collection schema definitions.
+ * Schemas define the structure, validation rules, and data types for collections.
+ *
+ * @example
+ * // Initialize the schema module
+ * const client = new UrBackendClient({ secretKey: 'sk_live_xxx' });
+ * const schema = new SchemaModule(client);
+ *
+ * // Get schema for a collection
+ * const collectionSchema = await schema.getSchema('users');
+ * console.log(collectionSchema.fields);
+ */
+declare class SchemaModule {
+    private client;
+    /**
+     * Creates an instance of SchemaModule
+     *
+     * @param {UrBackendClient} client - The authenticated urBackend client instance
+     *
+     * @example
+     * const client = new UrBackendClient({ secretKey: 'sk_live_xxx' });
+     * const schema = new SchemaModule(client);
+     */
+    constructor(client: UrBackendClient);
+    /**
+     * Fetches the schema definition for a specific collection
+     *
+     * @param {string} collection - Name of the collection to fetch schema for
+     * @returns {Promise<CollectionSchema>} Promise resolving to the collection schema definition
+     *
+     * @throws {Error} If collection name is empty or contains only whitespace
+     * @throws {Error} If collection does not exist
+     * @throws {Error} If authentication fails
+     *
+     * @example
+     * // Get schema for users collection
+     * const userSchema = await schema.getSchema('users');
+     * console.log(userSchema.fields);
+     *
+     * @example
+     * // Get schema for products collection with error handling
+     * try {
+     *   const productSchema = await schema.getSchema('products');
+     *   console.log('Schema fields:', Object.keys(productSchema.fields));
+     * } catch (error) {
+     *   console.error('Failed to fetch schema:', error.message);
+     * }
+     *
+     * @example
+     * // Validate collection name before fetching
+     * const collectionName = 'my_collection';
+     * if (collectionName.trim()) {
+     *   const schemaDef = await schema.getSchema(collectionName);
+     *   // Use schema definition
+     * }
+     */
+    getSchema(collection: string): Promise<CollectionSchema>;
+}
+
+/**
+ * Module for handling email operations in urBackend
+ *
+ * @class MailModule
+ * @description Provides methods to send emails using the urBackend mail service.
+ * Requires a Secret Key (sk_live_...) and should be called from a server environment.
+ *
+ * @example
+ * // Initialize the mail module
+ * const client = new UrBackendClient({ secretKey: 'sk_live_xxx' });
+ * const mail = new MailModule(client);
+ *
+ * // Send an email
+ * const result = await mail.send({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome!',
+ *   html: '<h1>Hello World</h1>'
+ * });
+ */
+declare class MailModule {
+    private client;
+    /**
+     * Creates an instance of MailModule
+     *
+     * @param {UrBackendClient} client - The authenticated urBackend client instance
+     *
+     * @example
+     * const client = new UrBackendClient({ secretKey: 'sk_live_xxx' });
+     * const mail = new MailModule(client);
+     */
+    constructor(client: UrBackendClient);
+    /**
+     * Sends an email using the urBackend mail service
+     *
+     * @param {SendMailPayload} payload - The email content and configuration
+     * @param {string} payload.to - Recipient email address
+     * @param {string} payload.subject - Email subject line
+     * @param {string} payload.html - HTML content of the email
+     * @param {string} [payload.from] - Optional sender email address (defaults to configured sender)
+     * @param {string[]} [payload.cc] - Optional CC recipient email addresses
+     * @param {string[]} [payload.bcc] - Optional BCC recipient email addresses
+     * @returns {Promise<SendMailResponse>} Promise resolving to email sending status and message ID
+     *
+     * @throws {Error} If secret key is missing or invalid
+     * @throws {Error} If email validation fails
+     * @throws {Error} If rate limit is exceeded
+     *
+     * @example
+     * // Send a basic email
+     * const result = await mail.send({
+     *   to: 'user@example.com',
+     *   subject: 'Welcome to urBackend',
+     *   html: '<h1>Welcome!</h1><p>Thanks for joining.</p>'
+     * });
+     * console.log(result.messageId);
+     *
+     * @example
+     * // Send an email with CC and custom sender
+     * const result = await mail.send({
+     *   from: 'noreply@myapp.com',
+     *   to: 'user@example.com',
+     *   cc: ['admin@example.com'],
+     *   subject: 'Important Update',
+     *   html: '<p>Your account has been updated.</p>'
+     * });
+     *
+     * @example
+     * // Send email with error handling
+     * try {
+     *   const result = await mail.send({
+     *     to: 'user@example.com',
+     *     subject: 'Test',
+     *     html: '<p>Test email</p>'
+     *   });
+     *   console.log('Email sent:', result);
+     * } catch (error) {
+     *   console.error('Failed to send email:', error);
+     * }
+     */
+    send(payload: SendMailPayload): Promise<SendMailResponse>;
+}
+
+declare class UrBackendClient {
+    private apiKey;
+    private baseUrl;
+    private _auth?;
+    private _db?;
+    private _storage?;
+    private _schema?;
+    private _mail?;
+    private headers;
+    constructor(config: UrBackendConfig);
+    get auth(): AuthModule;
+    get db(): DatabaseModule;
+    get storage(): StorageModule;
+    get schema(): SchemaModule;
+    get mail(): MailModule;
+    getBaseUrl(): string;
+    getApiKey(): string;
+    /**
+     * Internal request handler
+     */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+
+declare class UrBackendError extends Error {
+    message: string;
+    statusCode: number;
+    endpoint: string;
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+declare class AuthError extends UrBackendError {
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+declare class NotFoundError extends UrBackendError {
+    constructor(message: string, endpoint: string);
+}
+declare class RateLimitError extends UrBackendError {
+    retryAfter?: number;
+    constructor(message: string, endpoint: string, retryAfter?: number);
+}
+declare class StorageError extends UrBackendError {
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+declare class ValidationError extends UrBackendError {
+    constructor(message: string, endpoint: string);
+}
+declare function parseApiError(response: Response): Promise<UrBackendError>;
+
+/**
+ * Factory function to create a new urBackend client
+ */
+declare function urBackend(config: UrBackendConfig): UrBackendClient;
+
+export { type ApiResponse, AuthError, AuthModule, type AuthResponse, type AuthUser, type ChangePasswordPayload, type CollectionSchema, DatabaseModule, type DocumentData, type InsertPayload, type LoginPayload, MailModule, NotFoundError, type PatchPayload, type QueryParams, RateLimitError, type RequestOptions, type RequestPasswordResetPayload, type ResendOtpPayload, type ResetPasswordPayload, type SchemaField, SchemaModule, type SendMailPayload, type SendMailResponse, type SignUpPayload, type SocialExchangePayload, type SocialExchangeResponse, StorageError, StorageModule, type UpdatePayload, type UpdateProfilePayload, type UploadResponse, UrBackendClient, type UrBackendConfig, UrBackendError, ValidationError, type VerifyEmailPayload, urBackend as default, parseApiError };