@base44/sdk 0.8.18 → 0.8.19

package/README.md

@@ -1,22 +1,42 @@
 # Base44 JavaScript SDK
 
-The Base44 SDK provides a JavaScript interface for building apps on the Base44 platform. When Base44 generates your app, the generated code uses the SDK to authenticate users, manage your app's data, interact with AI agents, and more. You can then use the same SDK to modify and extend your app.
+The Base44 SDK provides a JavaScript interface for building apps on the Base44 platform. 
+
+You can use it in two ways:
+
+- **Inside Base44 apps**: When Base44 generates your app, the SDK is already set up and ready to use.
+- **External apps**: Use the SDK to build your own frontend or backend that uses Base44 as a backend service.
+
+## Installation
+
+**Inside Base44 apps**: The SDK is already available. No installation needed.
+
+**External apps**: Install the SDK via npm:
+
+```bash
+npm install @base44/sdk
+```
 
 ## Modules
 
 The SDK provides access to Base44's functionality through the following modules:
 
-- **[`agents`](https://docs.base44.com/sdk-docs/interfaces/agents)**: Interact with AI agents and manage conversations.
-- **[`app-logs`](https://docs.base44.com/sdk-docs/interfaces/app-logs)**: Access and query app logs.
-- **[`auth`](https://docs.base44.com/sdk-docs/interfaces/auth)**: Manage user authentication, registration, and session handling.
-- **[`connectors`](https://docs.base44.com/sdk-docs/interfaces/connectors)**: Manage OAuth connections and access tokens for third-party services.
-- **[`entities`](https://docs.base44.com/sdk-docs/interfaces/entities)**: Work with your app's data entities using CRUD operations.
-- **[`functions`](https://docs.base44.com/sdk-docs/interfaces/functions)**: Execute backend functions.
-- **[`integrations`](https://docs.base44.com/sdk-docs/type-aliases/integrations)**: Pre-built server-side functions for external services.
+- **[`agents`](https://docs.base44.com/developers/references/sdk/docs/interfaces/agents)**: Interact with AI agents and manage conversations.
+- **[`analytics`](https://docs.base44.com/developers/references/sdk/docs/interfaces/analytics)**: Track custom events in your app.
+- **[`app-logs`](https://docs.base44.com/developers/references/sdk/docs/interfaces/app-logs)**: Access and query app logs.
+- **[`auth`](https://docs.base44.com/developers/references/sdk/docs/interfaces/auth)**: Manage user authentication, registration, and session handling.
+- **[`connectors`](https://docs.base44.com/developers/references/sdk/docs/interfaces/connectors)**: Manage OAuth connections and access tokens for third-party services.
+- **[`entities`](https://docs.base44.com/developers/references/sdk/docs/interfaces/entities)**: Work with your app's data entities using CRUD operations.
+- **[`functions`](https://docs.base44.com/developers/references/sdk/docs/interfaces/functions)**: Execute backend functions.
+- **[`integrations`](https://docs.base44.com/developers/references/sdk/docs/type-aliases/integrations)**: Access pre-built and third-party integrations.
+
+## Quickstarts
 
-## Example
+How you get started depends on whether you're working inside a Base44-generated app or building your own.
 
-Here's a quick look at working with data in the SDK, using the `entities` module to create, update, and list records. In this example, we're working with a custom `Task` entity:
+### Inside Base44 apps
+
+In Base44-generated apps, the client is pre-configured. Just import and use it:
 
 ```typescript
 import { base44 } from "@/api/base44Client";
@@ -37,14 +57,63 @@ await base44.entities.Task.update(newTask.id, {
 const tasks = await base44.entities.Task.list();
 ```
 
+### External apps
+
+When using Base44 as a backend for your own app, install the SDK and create the client yourself:
+
+```typescript
+import { createClient } from "@base44/sdk";
+
+// Create a client for your Base44 app
+const base44 = createClient({
+  appId: "your-app-id", // Find this in the Base44 editor URL
+});
+
+// Read public data
+const products = await base44.entities.Products.list();
+
+// Authenticate a user (token is automatically set)
+await base44.auth.loginViaEmailPassword("user@example.com", "password");
+
+// Access user's data
+const userOrders = await base44.entities.Orders.list();
+```
+
+### Service role
+
+By default, the client operates with user-level permissions, limiting access to what the current user can see and do. The service role provides elevated permissions for backend operations and is only available in Base44-hosted backend functions. External backends can't use service role permissions.
+
+```typescript
+import { createClientFromRequest } from "npm:@base44/sdk";
+
+Deno.serve(async (req) => {
+  const base44 = createClientFromRequest(req);
+
+  // Access all data with admin-level permissions
+  const allOrders = await base44.asServiceRole.entities.Orders.list();
+
+  return Response.json({ orders: allOrders });
+});
+```
+
 ## Learn more
 
-For complete documentation, guides, and API reference, visit the **[Base44 SDK Documentation](https://docs.base44.com/sdk-getting-started/overview)**.
+The best way to get started with the JavaScript SDK is to have Base44 build an app for you. Once you have an app, you can explore the generated code and experiment with the SDK to see how it works in practice. You can also ask Base44 to demonstrate specific features of the SDK.
+
+For a deeper understanding, check out these guides:
+
+1. [Base44 client](https://docs.base44.com/developers/references/sdk/getting-started/client) - Work with the client in frontend, backend, and external app contexts.
+2. [Work with data](https://docs.base44.com/developers/references/sdk/getting-started/work-with-data) - Create, read, update, and delete data.
+3. [Common SDK patterns](https://docs.base44.com/developers/references/sdk/getting-started/work-with-sdk) - Authentication, integrations, functions, and error handling.
+
+For the complete documentation and API reference, visit the **[Base44 Developer Docs](https://docs.base44.com/developers/home)**.
 
 ## Development
 
 ### Build the SDK
 
+Build the SDK from source:
+
 ```bash
 npm install
 npm run build
@@ -52,6 +121,8 @@ npm run build
 
 ### Run tests
 
+Run the test suite:
+
 ```bash
 # Run all tests
 npm test
@@ -64,6 +135,7 @@ npm run test:coverage
 ```
 
 For E2E tests, create a `tests/.env` file with:
+
 ```
 BASE44_APP_ID=your_app_id
 BASE44_AUTH_TOKEN=your_auth_token

package/dist/client.d.ts

@@ -5,12 +5,14 @@ export type { Base44Client, CreateClientConfig, CreateClientOptions };
  *
  * This is the main entry point for the Base44 SDK. It creates a client that provides access to the SDK's modules, such as {@linkcode EntitiesModule | entities}, {@linkcode AuthModule | auth}, and {@linkcode FunctionsModule | functions}.
  *
- * Typically, you don't need to call this function because Base44 creates the client for you. You can then import and use the client to make API calls. The client takes care of managing authentication for you.
+ * How you get a client depends on your context:
+ * - **Inside a Base44 app:** The client is automatically created and configured for you. Import it from `@/api/base44Client`.
+ * - **External app using Base44 as a backend:** Call `createClient()` directly in your code to create and configure the client.
  *
  * The client supports three authentication modes:
- * - **Anonymous**: Access modules anonymously without authentication using `base44.moduleName`. Operations are scoped to public data and permissions.
- * - **User authentication**: Access modules with user-level permissions using `base44.moduleName`. Operations are scoped to the authenticated user's data and permissions.
- * - **Service role authentication**: Access modules with elevated permissions using `base44.asServiceRole.moduleName`. Operations can access any data available to the app's admin. Can only be used in the backend. Typically, you create a client with service role authentication using the {@linkcode createClientFromRequest | createClientFromRequest()} function in your backend functions.
+ * - **Anonymous**: Access modules without authentication using `base44.moduleName`. Operations are scoped to public data and permissions.
+ * - **User authentication**: Access modules with user-level permissions using `base44.moduleName`. Operations are scoped to the authenticated user's data and permissions. Use `base44.auth.loginViaEmailPassword()` or other auth methods to get a token.
+ * - **Service role authentication**: Access modules with elevated permissions using `base44.asServiceRole.moduleName`. Operations can access any data available to the app's admin. Only available in Base44-hosted backend functions. Create a client with service role authentication using {@linkcode createClientFromRequest | createClientFromRequest()}.
  *
  * For example, when using the {@linkcode EntitiesModule | entities} module:
  * - **Anonymous**: Can only read public data.
@@ -39,7 +41,9 @@ export declare function createClient(config: CreateClientConfig): Base44Client;
 /**
  * Creates a Base44 client from an HTTP request.
  *
- * The client is created by automatically extracting authentication tokens from a request to a backend function. Base44 inserts the necessary headers when forwarding requests to backend functions.
+ * This function is designed for use in Base44-hosted backend functions. For frontends and external backends, use {@linkcode createClient | createClient()} instead.
+ *
+ * When used in a Base44-hosted backend function, `createClientFromRequest()` automatically extracts authentication tokens from the request headers that Base44 injects when forwarding requests. The returned client includes service role access using `base44.asServiceRole`, which provides admin-level permissions.
  *
  * To learn more about the Base44 client, see {@linkcode createClient | createClient()}.
  *

package/dist/client.js

@@ -16,12 +16,14 @@ import { createAnalyticsModule } from "./modules/analytics.js";
  *
  * This is the main entry point for the Base44 SDK. It creates a client that provides access to the SDK's modules, such as {@linkcode EntitiesModule | entities}, {@linkcode AuthModule | auth}, and {@linkcode FunctionsModule | functions}.
  *
- * Typically, you don't need to call this function because Base44 creates the client for you. You can then import and use the client to make API calls. The client takes care of managing authentication for you.
+ * How you get a client depends on your context:
+ * - **Inside a Base44 app:** The client is automatically created and configured for you. Import it from `@/api/base44Client`.
+ * - **External app using Base44 as a backend:** Call `createClient()` directly in your code to create and configure the client.
  *
  * The client supports three authentication modes:
- * - **Anonymous**: Access modules anonymously without authentication using `base44.moduleName`. Operations are scoped to public data and permissions.
- * - **User authentication**: Access modules with user-level permissions using `base44.moduleName`. Operations are scoped to the authenticated user's data and permissions.
- * - **Service role authentication**: Access modules with elevated permissions using `base44.asServiceRole.moduleName`. Operations can access any data available to the app's admin. Can only be used in the backend. Typically, you create a client with service role authentication using the {@linkcode createClientFromRequest | createClientFromRequest()} function in your backend functions.
+ * - **Anonymous**: Access modules without authentication using `base44.moduleName`. Operations are scoped to public data and permissions.
+ * - **User authentication**: Access modules with user-level permissions using `base44.moduleName`. Operations are scoped to the authenticated user's data and permissions. Use `base44.auth.loginViaEmailPassword()` or other auth methods to get a token.
+ * - **Service role authentication**: Access modules with elevated permissions using `base44.asServiceRole.moduleName`. Operations can access any data available to the app's admin. Only available in Base44-hosted backend functions. Create a client with service role authentication using {@linkcode createClientFromRequest | createClientFromRequest()}.
  *
  * For example, when using the {@linkcode EntitiesModule | entities} module:
  * - **Anonymous**: Can only read public data.
@@ -48,6 +50,8 @@ import { createAnalyticsModule } from "./modules/analytics.js";
  */
 export function createClient(config) {
     const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, } = config;
+    // Normalize appBaseUrl to always be a string (empty if not provided or invalid)
+    const normalizedAppBaseUrl = typeof appBaseUrl === "string" ? appBaseUrl : "";
     const socketConfig = {
         serverUrl,
         mountPath: "/ws-user-apps/socket.io/",
@@ -100,7 +104,7 @@ export function createClient(config) {
         interceptResponses: false,
     });
     const userAuthModule = createAuthModule(axiosClient, functionsAxiosClient, appId, {
-        appBaseUrl,
+        appBaseUrl: normalizedAppBaseUrl,
         serverUrl,
     });
     const userModules = {
@@ -224,7 +228,7 @@ export function createClient(config) {
         /**
          * Provides access to service role modules.
          *
-         * Service role authentication provides elevated permissions for server-side operations. Unlike user authentication, which is scoped to a specific user's permissions, service role authentication has access to the data and operations available to the app's admin.
+         * Service role authentication provides elevated permissions for backend operations. Unlike user authentication, which is scoped to a specific user's permissions, service role authentication has access to the data and operations available to the app's admin.
          *
          * @throws {Error} When accessed without providing a serviceToken during client creation.
          *
@@ -251,7 +255,9 @@ export function createClient(config) {
 /**
  * Creates a Base44 client from an HTTP request.
  *
- * The client is created by automatically extracting authentication tokens from a request to a backend function. Base44 inserts the necessary headers when forwarding requests to backend functions.
+ * This function is designed for use in Base44-hosted backend functions. For frontends and external backends, use {@linkcode createClient | createClient()} instead.
+ *
+ * When used in a Base44-hosted backend function, `createClientFromRequest()` automatically extracts authentication tokens from the request headers that Base44 injects when forwarding requests. The returned client includes service role access using `base44.asServiceRole`, which provides admin-level permissions.
  *
  * To learn more about the Base44 client, see {@linkcode createClient | createClient()}.
  *

package/dist/client.types.d.ts

@@ -39,10 +39,13 @@ export interface CreateClientConfig {
     appId: string;
     /**
      * User authentication token. Used to authenticate as a specific user.
+     *
+     * Inside Base44 apps, the token is managed automatically. For external apps, use auth methods like {@linkcode AuthModule.loginViaEmailPassword | loginViaEmailPassword()} which set the token automatically.
      */
     token?: string;
     /**
-     * Service role authentication token. Use this in the backend when you need elevated permissions to access data available to the app's admin or perform admin operations. This token should be kept secret and never exposed in the app's frontend. Typically, you get this token from a request to a backend function using {@linkcode createClientFromRequest | createClientFromRequest()}.
+     * Service role authentication token. Provides elevated permissions to access data available to the app's admin. Only available in Base44-hosted backend functions. Automatically added to client's created using {@linkcode createClientFromRequest | createClientFromRequest()}.
+     * @internal
      */
     serviceToken?: string;
     /**
@@ -71,20 +74,20 @@ export interface CreateClientConfig {
  * Provides access to all SDK modules for interacting with the app.
  */
 export interface Base44Client {
-    /** {@link EntitiesModule | Entities module} for CRUD operations on your data models. */
-    entities: EntitiesModule;
-    /** {@link IntegrationsModule | Integrations module} for calling pre-built integration endpoints. */
-    integrations: IntegrationsModule;
-    /** {@link AuthModule | Auth module} for user authentication and management. */
-    auth: AuthModule;
-    /** {@link FunctionsModule | Functions module} for invoking custom backend functions. */
-    functions: FunctionsModule;
     /** {@link AgentsModule | Agents module} for managing AI agent conversations. */
     agents: AgentsModule;
+    /** {@link AnalyticsModule | Analytics module} for tracking custom events in your app. */
+    analytics: AnalyticsModule;
     /** {@link AppLogsModule | App logs module} for tracking app usage. */
     appLogs: AppLogsModule;
-    /** {@link AnalyticsModule | Analytics module} for tracking app usage. */
-    analytics: AnalyticsModule;
+    /** {@link AuthModule | Auth module} for user authentication and management. */
+    auth: AuthModule;
+    /** {@link EntitiesModule | Entities module} for CRUD operations on your data models. */
+    entities: EntitiesModule;
+    /** {@link FunctionsModule | Functions module} for invoking custom backend functions. */
+    functions: FunctionsModule;
+    /** {@link IntegrationsModule | Integrations module} for calling pre-built integration endpoints. */
+    integrations: IntegrationsModule;
     /** Cleanup function to disconnect WebSocket connections. Call when you're done with the client. */
     cleanup: () => void;
     /**
@@ -112,22 +115,22 @@ export interface Base44Client {
      * @throws {Error} When accessed without providing a serviceToken during client creation
      */
     readonly asServiceRole: {
+        /** {@link AgentsModule | Agents module} with elevated permissions. */
+        agents: AgentsModule;
+        /** {@link AppLogsModule | App logs module} with elevated permissions. */
+        appLogs: AppLogsModule;
+        /** {@link ConnectorsModule | Connectors module} for OAuth token retrieval. */
+        connectors: ConnectorsModule;
         /** {@link EntitiesModule | Entities module} with elevated permissions. */
         entities: EntitiesModule;
+        /** {@link FunctionsModule | Functions module} with elevated permissions. */
+        functions: FunctionsModule;
         /** {@link IntegrationsModule | Integrations module} with elevated permissions. */
         integrations: IntegrationsModule;
         /** {@link SsoModule | SSO module} for generating SSO tokens.
          * @internal
          */
         sso: SsoModule;
-        /** {@link ConnectorsModule | Connectors module} for OAuth token retrieval. */
-        connectors: ConnectorsModule;
-        /** {@link FunctionsModule | Functions module} with elevated permissions. */
-        functions: FunctionsModule;
-        /** {@link AgentsModule | Agents module} with elevated permissions. */
-        agents: AgentsModule;
-        /** {@link AppLogsModule | App logs module} with elevated permissions. */
-        appLogs: AppLogsModule;
         /** Cleanup function to disconnect WebSocket connections. */
         cleanup: () => void;
     };

package/dist/index.d.ts

@@ -4,11 +4,11 @@ import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
 export type { Base44Client, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
 export * from "./types.js";
-export type { EntitiesModule, EntityHandler, RealtimeEventType, RealtimeEvent, RealtimeCallback, Subscription, } from "./modules/entities.types.js";
+export type { EntitiesModule, EntityHandler, EntityRecord, EntityTypeRegistry, RealtimeEventType, RealtimeEvent, RealtimeCallback, } from "./modules/entities.types.js";
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
 export type { IntegrationsModule, IntegrationPackage, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
-export type { FunctionsModule } from "./modules/functions.types.js";
-export type { AgentsModule, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
+export type { FunctionsModule, FunctionNameRegistry, } from "./modules/functions.types.js";
+export type { AgentsModule, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
 export type { AppLogsModule } from "./modules/app-logs.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
 export type { ConnectorsModule } from "./modules/connectors.types.js";

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

@@ -1,6 +1,16 @@
 import { AxiosInstance } from "axios";
 import { RoomsSocket } from "../utils/socket-utils.js";
 import { ModelFilterParams } from "../types.js";
+/**
+ * Registry of agent names.
+ * Augment this interface to enable autocomplete for agent names.
+ */
+export interface AgentNameRegistry {
+}
+/**
+ * Agent name type - uses registry keys if augmented, otherwise string.
+ */
+export type AgentName = keyof AgentNameRegistry extends never ? string : keyof AgentNameRegistry;
 /**
  * Reasoning information for an agent message.
  *
@@ -72,7 +82,7 @@ export interface AgentMessageMetadata {
 export interface AgentConversation {
     /** Unique identifier for the conversation. */
     id: string;
-    /** Application ID. */
+    /** App ID. */
     app_id: string;
     /** Name of the agent in this conversation. */
     agent_name: string;
@@ -127,7 +137,7 @@ export interface AgentMessage {
  */
 export interface CreateConversationParams {
     /** The name of the agent to create a conversation with. */
-    agent_name: string;
+    agent_name: AgentName;
     /** Optional metadata to attach to the conversation. */
     metadata?: Record<string, any>;
 }
@@ -138,9 +148,9 @@ export interface CreateConversationParams {
 export interface AgentsModuleConfig {
     /** Axios instance for HTTP requests */
     axios: AxiosInstance;
-    /** Function to get WebSocket instance for real-time updates (lazy initialization) */
+    /** Function to get WebSocket instance for realtime updates (lazy initialization) */
     getSocket: () => ReturnType<typeof RoomsSocket>;
-    /** Application ID */
+    /** App ID */
     appId: string;
     /** Server URL */
     serverUrl?: string;
@@ -151,7 +161,7 @@ export interface AgentsModuleConfig {
  * Agents module for managing AI agent conversations.
  *
  * This module provides methods to create and manage conversations with AI agents,
- * send messages, and subscribe to real-time updates. Conversations can be used
+ * send messages, and subscribe to realtime updates. Conversations can be used
  * for chat interfaces, support systems, or any interactive AI app.
  *
  * The agents module enables you to:
@@ -159,7 +169,7 @@ export interface AgentsModuleConfig {
  * - **Create conversations** with agents defined in the app.
  * - **Send messages** from users to agents and receive AI-generated responses.
  * - **Retrieve conversations** individually or as filtered lists with sorting and pagination.
- * - **Subscribe to real-time updates** using WebSocket connections to receive instant notifications when new messages arrive.
+ * - **Subscribe to realtime updates** using WebSocket connections to receive instant notifications when new messages arrive.
  * - **Attach metadata** to conversations for tracking context, categories, priorities, or linking to external systems.
  * - **Generate WhatsApp connection URLs** for users to interact with agents through WhatsApp.
  *
@@ -171,7 +181,7 @@ export interface AgentsModuleConfig {
  *
  * This module is available to use with a client in all authentication modes:
  *
- * - **Anonymous or User authentication** (`base44.agents`): Access is scoped to the current user's permissions. Anonymous users can create conversations but can't retrieve them later, while authenticated users can access conversations they created.
+ * - **Anonymous or User authentication** (`base44.agents`): Access is scoped to the current user's permissions. Users must be authenticated to create and access conversations.
  * - **Service role authentication** (`base44.asServiceRole.agents`): Operations have elevated admin-level permissions. Can access all conversations that the app's admin role has access to.
  *
  */
@@ -200,6 +210,8 @@ export interface AgentsModule {
      * Retrieves a single conversation using its unique identifier. To retrieve
      * all conversations, use {@linkcode getConversations | getConversations()} To filter, sort, or paginate conversations, use {@linkcode listConversations | listConversations()}.
      *
+     * This function returns the complete stored conversation including full tool call results, even for large responses.
+     *
      * @param conversationId - The unique identifier of the conversation.
      * @returns Promise resolving to the conversation, or undefined if not found.
      *
@@ -275,7 +287,7 @@ export interface AgentsModule {
      * Adds a message to a conversation.
      *
      * Sends a message to the agent and updates the conversation. This method
-     * also updates the real-time socket to notify any subscribers.
+     * also updates the realtime socket to notify any subscribers.
      *
      * @param conversation - The conversation to add the message to.
      * @param message - The message to add.
@@ -293,19 +305,29 @@ export interface AgentsModule {
      */
     addMessage(conversation: AgentConversation, message: Partial<AgentMessage>): Promise<AgentMessage>;
     /**
-     * Subscribes to real-time updates for a conversation.
+     * Subscribes to realtime updates for a conversation.
      *
      * Establishes a WebSocket connection to receive instant updates when new
      * messages are added to the conversation. Returns an unsubscribe function
      * to clean up the connection.
+     *
+     * <Note>
+  When receiving messages through this function, tool call data is truncated for efficiency. The `arguments_string` is limited to 500 characters and `results` to 50 characters. The complete tool call data is always saved in storage and can be retrieved by calling {@linkcode getConversation | getConversation()} after the message completes.
+  </Note>
      *
      * @param conversationId - The conversation ID to subscribe to.
-     * @param onUpdate - Callback function called when the conversation is updated.
+     * @param onUpdate - Callback function called when the conversation is updated. The callback receives a conversation object with the following properties:
+     * - `id`: Unique identifier for the conversation.
+     * - `agent_name`: Name of the agent in this conversation.
+     * - `created_date`: ISO 8601 timestamp of when the conversation was created.
+     * - `updated_date`: ISO 8601 timestamp of when the conversation was last updated.
+     * - `messages`: Array of messages in the conversation. Each message includes `id`, `role` (`'user'`, `'assistant'`, or `'system'`), `content`, `created_date`, and optionally `tool_calls`, `reasoning`, `file_urls`, and `usage`.
+     * - `metadata`: Optional metadata associated with the conversation.
      * @returns Unsubscribe function to stop receiving updates.
      *
      * @example
      * ```typescript
-     * // Subscribe to real-time updates
+     * // Subscribe to realtime updates
      * const unsubscribe = base44.agents.subscribeToConversation(
      *   'conv-123',
      *   (updatedConversation) => {
@@ -336,5 +358,5 @@ export interface AgentsModule {
      * // User can open this URL to start a WhatsApp conversation
      * ```
      */
-    getWhatsAppConnectURL(agentName: string): string;
+    getWhatsAppConnectURL(agentName: AgentName): string;
 }

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

@@ -1,8 +1,38 @@
+/**
+ * Properties for analytics events.
+ *
+ * Key-value pairs with additional event data. Values can be strings, numbers, booleans, or null.
+ */
 export type TrackEventProperties = {
     [key: string]: string | number | boolean | null | undefined;
 };
+/**
+ * Parameters for tracking an analytics event.
+ */
 export type TrackEventParams = {
+    /**
+     * Name of the event to track.
+     *
+     * Use descriptive names like `button_click`, `form_submit`, or `purchase_completed`.
+     */
     eventName: string;
+    /**
+     * Optional key-value pairs with additional event data.
+     *
+     * Values can be strings, numbers, booleans, or null.
+     *
+     * @example
+     * ```typescript
+     * base44.analytics.track({
+     *   eventName: 'add_to_cart',
+     *   properties: {
+     *     product_id: 'prod_123',
+     *     price: 29.99,
+     *     quantity: 2
+     *   }
+     * });
+     * ```
+     */
     properties?: TrackEventProperties;
 };
 export type TrackEventIntrinsicData = {
@@ -37,6 +67,52 @@ export type AnalyticsModuleOptions = {
     batchSize?: number;
     heartBeatInterval?: number;
 };
-export type AnalyticsModule = {
-    track: (params: TrackEventParams) => void;
-};
+/**
+ * Analytics module for tracking custom events in your app.
+ *
+ * Use this module to track specific user actions. Track things like button clicks, form submissions, purchases, and feature usage.
+ *
+ * <Note> Analytics events tracked with this module appear as custom event cards in the [Analytics dashboard](/documentation/performance-and-seo/app-analytics).</Note>
+ *
+ * When tracking events:
+ *
+ * - Choose clear, descriptive event names in snake_case like `signup_button_click` or `purchase_completed` rather than generic names like `click`.
+ * - Include relevant context in your properties such as identifiers like `product_id`, measurements like `price`, and flags like `is_first_purchase`.
+ *
+ * This module is only available in user authentication mode (`base44.analytics`).
+ */
+export interface AnalyticsModule {
+    /**
+     * Tracks a custom event that appears as a card in your Analytics dashboard.
+     *
+     * Each unique event name becomes its own card showing total count and trends over time. This method returns immediately and events are sent in batches in the background.
+     *
+     * @param params - Event parameters.
+     * @param params.eventName - Name of the event. This becomes the card title in your dashboard. Use descriptive names like `'signup_button_click'` or `'purchase_completed'`.
+     * @param params.properties - Optional data to attach to the event. You can filter and analyze events by these properties in the dashboard.
+     *
+     * @example Track a button click
+     * ```typescript
+     * // Track a button click
+     * base44.analytics.track({
+     *   eventName: 'signup_button_click'
+     * });
+     * ```
+     *
+     * @example Track with properties
+     * ```typescript
+     * // Track with properties
+     * base44.analytics.track({
+     *   eventName: 'add_to_cart',
+     *   properties: {
+     *     product_id: 'prod_123',
+     *     product_name: 'Premium Widget',
+     *     price: 29.99,
+     *     quantity: 2,
+     *     is_first_purchase: true
+     *   }
+     * });
+     * ```
+     */
+    track(params: TrackEventParams): void;
+}

package/dist/modules/auth.js

@@ -20,7 +20,6 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
         },
         // Redirects the user to the app's login page
         redirectToLogin(nextUrl) {
-            var _a;
             // This function only works in a browser environment
             if (typeof window === "undefined") {
                 throw new Error("Login method can only be used in a browser environment");
@@ -30,7 +29,7 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
                 ? new URL(nextUrl, window.location.origin).toString()
                 : window.location.href;
             // Build the login URL
-            const loginUrl = `${(_a = options.appBaseUrl) !== null && _a !== void 0 ? _a : ""}/login?from_url=${encodeURIComponent(redirectUrl)}`;
+            const loginUrl = `${options.appBaseUrl}/login?from_url=${encodeURIComponent(redirectUrl)}`;
             // Redirect to the login page
             window.location.href = loginUrl;
         },
@@ -40,34 +39,32 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
             const redirectUrl = new URL(fromUrl, window.location.origin).toString();
             // Build the provider login URL (google is the default, so no provider path needed)
             const providerPath = provider === "google" ? "" : `/${provider}`;
-            const loginUrl = `${options.serverUrl}/api/apps/auth${providerPath}/login?app_id=${appId}&from_url=${encodeURIComponent(redirectUrl)}`;
+            const loginUrl = `${options.appBaseUrl}/api/apps/auth${providerPath}/login?app_id=${appId}&from_url=${encodeURIComponent(redirectUrl)}`;
             // Redirect to the provider 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
         logout(redirectUrl) {
-            // Remove token from axios headers
+            // Remove token from axios headers (always do this)
             delete axios.defaults.headers.common["Authorization"];
-            // Remove token from localStorage
-            if (typeof window !== "undefined" && window.localStorage) {
-                try {
-                    window.localStorage.removeItem("base44_access_token");
-                    // Remove "token" that is set by the built-in SDK of platform version 2
-                    window.localStorage.removeItem("token");
-                }
-                catch (e) {
-                    console.error("Failed to remove token from localStorage:", e);
-                }
-            }
-            // Redirect if a URL is provided
+            // Only do the rest if in a browser environment
             if (typeof window !== "undefined") {
-                if (redirectUrl) {
-                    window.location.href = redirectUrl;
-                }
-                else {
-                    window.location.reload();
+                // Remove token from localStorage
+                if (window.localStorage) {
+                    try {
+                        window.localStorage.removeItem("base44_access_token");
+                        // Remove "token" that is set by the built-in SDK of platform version 2
+                        window.localStorage.removeItem("token");
+                    }
+                    catch (e) {
+                        console.error("Failed to remove token from localStorage:", e);
+                    }
                 }
+                // Determine the from_url parameter
+                const fromUrl = redirectUrl || window.location.href;
+                // Redirect to server-side logout endpoint to clear HTTP-only cookies
+                const logoutUrl = `${options.appBaseUrl}/api/apps/auth/logout?from_url=${encodeURIComponent(fromUrl)}`;
+                window.location.href = logoutUrl;
             }
         },
         // Set authentication token

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

@@ -90,8 +90,8 @@ export interface ResetPasswordParams {
 export interface AuthModuleOptions {
     /** Server URL for API requests. */
     serverUrl: string;
-    /** Optional base URL for the app (used for login redirects). */
-    appBaseUrl?: string;
+    /** 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.
@@ -174,10 +174,15 @@ export interface AuthModule {
     /**
      * Redirects the user to a third-party authentication provider's login page.
      *
-     * Initiates OAuth/SSO login flow with providers like Google, Microsoft, etc. Requires a browser environment and can't be used in the backend.
+     * Initiates an OAuth login flow with one of the built-in providers. Requires a browser environment and can't be used in the backend.
      *
-     * @param provider - Name of the supported authentication provider (e.g., 'google', 'microsoft').
-     * @param fromUrl - URL to redirect to after successful authentication. Defaults to '/'.
+     * Supported providers:
+     * - `'google'` - {@link https://developers.google.com/identity/protocols/oauth2 | Google OAuth}. Enabled by default.
+     * - `'microsoft'` - {@link https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow | Microsoft OAuth}. Enable Microsoft in your app's authentication settings before specifying this provider.
+     * - `'facebook'` - {@link https://developers.facebook.com/docs/facebook-login | Facebook Login}. Enable this in your app's authentication settings before using.
+     *
+     * @param provider - The authentication provider to use: `'google'`, `'microsoft'`, or `'facebook'`.
+     * @param fromUrl - URL to redirect to after successful authentication. Defaults to `'/'`.
      *
      * @example
      * ```typescript
@@ -187,7 +192,7 @@ export interface AuthModule {
      *
      * @example
      * ```typescript
-     * // Login with GitHub and redirect to dashboard
+     * // Login with Microsoft and redirect to dashboard
      * base44.auth.loginWithProvider('microsoft', '/dashboard');
      * ```
      */

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

@@ -1,7 +1,14 @@
+/**
+ * Registry of connector integration types.
+ * Augment this interface to enable autocomplete for connector integration types.
+ */
+export interface ConnectorIntegrationTypeRegistry {
+}
 /**
  * The type of external integration/connector, such as `'googlecalendar'`, `'slack'`, or `'github'`.
+ * Uses registry keys if augmented, otherwise falls back to string.
  */
-export type ConnectorIntegrationType = string;
+export type ConnectorIntegrationType = keyof ConnectorIntegrationTypeRegistry extends never ? string : keyof ConnectorIntegrationTypeRegistry;
 /**
  * Response from the connectors access token endpoint.
  */
@@ -11,9 +18,7 @@ export interface ConnectorAccessTokenResponse {
 /**
  * Connectors module for managing OAuth tokens for external services.
  *
- * This module allows you to retrieve OAuth access tokens for external services
- * that the app has connected to. Use these tokens to make API
- * calls to external services.
+ * This module allows you to retrieve OAuth access tokens for external services that the app has connected to. Connectors are app-scoped. When an app builder connects an integration like Google Calendar or Slack, all users of the app share that same connection.
  *
  * Unlike the integrations module that provides pre-built functions, connectors give you
  * raw OAuth tokens so you can call external service APIs directly with full control over
@@ -26,9 +31,9 @@ export interface ConnectorsModule {
     /**
      * Retrieves an OAuth access token for a specific external integration type.
      *
-     * Returns the OAuth token string for an external service that the app
-     * has connected to. You can then use this token to make authenticated API calls
-     * to that external service.
+     * Returns the OAuth token string for an external service that an app builder
+     * has connected to. This token represents the connected app builder's account
+     * and can be used to make authenticated API calls to that external service on behalf of the app.
      *
      * @param integrationType - The type of integration, such as `'googlecalendar'`, `'slack'`, or `'github'`.
      * @returns Promise resolving to the access token string.

package/dist/modules/custom-integrations.types.d.ts

@@ -1,5 +1,6 @@
 /**
  * Parameters for calling a custom integration endpoint.
+ * @internal
  */
 export interface CustomIntegrationCallParams {
     /**
@@ -7,21 +8,17 @@ export interface CustomIntegrationCallParams {
      */
     payload?: Record<string, any>;
     /**
-     * Path parameters to substitute in the URL (e.g., `{ owner: "user", repo: "repo" }`).
+     * Path parameters to substitute in the URL. For example, `{ owner: "user", repo: "repo" }`.
      */
     pathParams?: Record<string, string>;
     /**
      * Query string parameters to append to the URL.
      */
     queryParams?: Record<string, any>;
-    /**
-     * Additional headers to send with this specific request.
-     * These are merged with the integration's configured headers.
-     */
-    headers?: Record<string, string>;
 }
 /**
  * Response from a custom integration call.
+ * @internal
  */
 export interface CustomIntegrationCallResponse {
     /**
@@ -39,60 +36,17 @@ export interface CustomIntegrationCallResponse {
     data: any;
 }
 /**
- * Module for calling custom workspace-level API integrations.
- *
- * Custom integrations allow workspace administrators to connect any external API
- * by importing an OpenAPI specification. Apps in the workspace can then call
- * these integrations using this module.
- *
- * Unlike the built-in integrations (like `Core`), custom integrations:
- * - Are defined per-workspace by importing OpenAPI specs
- * - Use a slug-based identifier instead of package names
- * - Proxy requests through Base44's backend (credentials never exposed to frontend)
- *
- * @example
- * ```typescript
- * // Call a custom GitHub integration
- * const response = await base44.integrations.custom.call(
- *   "github",        // integration slug (defined by workspace admin)
- *   "listIssues",    // operation ID from the OpenAPI spec
- *   {
- *     pathParams: { owner: "myorg", repo: "myrepo" },
- *     queryParams: { state: "open", per_page: 100 }
- *   }
- * );
+ * Module for calling custom pre-configured API integrations.
  *
- * if (response.success) {
- *   console.log("Issues:", response.data);
- * } else {
- *   console.error("API returned error:", response.status_code);
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Call with request body payload
- * const response = await base44.integrations.custom.call(
- *   "github",
- *   "createIssue",
- *   {
- *     pathParams: { owner: "myorg", repo: "myrepo" },
- *     payload: {
- *       title: "Bug report",
- *       body: "Something is broken",
- *       labels: ["bug"]
- *     }
- *   }
- * );
- * ```
+ * Custom integrations allow workspace administrators to connect any external API by importing an OpenAPI specification. Apps in the workspace can then call these integrations using this module.
  */
 export interface CustomIntegrationsModule {
     /**
      * Call a custom integration endpoint.
      *
-     * @param slug - The integration's unique identifier (slug), as defined by the workspace admin.
-     * @param operationId - The operation ID from the OpenAPI spec (e.g., "listIssues", "getUser").
-     * @param params - Optional parameters including payload, pathParams, queryParams, and headers.
+     * @param slug - The integration's unique identifier, as defined by the workspace admin.
+     * @param operationId - The endpoint in `method:path` format. For example, `"get:/contacts"`, or `"post:/users/{id}"`. The method is the HTTP verb in lowercase and the path matches the OpenAPI specification.
+     * @param params - Optional parameters including payload, pathParams, and queryParams.
      * @returns Promise resolving to the integration call response.
      *
      * @throws {Error} If slug is not provided.
@@ -100,6 +54,36 @@ export interface CustomIntegrationsModule {
      * @throws {Base44Error} If the integration or operation is not found (404).
      * @throws {Base44Error} If the external API call fails (502).
      * @throws {Base44Error} If the request times out (504).
+     *
+     * @example
+     * ```typescript
+     * // Call a custom CRM integration
+     * const response = await base44.integrations.custom.call(
+     *   "my-crm",
+     *   "get:/contacts",
+     *   { queryParams: { limit: 10 } }
+     * );
+     *
+     * if (response.success) {
+     *   console.log("Contacts:", response.data);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Call with path params and request body
+     * const response = await base44.integrations.custom.call(
+     *   "github",
+     *   "post:/repos/{owner}/{repo}/issues",
+     *   {
+     *     pathParams: { owner: "myorg", repo: "myrepo" },
+     *     payload: {
+     *       title: "Bug report",
+     *       body: "Something is broken"
+     *     }
+     *   }
+     * );
+     * ```
      */
     call(slug: string, operationId: string, params?: CustomIntegrationCallParams): Promise<CustomIntegrationCallResponse>;
 }

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

@@ -4,12 +4,14 @@
 export type RealtimeEventType = "create" | "update" | "delete";
 /**
  * Payload received when a realtime event occurs.
+ *
+ * @typeParam T - The entity type for the data field. Defaults to `any`.
  */
-export interface RealtimeEvent {
+export interface RealtimeEvent<T = any> {
     /** The type of change that occurred */
     type: RealtimeEventType;
     /** The entity data */
-    data: any;
+    data: T;
     /** The unique identifier of the affected entity */
     id: string;
     /** ISO 8601 timestamp of when the event occurred */
@@ -17,29 +19,108 @@ export interface RealtimeEvent {
 }
 /**
  * Callback function invoked when a realtime event occurs.
+ *
+ * @typeParam T - The entity type for the event data. Defaults to `any`.
+ */
+export type RealtimeCallback<T = any> = (event: RealtimeEvent<T>) => void;
+/**
+ * Result returned when deleting a single entity.
+ */
+export interface DeleteResult {
+    /** Whether the deletion was successful */
+    success: boolean;
+}
+/**
+ * Result returned when deleting multiple entities.
+ */
+export interface DeleteManyResult {
+    /** Whether the deletion was successful */
+    success: boolean;
+    /** Number of entities that were deleted */
+    deleted: number;
+}
+/**
+ * Result returned when importing entities from a file.
+ *
+ * @typeParam T - The entity type for imported records. Defaults to `any`.
  */
-export type RealtimeCallback = (event: RealtimeEvent) => void;
+export interface ImportResult<T = any> {
+    /** Status of the import operation */
+    status: "success" | "error";
+    /** Details message, e.g., "Successfully imported 3 entities with RLS enforcement" */
+    details: string | null;
+    /** Array of created entity objects when successful, or null on error */
+    output: T[] | null;
+}
 /**
- * Function returned from subscribe, call it to unsubscribe.
+ * Sort field type for entity queries.
+ *
+ * Supports ascending (no prefix or `'+'`) and descending (`'-'`) sorting.
+ *
+ * @typeParam T - The entity type to derive sortable fields from.
+ *
+ * @example
+ * ```typescript
+ * // Ascending sort (default)
+ * 'created_date'
+ * '+created_date'
+ *
+ * // Descending sort
+ * '-created_date'
+ * ```
  */
-export type Subscription = () => void;
+export type SortField<T> = (keyof T & string) | `+${keyof T & string}` | `-${keyof T & string}`;
+/**
+ * Fields added by the server to every entity record (id, dates, created_by, etc.).
+ */
+interface ServerEntityFields {
+    /** Unique identifier of the record */
+    id: string;
+    /** ISO 8601 timestamp when the record was created */
+    created_date: string;
+    /** ISO 8601 timestamp when the record was last updated */
+    updated_date: string;
+    /** Email of the user who created the record (may be hidden in some responses) */
+    created_by?: string | null;
+    /** ID of the user who created the record */
+    created_by_id?: string | null;
+    /** Whether the record is sample/seed data */
+    is_sample?: boolean;
+}
+/**
+ * Registry mapping entity names to their TypeScript types.
+ * Augment this interface with your entity schema (user-defined fields only).
+ */
+export interface EntityTypeRegistry {
+}
+/**
+ * Full record type for each entity: schema fields + server-injected fields (id, created_date, etc.).
+ */
+export type EntityRecord = {
+    [K in keyof EntityTypeRegistry]: EntityTypeRegistry[K] & ServerEntityFields;
+};
 /**
  * Entity handler providing CRUD operations for a specific entity type.
  *
  * Each entity in the app gets a handler with these methods for managing data.
+ *
+ * @typeParam T - The entity type. Defaults to `any` for backward compatibility.
  */
-export interface EntityHandler {
+export interface EntityHandler<T = any> {
     /**
      * Lists records with optional pagination and sorting.
      *
      * Retrieves all records of this type with support for sorting,
      * pagination, and field selection.
      *
+     * **Note:** The maximum limit is 5,000 items per request.
+     *
+     * @typeParam K - The fields to include in the response. Defaults to all fields.
      * @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.
+     * @returns Promise resolving to an array of records with selected fields.
      *
      * @example
      * ```typescript
@@ -66,13 +147,16 @@ export interface EntityHandler {
      * const fields = await base44.entities.MyEntity.list('-created_date', 10, 0, ['name', 'status']);
      * ```
      */
-    list(sort?: string, limit?: number, skip?: number, fields?: string[]): Promise<any>;
+    list<K extends keyof T = keyof T>(sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
     /**
      * Filters records based on a query.
      *
      * Retrieves records that match specific criteria with support for
      * sorting, pagination, and field selection.
      *
+     * **Note:** The maximum limit is 5,000 items per request.
+     *
+     * @typeParam K - The fields to include in the response. Defaults to all fields.
      * @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.
@@ -80,7 +164,7 @@ export interface EntityHandler {
      * @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.
+     * @returns Promise resolving to an array of filtered records with selected fields.
      *
      * @example
      * ```typescript
@@ -122,7 +206,7 @@ export interface EntityHandler {
      * );
      * ```
      */
-    filter(query: Record<string, any>, sort?: string, limit?: number, skip?: number, fields?: string[]): Promise<any>;
+    filter<K extends keyof T = keyof T>(query: Partial<T>, sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
     /**
      * Gets a single record by ID.
      *
@@ -138,7 +222,7 @@ export interface EntityHandler {
      * console.log(record.name);
      * ```
      */
-    get(id: string): Promise<any>;
+    get(id: string): Promise<T>;
     /**
      * Creates a new record.
      *
@@ -158,7 +242,7 @@ export interface EntityHandler {
      * console.log('Created record with ID:', newRecord.id);
      * ```
      */
-    create(data: Record<string, any>): Promise<any>;
+    create(data: Partial<T>): Promise<T>;
     /**
      * Updates an existing record.
      *
@@ -187,7 +271,7 @@ export interface EntityHandler {
      * });
      * ```
      */
-    update(id: string, data: Record<string, any>): Promise<any>;
+    update(id: string, data: Partial<T>): Promise<T>;
     /**
      * Deletes a single record by ID.
      *
@@ -200,10 +284,10 @@ export interface EntityHandler {
      * ```typescript
      * // Delete a record
      * const result = await base44.entities.MyEntity.delete('entity-123');
-     * console.log('Deleted:', result);
+     * console.log('Deleted:', result.success);
      * ```
      */
-    delete(id: string): Promise<any>;
+    delete(id: string): Promise<DeleteResult>;
     /**
      * Deletes multiple records matching a query.
      *
@@ -221,10 +305,10 @@ export interface EntityHandler {
      *   status: 'completed',
      *   priority: 'low'
      * });
-     * console.log('Deleted:', result);
+     * console.log('Deleted:', result.deleted);
      * ```
      */
-    deleteMany(query: Record<string, any>): Promise<any>;
+    deleteMany(query: Partial<T>): Promise<DeleteManyResult>;
     /**
      * Creates multiple records in a single request.
      *
@@ -244,7 +328,7 @@ export interface EntityHandler {
      * ]);
      * ```
      */
-    bulkCreate(data: Record<string, any>[]): Promise<any>;
+    bulkCreate(data: Partial<T>[]): Promise<T[]>;
     /**
      * Imports records from a file.
      *
@@ -252,7 +336,7 @@ export interface EntityHandler {
      * 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.
+     * @returns Promise resolving to the import result containing status, details, and created records.
      *
      * @example
      * ```typescript
@@ -261,19 +345,27 @@ export interface EntityHandler {
      *   const file = event.target.files?.[0];
      *   if (file) {
      *     const result = await base44.entities.MyEntity.importEntities(file);
-     *     console.log(`Imported ${result.count} records`);
+     *     if (result.status === 'success' && result.output) {
+     *       console.log(`Imported ${result.output.length} records`);
+     *     }
      *   }
      * };
      * ```
      */
-    importEntities(file: File): Promise<any>;
+    importEntities(file: File): Promise<ImportResult<T>>;
     /**
      * Subscribes to realtime updates for all records of this entity type.
      *
-     * Receives notifications whenever any record is created, updated, or deleted.
+     * Establishes a WebSocket connection to receive instant updates when any
+     * record is created, updated, or deleted. Returns an unsubscribe function
+     * to clean up the connection.
      *
-     * @param callback - Function called when an entity changes.
-     * @returns Unsubscribe function to stop listening.
+     * @param callback - Callback function called when an entity changes. The callback receives an event object with the following properties:
+     * - `type`: The type of change that occurred - `'create'`, `'update'`, or `'delete'`.
+     * - `data`: The entity data after the change.
+     * - `id`: The unique identifier of the affected entity.
+     * - `timestamp`: ISO 8601 timestamp of when the event occurred.
+     * @returns Unsubscribe function to stop receiving updates.
      *
      * @example
      * ```typescript
@@ -282,12 +374,24 @@ export interface EntityHandler {
      *   console.log(`Task ${event.id} was ${event.type}d:`, event.data);
      * });
      *
-     * // Later, unsubscribe
+     * // Later, clean up the subscription
      * unsubscribe();
      * ```
      */
-    subscribe(callback: RealtimeCallback): Subscription;
+    subscribe(callback: RealtimeCallback<T>): () => void;
 }
+/**
+ * Typed entities module - maps registry keys to typed handlers (full record type).
+ */
+type TypedEntitiesModule = {
+    [K in keyof EntityTypeRegistry]: EntityHandler<EntityRecord[K]>;
+};
+/**
+ * Dynamic entities module - allows any entity name with untyped handler.
+ */
+type DynamicEntitiesModule = {
+    [entityName: string]: EntityHandler<any>;
+};
 /**
  * Entities module for managing app data.
  *
@@ -321,18 +425,5 @@ export interface EntityHandler {
  * 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;
-}
+export type EntitiesModule = TypedEntitiesModule & DynamicEntitiesModule;
+export {};

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

@@ -1,3 +1,13 @@
+/**
+ * Registry of function names.
+ * Augment this interface to enable autocomplete for function names.
+ */
+export interface FunctionNameRegistry {
+}
+/**
+ * Function name type - uses registry keys if augmented, otherwise string.
+ */
+export type FunctionName = keyof FunctionNameRegistry extends never ? string : keyof FunctionNameRegistry;
 /**
  * Functions module for invoking custom backend functions.
  *
@@ -46,5 +56,5 @@ export interface FunctionsModule {
      * };
      * ```
      */
-    invoke(functionName: string, data: Record<string, any>): Promise<any>;
+    invoke(functionName: FunctionName, data?: Record<string, any>): Promise<any>;
 }

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

@@ -320,22 +320,28 @@ export interface CoreIntegrations {
     CreateFileSignedUrl(params: CreateFileSignedUrlParams): Promise<CreateFileSignedUrlResult>;
 }
 /**
- * Integrations module for calling integration endpoints.
+ * Integrations module for calling integration methods.
  *
- * This module provides access to integration endpoints for interacting with external
- * services. Integrations are organized into packages. Base44 provides built-in integrations
- * in the `Core` package.
+ * This module provides access to integration methods for interacting with external services. Unlike the connectors module that gives you raw OAuth tokens, integrations provide pre-built functions that Base44 executes on your behalf.
  *
- * Unlike the connectors module that gives you raw OAuth tokens, integrations provide
- * pre-built functions that Base44 executes on your behalf.
+ * There are two types of integrations:
  *
- * Integration endpoints are accessed dynamically using the pattern:
- * `base44.integrations.PackageName.EndpointName(params)`
+ * - **Built-in integrations** (`Core`): Pre-built functions provided by Base44 for common tasks such as AI-powered text generation, image creation, file uploads, and email. Access core integration methods using:
+ *   ```
+ *   base44.integrations.Core.FunctionName(params)
+ *   ```
+ *
+ * - **Custom integrations** (`custom`): Pre-configured external APIs. Custom integration calls are proxied through Base44's backend, so credentials are never exposed to the frontend. Access custom integration methods using:
+ *   ```
+ *   base44.integrations.custom.call(slug, operationId, params)
+ *   ```
+ *
+ *   <Info>To call a custom integration, it must be pre-configured by a workspace administrator who imports an OpenAPI specification.</Info>
  *
  * This module is available to use with a client in all authentication modes:
  *
- * - **Anonymous or User authentication** (`base44.integrations`): Integration endpoints are invoked with the current user's permissions. Anonymous users invoke endpoints without authentication, while authenticated users invoke endpoints with their authentication context.
- * - **Service role authentication** (`base44.asServiceRole.integrations`): Integration endpoints are invoked with elevated admin-level permissions. The endpoints execute with admin authentication context.
+ * - **Anonymous or User authentication** (`base44.integrations`): Integration methods are invoked with the current user's permissions. Anonymous users invoke methods without authentication, while authenticated users invoke methods with their authentication context.
+ * - **Service role authentication** (`base44.asServiceRole.integrations`): Integration methods are invoked with elevated admin-level permissions. The methods execute with admin authentication context.
  */
 export type IntegrationsModule = {
     /**
@@ -343,22 +349,7 @@ export type IntegrationsModule = {
      */
     Core: CoreIntegrations;
     /**
-     * Custom integrations module for calling workspace-level API integrations.
-     *
-     * Allows calling external APIs that workspace admins have configured
-     * by importing OpenAPI specifications.
-     *
-     * @example
-     * ```typescript
-     * const response = await base44.integrations.custom.call(
-     *   "github",        // integration slug
-     *   "listIssues",    // operation ID
-     *   {
-     *     pathParams: { owner: "myorg", repo: "myrepo" },
-     *     queryParams: { state: "open" }
-     *   }
-     * );
-     * ```
+     * Custom integrations module for calling pre-configured external APIs.
      */
     custom: CustomIntegrationsModule;
 } & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/sdk",
-  "version": "0.8.18",
+  "version": "0.8.19",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,8 @@
     "docs": "typedoc",
     "prepublishOnly": "npm run build",
     "create-docs": "npm run create-docs:generate && npm run create-docs:process",
-    "push-docs": "node scripts/mintlify-post-processing/push-to-docs-repo.js",
+    "create-docs-local": "npm run create-docs && npm run copy-docs-local",
+    "copy-docs-local": "node scripts/mintlify-post-processing/copy-to-local-docs.js",
     "create-docs:generate": "typedoc",
     "create-docs:process": "node scripts/mintlify-post-processing/file-processing/file-processing.js"
   },