@base44/sdk 0.8.5 → 0.8.7

package/dist/modules/auth.js

@@ -1,32 +1,24 @@
 /**
- * Creates the auth module for the Base44 SDK
- * @param {import('axios').AxiosInstance} axios - Axios instance
- * @param {string|number} appId - Application ID
- * @param {string} serverUrl - Server URL
- * @returns {Object} Auth module with authentication methods
+ * Creates the auth module for the Base44 SDK.
+ *
+ * @param axios - Axios instance for API requests
+ * @param functionsAxiosClient - Axios instance for functions API requests
+ * @param appId - Application ID
+ * @param options - Configuration options including server URLs
+ * @returns Auth module with authentication and user management methods
+ * @internal
  */
 export function createAuthModule(axios, functionsAxiosClient, appId, options) {
     return {
-        /**
-         * Get current user information
-         * @returns {Promise<Object>} Current user data
-         */
+        // Get current user information
         async me() {
             return axios.get(`/apps/${appId}/entities/User/me`);
         },
-        /**
-         * Update current user data
-         * @param {Object} data - Updated user data
-         * @returns {Promise<Object>} Updated user
-         */
+        // Update current user data
         async updateMe(data) {
             return axios.put(`/apps/${appId}/entities/User/me`, data);
         },
-        /**
-         * Redirects the user to the app's login page
-         * @param {string} nextUrl - URL to redirect to after successful login
-         * @throws {Error} When not in a browser environment
-         */
+        // Redirects the user to the app's login page
         redirectToLogin(nextUrl) {
             var _a;
             // This function only works in a browser environment
@@ -42,12 +34,8 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             // Redirect to the login page
             window.location.href = loginUrl;
         },
-        /**
-         * Logout the current user
-         * Removes the token from localStorage and optionally redirects to a URL or reloads the page
-         * @param redirectUrl - Optional URL to redirect to after logout. Reloads the page if not provided
-         * @returns {Promise<void>}
-         */
+        // Logout the current user
+        // Removes the token from localStorage and optionally redirects to a URL or reloads the page
         logout(redirectUrl) {
             // Remove token from axios headers
             delete axios.defaults.headers.common["Authorization"];
@@ -72,11 +60,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                 }
             }
         },
-        /**
-         * Set authentication token
-         * @param {string} token - Auth token
-         * @param {boolean} [saveToStorage=true] - Whether to save the token to localStorage
-         */
+        // Set authentication token
         setToken(token, saveToStorage = true) {
             if (!token)
                 return;
@@ -97,13 +81,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                 }
             }
         },
-        /**
-         * Login via username and password
-         * @param email - User email
-         * @param password - User password
-         * @param turnstileToken - Optional Turnstile captcha token
-         * @returns Login response with access_token and user
-         */
+        // Login using username and password
         async loginViaEmailPassword(email, password, turnstileToken) {
             var _a;
             try {
@@ -129,10 +107,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                 throw error;
             }
         },
-        /**
-         * Verify if the current token is valid
-         * @returns {Promise<boolean>} True if token is valid
-         */
+        // Verify if the current token is valid
         async isAuthenticated() {
             try {
                 await this.me();
@@ -142,35 +117,42 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                 return false;
             }
         },
+        // Invite a user to the app
         inviteUser(userEmail, role) {
             return axios.post(`/apps/${appId}/users/invite-user`, {
                 user_email: userEmail,
                 role,
             });
         },
+        // Register a new user account
         register(payload) {
             return axios.post(`/apps/${appId}/auth/register`, payload);
         },
+        // Verify an OTP (One-time password) code
         verifyOtp({ email, otpCode }) {
             return axios.post(`/apps/${appId}/auth/verify-otp`, {
                 email,
                 otp_code: otpCode,
             });
         },
+        // Resend an OTP code to the user's email
         resendOtp(email) {
             return axios.post(`/apps/${appId}/auth/resend-otp`, { email });
         },
