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

package/dist/modules/entities.js

@@ -1,8 +1,10 @@
 /**
- * Creates the entities module for the Base44 SDK
- * @param {import('axios').AxiosInstance} axios - Axios instance
- * @param {string|number} appId - Application ID
- * @returns {Object} Entities module
+ * Creates the entities module for the Base44 SDK.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns Entities module with dynamic entity access
+ * @internal
  */
 export function createEntitiesModule(axios, appId) {
     // Using Proxy to dynamically handle entity names
@@ -20,23 +22,18 @@ export function createEntitiesModule(axios, appId) {
     });
 }
 /**
- * Creates a handler for a specific entity
- * @param {import('axios').AxiosInstance} axios - Axios instance
- * @param {string|number} appId - Application ID
- * @param {string} entityName - Entity name
- * @returns {Object} Entity handler with CRUD methods
+ * Creates a handler for a specific entity.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @param entityName - Entity name
+ * @returns Entity handler with CRUD methods
+ * @internal
  */
 function createEntityHandler(axios, appId, entityName) {
     const baseURL = `/apps/${appId}/entities/${entityName}`;
     return {
-        /**
-         * List entities with optional pagination and sorting
-         * @param {string} [sort] - Sort parameter
-         * @param {number} [limit] - Limit results
-         * @param {number} [skip] - Skip results (pagination)
-         * @param {string[]} [fields] - Fields to include
-         * @returns {Promise<Array>} List of entities
-         */
+        // List entities with optional pagination and sorting
         async list(sort, limit, skip, fields) {
             const params = {};
             if (sort)
@@ -49,15 +46,7 @@ function createEntityHandler(axios, appId, entityName) {
                 params.fields = Array.isArray(fields) ? fields.join(",") : fields;
             return axios.get(baseURL, { params });
         },
-        /**
-         * Filter entities based on query
-         * @param {Object} query - Filter query
-         * @param {string} [sort] - Sort parameter
-         * @param {number} [limit] - Limit results
-         * @param {number} [skip] - Skip results (pagination)
-         * @param {string[]} [fields] - Fields to include
-         * @returns {Promise<Array>} Filtered entities
-         */
+        // Filter entities based on query
         async filter(query, sort, limit, skip, fields) {
             const params = {
                 q: JSON.stringify(query),
@@ -72,60 +61,31 @@ function createEntityHandler(axios, appId, entityName) {
                 params.fields = Array.isArray(fields) ? fields.join(",") : fields;
             return axios.get(baseURL, { params });
         },
-        /**
-         * Get entity by ID
-         * @param {string} id - Entity ID
-         * @returns {Promise<Object>} Entity
-         */
+        // Get entity by ID
         async get(id) {
             return axios.get(`${baseURL}/${id}`);
         },
-        /**
-         * Create new entity
-         * @param {Object} data - Entity data
-         * @returns {Promise<Object>} Created entity
-         */
+        // Create new entity
         async create(data) {
             return axios.post(baseURL, data);
         },
-        /**
-         * Update entity by ID
-         * @param {string} id - Entity ID
-         * @param {Object} data - Updated entity data
-         * @returns {Promise<Object>} Updated entity
-         */
+        // Update entity by ID
         async update(id, data) {
             return axios.put(`${baseURL}/${id}`, data);
         },
-        /**
-         * Delete entity by ID
-         * @param {string} id - Entity ID
-         * @returns {Promise<void>}
-         */
+        // Delete entity by ID
         async delete(id) {
             return axios.delete(`${baseURL}/${id}`);
         },
-        /**
-         * Delete multiple entities based on query
-         * @param {Object} query - Delete query
-         * @returns {Promise<void>}
-         */
+        // Delete multiple entities based on query
         async deleteMany(query) {
             return axios.delete(baseURL, { data: query });
         },
-        /**
-         * Create multiple entities in a single request
-         * @param {Array} data - Array of entity data
-         * @returns {Promise<Array>} Created entities
-         */
+        // Create multiple entities in a single request
         async bulkCreate(data) {
             return axios.post(`${baseURL}/bulk`, data);
         },
-        /**
-         * Import entities from a file
-         * @param {File} file - File to import
-         * @returns {Promise<Object>} Import result
-         */
+        // Import entities from a file
         async importEntities(file) {
             const formData = new FormData();
             formData.append("file", file, file.name);

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

@@ -0,0 +1,293 @@
+/**
+ * Entity handler providing CRUD operations for a specific entity type.
+ *
+ * Each entity in the app gets a handler with these methods for managing data.
+ */
+export interface EntityHandler {
+    /**
+     * Lists records with optional pagination and sorting.
+     *
+     * Retrieves all records of this type with support for sorting,
+     * pagination, and field selection.
+     *
+     * @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
+     * @param limit - Maximum number of results to return. Defaults to `50`.
+     * @param skip - Number of results to skip for pagination. Defaults to `0`.
+     * @param fields - Array of field names to include in the response. Defaults to all fields.
+     * @returns Promise resolving to an array of records.
+     *
+     * @example
+     * ```typescript
+     * // Get all records
+     * const records = await base44.entities.MyEntity.list();
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get first 10 records sorted by date
+     * const recentRecords = await base44.entities.MyEntity.list('-created_date', 10);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get paginated results
+     * // Skip first 20, get next 10
+     * const page3 = await base44.entities.MyEntity.list('-created_date', 10, 20);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Get only specific fields
+     * const fields = await base44.entities.MyEntity.list('-created_date', 10, 0, ['name', 'status']);
+     * ```
+     */
+    list(sort?: string, limit?: number, skip?: number, fields?: string[]): Promise<any>;
+    /**
+     * Filters records based on a query.
+     *
+     * Retrieves records that match specific criteria with support for
+     * sorting, pagination, and field selection.
+     *
+     * @param query - Query object with field-value pairs. Each key should be a field name
+     * from your entity schema, and each value is the criteria to match. Records matching all
+     * specified criteria are returned. Field names are case-sensitive.
+     * @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
+     * @param limit - Maximum number of results to return. Defaults to `50`.
+     * @param skip - Number of results to skip for pagination. Defaults to `0`.
+     * @param fields - Array of field names to include in the response. Defaults to all fields.
+     * @returns Promise resolving to an array of filtered records.
+     *
+     * @example
+     * ```typescript
+     * // Filter by single field
+     * const activeRecords = await base44.entities.MyEntity.filter({
+     *   status: 'active'
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter by multiple fields
+     * const filteredRecords = await base44.entities.MyEntity.filter({
+     *   priority: 'high',
+     *   status: 'active'
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter with sorting and pagination
+     * const results = await base44.entities.MyEntity.filter(
+     *   { status: 'active' },
+     *   '-created_date',
+     *   20,
+     *   0
+     * );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter with specific fields
+     * const fields = await base44.entities.MyEntity.filter(
+     *   { priority: 'high' },
+     *   '-created_date',
+     *   10,
+     *   0,
+     *   ['name', 'priority']
+     * );
+     * ```
+     */
+    filter(query: Record<string, any>, sort?: string, limit?: number, skip?: number, fields?: string[]): Promise<any>;
+    /**
+     * Gets a single record by ID.
+     *
+     * Retrieves a specific record using its unique identifier.
+     *
+     * @param id - The unique identifier of the record.
+     * @returns Promise resolving to the record.
+     *
+     * @example
+     * ```typescript
+     * // Get record by ID
+     * const record = await base44.entities.MyEntity.get('entity-123');
+     * console.log(record.name);
+     * ```
+     */
+    get(id: string): Promise<any>;
+    /**
+     * Creates a new record.
+     *
+     * Creates a new record with the provided data.
+     *
+     * @param data - Object containing the record data.
+     * @returns Promise resolving to the created record.
+     *
+     * @example
+     * ```typescript
+     * // Create a new record
+     * const newRecord = await base44.entities.MyEntity.create({
+     *   name: 'My Item',
+     *   status: 'active',
+     *   priority: 'high'
+     * });
+     * console.log('Created record with ID:', newRecord.id);
+     * ```
+     */
+    create(data: Record<string, any>): Promise<any>;
+    /**
+     * Updates an existing record.
+     *
+     * Updates a record by ID with the provided data. Only the fields
+     * included in the data object will be updated.
+     *
+     * @param id - The unique identifier of the record to update.
+     * @param data - Object containing the fields to update.
+     * @returns Promise resolving to the updated record.
+     *
+     * @example
+     * ```typescript
+     * // Update single field
+     * const updated = await base44.entities.MyEntity.update('entity-123', {
+     *   status: 'completed'
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Update multiple fields
+     * const updated = await base44.entities.MyEntity.update('entity-123', {
+     *   name: 'Updated name',
+     *   priority: 'low',
+     *   status: 'active'
+     * });
+     * ```
+     */
+    update(id: string, data: Record<string, any>): Promise<any>;
+    /**
+     * Deletes a single record by ID.
+     *
+     * Permanently removes a record from the database.
+     *
+     * @param id - The unique identifier of the record to delete.
+     * @returns Promise resolving to the deletion result.
+     *
+     * @example
+     * ```typescript
+     * // Delete a record
+     * const result = await base44.entities.MyEntity.delete('entity-123');
+     * console.log('Deleted:', result);
+     * ```
+     */
+    delete(id: string): Promise<any>;
+    /**
+     * Deletes multiple records matching a query.
+     *
+     * Permanently removes all records that match the provided query.
+     *
+     * @param query - Query object with field-value pairs. Each key should be a field name
+     * from your entity schema, and each value is the criteria to match. Records matching all
+     * specified criteria will be deleted. Field names are case-sensitive.
+     * @returns Promise resolving to the deletion result.
+     *
+     * @example
+     * ```typescript
+     * // Delete by multiple criteria
+     * const result = await base44.entities.MyEntity.deleteMany({
+     *   status: 'completed',
+     *   priority: 'low'
+     * });
+     * console.log('Deleted:', result);
+     * ```
+     */
+    deleteMany(query: Record<string, any>): Promise<any>;
+    /**
+     * Creates multiple records in a single request.
+     *
+     * Efficiently creates multiple records at once. This is faster
+     * than creating them individually.
+     *
+     * @param data - Array of record data objects.
+     * @returns Promise resolving to an array of created records.
+     *
+     * @example
+     * ```typescript
+     * // Create multiple records at once
+     * const result = await base44.entities.MyEntity.bulkCreate([
+     *   { name: 'Item 1', status: 'active' },
+     *   { name: 'Item 2', status: 'active' },
+     *   { name: 'Item 3', status: 'completed' }
+     * ]);
+     * ```
+     */
+    bulkCreate(data: Record<string, any>[]): Promise<any>;
+    /**
+     * Imports records from a file.
+     *
+     * Imports records from a file, typically CSV or similar format.
+     * The file format should match your entity structure. Requires a browser environment and can't be used in the backend.
+     *
+     * @param file - File object to import.
+     * @returns Promise resolving to the import result.
+     *
+     * @example
+     * ```typescript
+     * // Import records from file in React
+     * const handleFileImport = async (event: React.ChangeEvent<HTMLInputElement>) => {
+     *   const file = event.target.files?.[0];
+     *   if (file) {
+     *     const result = await base44.entities.MyEntity.importEntities(file);
+     *     console.log(`Imported ${result.count} records`);
+     *   }
+     * };
+     * ```
+     */
+    importEntities(file: File): Promise<any>;
+}
+/**
+ * Entities module for managing app data.
+ *
+ * This module provides dynamic access to all entities in the app.
+ * Each entity gets a handler with full CRUD operations and additional utility methods.
+ *
+ * Entities are accessed dynamically using the pattern:
+ * `base44.entities.EntityName.method()`
+ *
+ * This module is available to use with a client in all three authentication modes:
+ *
+ * - **Anonymous or User authentication** (`base44.entities`): Access is scoped to the current user's permissions. Anonymous users can only access public entities, while authenticated users can access entities they have permission to view or modify.
+ * - **Service role authentication** (`base44.asServiceRole.entities`): Operations have elevated admin-level permissions. Can access all entities that the app's admin role has access to.
+ *
+ * ## Built-in User Entity
+ *
+ * Every app includes a built-in `User` entity that stores user account information. This entity has special security rules that can't be changed.
+ *
+ * Regular users can only read and update their own user record. With service role authentication, you can read, update, and delete any user. You can't create users using the entities module. Instead, use the functions of the {@link AuthModule | auth module} to invite or register new users.
+ *
+ * @example
+ * ```typescript
+ * // Get all records from the MyEntity entity
+ * // Get all records the current user has permissions to view
+ * const myRecords = await base44.entities.MyEntity.list();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // List all users (admin only)
+ * const allUsers = await base44.asServiceRole.entities.User.list();
+ * ```
+ */
+export interface EntitiesModule {
+    /**
+     * Access any entity by name.
+     *
+     * Use this to access entities defined in the app.
+     *
+     * @example
+     * ```typescript
+     * // Access entities dynamically
+     * base44.entities.MyEntity
+     * base44.entities.AnotherEntity
+     * ```
+     */
+    [entityName: string]: EntityHandler;
+}

package/dist/modules/entities.types.js

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

package/dist/modules/functions.d.ts

@@ -1,10 +1,11 @@
 import { AxiosInstance } from "axios";
+import { FunctionsModule } from "./functions.types";
 /**
- * Creates the functions module for the Base44 SDK
- * @param {import('axios').AxiosInstance} axios - Axios instance
- * @param {string|number} appId - Application ID
- * @returns {Object} Functions module
+ * Creates the functions module for the Base44 SDK.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns Functions module with methods to invoke custom backend functions
+ * @internal
  */
-export declare function createFunctionsModule(axios: AxiosInstance, appId: string): {
-    invoke(functionName: string, data: Record<string, any>): Promise<import("axios").AxiosResponse<any, any>>;
-};
+export declare function createFunctionsModule(axios: AxiosInstance, appId: string): FunctionsModule;

package/dist/modules/functions.js

@@ -1,12 +1,14 @@
 /**
- * Creates the functions module for the Base44 SDK
- * @param {import('axios').AxiosInstance} axios - Axios instance
- * @param {string|number} appId - Application ID
- * @returns {Object} Functions module
+ * Creates the functions module for the Base44 SDK.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns Functions module with methods to invoke custom backend functions
+ * @internal
  */
 export function createFunctionsModule(axios, appId) {
-    // Using nested Proxy objects to handle dynamic function names
     return {
+        // Invoke a custom backend function by name
         async invoke(functionName, data) {
             // Validate input
             if (typeof data === "string") {

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

@@ -0,0 +1,50 @@
+/**
+ * Functions module for invoking custom backend functions.
+ *
+ * This module allows you to invoke the custom backend functions defined in the app.
+ *
+ * This module is available to use with a client in all authentication modes:
+ *
+ * - **Anonymous or User authentication** (`base44.functions`): Functions are invoked with the current user's permissions. Anonymous users invoke functions without authentication, while authenticated users invoke functions with their authentication context.
+ * - **Service role authentication** (`base44.asServiceRole.functions`): Functions are invoked with elevated admin-level permissions. The function code receives a request with admin authentication context.
+ */
+export interface FunctionsModule {
+    /**
+     * Invokes a custom backend function by name.
+     *
+     * Calls a custom backend function deployed to the app.
+     * The function receives the provided data as named parameters and returns
+     * the result. If any parameter is a `File` object, the request will automatically be
+     * sent as `multipart/form-data`. Otherwise, it will be sent as JSON.
+     *
+     * @param functionName - The name of the function to invoke.
+     * @param data - An object containing named parameters for the function.
+     * @returns Promise resolving to the function's response. The `data` property contains the data returned by the function, if there is any.
+     *
+     * @example
+     * ```typescript
+     * // Basic function call
+     * const result = await base44.functions.invoke('calculateTotal', {
+     *   items: ['item1', 'item2'],
+     *   discount: 0.1
+     * });
+     * console.log(result.data.total);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Function with file upload in React
+     * const handleFileUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
+     *   const file = event.target.files?.[0];
+     *   if (file) {
+     *     const processedImage = await base44.functions.invoke('processImage', {
+     *       image: file,
+     *       filter: 'grayscale',
+     *       quality: 80
+     *     });
+     *   }
+     * };
+     * ```
+     */
+    invoke(functionName: string, data: Record<string, any>): Promise<any>;
+}

package/dist/modules/functions.types.js

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

package/dist/modules/integrations.d.ts

@@ -1,8 +1,11 @@
 import { AxiosInstance } from "axios";
+import { IntegrationsModule } from "./integrations.types";
 /**
- * Creates the integrations module for the Base44 SDK
- * @param {import('axios').AxiosInstance} axios - Axios instance
- * @param {string|number} appId - Application ID
- * @returns {Object} Integrations module
+ * Creates the integrations module for the Base44 SDK.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns Integrations module with dynamic access to integration endpoints
+ * @internal
  */
-export declare function createIntegrationsModule(axios: AxiosInstance, appId: string): {};
+export declare function createIntegrationsModule(axios: AxiosInstance, appId: string): IntegrationsModule;

package/dist/modules/integrations.js

@@ -1,11 +1,12 @@
 /**
- * Creates the integrations module for the Base44 SDK
- * @param {import('axios').AxiosInstance} axios - Axios instance
- * @param {string|number} appId - Application ID
- * @returns {Object} Integrations module
+ * Creates the integrations module for the Base44 SDK.
+ *
+ * @param axios - Axios instance
+ * @param appId - Application ID
+ * @returns Integrations module with dynamic access to integration endpoints
+ * @internal
  */
 export function createIntegrationsModule(axios, appId) {
-    // Using nested Proxy objects to handle dynamic package and endpoint names
     return new Proxy({}, {
         get(target, packageName) {
             // Skip internal properties
@@ -24,6 +25,7 @@ export function createIntegrationsModule(axios, appId) {
                         return undefined;
                     }
                     // Return a function that calls the integration endpoint
+                    // This allows: client.integrations.PackageName.EndpointName(data)
                     return async (data) => {
                         // Validate input
                         if (typeof data === "string") {