@base44-preview/sdk 0.8.18-pr.78.cf66512 → 0.8.18-pr.79.454901f

package/dist/client.types.d.ts

@@ -74,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;
     /**
@@ -115,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,7 +4,7 @@ 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, 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";

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

@@ -72,7 +72,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;
@@ -138,9 +138,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 +151,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 +159,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.
  *
@@ -275,7 +275,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 +293,25 @@ 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.
      *
      * @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) => {

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.types.d.ts

@@ -176,6 +176,7 @@ export interface AuthModule {
      *
      * Initiates OAuth/SSO login flow with providers like Google, Microsoft, etc. Requires a browser environment and can't be used in the backend.
      *
+     * @internal
      * @param provider - Name of the supported authentication provider (e.g., 'google', 'microsoft').
      * @param fromUrl - URL to redirect to after successful authentication. Defaults to '/'.
      *
@@ -190,6 +191,7 @@ export interface AuthModule {
      * // Login with GitHub and redirect to dashboard
      * base44.auth.loginWithProvider('microsoft', '/dashboard');
      * ```
+     * @internal
      */
     loginWithProvider(provider: string, fromUrl?: string): void;
     /**

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

@@ -11,9 +11,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 +24,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

@@ -19,10 +19,6 @@ export interface RealtimeEvent {
  * Callback function invoked when a realtime event occurs.
  */
 export type RealtimeCallback = (event: RealtimeEvent) => void;
-/**
- * Function returned from subscribe, call it to unsubscribe.
- */
-export type Subscription = () => void;
 /**
  * Entity handler providing CRUD operations for a specific entity type.
  *
@@ -270,10 +266,16 @@ export interface EntityHandler {
     /**
      * 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,11 +284,11 @@ 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): () => void;
 }
 /**
  * Entities module for managing app data.

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-preview/sdk",
-  "version": "0.8.18-pr.78.cf66512",
+  "version": "0.8.18-pr.79.454901f",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,9 @@
     "docs": "typedoc",
     "prepublishOnly": "npm run build",
     "create-docs": "npm run create-docs:generate && npm run create-docs:process",
+    "create-docs-local": "npm run create-docs && npm run copy-docs-local",
     "push-docs": "node scripts/mintlify-post-processing/push-to-docs-repo.js",
+    "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"
   },