@depup/base44__sdk 0.8.22-depup.0

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { createClient, createClientFromRequest, type Base44Client, type CreateClientConfig, type CreateClientOptions } from "./client.js";
+import { Base44Error, type Base44ErrorJSON } from "./utils/axios-client.js";
+import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from "./utils/auth-utils.js";
+export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
+export type { Base44Client, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
+export * from "./types.js";
+export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
+export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
+export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
+export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";
+export type { AgentsModule, AgentName, 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, UserConnectorsModule, } from "./modules/connectors.types.js";
+export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";
+export type { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions, } from "./utils/auth-utils.types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+import { createClient, createClientFromRequest, } from "./client.js";
+import { Base44Error } from "./utils/axios-client.js";
+import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, } from "./utils/auth-utils.js";
+export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
+export * from "./types.js";

package/dist/modules/agents.d.ts

@@ -0,0 +1,2 @@
+import { AgentsModule, AgentsModuleConfig } from "./agents.types.js";
+export declare function createAgentsModule({ axios, getSocket, appId, serverUrl, token, }: AgentsModuleConfig): AgentsModule;

package/dist/modules/agents.js

@@ -0,0 +1,77 @@
+import { getAccessToken } from "../utils/auth-utils.js";
+export function createAgentsModule({ axios, getSocket, appId, serverUrl, token, }) {
+    const baseURL = `/apps/${appId}/agents`;
+    // Track active conversations
+    const currentConversations = {};
+    const getConversations = () => {
+        return axios.get(`${baseURL}/conversations`);
+    };
+    const getConversation = (conversationId) => {
+        return axios.get(`${baseURL}/conversations/${conversationId}`);
+    };
+    const listConversations = (filterParams) => {
+        return axios.get(`${baseURL}/conversations`, {
+            params: filterParams,
+        });
+    };
+    const createConversation = (conversation) => {
+        return axios.post(`${baseURL}/conversations`, conversation);
+    };
+    const addMessage = async (conversation, message) => {
+        return axios.post(`${baseURL}/conversations/v2/${conversation.id}/messages`, message);
+    };
+    const subscribeToConversation = (conversationId, onUpdate) => {
+        const room = `/agent-conversations/${conversationId}`;
+        const socket = getSocket();
+        // Store the promise for initial conversation state
+        const conversationPromise = getConversation(conversationId).then((conv) => {
+            currentConversations[conversationId] = conv;
+            return conv;
+        });
+        return socket.subscribeToRoom(room, {
+            connect: () => { },
+            update_model: async ({ data: jsonStr }) => {
+                const data = JSON.parse(jsonStr);
+                if (data._message) {
+                    // Wait for initial conversation to be loaded
+                    await conversationPromise;
+                    const message = data._message;
+                    // Update shared conversation state
+                    const currentConversation = currentConversations[conversationId];
+                    if (currentConversation) {
+                        const messages = currentConversation.messages || [];
+                        const existingIndex = messages.findIndex((m) => m.id === message.id);
+                        const updatedMessages = existingIndex !== -1
+                            ? messages.map((m, i) => (i === existingIndex ? message : m))
+                            : [...messages, message];
+                        currentConversations[conversationId] = {
+                            ...currentConversation,
+                            messages: updatedMessages,
+                        };
+                        onUpdate === null || onUpdate === void 0 ? void 0 : onUpdate(currentConversations[conversationId]);
+                    }
+                }
+            },
+        });
+    };
+    const getWhatsAppConnectURL = (agentName) => {
+        const baseUrl = `${serverUrl}/api/apps/${appId}/agents/${encodeURIComponent(agentName)}/whatsapp`;
+        const accessToken = token !== null && token !== void 0 ? token : getAccessToken();
+        if (accessToken) {
+            return `${baseUrl}?token=${accessToken}`;
+        }
+        else {
+            // No token - URL will redirect to login automatically
+            return baseUrl;
+        }
+    };
+    return {
+        getConversations,
+        getConversation,
+        listConversations,
+        createConversation,
+        addMessage,
+        subscribeToConversation,
+        getWhatsAppConnectURL,
+    };
+}

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

