@base44-preview/sdk 0.8.13-pr.63.6dc705a → 0.8.13-pr.70.e91dc9c

package/dist/client.js

@@ -47,11 +47,7 @@ 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, useStagingDb: configUseStagingDb, } = config;
-    // Config takes precedence, fallback to URL query param in browser
-    const urlHasStagingDb = typeof window !== "undefined"
-        && new URLSearchParams(window.location.search).get("use_staging_db") === "true";
-    const useStagingDb = configUseStagingDb !== null && configUseStagingDb !== void 0 ? configUseStagingDb : urlHasStagingDb;
+    const { serverUrl = "https://base44.app", appId, token, serviceToken, requiresAuth = false, appBaseUrl, options, functionsVersion, headers: optionalHeaders, } = config;
     const socketConfig = {
         serverUrl,
         mountPath: "/ws-user-apps/socket.io/",
@@ -71,7 +67,6 @@ export function createClient(config) {
     const headers = {
         ...optionalHeaders,
         "X-App-Id": String(appId),
-        "Base44-Use-Staging-DB": String(useStagingDb),
     };
     const functionHeaders = functionsVersion
         ? {
@@ -109,7 +104,11 @@ export function createClient(config) {
         serverUrl,
     });
     const userModules = {
-        entities: createEntitiesModule(axiosClient, appId),
+        entities: createEntitiesModule({
+            axios: axiosClient,
+            appId,
+            getSocket,
+        }),
         integrations: createIntegrationsModule(axiosClient, appId),
         auth: userAuthModule,
         functions: createFunctionsModule(functionsAxiosClient, appId),
@@ -136,7 +135,11 @@ export function createClient(config) {
         },
     };
     const serviceRoleModules = {
-        entities: createEntitiesModule(serviceRoleAxiosClient, appId),
+        entities: createEntitiesModule({
+            axios: serviceRoleAxiosClient,
+            appId,
+            getSocket,
+        }),
         integrations: createIntegrationsModule(serviceRoleAxiosClient, appId),
         sso: createSsoModule(serviceRoleAxiosClient, appId, token),
         connectors: createConnectorsModule(serviceRoleAxiosClient, appId),
@@ -304,7 +307,6 @@ export function createClientFromRequest(request) {
     const appId = request.headers.get("Base44-App-Id");
     const serverUrlHeader = request.headers.get("Base44-Api-Url");
     const functionsVersion = request.headers.get("Base44-Functions-Version");
-    const useStagingDb = request.headers.get("Base44-Use-Staging-DB") === "true";
     const stateHeader = request.headers.get("Base44-State");
     if (!appId) {
         throw new Error("Base44-App-Id header is required, but is was not found on the request");
@@ -339,7 +341,6 @@ export function createClientFromRequest(request) {
         token: userToken,
         serviceToken: serviceRoleToken,
         functionsVersion: functionsVersion !== null && functionsVersion !== void 0 ? functionsVersion : undefined,
-        useStagingDb: useStagingDb !== null && useStagingDb !== void 0 ? useStagingDb : undefined,
         headers: additionalHeaders,
     });
 }

package/dist/client.types.d.ts

@@ -60,11 +60,6 @@ export interface CreateClientConfig {
      * @internal
      */
     headers?: Record<string, string>;
-    /**
-     * Whether to use the staging database. Defaults to false.
-     * When true, API requests will use the staging database instead of production.
-     */
-    useStagingDb?: boolean;
     /**
      * Additional client options.
      */

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, } from "./modules/entities.types.js";
+export type { EntitiesModule, EntityHandler, RealtimeEventType, RealtimeEvent, RealtimeCallback, Subscription, } 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;
@@ -140,7 +140,7 @@ export interface AgentsModuleConfig {
     axios: AxiosInstance;
     /** Function to get WebSocket instance for real-time updates (lazy initialization) */
     getSocket: () => ReturnType<typeof RoomsSocket>;
-    /** Application ID */
+    /** App ID */
     appId: string;
     /** Server URL */
     serverUrl?: string;

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

@@ -3,20 +3,23 @@
  */
 export interface CustomIntegrationCallParams {
     /**
-     * Request body payload to send to the external API.
+     * Request body to send to the external API. The payload is JSON-serialized before being sent.
      */
     payload?: Record<string, any>;
     /**
-     * Path parameters to substitute in the URL (e.g., `{ owner: "user", repo: "repo" }`).
+     * Path parameters to substitute into the URL template.
+     * For example, if the API endpoint is `/repos/{owner}/{repo}/issues`,
+     * pass `{ owner: "myorg", repo: "myrepo" }`.
      */
     pathParams?: Record<string, string>;
     /**
      * Query string parameters to append to the URL.
+     * For example, `{ state: "open", per_page: 50 }` becomes `?state=open&per_page=50`.
      */
     queryParams?: Record<string, any>;
     /**
-     * Additional headers to send with this specific request.
-     * These are merged with the integration's configured headers.
+     * Additional HTTP headers to include in the request.
+     * These headers are merged with any headers configured for the integration itself, with headers specified here taking precedence in case of conflicts.
      */
     headers?: Record<string, string>;
 }
@@ -33,66 +36,25 @@ export interface CustomIntegrationCallResponse {
      */
     status_code: number;
     /**
-     * The response data from the external API.
-     * Can be any JSON-serializable value depending on the external API's response.
+     * The parsed JSON response body from the external API.
+     * The structure depends on the API endpoint being called.
      */
     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 }
- *   }
- * );
- *
- * 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 module for calling workspace-level API integrations.
  */
 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.
+     * Custom integrations are external APIs that have been pre-configured by a workspace administrator who imports an OpenAPI specification. Each integration is identified by a slug and exposes operations defined in the specification.
+     *
+     * Requests are proxied through Base44's backend, so API credentials aren't exposed. That means you can safely use this method to call external APIs from frontend code.
+     *
+     * @param slug - The integration's unique identifier, as defined by the workspace admin.
+     * @param operationId - The operation ID from the OpenAPI specification, such as `"listIssues"` or `"getUser"`.
+     * @param params - Optional parameters to send to the external API.
      * @returns Promise resolving to the integration call response.
      *
      * @throws {Error} If slug is not provided.
@@ -100,6 +62,38 @@ 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
+     * // GET request with path and query parameters
+     * const response = await base44.integrations.custom.call(
+     *   "github",
+     *   "listRepoIssues",
+     *   {
+     *     pathParams: { owner: "myorg", repo: "myrepo" },
+     *     queryParams: { state: "open", per_page: 50 }
+     *   }
+     * );
+     *
+     * if (response.success) {
+     *   console.log("Found issues:", response.data.length);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // POST request with a JSON body
+     * const response = await base44.integrations.custom.call(
+     *   "slack",
+     *   "postMessage",
+     *   {
+     *     payload: {
+     *       channel: "#general",
+     *       text: "Hello from Base44!"
+     *     }
+     *   }
+     * );
+     * ```
      */
     call(slug: string, operationId: string, params?: CustomIntegrationCallParams): Promise<CustomIntegrationCallResponse>;
 }

package/dist/modules/entities.d.ts

@@ -1,11 +1,20 @@
 import { AxiosInstance } from "axios";
 import { EntitiesModule } from "./entities.types";
+import { RoomsSocket } from "../utils/socket-utils.js";
+/**
+ * Configuration for the entities module.
+ * @internal
+ */
+export interface EntitiesModuleConfig {
+    axios: AxiosInstance;
+    appId: string;
+    getSocket: () => ReturnType<typeof RoomsSocket>;
+}
 /**
  * Creates the entities module for the Base44 SDK.
  *
- * @param axios - Axios instance
- * @param appId - Application ID
+ * @param config - Configuration object containing axios, appId, and getSocket
  * @returns Entities module with dynamic entity access
  * @internal
  */
-export declare function createEntitiesModule(axios: AxiosInstance, appId: string): EntitiesModule;
+export declare function createEntitiesModule(config: EntitiesModuleConfig): EntitiesModule;

package/dist/modules/entities.js

@@ -1,12 +1,12 @@
 /**
  * Creates the entities module for the Base44 SDK.
  *
- * @param axios - Axios instance
- * @param appId - Application ID
+ * @param config - Configuration object containing axios, appId, and getSocket
  * @returns Entities module with dynamic entity access
  * @internal
  */
-export function createEntitiesModule(axios, appId) {
+export function createEntitiesModule(config) {
+    const { axios, appId, getSocket } = config;
     // Using Proxy to dynamically handle entity names
     return new Proxy({}, {
         get(target, entityName) {
@@ -17,20 +17,41 @@ export function createEntitiesModule(axios, appId) {
                 return undefined;
             }
             // Create entity handler
-            return createEntityHandler(axios, appId, entityName);
+            return createEntityHandler(axios, appId, entityName, getSocket);
         },
     });
 }
+/**
+ * Parses the realtime message data and extracts event information.
+ * @internal
+ */
+function parseRealtimeMessage(dataStr) {
+    var _a;
+    try {
+        const parsed = JSON.parse(dataStr);
+        return {
+            type: parsed.type,
+            data: parsed.data,
+            id: parsed.id || ((_a = parsed.data) === null || _a === void 0 ? void 0 : _a.id),
+            timestamp: parsed.timestamp || new Date().toISOString(),
+        };
+    }
+    catch (error) {
+        console.warn("[Base44 SDK] Failed to parse realtime message:", error);
+        return null;
+    }
+}
 /**
  * Creates a handler for a specific entity.
  *
  * @param axios - Axios instance
  * @param appId - Application ID
  * @param entityName - Entity name
+ * @param getSocket - Function to get the socket instance
  * @returns Entity handler with CRUD methods
  * @internal
  */
-function createEntityHandler(axios, appId, entityName) {
+function createEntityHandler(axios, appId, entityName, getSocket) {
     const baseURL = `/apps/${appId}/entities/${entityName}`;
     return {
         // List entities with optional pagination and sorting
@@ -95,5 +116,26 @@ function createEntityHandler(axios, appId, entityName) {
                 },
             });
         },
+        // Subscribe to realtime updates
+        subscribe(callback) {
+            const room = `entities:${appId}:${entityName}`;
+            // Get the socket and subscribe to the room
+            const socket = getSocket();
+            const unsubscribe = socket.subscribeToRoom(room, {
+                update_model: (msg) => {
+                    const event = parseRealtimeMessage(msg.data);
+                    if (!event) {
+                        return;
+                    }
+                    try {
+                        callback(event);
+                    }
+                    catch (error) {
+                        console.error("[Base44 SDK] Subscription callback error:", error);
+                    }
+                },
+            });
+            return unsubscribe;
+        },
     };
 }

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

@@ -1,3 +1,28 @@
+/**
+ * Event types for realtime entity updates.
+ */
+export type RealtimeEventType = "create" | "update" | "delete";
+/**
+ * Payload received when a realtime event occurs.
+ */
+export interface RealtimeEvent {
+    /** The type of change that occurred */
+    type: RealtimeEventType;
+    /** The entity data */
+    data: any;
+    /** The unique identifier of the affected entity */
+    id: string;
+    /** ISO 8601 timestamp of when the event occurred */
+    timestamp: string;
+}
+/**
+ * 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.
  *
@@ -242,6 +267,26 @@ export interface EntityHandler {
      * ```
      */
     importEntities(file: File): Promise<any>;
+    /**
+     * Subscribes to realtime updates for all records of this entity type.
+     *
+     * Receives notifications whenever any record is created, updated, or deleted.
+     *
+     * @param callback - Function called when an entity changes.
+     * @returns Unsubscribe function to stop listening.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to all Task changes
+     * const unsubscribe = base44.entities.Task.subscribe((event) => {
+     *   console.log(`Task ${event.id} was ${event.type}d:`, event.data);
+     * });
+     *
+     * // Later, unsubscribe
+     * unsubscribe();
+     * ```
+     */
+    subscribe(callback: RealtimeCallback): Subscription;
 }
 /**
  * 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.13-pr.63.6dc705a",
+  "version": "0.8.13-pr.70.e91dc9c",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",