@base44-preview/sdk 0.8.5-pr.52.e60528e → 0.8.6-pr.48.d625f02

package/dist/utils/auth-utils.d.ts

@@ -1,55 +1,117 @@
+import { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions } from "./auth-utils.types.js";
 /**
- * Utility functions for authentication and token handling
- */
-/**
- * Retrieves an access token from either localStorage or URL parameters
- *
- * @param {Object} options - Configuration options
- * @param {string} [options.storageKey='base44_access_token'] - The key to use in localStorage
- * @param {string} [options.paramName='access_token'] - The URL parameter name
- * @param {boolean} [options.saveToStorage=true] - Whether to save the token to localStorage if found in URL
- * @param {boolean} [options.removeFromUrl=true] - Whether to remove the token from URL after retrieval
- * @returns {string|null} The access token or null if not found
+ * Retrieves an access token from URL parameters or local storage.
+ *
+ * Low-level utility for manually retrieving tokens. In most cases, the Base44 client handles
+ * token management automatically. This function is useful for custom authentication flows or when you need direct access to stored tokens. Requires a browser environment and can't be used in the backend.
+ *
+ * @internal
+ *
+ * @param options - Configuration options for token retrieval.
+ * @returns The access token string if found, null otherwise.
+ *
+ * @example
+ * ```typescript
+ * // Get access token from URL or local storage
+ * const token = getAccessToken();
+ *
+ * if (token) {
+ *   console.log('User is authenticated');
+ * } else {
+ *   console.log('No token found, redirect to login');
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * // Get access token from custom local storage key
+ * const token = getAccessToken({ storageKey: 'my_app_token' });
+ * ```
+ * @example
+ * ```typescript
+ * // Get access token from URL but don't save or remove it
+ * const token = getAccessToken({
+ *   saveToStorage: false,
+ *   removeFromUrl: false
+ * });
+ * ```
  */
-export declare function getAccessToken(options?: {
-    storageKey?: string;
-    paramName?: string;
-    saveToStorage?: boolean;
-    removeFromUrl?: boolean;
-}): string | null;
+export declare function getAccessToken(options?: GetAccessTokenOptions): string | null;
 /**
- * Saves an access token to localStorage
+ * Saves an access token to local storage.
+ *
+ * Low-level utility for manually saving tokens. In most cases, the Base44 client handles token management automatically. This function is useful for custom authentication flows or managing custom tokens. Requires a browser environment and can't be used in the backend.
+ *
+ * @internal
+ *
+ * @param token - The access token string to save.
+ * @param options - Configuration options for saving the token.
+ * @returns Returns`true` if the token was saved successfully, `false` otherwise.
  *
- * @param {string} token - The access token to save
- * @param {Object} options - Configuration options
- * @param {string} [options.storageKey='base44_access_token'] - The key to use in localStorage
- * @returns {boolean} Success status
+ * @example
+ * ```typescript
+ * // Save access token after login
+ * const response = await base44.auth.loginViaEmailPassword(email, password);
+ * const success = saveAccessToken(response.access_token, {});
+ *
+ * if (success) {
+ *   console.log('User is now authenticated');
+ *   // Token is now available for future page loads
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * // Save access token to local storage using custom key
+ * const success = saveAccessToken(token, {
+ *   storageKey: `my_custom_token_key`
+ * });
+ * ```
  */
-export declare function saveAccessToken(token: string, options: {
-    storageKey?: string;
-}): boolean;
+export declare function saveAccessToken(token: string, options: SaveAccessTokenOptions): boolean;
 /**
- * Removes the access token from localStorage
+ * Removes the access token from local storage.
+ *
+ * Low-level utility for manually removing tokens from the browser's local storage. In most cases, the Base44 client handles token management automatically. For standard logout flows, use {@linkcode AuthModule.logout | base44.auth.logout()} instead, which handles token removal and redirects automatically. This function is useful for custom authentication flows or when you need to manually remove tokens. Requires a browser environment and can't be used in the backend.
+ *
+ * @internal
+ *
+ * @param options - Configuration options for token removal.
+ * @returns Returns `true` if the token was removed successfully, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * // Remove custom token key
+ * const success = removeAccessToken({
+ *   storageKey: 'my_custom_token_key'
+ * });
+ * ```
  *
- * @param {Object} options - Configuration options
- * @param {string} [options.storageKey='base44_access_token'] - The key to use in localStorage
- * @returns {boolean} Success status
+ * @example
+ * ```typescript
+ * // Standard logout flow with token removal and redirect
+ * base44.auth.logout('/login');
+ * ```
  */