@@ -0,0 +1,377 @@
+import { AxiosInstance } from "axios";
+import { RoomsSocket } from "../utils/socket-utils.js";
+import { ModelFilterParams } from "../types.js";
+/**
+ * Registry of agent names. The [`types generate`](/developers/references/cli/commands/types-generate) command fills this registry, then [`AgentName`](#agentname) resolves to a union of the keys.
+ */
+export interface AgentNameRegistry {
+}
+/**
+ * Union of all agent names from the [`AgentNameRegistry`](#agentnameregistry). Defaults to `string` when no types have been generated.
+ *
+ * @example
+ * ```typescript
+ * // Using generated agent name types
+ * // With generated types, you get autocomplete on agent names
+ * const conversation = await base44.agents.createConversation({ agent_name: 'SupportBot' });
+ * ```
+ */
+export type AgentName = keyof AgentNameRegistry extends never ? string : keyof AgentNameRegistry;
+/**
+ * Reasoning information for an agent message.
+ *
+ * Contains details about the agent's reasoning process when generating a response.
+ */
+export interface AgentMessageReasoning {
+    /** When reasoning started. */
+    start_date: string;
+    /** When reasoning ended. */
+    end_date?: string;
+    /** Reasoning content. */
+    content: string;
+}
+/**
+ * A tool call made by the agent.
+ *
+ * Represents a function or tool that the agent invoked during message generation.
+ */
+export interface AgentMessageToolCall {
+    /** Tool call ID. */
+    id: string;
+    /** Name of the tool called. */
+    name: string;
+    /** Arguments passed to the tool as JSON string. */
+    arguments_string: string;
+    /** Status of the tool call. */
+    status: "running" | "success" | "error" | "stopped";
+    /** Results from the tool call. */
+    results?: string;
+}
+/**
+ * Token usage statistics for an agent message.
+ *
+ * Tracks the number of tokens consumed when generating the message.
+ */
+export interface AgentMessageUsage {
+    /** Number of tokens in the prompt. */
+    prompt_tokens?: number;
+    /** Number of tokens in the completion. */
+    completion_tokens?: number;
+}
+/**
+ * Custom context provided with an agent message.
+ *
+ * Additional contextual information that can be passed to the agent.
+ */
+export interface AgentMessageCustomContext {
+    /** Context message. */
+    message: string;
+    /** Associated data for the context. */
+    data: Record<string, any>;
+    /** Type of context. */
+    type: string;
+}
+/**
+ * Metadata about when and by whom a message was created.
+ */
+export interface AgentMessageMetadata {
+    /** When the message was created. */
+    created_date: string;
+    /** Email of the user who created the message. */
+    created_by_email: string;
+    /** Full name of the user who created the message. */
+    created_by_full_name: string;
+}
+/**
+ * An agent conversation containing messages exchanged with an AI agent.
+ */
+export interface AgentConversation {
+    /** Unique identifier for the conversation. */
+    id: string;
+    /** App ID. */
+    app_id: string;
+    /** Name of the agent in this conversation. */
+    agent_name: string;
+    /** ID of the user who created the conversation. */
+    created_by_id: string;
+    /** When the conversation was created. */
+    created_date: string;
+    /** When the conversation was last updated. */
+    updated_date: string;
+    /** Array of messages in the conversation. */
+    messages: AgentMessage[];
+    /** Optional metadata associated with the conversation. */
+    metadata?: Record<string, any>;
+}
+/**
+ * A message in an agent conversation.
+ */
+export interface AgentMessage {
+    /** Unique identifier for the message. */
+    id: string;
+    /** Role of the message sender. */
+    role: "user" | "assistant" | "system";
+    /** When the message was created. */
+    created_date: string;
+    /** When the message was last updated. */
+    updated_date: string;
+    /** Optional reasoning information for the message. */
+    reasoning?: AgentMessageReasoning | null;
+    /** Message content. */
+    content?: string | Record<string, any>;
+    /** URLs to files attached to the message. */
+    file_urls?: string[];
+    /** Tool calls made by the agent. */
+    tool_calls?: AgentMessageToolCall[];
+    /** Token usage statistics. */
+    usage?: AgentMessageUsage;
+    /** Whether the message is hidden from the user. */
+    hidden?: boolean;
+    /** Custom context provided with the message. */
+    custom_context?: AgentMessageCustomContext[];
+    /** Model used to generate the message. */
+    model?: string;
+    /** Checkpoint ID for the message. */
+    checkpoint_id?: string;
+    /** Metadata about when and by whom the message was created. */
+    metadata?: AgentMessageMetadata;
+    /** Additional custom parameters for the message. */
+    additional_message_params?: Record<string, any>;
+}
+/**
+ * Parameters for creating a new conversation.
+ */
+export interface CreateConversationParams {
+    /** The name of the agent to create a conversation with. */
+    agent_name: AgentName;
+    /** Optional metadata to attach to the conversation. */
+    metadata?: Record<string, any>;
+}
+/**
+ * Configuration for creating the agents module.
+ * @internal
+ */
+export interface AgentsModuleConfig {
+    /** Axios instance for HTTP requests */
+    axios: AxiosInstance;
+    /** Function to get WebSocket instance for realtime updates (lazy initialization) */
+    getSocket: () => ReturnType<typeof RoomsSocket>;
+    /** App ID */
+    appId: string;
+    /** Server URL */
+    serverUrl?: string;
+    /** Authentication token */
+    token?: string;
+}
+/**
+ * Agents module for managing AI agent conversations.
+ *
+ * This module provides methods to create and manage conversations with AI agents,
+ * send messages, and subscribe to realtime updates. Conversations can be used
+ * for chat interfaces, support systems, or any interactive AI app.
+ *
+ * ## Key Features
+ *
+ * The agents module enables you to:
+ *
+ * - **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 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.
+ *
+ * ## Conversation Structure
+ *
+ * The agents module operates with a two-level hierarchy:
+ *
+ * 1. **Conversations**: Top-level containers that represent a dialogue with a specific agent. Each conversation has a unique ID, is associated with an agent by name, and belongs to the user who created it. Conversations can include optional metadata for tracking app-specific context like ticket IDs, categories, or custom fields.
+ *
+ * 2. **Messages**: Individual exchanges within a conversation. Each message has a role, content, and optional metadata like token usage, tool calls, file attachments, and reasoning information. Messages are stored as an array within their parent conversation.
+ *
+ * ## Authentication Modes
+ *
+ * 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. 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.
+ *
+ * ## Generated Types
+ *
+ * If you're working in a TypeScript project, you can generate types from your agents to get autocomplete on agent names when creating conversations or subscribing to updates. See the [Dynamic Types](/developers/references/sdk/getting-started/dynamic-types) guide to get started.
+ */
+export interface AgentsModule {
+    /**
+     * Gets all conversations from all agents in the app.
+     *
+     * Retrieves all conversations. Use {@linkcode listConversations | listConversations()} to filter which conversations are returned, apply sorting, or paginate results. Use {@linkcode getConversation | getConversation()} to retrieve a specific conversation by ID.
+     *
+     * @returns Promise resolving to an array of conversations.
+     *
+     * @example
+     * ```typescript
+     * // Get all conversations
+     * const conversations = await base44.agents.getConversations();
+     * console.log(`Total conversations: ${conversations.length}`);
+     * ```
+     *
+     * @see {@linkcode listConversations | listConversations()} for filtering, sorting, and pagination
+     * @see {@linkcode getConversation | getConversation()} for retrieving a specific conversation by ID
+     */
+    getConversations(): Promise<AgentConversation[]>;
+    /**
+     * Gets a specific conversation by ID.
+     *
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * // Get a specific conversation by ID
+     * const conversation = await base44.agents.getConversation('conv-123');
+     * if (conversation) {
+     *   console.log(`Conversation has ${conversation.messages.length} messages`);
+     * }
+     * ```
+     *
+     * @see {@linkcode getConversations | getConversations()} for retrieving all conversations
+     * @see {@linkcode listConversations | listConversations()} for filtering and sorting conversations
+     */
+    getConversation(conversationId: string): Promise<AgentConversation | undefined>;
+    /**
+     * Lists conversations with filtering, sorting, and pagination.
+     *
+     * Provides querying capabilities including filtering by fields, sorting, pagination, and field selection. For cases where you need all conversations without filtering, use {@linkcode getConversations | getConversations()}. To retrieve a specific conversation by ID, use {@linkcode getConversation | getConversation()}.
+     *
+     * @param filterParams - Filter parameters for querying conversations.
+     * @returns Promise resolving to an array of filtered conversations.
+     *
+     * @example
+     * ```typescript
+     * // List recent conversations with pagination
+     * const recentConversations = await base44.agents.listConversations({
+     *   limit: 10,
+     *   sort: '-created_date'
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filter by agent and metadata
+     * const supportConversations = await base44.agents.listConversations({
+     *   q: {
+     *     agent_name: 'support-agent',
+     *     'metadata.priority': 'high'
+     *   },
+     *   sort: '-created_date',
+     *   limit: 20
+     * });
+     * ```
+     *
+     * @see {@linkcode getConversations | getConversations()} for retrieving all conversations without filtering
+     * @see {@linkcode getConversation | getConversation()} for retrieving a specific conversation by ID
+     */
+    listConversations(filterParams: ModelFilterParams): Promise<AgentConversation[]>;
+    /**
+     * Creates a new conversation with an agent.
+     *
+     * @param conversation - Conversation details including agent name and optional metadata.
+     * @returns Promise resolving to the created conversation.
+     *
+     * @example
+     * ```typescript
+     * // Create a new conversation with metadata
+     * const conversation = await base44.agents.createConversation({
+     *   agent_name: 'support-agent',
+     *   metadata: {
+     *     order_id: 'ORD-789',
+     *     product_id: 'PROD-456',
+     *     category: 'technical-support'
+     *   }
+     * });
+     * console.log(`Created conversation: ${conversation.id}`);
+     * ```
+     */
+    createConversation(conversation: CreateConversationParams): Promise<AgentConversation>;
+    /**
+     * Adds a message to a conversation.
+     *
+     * Sends a message to the agent and updates the conversation. This method
+     * also updates the realtime socket to notify any subscribers.
+     *
+     * @param conversation - The conversation to add the message to.
+     * @param message - The message to add.
+     * @returns Promise resolving to the created message.
+     *
+     * @example
+     * ```typescript
+     * // Send a message to the agent
+     * const message = await base44.agents.addMessage(conversation, {
+     *   role: 'user',
+     *   content: 'Hello, I need help with my order #12345'
+     * });
+     * console.log(`Message sent with ID: ${message.id}`);
+     * ```
+     */
+    addMessage(conversation: AgentConversation, message: Partial<AgentMessage>): Promise<AgentMessage>;
+    /**
+     * 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. 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 realtime updates
+     * const unsubscribe = base44.agents.subscribeToConversation(
+     *   'conv-123',
+     *   (updatedConversation) => {
+     *     const latestMessage = updatedConversation.messages[updatedConversation.messages.length - 1];
+     *     console.log('New message:', latestMessage.content);
+     *   }
+     * );
+     *
+     * // Later, clean up the subscription
+     * unsubscribe();
+     * ```
+     */
+    subscribeToConversation(conversationId: string, onUpdate?: (conversation: AgentConversation) => void): () => void;
+    /**
+     * Gets WhatsApp connection URL for an agent.
+     *
+     * Generates a URL that users can use to connect with the agent through WhatsApp.
+     * The URL includes authentication if a token is available.
+     *
+     * @param agentName - The name of the agent.
+     * @returns WhatsApp connection URL.
+     *
+     * @example
+     * ```typescript
+     * // Get WhatsApp connection URL
+     * const whatsappUrl = base44.agents.getWhatsAppConnectURL('support-agent');
+     * console.log(`Connect through WhatsApp: ${whatsappUrl}`);
+     * // User can open this URL to start a WhatsApp conversation
+     * ```
+     */
+    getWhatsAppConnectURL(agentName: AgentName): string;
+}