+        // Request a password reset
         resetPasswordRequest(email) {
             return axios.post(`/apps/${appId}/auth/reset-password-request`, {
                 email,
             });
         },
-        resetPassword({ resetToken, newPassword, }) {
+        // Reset password using a reset token
+        resetPassword({ resetToken, newPassword }) {
             return axios.post(`/apps/${appId}/auth/reset-password`, {
                 reset_token: resetToken,
                 new_password: newPassword,
             });
         },
+        // Change the user's password
         changePassword({ userId, currentPassword, newPassword, }) {
             return axios.post(`/apps/${appId}/auth/change-password`, {
                 user_id: userId,

package/dist/modules/auth.types.d.ts

@@ -0,0 +1,436 @@
+/**
+ * An authenticated user.
+ */
+export interface User {
+    /** Unique user identifier. */
+    id: string;
+    /** When the user was created. */
+    created_date: string;
+    /** When the user was last updated. */
+    updated_date: string;
+    /** User's email address. */
+    email: string;
+    /** User's full name. */
+    full_name: string | null;
+    /** Whether the user is disabled. */
+    disabled: boolean | null;
+    /** Whether the user's email has been verified. */
+    is_verified: boolean;
+    /** The app ID this user belongs to. */
+    app_id: string;
+    /** Whether this is a service account. */
+    is_service: boolean;
+    /** Internal app role.
+     * @internal
+     */
+    _app_role: string;
+    /**
+     * User's role in the app. Roles are configured in the app settings and determine the user's permissions and access levels.
+     */
+    role: string;
+    /**
+     * Additional custom fields defined in the user schema. Any custom properties added to the user schema in the app will be available here with their configured types and values.
+     */
+    [key: string]: any;
+}
+/**
+ * Response from login endpoints containing user information and access token.
+ */
+export interface LoginResponse {
+    /** JWT access token for authentication. */
+    access_token: string;
+    /** User information. */
+    user: User;
+}
+/**
+ * Payload for user registration.
+ */
+export interface RegisterParams {
+    /** User's email address. */
+    email: string;
+    /** User's password. */
+    password: string;
+    /** Optional {@link https://developers.cloudflare.com/turnstile/ | Cloudflare Turnstile CAPTCHA token} for bot protection. */
+    turnstile_token?: string | null;
+    /** Optional {@link https://docs.base44.com/Getting-Started/Referral-program | referral code} from an existing user. */
+    referral_code?: string | null;
+}
+/**
+ * Parameters for OTP verification.
+ */
+export interface VerifyOtpParams {
+    /** User's email address. */
+    email: string;
+    /** One-time password code received by email. */
+    otpCode: string;
+}
+/**
+ * Parameters for changing a user's password.
+ */
+export interface ChangePasswordParams {
+    /** User ID. */
+    userId: string;
+    /** Current password for verification. */
+    currentPassword: string;
+    /** New password to set. */
+    newPassword: string;
+}
+/**
+ * Parameters for resetting a password with a token.
+ */
+export interface ResetPasswordParams {
+    /** Reset token received by email. */
+    resetToken: string;
+    /** New password to set. */
+    newPassword: string;
+}
+/**
+ * Configuration options for the auth module.
+ */
+export interface AuthModuleOptions {
+    /** Server URL for API requests. */
+    serverUrl: string;
+    /** Optional base URL for the app (used for login redirects). */
+    appBaseUrl?: string;
+}
+/**
+ * Authentication module for managing user authentication and authorization. The module automatically stores tokens in local storage when available and manages authorization headers for API requests.
+ *
+ * This module provides comprehensive authentication functionality including:
+ * - Email/password login and registration
+ * - Token management
+ * - User profile access and updates
+ * - Password reset flows
+ * - OTP verification
+ * - User invitations
+ *
+ * The auth module is only available in user authentication mode (`base44.auth`).
+ */
+export interface AuthModule {
+    /**
+     * Gets the current authenticated user's information.
+     *
+     * @returns Promise resolving to the user's profile data.
+     *
+     * @example
+     * ```typescript
+     * // Get current user information
+     * const user = await base44.auth.me();
+     * console.log(`Logged in as: ${user.email}`);
+     * console.log(`User ID: ${user.id}`);
+     * ```
+     */
+    me(): Promise<User>;
+    /**
+     * Updates the current authenticated user's information.
+     *
+     * Only the fields included in the data object will be updated.
+     * Commonly updated fields include `full_name` and custom profile fields.
+     *
+     * @param data - Object containing the fields to update.
+     * @returns Promise resolving to the updated user data.
+     *
+     * @example
+     * ```typescript
+     * // Update specific fields
+     * const updatedUser = await base44.auth.updateMe({
+     *   full_name: 'John Doe'
+     * });
+     * console.log(`Updated user: ${updatedUser.full_name}`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Update custom fields defined in your User entity
+     * await base44.auth.updateMe({
+     *   bio: 'Software developer',
+     *   phone: '+1234567890',
+     *   preferences: { theme: 'dark' }
+     * });
+     * ```
+     */
+    updateMe(data: Partial<Omit<User, "id" | "created_date" | "updated_date">>): Promise<User>;
+    /**
+     * Redirects the user to the app's login page.
+     *
+     * Redirects with a callback URL to return to after successful authentication. Requires a browser environment and can't be used in the backend.
+     *
+     * @param nextUrl - URL to redirect to after successful login.
+     * @throws {Error} When not in a browser environment.
+     *
+     * @example
+     * ```typescript
+     * // Redirect to login and come back to current page
+     * base44.auth.redirectToLogin(window.location.href);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Redirect to login and then go to the dashboard page
+     * base44.auth.redirectToLogin('/dashboard');
+     * ```
+     */
+    redirectToLogin(nextUrl: string): void;
+    /**
+     * Logs out the current user.
+     *
+     * Removes the authentication token from local storage and Axios headers, then optionally redirects to a URL or reloads the page. Requires a browser environment and can't be used in the backend.
+     *
+     * @param redirectUrl - Optional URL to redirect to after logout. Reloads the page if not provided.
+     *
+     * @example
+     * ```typescript
+     * // Logout and reload page
+     * base44.auth.logout();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Logout and redirect to login page
+     * base44.auth.logout('/login');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Logout and redirect to home
+     * base44.auth.logout('/');
+     * ```
+     */
+    logout(redirectUrl?: string): void;
+    /**
+     * Sets the authentication token.
+     *
+     * Updates the authorization header for API requests and optionally saves the token to local storage for persistence. Saving to local storage requires a browser environment and is automatically skipped in backend environments.
+     *
+     * @param token - JWT authentication token.
+     * @param saveToStorage - Whether to save the token to local storage. Defaults to true.
+     *
+     * @example
+     * ```typescript
+     * // Set token and save to local storage
+     * base44.auth.setToken('eyJhbGciOiJIUzI1NiIs...');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Set token without saving to local storage
+     * base44.auth.setToken('eyJhbGciOiJIUzI1NiIs...', false);
+     * ```
+     */
+    setToken(token: string, saveToStorage?: boolean): void;
+    /**
+     * Logs in a registered user using email and password.
+     *
+     * Authenticates a user with email and password credentials. The user must already have a registered account. For new users, use {@linkcode register | register()} first to create an account. On successful login, automatically sets the token for subsequent requests.
+     *
+     * @param email - User's email address.
+     * @param password - User's password.
+     * @param turnstileToken - Optional {@link https://developers.cloudflare.com/turnstile/ | Cloudflare Turnstile CAPTCHA token} for bot protection.
+     * @returns Promise resolving to login response with access token and user data.
+     * @throws Error if the email and password combination is invalid or the user is not registered.
+     *
+     * @example
+     * ```typescript
+     * // Login with email and password
+     * try {
+     *   const { access_token, user } = await base44.auth.loginViaEmailPassword(
+     *     'user@example.com',
+     *     'securePassword123'
+     *   );
+     *   console.log('Login successful!', user);
+     * } catch (error) {
+     *   console.error('Login failed:', error);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With captcha token
+     * const response = await base44.auth.loginViaEmailPassword(
+     *   'user@example.com',
+     *   'securePassword123',
+     *   'captcha-token-here'
+     * );
+     * ```
+     */
+    loginViaEmailPassword(email: string, password: string, turnstileToken?: string): Promise<LoginResponse>;
+    /**
+     * Checks if the current user is authenticated.
+     *
+     * @returns Promise resolving to true if authenticated, false otherwise.
+     *
+     * @example
+     * ```typescript
+     * // Check authentication status
+     * const isAuthenticated = await base44.auth.isAuthenticated();
+     * if (isAuthenticated) {
+     *   console.log('User is logged in');
+     * } else {
+     *   // Redirect to login page
+     *   base44.auth.redirectToLogin(window.location.href);
+     * }
+     * ```
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Invites a user to the app.
+     *
+     * Sends an invitation email to a potential user with a specific role.
+     * Roles are configured in the app settings and determine
+     * the user's permissions and access levels.
+     *
+     * @param userEmail - Email address of the user to invite.
+     * @param role - Role to assign to the invited user. Must match a role defined in the app. For example, `'admin'` or `'user'`.
+     * @returns Promise that resolves when the invitation is sent successfully. Throws an error if the invitation fails.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await base44.auth.inviteUser('newuser@example.com', 'user');
+     *   console.log('Invitation sent successfully!');
+     * } catch (error) {
+     *   console.error('Failed to send invitation:', error);
+     * }
+     * ```
+     */
+    inviteUser(userEmail: string, role: string): Promise<any>;
+    /**
+     * Registers a new user account.
+     *
+     * Creates a new user account with email and password. After successful registration,
+     * use {@linkcode loginViaEmailPassword | loginViaEmailPassword()} to log in the user.
+     *
+     * @param params - Registration details including email, password, and optional fields.
+     * @returns Promise resolving to the registration response.
+     *
+     * @example
+     * ```typescript
+     * // Register a new user
+     * await base44.auth.register({
+     *   email: 'newuser@example.com',
+     *   password: 'securePassword123',
+     *   referral_code: 'FRIEND2024'
+     * });
+     *
+     * // Login after registration
+     * const { access_token, user } = await base44.auth.loginViaEmailPassword(
+     *   'newuser@example.com',
+     *   'securePassword123'
+     * );
+     * ```
+     */
+    register(params: RegisterParams): Promise<any>;
+    /**
+     * Verifies an OTP (One-time password) code.
+     *
+     * Validates an OTP code sent to the user's email during registration
+     * or authentication.
+     *
+     * @param params - Object containing email and OTP code.
+     * @returns Promise resolving to the verification response if valid.
+     * @throws Error if the OTP code is invalid, expired, or verification fails.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await base44.auth.verifyOtp({
+     *     email: 'user@example.com',
+     *     otpCode: '123456'
+     *   });
+     *   console.log('Email verified successfully!');
+     * } catch (error) {
+     *   console.error('Invalid or expired OTP code');
+     * }
+     * ```
+     */
+    verifyOtp(params: VerifyOtpParams): Promise<any>;
+    /**
+     * Resends an OTP code to the user's email address.
+     *
+     * Requests a new OTP code to be sent to the specified email address.
+     *
+     * @param email - Email address to send the OTP to.
+     * @returns Promise resolving when the OTP is sent successfully.
+     * @throws Error if the email is invalid or the request fails.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await base44.auth.resendOtp('user@example.com');
+     *   console.log('OTP resent! Please check your email.');
+     * } catch (error) {
+     *   console.error('Failed to resend OTP:', error);
+     * }
+     * ```
+     */
+    resendOtp(email: string): Promise<any>;
+    /**
+     * Requests a password reset.
+     *
+     * Sends a password reset email to the specified email address.
+     *
+     * @param email - Email address for the account to reset.
+     * @returns Promise resolving when the password reset email is sent successfully.
+     * @throws Error if the email is invalid or the request fails.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await base44.auth.resetPasswordRequest('user@example.com');
+     *   console.log('Password reset email sent!');
+     * } catch (error) {
+     *   console.error('Failed to send password reset email:', error);
+     * }
+     * ```
+     */
+    resetPasswordRequest(email: string): Promise<any>;
+    /**
+     * Resets password using a reset token.
+     *
+     * Completes the password reset flow by setting a new password
+     * using the token received by email.
+     *
+     * @param params - Object containing the reset token and new password.
+     * @returns Promise resolving when the password is reset successfully.
+     * @throws Error if the reset token is invalid, expired, or the request fails.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await base44.auth.resetPassword({
+     *     resetToken: 'token-from-email',
+     *     newPassword: 'newSecurePassword456'
+     *   });
+     *   console.log('Password reset successful!');
+     * } catch (error) {
+     *   console.error('Failed to reset password:', error);
+     * }
+     * ```
+     */
+    resetPassword(params: ResetPasswordParams): Promise<any>;
+    /**
+     * Changes the user's password.
+     *
+     * Updates the password for an authenticated user by verifying
+     * the current password and setting a new one.
+     *
+     * @param params - Object containing user ID, current password, and new password.
+     * @returns Promise resolving when the password is changed successfully.
+     * @throws Error if the current password is incorrect or the request fails.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await base44.auth.changePassword({
+     *     userId: 'user-123',
+     *     currentPassword: 'oldPassword123',
+     *     newPassword: 'newSecurePassword456'
+     *   });
+     *   console.log('Password changed successfully!');
+     * } catch (error) {
+     *   console.error('Failed to change password:', error);
+     * }
+     * ```
+     */
+    changePassword(params: ChangePasswordParams): Promise<any>;
+}

package/dist/modules/auth.types.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/connectors.d.ts

@@ -1,16 +1,11 @@
 import { AxiosInstance } from "axios";
-import { ConnectorIntegrationType, ConnectorAccessTokenResponse } from "./connectors.types.js";
+import { ConnectorsModule } from "./connectors.types.js";
 /**
- * Creates the Connectors module for the Base44 SDK
+ * Creates the Connectors module for the Base44 SDK.
+ *
  * @param axios - Axios instance (should be service role client)
  * @param appId - Application ID
- * @returns Connectors module
+ * @returns Connectors module with methods to retrieve OAuth tokens
+ * @internal
  */
-export declare function createConnectorsModule(axios: AxiosInstance, appId: string): {
-    /**
-     * Retrieve an access token for a given integration type
-     * @param integrationType - The integration type to get access token for
-     * @returns Access token response
-     */
-    getAccessToken(integrationType: ConnectorIntegrationType): Promise<ConnectorAccessTokenResponse>;
-};
+export declare function createConnectorsModule(axios: AxiosInstance, appId: string): ConnectorsModule;

package/dist/modules/connectors.js

@@ -1,16 +1,15 @@
 /**
- * Creates the Connectors module for the Base44 SDK
+ * Creates the Connectors module for the Base44 SDK.
+ *
  * @param axios - Axios instance (should be service role client)
  * @param appId - Application ID
- * @returns Connectors module
+ * @returns Connectors module with methods to retrieve OAuth tokens
+ * @internal
  */
 export function createConnectorsModule(axios, appId) {
     return {
-        /**
-         * Retrieve an access token for a given integration type
-         * @param integrationType - The integration type to get access token for
-         * @returns Access token response
-         */
+        // Retrieve an OAuth access token for a specific external integration type
+        // @ts-expect-error Return type mismatch with interface - implementation returns object, interface expects string
         async getAccessToken(integrationType) {
             if (!integrationType || typeof integrationType !== "string") {
                 throw new Error("Integration type is required and must be a string");