-export declare function removeAccessToken(options: {
-    storageKey?: string;
-}): boolean;
+export declare function removeAccessToken(options: RemoveAccessTokenOptions): boolean;
 /**
- * Constructs the absolute URL for the login page
- *
- * @param {string} nextUrl - URL to redirect back to after login
- * @param {Object} options - Configuration options
- * @param {string} options.serverUrl - Server URL (e.g., 'https://base44.app')
- * @param {string|number} options.appId - Application ID
- * @param {string} [options.loginPath='/login'] - Path to the login endpoint
- * @returns {string} The complete login URL
+ * Constructs the absolute URL for the login page with a redirect parameter.
+ *
+ * Low-level utility for building login URLs. For standard login redirects, use {@linkcode AuthModule.redirectToLogin | base44.auth.redirectToLogin()} instead, which handles this automatically. This function is useful when you need to construct login URLs without a client instance or for custom authentication flows.
+ *
+ * @internal
+ *
+ * @param nextUrl - The URL to redirect to after successful login.
+ * @param options - Configuration options.
+ * @returns The complete login URL with encoded redirect parameters.
+ *
+ * @example
+ * ```typescript
+ * // Redirect to login page
+ * const loginUrl = getLoginUrl('/dashboard', {
+ *   serverUrl: 'https://base44.app',
+ *   appId: 'my-app-123'
+ * });
+ * window.location.href = loginUrl;
+ * // User will be redirected back to /dashboard after login
+ * ```
  */
-export declare function getLoginUrl(nextUrl: string, options: {
-    serverUrl: string;
-    appId: string;
-    loginPath?: string;
-}): string;
+export declare function getLoginUrl(nextUrl: string, options: GetLoginUrlOptions): string;

package/dist/utils/auth-utils.js