package/dist/modules/agents.types.js

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

package/dist/modules/analytics.d.ts

@@ -0,0 +1,20 @@
+import { AxiosInstance } from "axios";
+import { TrackEventParams, AnalyticsModuleOptions } from "./analytics.types";
+import type { AuthModule } from "./auth.types";
+export declare const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
+export declare const ANALYTICS_INITIALIZATION_EVENT_NAME = "__initialization_event__";
+export declare const ANALYTICS_SESSION_DURATION_EVENT_NAME = "__session_duration_event__";
+export declare const ANALYTICS_CONFIG_ENABLE_URL_PARAM_KEY = "analytics-enable";
+export declare const ANALYTICS_SESSION_ID_LOCAL_STORAGE_KEY = "base44_analytics_session_id";
+export interface AnalyticsModuleArgs {
+    axiosClient: AxiosInstance;
+    serverUrl: string;
+    appId: string;
+    userAuthModule: AuthModule;
+}
+export declare const createAnalyticsModule: ({ axiosClient, serverUrl, appId, userAuthModule, }: AnalyticsModuleArgs) => {
+    track: (params: TrackEventParams) => void;
+    cleanup: () => void;
+};
+export declare function getAnalyticsConfigFromUrlParams(): AnalyticsModuleOptions | undefined;
+export declare function getAnalyticsSessionId(): string;