@urbackend/sdk 0.2.7 → 0.2.8

package/dist/index.cjs

@@ -112,17 +112,90 @@ async function parseApiError(response) {
 
 // src/modules/auth.ts
 var AuthModule = class {
+  /**
+   * 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) {
     this.client = client;
   }
   /**
-   * 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');
+   *   }
+   * }
    */
   async signUp(payload) {
     return this.client.request("POST", "/api/userAuth/signup", { body: payload });
   }
   /**
-   * 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');
+   *   }
+   * }
    */
   async login(payload) {
     const response = await this.client.request("POST", "/api/userAuth/login", {
@@ -137,7 +210,33 @@ var AuthModule = class {
     return response;
   }
   /**
-   * 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');
+   *   }
+   * }
    */
   async me(token) {
     const activeToken = token || this.sessionToken;
@@ -151,7 +250,37 @@ var AuthModule = class {
     return this.client.request("GET", "/api/userAuth/me", { token: activeToken });
   }
   /**
-   * 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');
+   * }
    */
   async updateProfile(payload, token) {
     const activeToken = token || this.sessionToken;
@@ -164,7 +293,38 @@ var AuthModule = class {
     });
   }
   /**
-   * 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');
+   *   }
+   * }
    */
   async changePassword(payload, token) {
     const activeToken = token || this.sessionToken;
@@ -177,7 +337,31 @@ var AuthModule = class {
     });
   }
   /**
-   * 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.');
+   * }
    */
   async verifyEmail(payload) {
     return this.client.request("POST", "/api/userAuth/verify-email", {
@@ -185,7 +369,21 @@ var AuthModule = class {
     });
   }
   /**
-   * 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);
    */
   async resendVerificationOtp(payload) {
     return this.client.request("POST", "/api/userAuth/resend-verification-otp", {
@@ -193,7 +391,21 @@ var AuthModule = class {
     });
   }
   /**
-   * 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);
    */
   async requestPasswordReset(payload) {
     return this.client.request("POST", "/api/userAuth/request-password-reset", {
@@ -201,7 +413,38 @@ var AuthModule = class {
     });
   }
   /**
-   * 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.');
+   * }
    */
   async resetPassword(payload) {
     return this.client.request("POST", "/api/userAuth/reset-password", {
@@ -209,14 +452,57 @@ var AuthModule = class {
     });
   }
   /**
-   * 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');
+   * }
    */
   async publicProfile(username) {
     return this.client.request("GET", `/api/userAuth/public/${username}`);
   }
   /**
-   * 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
+   *   }
+   * }
    */
   async refreshToken(refreshToken) {
     const options = {};
@@ -230,14 +516,45 @@ var AuthModule = class {
     return response;
   }
   /**
-   * 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) {
     return `${this.client.getBaseUrl()}/api/userAuth/social/${provider}/start?key=${this.client.getApiKey()}`;
   }
   /**
-   * 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);
+   * }
    */
   async socialExchange(payload) {
     return this.client.request("POST", "/api/userAuth/social/exchange", {
@@ -245,7 +562,30 @@ var AuthModule = class {
     });
   }
   /**
-   * 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');
+   * }
    */
   async logout(token) {
     const activeToken = token || this.sessionToken;
@@ -265,13 +605,45 @@ var AuthModule = class {
     return result;
   }
   /**
-   * 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) {
     this.sessionToken = token;
   }
   /**
-   * 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() {
     return this.sessionToken;
@@ -280,11 +652,49 @@ var AuthModule = class {
 
 // src/modules/database.ts
 var DatabaseModule = class {
+  /**
+   * 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) {
     this.client = client;
   }
   /**
-   * 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']
+   * });
    */
   async getAll(collection, params = {}) {
     const queryString = this.buildQueryString(params);
@@ -299,14 +709,118 @@ var DatabaseModule = class {
     }
   }
   /**
-   * 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);
+   */
+  async count(collection, params = {}) {
+    const queryString = this.buildQueryString({ ...params, count: "true" });
+    const path = `/api/data/${collection}${queryString}`;
+    const result = await this.client.request("GET", path);
+    return result.count;
+  }
+  /**
+   * 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');
+   *   }
+   * }
    */
   async getOne(collection, id, options = {}) {
     const queryString = this.buildQueryString(options);
     return this.client.request("GET", `/api/data/${collection}/${id}${queryString}`);
   }
   /**
-   * 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');
+   *   }
+   * }
    */
   async insert(collection, data, token) {
     return this.client.request("POST", `/api/data/${collection}`, {
@@ -315,7 +829,38 @@ var DatabaseModule = class {
     });
   }
   /**
-   * 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');
+   *   }
+   * }
    */
   async update(collection, id, data, token) {
     return this.client.request("PUT", `/api/data/${collection}/${id}`, {
@@ -324,7 +869,42 @@ var DatabaseModule = class {
     });
   }
   /**
-   * 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);
+   * }
    */
   async patch(collection, id, data, token) {
     return this.client.request("PATCH", `/api/data/${collection}/${id}`, {
@@ -333,7 +913,42 @@ var DatabaseModule = class {
     });
   }
   /**
-   * 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');
+   * }
    */
   async delete(collection, id, token) {
     const result = await this.client.request(
@@ -346,6 +961,20 @@ var DatabaseModule = class {
   }
   /**
    * 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 } })
    */
   buildQueryString(params) {
     const searchParams = new URLSearchParams();
@@ -370,11 +999,59 @@ var DatabaseModule = class {
 
 // src/modules/storage.ts
 var StorageModule = class {
+  /**
+   * 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) {
     this.client = client;
   }
   /**
-   * 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.
+   * }
    */
   async upload(file, filename) {
     const formData = new FormData();
@@ -390,7 +1067,40 @@ var StorageModule = class {
     });
   }
   /**
-   * 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');
    */
   async deleteFile(path) {
     return this.client.request("DELETE", "/api/storage/file", {
@@ -401,11 +1111,49 @@ var StorageModule = class {
 
 // src/modules/schema.ts
 var SchemaModule = class {
+  /**
+   * 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) {
     this.client = client;
   }
   /**
-   * 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
+   * }
    */
   async getSchema(collection) {
     const trimmedCollection = collection.trim();
@@ -420,12 +1168,65 @@ var SchemaModule = class {
 
 // src/modules/mail.ts
 var MailModule = class {
+  /**
+   * 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) {
     this.client = client;
   }
   /**
-   * 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);
+   * }
    */
   async send(payload) {
     return this.client.request("POST", "/api/mail/send", {