@@ -1,15 +1,38 @@
 /**
- * Utility functions for authentication and token handling
- */
-/**
- * Retrieves an access token from either localStorage or URL parameters
- *
- * @param {Object} options - Configuration options
- * @param {string} [options.storageKey='base44_access_token'] - The key to use in localStorage
- * @param {string} [options.paramName='access_token'] - The URL parameter name
- * @param {boolean} [options.saveToStorage=true] - Whether to save the token to localStorage if found in URL
- * @param {boolean} [options.removeFromUrl=true] - Whether to remove the token from URL after retrieval
- * @returns {string|null} The access token or null if not found
+ * Retrieves an access token from URL parameters or local storage.
+ *
+ * Low-level utility for manually retrieving tokens. In most cases, the Base44 client handles
+ * token management automatically. This function is useful for custom authentication flows or when you need direct access to stored tokens. Requires a browser environment and can't be used in the backend.
+ *
+ * @internal
+ *
+ * @param options - Configuration options for token retrieval.
+ * @returns The access token string if found, null otherwise.
+ *
+ * @example
+ * ```typescript
+ * // Get access token from URL or local storage
+ * const token = getAccessToken();
+ *
+ * if (token) {
+ *   console.log('User is authenticated');
+ * } else {
+ *   console.log('No token found, redirect to login');
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * // Get access token from custom local storage key
+ * const token = getAccessToken({ storageKey: 'my_app_token' });
+ * ```
+ * @example
+ * ```typescript
+ * // Get access token from URL but don't save or remove it
+ * const token = getAccessToken({
+ *   saveToStorage: false,
+ *   removeFromUrl: false
+ * });
+ * ```
  */
 export function getAccessToken(options = {}) {
     const { storageKey = "base44_access_token", paramName = "access_token", saveToStorage = true, removeFromUrl = true, } = options;
@@ -21,7 +44,7 @@ export function getAccessToken(options = {}) {
             token = urlParams.get(paramName);
             // If token found in URL
             if (token) {
-                // Save token to localStorage if requested
+                // Save token to local storage if requested
                 if (saveToStorage) {
                     saveAccessToken(token, { storageKey });
                 }
@@ -38,25 +61,47 @@ export function getAccessToken(options = {}) {
             console.error("Error retrieving token from URL:", e);
         }
     }
-    // If no token in URL, try localStorage
+    // If no token in URL, try local storage
     if (typeof window !== "undefined" && window.localStorage) {
         try {
             token = window.localStorage.getItem(storageKey);
             return token;
         }
         catch (e) {
-            console.error("Error retrieving token from localStorage:", e);
+            console.error("Error retrieving token from local storage:", e);
         }
     }
     return null;
 }
 /**
- * Saves an access token to localStorage
+ * Saves an access token to local storage.
+ *
+ * Low-level utility for manually saving tokens. In most cases, the Base44 client handles token management automatically. This function is useful for custom authentication flows or managing custom tokens. Requires a browser environment and can't be used in the backend.
+ *
+ * @internal
+ *
+ * @param token - The access token string to save.
+ * @param options - Configuration options for saving the token.
+ * @returns Returns`true` if the token was saved successfully, `false` otherwise.
  *
- * @param {string} token - The access token to save
- * @param {Object} options - Configuration options
- * @param {string} [options.storageKey='base44_access_token'] - The key to use in localStorage
- * @returns {boolean} Success status
+ * @example
+ * ```typescript
+ * // Save access token after login
+ * const response = await base44.auth.loginViaEmailPassword(email, password);
+ * const success = saveAccessToken(response.access_token, {});
+ *
+ * if (success) {
+ *   console.log('User is now authenticated');
+ *   // Token is now available for future page loads
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * // Save access token to local storage using custom key
+ * const success = saveAccessToken(token, {
+ *   storageKey: `my_custom_token_key`
+ * });
+ * ```
  */
 export function saveAccessToken(token, options) {
     const { storageKey = "base44_access_token" } = options;
@@ -70,16 +115,33 @@ export function saveAccessToken(token, options) {
         return true;
     }
     catch (e) {
-        console.error("Error saving token to localStorage:", e);
+        console.error("Error saving token to local storage:", e);
         return false;
     }
 }
 /**
- * Removes the access token from localStorage
+ * Removes the access token from local storage.
+ *
+ * Low-level utility for manually removing tokens from the browser's local storage. In most cases, the Base44 client handles token management automatically. For standard logout flows, use {@linkcode AuthModule.logout | base44.auth.logout()} instead, which handles token removal and redirects automatically. This function is useful for custom authentication flows or when you need to manually remove tokens. Requires a browser environment and can't be used in the backend.
+ *
+ * @internal
+ *
+ * @param options - Configuration options for token removal.
+ * @returns Returns `true` if the token was removed successfully, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * // Remove custom token key
+ * const success = removeAccessToken({
+ *   storageKey: 'my_custom_token_key'
+ * });
+ * ```
  *
- * @param {Object} options - Configuration options
- * @param {string} [options.storageKey='base44_access_token'] - The key to use in localStorage
- * @returns {boolean} Success status
+ * @example
+ * ```typescript
+ * // Standard logout flow with token removal and redirect
+ * base44.auth.logout('/login');
+ * ```
  */
 export function removeAccessToken(options) {
     const { storageKey = "base44_access_token" } = options;
@@ -91,19 +153,31 @@ export function removeAccessToken(options) {
         return true;
     }
     catch (e) {
-        console.error("Error removing token from localStorage:", e);
+        console.error("Error removing token from local storage:", e);
         return false;
     }
 }
 /**
- * Constructs the absolute URL for the login page
- *
- * @param {string} nextUrl - URL to redirect back to after login
- * @param {Object} options - Configuration options
- * @param {string} options.serverUrl - Server URL (e.g., 'https://base44.app')
- * @param {string|number} options.appId - Application ID
- * @param {string} [options.loginPath='/login'] - Path to the login endpoint
- * @returns {string} The complete login URL
+ * Constructs the absolute URL for the login page with a redirect parameter.
+ *
+ * Low-level utility for building login URLs. For standard login redirects, use {@linkcode AuthModule.redirectToLogin | base44.auth.redirectToLogin()} instead, which handles this automatically. This function is useful when you need to construct login URLs without a client instance or for custom authentication flows.
+ *
+ * @internal
+ *
+ * @param nextUrl - The URL to redirect to after successful login.
+ * @param options - Configuration options.
+ * @returns The complete login URL with encoded redirect parameters.
+ *
+ * @example
+ * ```typescript
+ * // Redirect to login page
+ * const loginUrl = getLoginUrl('/dashboard', {
+ *   serverUrl: 'https://base44.app',
+ *   appId: 'my-app-123'
+ * });
+ * window.location.href = loginUrl;
+ * // User will be redirected back to /dashboard after login
+ * ```
  */
 export function getLoginUrl(nextUrl, options) {
     const { serverUrl, appId, loginPath = "/login" } = options;

package/dist/utils/auth-utils.types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Configuration options for retrieving an access token.
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * // Get access token from URL or local storage using default options
+ * const token = getAccessToken();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Get access token from custom local storage key
+ * const token = getAccessToken({ storageKey: 'my_app_token' });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Get token from URL but don't save or remove from URL
+ * const token = getAccessToken({
+ *   saveToStorage: false,
+ *   removeFromUrl: false
+ * });
+ * ```
+ */
+export interface GetAccessTokenOptions {
+    /**
+     * The key to use when storing or retrieving the token in local storage.
+     * @default 'base44_access_token'
+     */
+    storageKey?: string;
+    /**
+     * The URL parameter name to check for the access token.
+     * @default 'access_token'
+     */
+    paramName?: string;
+    /**
+     * Whether to save the token to local storage if found in the URL.
+     * @default true
+     */
+    saveToStorage?: boolean;
+    /**
+     * Whether to remove the token from the URL after retrieval for security.
+     * @default true
+     */
+    removeFromUrl?: boolean;
+}
+/**
+ * Configuration options for saving an access token.
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * // Use default storage key
+ * saveAccessToken('my-token-123', {});
+ *
+ * // Use custom storage key
+ * saveAccessToken('my-token-123', { storageKey: 'my_app_token' });
+ * ```
+ */
+export interface SaveAccessTokenOptions {
+    /**
+     * The key to use when storing the token in local storage.
+     * @default 'base44_access_token'
+     */
+    storageKey?: string;
+}
+/**
+ * Configuration options for removing an access token.
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * // Remove token from default storage key
+ * removeAccessToken({});
+ *
+ * // Remove token from custom storage key
+ * removeAccessToken({ storageKey: 'my_app_token' });
+ * ```
+ */
+export interface RemoveAccessTokenOptions {
+    /**
+     * The key to use when removing the token from local storage.
+     * @default 'base44_access_token'
+     */
+    storageKey?: string;
+}
+/**
+ * Configuration options for constructing a login URL.
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const loginUrl = getLoginUrl('/dashboard', {
+ *   serverUrl: 'https://base44.app',
+ *   appId: 'my-app-123'
+ * });
+ * // Returns: 'https://base44.app/login?from_url=%2Fdashboard&app_id=my-app-123'
+ *
+ * // Custom login path
+ * const loginUrl = getLoginUrl('/dashboard', {
+ *   serverUrl: 'https://base44.app',
+ *   appId: 'my-app-123',
+ *   loginPath: '/auth/login'
+ * });
+ * ```
+ */
+export interface GetLoginUrlOptions {
+    /**
+     * The base server URL (e.g., 'https://base44.app').
+     */
+    serverUrl: string;
+    /**
+     * The app ID.
+     */
+    appId: string;
+    /**
+     * The path to the login endpoint.
+     * @default '/login'
+     */
+    loginPath?: string;
+}
+/**
+ * Type definition for getAccessToken function.
+ * @internal
+ */
+export type GetAccessTokenFunction = (options?: GetAccessTokenOptions) => string | null;
+/**
+ * Type definition for saveAccessToken function.
+ * @internal
+ */
+export type SaveAccessTokenFunction = (token: string, options: SaveAccessTokenOptions) => boolean;
+/**
+ * Type definition for removeAccessToken function.
+ * @internal
+ */
+export type RemoveAccessTokenFunction = (options: RemoveAccessTokenOptions) => boolean;
+/**
+ * Type definition for getLoginUrl function.
+ * @internal
+ */
+export type GetLoginUrlFunction = (nextUrl: string, options: GetLoginUrlOptions) => string;

package/dist/utils/auth-utils.types.js

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

package/dist/utils/axios-client.d.ts

@@ -1,27 +1,94 @@
+import type { Base44ErrorJSON } from "./axios-client.types.js";
+/**
+ * Custom error class for Base44 SDK errors.
+ *
+ * This error is thrown when API requests fail. It extends the standard `Error` class and includes additional information about the HTTP status, error code, and response data from the server.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.entities.Todo.get('invalid-id');
+ * } catch (error) {
+ *   if (error instanceof Base44Error) {
+ *     console.error('Status:', error.status);      // 404
+ *     console.error('Message:', error.message);    // "Not found"
+ *     console.error('Code:', error.code);          // "NOT_FOUND"
+ *     console.error('Data:', error.data);          // Full response data
+ *   }
+ * }
+ * ```
+ *
+ */
 export declare class Base44Error extends Error {
+    /**
+     * HTTP status code of the error.
+     */
     status: number;
+    /**
+     * Error code from the API.
+     */
     code: string;
+    /**
+     * Full response data from the server containing error details.
+     */
     data: any;
+    /**
+     * The original error object from Axios.
+     */
     originalError: unknown;
+    /**
+     * Creates a new Base44Error instance.
+     *
+     * @param message - Human-readable error message
+     * @param status - HTTP status code
+     * @param code - Error code from the API
+     * @param data - Full response data from the server
+     * @param originalError - Original axios error object
+     * @internal
+     */
     constructor(message: string, status: number, code: string, data: any, originalError: unknown);
-    toJSON(): {
-        name: string;
-        message: string;
-        status: number;
-        code: string;
-        data: any;
-    };
+    /**
+     * Serializes the error to a JSON-safe object.
+     *
+     * Useful for logging or sending error information to external services
+     * without circular reference issues.
+     *
+     * @returns JSON-safe representation of the error.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await client.entities.Todo.get('invalid-id');
+     * } catch (error) {
+     *   if (error instanceof Base44Error) {
+     *     const json = error.toJSON();
+     *     console.log(json);
+     *     // {
+     *     //   name: "Base44Error",
+     *     //   message: "Not found",
+     *     //   status: 404,
+     *     //   code: "NOT_FOUND",
+     *     //   data: { ... }
+     *     // }
+     *   }
+     * }
+     * ```
+     */
+    toJSON(): Base44ErrorJSON;
 }
 /**
- * Creates an axios client with default configuration and interceptors
- * @param {Object} options - Client configuration options
- * @param {string} options.baseURL - Base URL for all requests
- * @param {Object} options.headers - Additional headers
- * @param {string} options.token - Auth token
- * @param {boolean} options.requiresAuth - Whether the application requires authentication
- * @param {string|number} options.appId - Application ID (needed for login redirect)
- * @param {string} options.serverUrl - Server URL (needed for login redirect)
- * @returns {import('axios').AxiosInstance} Configured axios instance
+ * Creates an axios client with default configuration and interceptors.
+ *
+ * Sets up an axios instance with:
+ * - Default headers
+ * - Authentication token injection
+ * - Response data unwrapping
+ * - Error transformation to Base44Error
+ * - iframe messaging support
+ *
+ * @param options - Client configuration options
+ * @returns Configured axios instance
+ * @internal
  */
 export declare function createAxiosClient({ baseURL, headers, token, interceptResponses, onError, }: {
     baseURL: string;
@@ -30,3 +97,4 @@ export declare function createAxiosClient({ baseURL, headers, token, interceptRe
     interceptResponses?: boolean;
     onError?: (error: Error) => void;
 }): import("axios").AxiosInstance;
+export type { Base44ErrorJSON } from "./axios-client.types.js";