@base44-preview/sdk 0.8.18-pr.91.cfad1b0 → 0.8.19-pr.126.c537ed8

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, } 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.js

@@ -3,6 +3,8 @@ export function createAgentsModule({ axios, getSocket, appId, serverUrl, token,
     const baseURL = `/apps/${appId}/agents`;
     // Track active conversations
     const currentConversations = {};
+    // Stores client tool handlers keyed by conversation ID
+    const clientToolHandlers = {};
     const getConversations = () => {
         return axios.get(`${baseURL}/conversations`);
     };
@@ -20,6 +22,60 @@ export function createAgentsModule({ axios, getSocket, appId, serverUrl, token,
     const addMessage = async (conversation, message) => {
         return axios.post(`${baseURL}/conversations/v2/${conversation.id}/messages`, message);
     };
+    const registerClientToolHandlers = (conversationId, handlers) => {
+        clientToolHandlers[conversationId] = {
+            ...(clientToolHandlers[conversationId] || {}),
+            ...handlers,
+        };
+    };
+    const submitToolResults = (conversationId, results) => {
+        return axios.post(`${baseURL}/conversations/${conversationId}/client-tool-results`, { results });
+    };
+    const handlePendingClientTools = async (conversationId, message) => {
+        var _a;
+        if (!(message === null || message === void 0 ? void 0 : message.tool_calls))
+            return false;
+        const pendingCalls = message.tool_calls.filter((tc) => tc.status === "pending_client_execution");
+        if (pendingCalls.length === 0)
+            return false;
+        const handlers = clientToolHandlers[conversationId];
+        if (!handlers)
+            return false;
+        const results = [];
+        for (const tc of pendingCalls) {
+            const handler = handlers[tc.name];
+            if (!handler) {
+                results.push({
+                    tool_call_id: tc.id,
+                    result: `Error: No handler registered for client tool '${tc.name}'`,
+                });
+                continue;
+            }
+            try {
+                const args = JSON.parse(tc.arguments_string);
+                const context = {
+                    appId,
+                    conversationId,
+                    toolCallId: tc.id,
+                    toolName: tc.name,
+                    messages: ((_a = currentConversations[conversationId]) === null || _a === void 0 ? void 0 : _a.messages) || [],
+                };
+                const result = await handler(args, context);
+                results.push({
+                    tool_call_id: tc.id,
+                    result: typeof result === "string" ? result : JSON.stringify(result),
+                });
+            }
+            catch (error) {
+                results.push({
+                    tool_call_id: tc.id,
+                    result: `Error executing client tool '${tc.name}': ${error.message}`,
+                });
+            }
+        }
+        await submitToolResults(conversationId, results);
+        return true;
+    };
     const subscribeToConversation = (conversationId, onUpdate) => {
         const room = `/agent-conversations/${conversationId}`;
         const socket = getSocket();
@@ -49,6 +105,8 @@ export function createAgentsModule({ axios, getSocket, appId, serverUrl, token,
                             messages: updatedMessages,
                         };
                         onUpdate === null || onUpdate === void 0 ? void 0 : onUpdate(currentConversations[conversationId]);
+                        // Automatically handle pending client tool calls
+                        await handlePendingClientTools(conversationId, message);
                     }
                 }
             },
@@ -71,6 +129,9 @@ export function createAgentsModule({ axios, getSocket, appId, serverUrl, token,
         listConversations,
         createConversation,
         addMessage,
+        registerClientToolHandlers,
+        submitToolResults,
+        handlePendingClientTools,
         subscribeToConversation,
         getWhatsAppConnectURL,
     };

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.
  *
@@ -27,7 +37,7 @@ export interface AgentMessageToolCall {
     /** Arguments passed to the tool as JSON string. */
     arguments_string: string;
     /** Status of the tool call. */
-    status: "running" | "success" | "error" | "stopped";
+    status: "running" | "success" | "error" | "stopped" | "pending_client_execution";
     /** Results from the tool call. */
     results?: string;
 }
@@ -127,10 +137,41 @@ 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>;
 }
+/**
+ * Context passed to client tool handlers during execution.
+ */
+export interface ClientToolContext {
+    /** The app ID. */
+    appId: string;
+    /** The conversation ID. */
+    conversationId: string;
+    /** The unique tool call ID. */
+    toolCallId: string;
+    /** The tool name. */
+    toolName: string;
+    /** The conversation messages so far. */
+    messages: AgentMessage[];
+}
+/**
+ * A client tool handler function.
+ *
+ * Receives parsed arguments and execution context, returns a string result
+ * (or an object that will be JSON.stringified).
+ */
+export type ClientToolHandler = (args: Record<string, any>, context: ClientToolContext) => Promise<string | Record<string, any>> | string | Record<string, any>;
+/**
+ * Result of a client tool execution, to be submitted back to the server.
+ */
+export interface ClientToolResult {
+    /** The tool call ID this result corresponds to. */
+    tool_call_id: string;
+    /** The result string. */
+    result: string;
+}
 /**
  * Configuration for creating the agents module.
  * @internal
@@ -171,7 +212,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 +241,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.
      *
@@ -292,12 +335,84 @@ export interface AgentsModule {
      * ```
      */
     addMessage(conversation: AgentConversation, message: Partial<AgentMessage>): Promise<AgentMessage>;
+    /**
+     * Registers handler functions for client-side tools defined in the agent configuration.
+     *
+     * Client tools are tools that execute in the browser rather than on the server.
+     * They are defined by the app builder in the agent configuration (name, description,
+     * parameters). The SDK caller provides the handler functions that run locally when
+     * the agent invokes these tools.
+     *
+     * When subscribed to the conversation via {@linkcode subscribeToConversation | subscribeToConversation()},
+     * client tool calls are handled automatically — the SDK detects pending client tool calls,
+     * executes the registered handlers, and submits results back to the server.
+     *
+     * For user info inside a handler, call `base44.auth.me()` from the handler body.
+     *
+     * @param conversationId - The conversation ID to register handlers for.
+     * @param handlers - Map of tool name to handler function. Each handler receives
+     *   `(args, context)` where `args` are the parsed tool arguments and `context`
+     *   includes `appId`, `conversationId`, `toolCallId`, `toolName`, and `messages`.
+     *
+     * @example
+     * ```typescript
+     * base44.agents.registerClientToolHandlers(conversation.id, {
+     *   get_current_location: async ({ accuracy }, { conversationId, messages }) => {
+     *     const pos = await new Promise((resolve, reject) =>
+     *       navigator.geolocation.getCurrentPosition(resolve, reject, {
+     *         enableHighAccuracy: accuracy === 'high'
+     *       })
+     *     );
+     *     return JSON.stringify({
+     *       lat: pos.coords.latitude,
+     *       lng: pos.coords.longitude
+     *     });
+     *   },
+     *   get_clipboard_text: async () => {
+     *     return await navigator.clipboard.readText();
+     *   }
+     * });
+     * ```
+     */
+    registerClientToolHandlers(conversationId: string, handlers: Record<string, ClientToolHandler>): void;
+    /**
+     * Submits results for client-side tool calls.
+     *
+     * This is called automatically when using {@linkcode subscribeToConversation | subscribeToConversation()}
+     * with registered handlers. You only need to call this directly if you are
+     * implementing custom tool call handling logic outside of the subscription flow.
+     *
+     * @param conversationId - The conversation ID.
+     * @param results - Array of tool call results.
+     */
+    submitToolResults(conversationId: string, results: ClientToolResult[]): Promise<any>;
+    /**
+     * Processes pending client-side tool calls from a message.
+     *
+     * Finds tool calls with `pending_client_execution` status, executes their
+     * registered handlers, and submits the results back to the server.
+     *
+     * This is called automatically by {@linkcode subscribeToConversation | subscribeToConversation()}.
+     * You only need to call this directly for custom handling flows.
+     *
+     * @param conversationId - The conversation ID.
+     * @param message - The message containing tool calls.
+     * @returns `true` if client tool calls were processed, `false` otherwise.
+     */
+    handlePendingClientTools(conversationId: string, message: AgentMessage): Promise<boolean>;
     /**
      * 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.
+     *
+     * Client tool handlers registered via {@linkcode registerClientToolHandlers | registerClientToolHandlers()}
+     * are automatically executed when tool calls with `pending_client_execution` status arrive.
+     *
+     * <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. The callback receives a conversation object with the following properties:
@@ -342,5 +457,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/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.
  */

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

@@ -70,6 +70,35 @@ export interface ImportResult<T = any> {
  * ```
  */
 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.
  *
@@ -276,7 +305,7 @@ export interface EntityHandler<T = any> {
      *   status: 'completed',
      *   priority: 'low'
      * });
-     * console.log('Deleted:', result);
+     * console.log('Deleted:', result.deleted);
      * ```
      */
     deleteMany(query: Partial<T>): Promise<DeleteManyResult>;
@@ -351,6 +380,18 @@ export interface EntityHandler<T = any> {
      */
     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.
  *
@@ -384,18 +425,5 @@ export interface EntityHandler<T = any> {
  * 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<any>;
-}
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.18-pr.91.cfad1b0",
+  "version": "0.8.19-pr.126.c537ed8",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",