@urbackend/sdk 0.2.7 → 0.3.0

package/dist/index.d.ts

@@ -105,9 +105,17 @@ 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[];
-    subject: string;
+    variables?: Record<string, unknown>;
+    templateId?: string;
+    templateName?: string;
+    subject?: string;
     text?: string;
     html?: string;
 }
@@ -129,161 +137,1071 @@ interface ApiResponse<T> {
     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);
     /**
-     * Create a new user account
+     * 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>;
     /**
-     * Log in an existing user and store the session token
+     * 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>;
     /**
-     * Get the current authenticated user's profile
+     * 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>;
     /**
-     * Update the current authenticated user's profile
+     * 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;
     }>;
     /**
-     * Change the current authenticated user's password
+     * 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;
     }>;
     /**
-     * Verify user email with OTP
+     * 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;
     }>;
     /**
-     * Resend verification OTP
+     * 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;
     }>;
     /**
-     * Request password reset OTP
+     * 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;
     }>;
     /**
-     * Reset user password with OTP
+     * 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;
     }>;
     /**
-     * Get public-safe profile by username
+     * 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>;
     /**
-     * Refresh the access token
-     * @param refreshToken Optional refresh token for header mode. If omitted, uses cookie mode.
+     * 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.
-     * Redirect the user's browser to this URL to begin the flow.
+     * 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;
     /**
-     * Exchange social auth rtCode for a refresh token
+     * 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>;
     /**
-     * Revoke the current session and clear local state
+     * 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 set the session token (e.g. after social auth exchange)
+     * 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;
     /**
-     * Get the current stored session token
+     * 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);
     /**
-     * Fetch all documents from a collection with optional query parameters
+     * 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
+     * @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): Promise<T[]>;
     /**
-     * Fetch a single document by its ID
+     * 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
+     * @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'>): 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
+     * @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[];
     }): Promise<T>;
     /**
-     * Insert a new document into a collection
+     * 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>;
     /**
-     * Update an existing document by its ID (Full replacement)
+     * 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 update an existing document by its ID
+     * 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>;
     /**
-     * Delete a document by its ID
+     * 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);
     /**
-     * Upload a file to storage
+     * 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>;
     /**
-     * Delete a file from storage by its path
+     * 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);
     /**
-     * Fetch the schema definition for a collection
+     * 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);
     /**
-     * Send an email using the urBackend mail service.
-     * Note: This requires a Secret Key (sk_live_...) and should be called from a server environment.
+     * 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>;
 }