@base44/sdk 0.8.19 → 0.8.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/client.js CHANGED
@@ -3,7 +3,7 @@ import { createEntitiesModule } from "./modules/entities.js";
3
3
  import { createIntegrationsModule } from "./modules/integrations.js";
4
4
  import { createAuthModule } from "./modules/auth.js";
5
5
  import { createSsoModule } from "./modules/sso.js";
6
- import { createConnectorsModule } from "./modules/connectors.js";
6
+ import { createConnectorsModule, createUserConnectorsModule, } from "./modules/connectors.js";
7
7
  import { getAccessToken } from "./utils/auth-utils.js";
8
8
  import { createFunctionsModule } from "./modules/functions.js";
9
9
  import { createAgentsModule } from "./modules/agents.js";
@@ -114,6 +114,7 @@ export function createClient(config) {
114
114
  getSocket,
115
115
  }),
116
116
  integrations: createIntegrationsModule(axiosClient, appId),
117
+ connectors: createUserConnectorsModule(axiosClient, appId),
117
118
  auth: userAuthModule,
118
119
  functions: createFunctionsModule(functionsAxiosClient, appId),
119
120
  agents: createAgentsModule({
@@ -2,7 +2,7 @@ import type { EntitiesModule } from "./modules/entities.types.js";
2
2
  import type { IntegrationsModule } from "./modules/integrations.types.js";
3
3
  import type { AuthModule } from "./modules/auth.types.js";
4
4
  import type { SsoModule } from "./modules/sso.types.js";
5
- import type { ConnectorsModule } from "./modules/connectors.types.js";
5
+ import type { ConnectorsModule, UserConnectorsModule } from "./modules/connectors.types.js";
6
6
  import type { FunctionsModule } from "./modules/functions.types.js";
7
7
  import type { AgentsModule } from "./modules/agents.types.js";
8
8
  import type { AppLogsModule } from "./modules/app-logs.types.js";
@@ -21,8 +21,13 @@ export interface CreateClientOptions {
21
21
  */
22
22
  export interface CreateClientConfig {
23
23
  /**
24
- * The Base44 server URL. Defaults to "https://base44.app".
25
- * @internal
24
+ * The Base44 server URL.
25
+ *
26
+ * You don't need to set this for production use. The SDK defaults to `https://base44.app`.
27
+ *
28
+ * Set this when using a local development server to point SDK requests at your local machine instead of the hosted backend.
29
+ *
30
+ * @defaultValue `"https://base44.app"`
26
31
  */
27
32
  serverUrl?: string;
28
33
  /**
@@ -82,6 +87,8 @@ export interface Base44Client {
82
87
  appLogs: AppLogsModule;
83
88
  /** {@link AuthModule | Auth module} for user authentication and management. */
84
89
  auth: AuthModule;
90
+ /** {@link UserConnectorsModule | Connectors module} for app-user OAuth flows. */
91
+ connectors: UserConnectorsModule;
85
92
  /** {@link EntitiesModule | Entities module} for CRUD operations on your data models. */
86
93
  entities: EntitiesModule;
87
94
  /** {@link FunctionsModule | Functions module} for invoking custom backend functions. */
package/dist/index.d.ts CHANGED
@@ -4,13 +4,13 @@ import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from
4
4
  export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
5
5
  export type { Base44Client, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
6
6
  export * from "./types.js";
7
- export type { EntitiesModule, EntityHandler, EntityRecord, EntityTypeRegistry, RealtimeEventType, RealtimeEvent, RealtimeCallback, } from "./modules/entities.types.js";
7
+ export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
8
8
  export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
9
- export type { IntegrationsModule, IntegrationPackage, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
10
- export type { FunctionsModule, FunctionNameRegistry, } from "./modules/functions.types.js";
11
- export type { AgentsModule, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
9
+ export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
10
+ export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";
11
+ export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
12
12
  export type { AppLogsModule } from "./modules/app-logs.types.js";
13
13
  export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
14
- export type { ConnectorsModule } from "./modules/connectors.types.js";
14
+ export type { ConnectorsModule, UserConnectorsModule, } from "./modules/connectors.types.js";
15
15
  export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";
16
16
  export type { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions, } from "./utils/auth-utils.types.js";
@@ -2,13 +2,19 @@ import { AxiosInstance } from "axios";
2
2
  import { RoomsSocket } from "../utils/socket-utils.js";
3
3
  import { ModelFilterParams } from "../types.js";
4
4
  /**
5
- * Registry of agent names.
6
- * Augment this interface to enable autocomplete for agent names.
5
+ * 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.
7
6
  */
8
7
  export interface AgentNameRegistry {
9
8
  }
10
9
  /**
11
- * Agent name type - uses registry keys if augmented, otherwise string.
10
+ * Union of all agent names from the [`AgentNameRegistry`](#agentnameregistry). Defaults to `string` when no types have been generated.
11
+ *
12
+ * @example
13
+ * ```typescript
14
+ * // Using generated agent name types
15
+ * // With generated types, you get autocomplete on agent names
16
+ * const conversation = await base44.agents.createConversation({ agent_name: 'SupportBot' });
17
+ * ```
12
18
  */
13
19
  export type AgentName = keyof AgentNameRegistry extends never ? string : keyof AgentNameRegistry;
14
20
  /**
@@ -164,6 +170,8 @@ export interface AgentsModuleConfig {
164
170
  * send messages, and subscribe to realtime updates. Conversations can be used
165
171
  * for chat interfaces, support systems, or any interactive AI app.
166
172
  *
173
+ * ## Key Features
174
+ *
167
175
  * The agents module enables you to:
168
176
  *
169
177
  * - **Create conversations** with agents defined in the app.
@@ -173,17 +181,24 @@ export interface AgentsModuleConfig {
173
181
  * - **Attach metadata** to conversations for tracking context, categories, priorities, or linking to external systems.
174
182
  * - **Generate WhatsApp connection URLs** for users to interact with agents through WhatsApp.
175
183
  *
184
+ * ## Conversation Structure
185
+ *
176
186
  * The agents module operates with a two-level hierarchy:
177
187
  *
178
188
  * 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.
179
189
  *
180
190
  * 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.
181
191
  *
192
+ * ## Authentication Modes
193
+ *
182
194
  * This module is available to use with a client in all authentication modes:
183
195
  *
184
196
  * - **Anonymous or User authentication** (`base44.agents`): Access is scoped to the current user's permissions. Users must be authenticated to create and access conversations.
185
197
  * - **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.
186
198
  *
199
+ * ## Generated Types
200
+ *
201
+ * 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.
187
202
  */
188
203
  export interface AgentsModule {
189
204
  /**
@@ -208,7 +223,7 @@ export interface AgentsModule {
208
223
  * Gets a specific conversation by ID.
209
224
  *
210
225
  * Retrieves a single conversation using its unique identifier. To retrieve
211
- * all conversations, use {@linkcode getConversations | getConversations()} To filter, sort, or paginate conversations, use {@linkcode listConversations | listConversations()}.
226
+ * all conversations, use {@linkcode getConversations | getConversations()}. To filter, sort, or paginate conversations, use {@linkcode listConversations | listConversations()}.
212
227
  *
213
228
  * This function returns the complete stored conversation including full tool call results, even for large responses.
214
229
  *
@@ -312,8 +327,8 @@ export interface AgentsModule {
312
327
  * to clean up the connection.
313
328
  *
314
329
  * <Note>
315
- 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.
316
- </Note>
330
+ * 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.
331
+ * </Note>
317
332
  *
318
333
  * @param conversationId - The conversation ID to subscribe to.
319
334
  * @param onUpdate - Callback function called when the conversation is updated. The callback receives a conversation object with the following properties:
@@ -74,11 +74,15 @@ export type AnalyticsModuleOptions = {
74
74
  *
75
75
  * <Note> Analytics events tracked with this module appear as custom event cards in the [Analytics dashboard](/documentation/performance-and-seo/app-analytics).</Note>
76
76
  *
77
+ * ## Best Practices
78
+ *
77
79
  * When tracking events:
78
80
  *
79
81
  * - Choose clear, descriptive event names in snake_case like `signup_button_click` or `purchase_completed` rather than generic names like `click`.
80
82
  * - Include relevant context in your properties such as identifiers like `product_id`, measurements like `price`, and flags like `is_first_purchase`.
81
83
  *
84
+ * ## Authentication Modes
85
+ *
82
86
  * This module is only available in user authentication mode (`base44.analytics`).
83
87
  */
84
88
  export interface AnalyticsModule {
@@ -3,6 +3,8 @@
3
3
  *
4
4
  * This module provides a method to log user activity. The logs are reflected in the Analytics page in the app dashboard.
5
5
  *
6
+ * ## Authentication Modes
7
+ *
6
8
  * This module is available to use with a client in all authentication modes.
7
9
  */
8
10
  export interface AppLogsModule {
@@ -37,9 +37,18 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
37
37
  loginWithProvider(provider, fromUrl = "/") {
38
38
  // Build the full redirect URL
39
39
  const redirectUrl = new URL(fromUrl, window.location.origin).toString();
40
- // Build the provider login URL (google is the default, so no provider path needed)
41
- const providerPath = provider === "google" ? "" : `/${provider}`;
42
- const loginUrl = `${options.appBaseUrl}/api/apps/auth${providerPath}/login?app_id=${appId}&from_url=${encodeURIComponent(redirectUrl)}`;
40
+ const queryParams = `app_id=${appId}&from_url=${encodeURIComponent(redirectUrl)}`;
41
+ // SSO uses a different URL structure with appId in the path
42
+ let authPath;
43
+ if (provider === "sso") {
44
+ authPath = `/apps/${appId}/auth/sso/login`;
45
+ }
46
+ else {
47
+ // Google is the default provider, so no provider path segment needed
48
+ const providerPath = provider === "google" ? "" : `/${provider}`;
49
+ authPath = `/apps/auth${providerPath}/login`;
50
+ }
51
+ const loginUrl = `${options.appBaseUrl}/api${authPath}?${queryParams}`;
43
52
  // Redirect to the provider login page
44
53
  window.location.href = loginUrl;
45
54
  },
@@ -96,6 +96,8 @@ export interface AuthModuleOptions {
96
96
  /**
97
97
  * Authentication module for managing user authentication and authorization. The module automatically stores tokens in local storage when available and manages authorization headers for API requests.
98
98
  *
99
+ * ## Features
100
+ *
99
101
  * This module provides comprehensive authentication functionality including:
100
102
  * - Email/password login and registration
101
103
  * - Token management
@@ -104,6 +106,8 @@ export interface AuthModuleOptions {
104
106
  * - OTP verification
105
107
  * - User invitations
106
108
  *
109
+ * ## Authentication Modes
110
+ *
107
111
  * The auth module is only available in user authentication mode (`base44.auth`).
108
112
  */
109
113
  export interface AuthModule {
@@ -177,24 +181,39 @@ export interface AuthModule {
177
181
  * Initiates an OAuth login flow with one of the built-in providers. Requires a browser environment and can't be used in the backend.
178
182
  *
179
183
  * Supported providers:
180
- * - `'google'` - {@link https://developers.google.com/identity/protocols/oauth2 | Google OAuth}. Enabled by default.
181
- * - `'microsoft'` - {@link https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow | Microsoft OAuth}. Enable Microsoft in your app's authentication settings before specifying this provider.
182
- * - `'facebook'` - {@link https://developers.facebook.com/docs/facebook-login | Facebook Login}. Enable this in your app's authentication settings before using.
184
+ * - `'google'`: {@link https://developers.google.com/identity/protocols/oauth2 | Google OAuth}. Enabled by default.
185
+ * - `'microsoft'`: {@link https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow | Microsoft OAuth}. Enable Microsoft in your app's authentication settings before specifying this provider.
186
+ * - `'facebook'`: {@link https://developers.facebook.com/docs/facebook-login | Facebook Login}. Enable Facebook in your app's authentication settings before using.
187
+ * - `'apple'`: {@link https://developer.apple.com/sign-in-with-apple/ | Sign in with Apple}. Enable Apple in your app's authentication settings before using this provider.
188
+ * - `'sso'`: Enterprise SSO. {@link https://docs.base44.com/Setting-up-your-app/Setting-up-SSO | Set up an SSO provider} in your app's authentication settings before using this provider.
183
189
  *
184
- * @param provider - The authentication provider to use: `'google'`, `'microsoft'`, or `'facebook'`.
190
+ * @param provider - The authentication provider to use: `'google'`, `'microsoft'`, `'facebook'`, `'apple'`, or `'sso'`.
185
191
  * @param fromUrl - URL to redirect to after successful authentication. Defaults to `'/'`.
186
192
  *
187
193
  * @example
188
194
  * ```typescript
189
- * // Login with Google and return to current page
195
+ * // Google
190
196
  * base44.auth.loginWithProvider('google', window.location.pathname);
191
197
  * ```
192
198
  *
193
199
  * @example
194
200
  * ```typescript
195
- * // Login with Microsoft and redirect to dashboard
201
+ * // Microsoft
196
202
  * base44.auth.loginWithProvider('microsoft', '/dashboard');
197
203
  * ```
204
+ *
205
+ * @example
206
+ * ```typescript
207
+ * // Apple
208
+ * base44.auth.loginWithProvider('apple', '/dashboard');
209
+ * ```
210
+ *
211
+ * @example
212
+ * ```typescript
213
+ * // SSO
214
+ * base44.auth.loginWithProvider('sso', '/dashboard');
215
+ * ```
216
+ *
198
217
  */
199
218
  loginWithProvider(provider: string, fromUrl?: string): void;
200
219
  /**
@@ -1,5 +1,5 @@
1
1
  import { AxiosInstance } from "axios";
2
- import { ConnectorsModule } from "./connectors.types.js";
2
+ import { ConnectorsModule, UserConnectorsModule } from "./connectors.types.js";
3
3
  /**
4
4
  * Creates the Connectors module for the Base44 SDK.
5
5
  *
@@ -9,3 +9,12 @@ import { ConnectorsModule } from "./connectors.types.js";
9
9
  * @internal
10
10
  */
11
11
  export declare function createConnectorsModule(axios: AxiosInstance, appId: string): ConnectorsModule;
12
+ /**
13
+ * Creates the user-scoped Connectors module (app-user OAuth flows).
14
+ *
15
+ * @param axios - Axios instance (user-scoped client)
16
+ * @param appId - Application ID
17
+ * @returns User connectors module with app-user OAuth methods
18
+ * @internal
19
+ */
20
+ export declare function createUserConnectorsModule(axios: AxiosInstance, appId: string): UserConnectorsModule;
@@ -8,8 +8,11 @@
8
8
  */
9
9
  export function createConnectorsModule(axios, appId) {
10
10
  return {
11
- // Retrieve an OAuth access token for a specific external integration type
12
- // @ts-expect-error Return type mismatch with interface - implementation returns object, interface expects string
11
+ /**
12
+ * Retrieve an OAuth access token for a specific external integration type.
13
+ * @deprecated Use getConnection(integrationType) and use the returned accessToken (and connectionConfig when needed) instead.
14
+ */
15
+ // @ts-expect-error Return type mismatch with interface - implementation returns string, interface expects string but implementation is typed as ConnectorAccessTokenResponse
13
16
  async getAccessToken(integrationType) {
14
17
  if (!integrationType || typeof integrationType !== "string") {
15
18
  throw new Error("Integration type is required and must be a string");
@@ -18,5 +21,51 @@ export function createConnectorsModule(axios, appId) {
18
21
  // @ts-expect-error
19
22
  return response.access_token;
20
23
  },
24
+ async getConnection(integrationType) {
25
+ var _a;
26
+ if (!integrationType || typeof integrationType !== "string") {
27
+ throw new Error("Integration type is required and must be a string");
28
+ }
29
+ const response = await axios.get(`/apps/${appId}/external-auth/tokens/${integrationType}`);
30
+ const data = response;
31
+ return {
32
+ accessToken: data.access_token,
33
+ connectionConfig: (_a = data.connection_config) !== null && _a !== void 0 ? _a : null,
34
+ };
35
+ },
36
+ };
37
+ }
38
+ /**
39
+ * Creates the user-scoped Connectors module (app-user OAuth flows).
40
+ *
41
+ * @param axios - Axios instance (user-scoped client)
42
+ * @param appId - Application ID
43
+ * @returns User connectors module with app-user OAuth methods
44
+ * @internal
45
+ */
46
+ export function createUserConnectorsModule(axios, appId) {
47
+ return {
48
+ async getCurrentAppUserAccessToken(connectorId) {
49
+ if (!connectorId || typeof connectorId !== "string") {
50
+ throw new Error("Connector ID is required and must be a string");
51
+ }
52
+ const response = await axios.get(`/apps/${appId}/app-user-auth/connectors/${connectorId}/token`);
53
+ const data = response;
54
+ return data.access_token;
55
+ },
56
+ async connectAppUser(connectorId) {
57
+ if (!connectorId || typeof connectorId !== "string") {
58
+ throw new Error("Connector ID is required and must be a string");
59
+ }
60
+ const response = await axios.post(`/apps/${appId}/app-user-auth/connectors/${connectorId}/initiate`);
61
+ const data = response;
62
+ return data.redirect_url;
63
+ },
64
+ async disconnectAppUser(connectorId) {
65
+ if (!connectorId || typeof connectorId !== "string") {
66
+ throw new Error("Connector ID is required and must be a string");
67
+ }
68
+ await axios.delete(`/apps/${appId}/app-user-auth/connectors/${connectorId}`);
69
+ },
21
70
  };
22
71
  }
@@ -1,12 +1,18 @@
1
1
  /**
2
- * Registry of connector integration types.
3
- * Augment this interface to enable autocomplete for connector integration types.
2
+ * Registry of connector integration type names. The [`types generate`](/developers/references/cli/commands/types-generate) command fills this registry, then [`ConnectorIntegrationType`](#connectorintegrationtype) resolves to a union of the keys.
4
3
  */
5
4
  export interface ConnectorIntegrationTypeRegistry {
6
5
  }
7
6
  /**
8
- * The type of external integration/connector, such as `'googlecalendar'`, `'slack'`, or `'github'`.
9
- * Uses registry keys if augmented, otherwise falls back to string.
7
+ * Union of all connector integration type names from the [`ConnectorIntegrationTypeRegistry`](#connectorintegrationtyperegistry). Defaults to `string` when no types have been generated.
8
+ *
9
+ * @example
10
+ * ```typescript
11
+ * // Using generated connector type names
12
+ * // With generated types, you get autocomplete on integration types
13
+ * const connection = await base44.asServiceRole.connectors.getConnection('googlecalendar');
14
+ * const token = connection.accessToken;
15
+ * ```
10
16
  */
11
17
  export type ConnectorIntegrationType = keyof ConnectorIntegrationTypeRegistry extends never ? string : keyof ConnectorIntegrationTypeRegistry;
12
18
  /**
@@ -14,28 +20,91 @@ export type ConnectorIntegrationType = keyof ConnectorIntegrationTypeRegistry ex
14
20
  */
15
21
  export interface ConnectorAccessTokenResponse {
16
22
  access_token: string;
23
+ integration_type: string;
24
+ connection_config: Record<string, string> | null;
25
+ }
26
+ /**
27
+ * Connection details.
28
+ */
29
+ export interface ConnectorConnectionResponse {
30
+ /** The OAuth access token for the external service. */
31
+ accessToken: string;
32
+ /** Key-value configuration for the connection, or `null` if the connector does not provide one. */
33
+ connectionConfig: Record<string, string> | null;
17
34
  }
18
35
  /**
19
- * Connectors module for managing OAuth tokens for external services.
36
+ * Connectors module for managing app-scoped OAuth tokens for external services.
20
37
  *
21
- * 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.
38
+ * 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, Slack, or GitHub, all users of the app share that same connection.
22
39
  *
23
40
  * Unlike the integrations module that provides pre-built functions, connectors give you
24
41
  * raw OAuth tokens so you can call external service APIs directly with full control over
25
42
  * the API calls you make. This is useful when you need custom API interactions that aren't
26
43
  * covered by Base44's pre-built integrations.
27
44
  *
45
+ * ## Available connectors
46
+ *
47
+ * All connectors work through [`getConnection()`](#getconnection). Pass the integration type string and use the returned OAuth token to call the external service's API directly.
48
+ *
49
+ * | Service | Type identifier |
50
+ * |---|---|
51
+ * | Airtable | `airtable` |
52
+ * | Box | `box` |
53
+ * | ClickUp | `clickup` |
54
+ * | Discord | `discord` |
55
+ * | Dropbox | `dropbox` |
56
+ * | GitHub | `github` |
57
+ * | Gmail | `gmail` |
58
+ * | Google Analytics | `google_analytics` |
59
+ * | Google BigQuery | `googlebigquery` |
60
+ * | Google Calendar | `googlecalendar` |
61
+ * | Google Classroom | `google_classroom` |
62
+ * | Google Docs | `googledocs` |
63
+ * | Google Drive | `googledrive` |
64
+ * | Google Search Console | `google_search_console` |
65
+ * | Google Sheets | `googlesheets` |
66
+ * | Google Slides | `googleslides` |
67
+ * | HubSpot | `hubspot` |
68
+ * | Linear | `linear` |
69
+ * | LinkedIn | `linkedin` |
70
+ * | Microsoft Teams | `microsoft_teams` |
71
+ * | Microsoft OneDrive | `one_drive` |
72
+ * | Notion | `notion` |
73
+ * | Outlook | `outlook` |
74
+ * | Salesforce | `salesforce` |
75
+ * | SharePoint | `share_point` |
76
+ * | Slack User | `slack` |
77
+ * | Slack Bot | `slackbot` |
78
+ * | Splitwise | `splitwise` |
79
+ * | TikTok | `tiktok` |
80
+ * | Typeform | `typeform` |
81
+ * | Wix | `wix` |
82
+ * | Wrike | `wrike` |
83
+ *
84
+ * See the integration guides for more details:
85
+ *
86
+ * - **Scopes and permissions**: {@link https://docs.base44.com/Integrations/gmail-connector#gmail-scopes-and-permissions | Gmail}, {@link https://docs.base44.com/Integrations/linkedin-connector#linkedin-scopes-and-permissions | LinkedIn}, {@link https://docs.base44.com/Integrations/slack-connector#slack-scopes-and-permissions | Slack}, {@link https://docs.base44.com/Integrations/github-connector#github-scopes-and-permissions | GitHub}
87
+ * - **Slack connector types**: {@link https://docs.base44.com/Integrations/slack-connector#about-the-slack-connectors | About the Slack connectors} explains the difference between `slack` and `slackbot`
88
+ *
89
+ * ## Authentication Modes
90
+ *
28
91
  * This module is only available to use with a client in service role authentication mode, which means it can only be used in backend environments.
92
+ *
93
+ * ## Dynamic Types
94
+ *
95
+ * If you're working in a TypeScript project, you can generate types from your app's connector configurations to get autocomplete on integration type names when calling `getConnection()`. See the [Dynamic Types](/developers/references/sdk/getting-started/dynamic-types) guide to get started.
29
96
  */
30
97
  export interface ConnectorsModule {
31
98
  /**
32
- * Retrieves an OAuth access token for a specific external integration type.
99
+ * Retrieves an OAuth access token for a specific [external integration type](#available-connectors).
100
+ *
101
+ * @deprecated Use {@link getConnection} instead.
33
102
  *
34
103
  * Returns the OAuth token string for an external service that an app builder
35
104
  * has connected to. This token represents the connected app builder's account
36
105
  * and can be used to make authenticated API calls to that external service on behalf of the app.
37
106
  *
38
- * @param integrationType - The type of integration, such as `'googlecalendar'`, `'slack'`, or `'github'`.
107
+ * @param integrationType - The type of integration, such as `'googlecalendar'`, `'slack'`, `'slackbot'`, `'github'`, or `'discord'`. See [Available connectors](#available-connectors) for the full list.
39
108
  * @returns Promise resolving to the access token string.
40
109
  *
41
110
  * @example
@@ -57,8 +126,8 @@ export interface ConnectorsModule {
57
126
  *
58
127
  * @example
59
128
  * ```typescript
60
- * // Slack connection
61
- * // Get Slack OAuth token and list channels
129
+ * // Slack User connection
130
+ * // Get Slack user token and list channels
62
131
  * const slackToken = await base44.asServiceRole.connectors.getAccessToken('slack');
63
132
  *
64
133
  * // List all public and private channels
@@ -70,6 +139,158 @@ export interface ConnectorsModule {
70
139
  *
71
140
  * const data = await slackResponse.json();
72
141
  * ```
142
+ *
143
+ * @example
144
+ * ```typescript
145
+ * // Slack Bot connection
146
+ * // Get Slack bot token and post a message with a custom bot identity
147
+ * const botToken = await base44.asServiceRole.connectors.getAccessToken('slackbot');
148
+ *
149
+ * const response = await fetch('https://slack.com/api/chat.postMessage', {
150
+ * method: 'POST',
151
+ * headers: {
152
+ * 'Authorization': `Bearer ${botToken}`,
153
+ * 'Content-Type': 'application/json'
154
+ * },
155
+ * body: JSON.stringify({
156
+ * channel: '#alerts',
157
+ * text: 'Deployment to production completed successfully.',
158
+ * username: 'Deploy Bot',
159
+ * icon_emoji: ':rocket:'
160
+ * })
161
+ * });
162
+ *
163
+ * const result = await response.json();
164
+ * ```
73
165
  */
74
166
  getAccessToken(integrationType: ConnectorIntegrationType): Promise<string>;
167
+ /**
168
+ * Retrieves the OAuth access token and connection configuration for a specific [external integration type](#available-connectors).
169
+ *
170
+ * Some connectors require connection-specific parameters to build API calls.
171
+ * In such cases, the returned `connectionConfig` is an object with the additional parameters. If there are no extra parameters needed for the connection, the `connectionConfig` is `null`.
172
+ *
173
+ * For example, a service might need a subdomain to construct the API URL in
174
+ * the form of `{subdomain}.example.com`. In such a case the subdomain will be available as a property of the `connectionConfig` object.
175
+ *
176
+ * @param integrationType - The type of integration, such as `'googlecalendar'`, `'slack'`, `'slackbot'`, `'github'`, or `'discord'`. See [Available connectors](#available-connectors) for the full list.
177
+ * @returns Promise resolving to a {@link ConnectorConnectionResponse} with `accessToken` and `connectionConfig`.
178
+ *
179
+ * @example
180
+ * ```typescript
181
+ * // Google Calendar connection
182
+ * // Get Google Calendar OAuth token and fetch upcoming events
183
+ * const { accessToken } = await base44.asServiceRole.connectors.getConnection('googlecalendar');
184
+ *
185
+ * const timeMin = new Date().toISOString();
186
+ * const url = `https://www.googleapis.com/calendar/v3/calendars/primary/events?maxResults=10&orderBy=startTime&singleEvents=true&timeMin=${timeMin}`;
187
+ *
188
+ * const calendarResponse = await fetch(url, {
189
+ * headers: { Authorization: `Bearer ${accessToken}` }
190
+ * });
191
+ *
192
+ * const events = await calendarResponse.json();
193
+ * ```
194
+ *
195
+ * @example
196
+ * ```typescript
197
+ * // Slack connection
198
+ * // Get Slack OAuth token and list channels
199
+ * const { accessToken } = await base44.asServiceRole.connectors.getConnection('slack');
200
+ *
201
+ * const url = 'https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=100';
202
+ *
203
+ * const slackResponse = await fetch(url, {
204
+ * headers: { Authorization: `Bearer ${accessToken}` }
205
+ * });
206
+ *
207
+ * const data = await slackResponse.json();
208
+ * ```
209
+ *
210
+ * @example
211
+ * ```typescript
212
+ * // Using connectionConfig
213
+ * // Some connectors return a subdomain or other params needed to build the API URL
214
+ * const { accessToken, connectionConfig } = await base44.asServiceRole.connectors.getConnection('myservice');
215
+ *
216
+ * const subdomain = connectionConfig?.subdomain;
217
+ * const response = await fetch(
218
+ * `https://${subdomain}.example.com/api/v1/resources`,
219
+ * { headers: { Authorization: `Bearer ${accessToken}` } }
220
+ * );
221
+ *
222
+ * const data = await response.json();
223
+ * ```
224
+ */
225
+ getConnection(integrationType: ConnectorIntegrationType): Promise<ConnectorConnectionResponse>;
226
+ }
227
+ /**
228
+ * User-scoped connectors module for managing app-user OAuth connections.
229
+ *
230
+ * This module provides methods for app-user OAuth flows: initiating an OAuth connection,
231
+ * retrieving the end user's access token, and disconnecting the end user's connection.
232
+ *
233
+ * Unlike {@link ConnectorsModule | ConnectorsModule} which manages app-scoped tokens,
234
+ * this module manages tokens scoped to individual end users. Methods are keyed on
235
+ * the connector ID (the OrgConnector's database ID) rather than the integration type.
236
+ *
237
+ * Available via `base44.connectors`.
238
+ */
239
+ export interface UserConnectorsModule {
240
+ /**
241
+ * Retrieves an OAuth access token for an end user's connection to a specific connector.
242
+ *
243
+ * Returns the OAuth token string that belongs to the currently authenticated end user
244
+ * for the specified connector.
245
+ *
246
+ * @param connectorId - The connector ID (OrgConnector database ID).
247
+ * @returns Promise resolving to the access token string.
248
+ *
249
+ * @example
250
+ * ```typescript
251
+ * // Get the end user's access token for a connector
252
+ * const token = await base44.connectors.getCurrentAppUserAccessToken('abc123def');
253
+ *
254
+ * const response = await fetch('https://www.googleapis.com/calendar/v3/calendars/primary/events', {
255
+ * headers: { 'Authorization': `Bearer ${token}` }
256
+ * });
257
+ * ```
258
+ */
259
+ getCurrentAppUserAccessToken(connectorId: string): Promise<string>;
260
+ /**
261
+ * Initiates the app-user OAuth flow for a specific connector.
262
+ *
263
+ * Returns a redirect URL that the end user should be navigated to in order to
264
+ * authenticate with the external service. The scopes and integration type are
265
+ * derived from the connector configuration server-side.
266
+ *
267
+ * @param connectorId - The connector ID (OrgConnector database ID).
268
+ * @returns Promise resolving to the redirect URL string.
269
+ *
270
+ * @example
271
+ * ```typescript
272
+ * // Start OAuth for the end user
273
+ * const redirectUrl = await base44.connectors.connectAppUser('abc123def');
274
+ *
275
+ * // Redirect the user to the OAuth provider
276
+ * window.location.href = redirectUrl;
277
+ * ```
278
+ */
279
+ connectAppUser(connectorId: string): Promise<string>;
280
+ /**
281
+ * Disconnects an end user's OAuth connection for a specific connector.
282
+ *
283
+ * Removes the stored OAuth credentials for the currently authenticated end user's
284
+ * connection to the specified connector.
285
+ *
286
+ * @param connectorId - The connector ID (OrgConnector database ID).
287
+ * @returns Promise resolving when the connection has been removed.
288
+ *
289
+ * @example
290
+ * ```typescript
291
+ * // Disconnect the end user's connection
292
+ * await base44.connectors.disconnectAppUser('abc123def');
293
+ * ```
294
+ */
295
+ disconnectAppUser(connectorId: string): Promise<void>;
75
296
  }
@@ -106,6 +106,14 @@ function createEntityHandler(axios, appId, entityName, getSocket) {
106
106
  async bulkCreate(data) {
107
107
  return axios.post(`${baseURL}/bulk`, data);
108
108
  },
109
+ // Update multiple entities matching a query using a MongoDB update operator
110
+ async updateMany(query, data) {
111
+ return axios.patch(`${baseURL}/update-many`, { query, data });
112
+ },
113
+ // Update multiple entities by ID, each with its own update data
114
+ async bulkUpdate(data) {
115
+ return axios.put(`${baseURL}/bulk`, data);
116
+ },
109
117
  // Import entities from a file
110
118
  async importEntities(file) {
111
119
  const formData = new FormData();
@@ -27,41 +27,55 @@ export type RealtimeCallback<T = any> = (event: RealtimeEvent<T>) => void;
27
27
  * Result returned when deleting a single entity.
28
28
  */
29
29
  export interface DeleteResult {
30
- /** Whether the deletion was successful */
30
+ /** Whether the deletion was successful. */
31
31
  success: boolean;
32
32
  }
33
33
  /**
34
34
  * Result returned when deleting multiple entities.
35
35
  */
36
36
  export interface DeleteManyResult {
37
- /** Whether the deletion was successful */
37
+ /** Whether the deletion was successful. */
38
38
  success: boolean;
39
- /** Number of entities that were deleted */
39
+ /** Number of entities that were deleted. */
40
40
  deleted: number;
41
41
  }
42
+ /**
43
+ * Result returned when updating multiple entities via a query.
44
+ */
45
+ export interface UpdateManyResult {
46
+ /** Whether the operation was successful. */
47
+ success: boolean;
48
+ /** Number of entities that were updated. */
49
+ updated: number;
50
+ /** Whether there are more entities matching the query that were not updated in this batch. When `true`, call `updateMany` again with the same query to update the next batch. */
51
+ has_more: boolean;
52
+ }
42
53
  /**
43
54
  * Result returned when importing entities from a file.
44
55
  *
45
56
  * @typeParam T - The entity type for imported records. Defaults to `any`.
46
57
  */
47
58
  export interface ImportResult<T = any> {
48
- /** Status of the import operation */
59
+ /** Status of the import operation. */
49
60
  status: "success" | "error";
50
- /** Details message, e.g., "Successfully imported 3 entities with RLS enforcement" */
61
+ /** Details message, e.g., "Successfully imported 3 entities with RLS enforcement". */
51
62
  details: string | null;
52
- /** Array of created entity objects when successful, or null on error */
63
+ /** Array of created entity objects when successful, or null on error. */
53
64
  output: T[] | null;
54
65
  }
55
66
  /**
56
67
  * Sort field type for entity queries.
57
68
  *
58
- * Supports ascending (no prefix or `'+'`) and descending (`'-'`) sorting.
69
+ * Accepts any field name from the entity type with an optional prefix:
70
+ * - `'+'` prefix or no prefix: ascending sort
71
+ * - `'-'` prefix: descending sort
59
72
  *
60
73
  * @typeParam T - The entity type to derive sortable fields from.
61
74
  *
62
75
  * @example
63
76
  * ```typescript
64
- * // Ascending sort (default)
77
+ * // Specify sort direction by prefixing field names with + or -
78
+ * // Ascending sort
65
79
  * 'created_date'
66
80
  * '+created_date'
67
81
  *
@@ -71,7 +85,7 @@ export interface ImportResult<T = any> {
71
85
  */
72
86
  export type SortField<T> = (keyof T & string) | `+${keyof T & string}` | `-${keyof T & string}`;
73
87
  /**
74
- * Fields added by the server to every entity record (id, dates, created_by, etc.).
88
+ * Fields added by the server to every entity record, such as `id`, `created_date`, `updated_date`, and `created_by`.
75
89
  */
76
90
  interface ServerEntityFields {
77
91
  /** Unique identifier of the record */
@@ -88,13 +102,29 @@ interface ServerEntityFields {
88
102
  is_sample?: boolean;
89
103
  }
90
104
  /**
91
- * Registry mapping entity names to their TypeScript types.
92
- * Augment this interface with your entity schema (user-defined fields only).
105
+ * Registry mapping entity names to their TypeScript types. The [`types generate`](/developers/references/cli/commands/types-generate) command fills this registry, then [`EntityRecord`](#entityrecord) adds server fields.
93
106
  */
94
107
  export interface EntityTypeRegistry {
95
108
  }
96
109
  /**
97
- * Full record type for each entity: schema fields + server-injected fields (id, created_date, etc.).
110
+ * Combines the [`EntityTypeRegistry`](#entitytyperegistry) schemas with server fields like `id`, `created_date`, and `updated_date` to give the complete record type for each entity. Use this when you need to type variables holding entity data.
111
+ *
112
+ * @example
113
+ * ```typescript
114
+ * // Using EntityRecord to get the complete type for an entity
115
+ * // Combine your schema with server fields (id, created_date, etc.)
116
+ * type TaskRecord = EntityRecord['Task'];
117
+ *
118
+ * const task: TaskRecord = await base44.entities.Task.create({
119
+ * title: 'My task',
120
+ * status: 'pending'
121
+ * });
122
+ *
123
+ * // Task now includes both your fields and server fields:
124
+ * console.log(task.id); // Server field
125
+ * console.log(task.created_date); // Server field
126
+ * console.log(task.title); // Your field
127
+ * ```
98
128
  */
99
129
  export type EntityRecord = {
100
130
  [K in keyof EntityTypeRegistry]: EntityTypeRegistry[K] & ServerEntityFields;
@@ -329,6 +359,87 @@ export interface EntityHandler<T = any> {
329
359
  * ```
330
360
  */
331
361
  bulkCreate(data: Partial<T>[]): Promise<T[]>;
362
+ /**
363
+ * Updates multiple records matching a query using a MongoDB update operator.
364
+ *
365
+ * Applies the same update operation to all records matching the query.
366
+ * The `data` parameter must contain one or more MongoDB update operators
367
+ * (e.g., `$set`, `$inc`, `$push`). Multiple operators can be combined in a
368
+ * single call, but each field may only appear in one operator.
369
+ *
370
+ * Results are batched in groups of up to 500 — when `has_more` is `true`
371
+ * in the response, call `updateMany` again with the same query to update
372
+ * the next batch.
373
+ *
374
+ * @param query - Query object to filter which records to update. Records matching all
375
+ * specified criteria will be updated.
376
+ * @param data - Update operation object containing one or more MongoDB update operators.
377
+ * Each field may only appear in one operator per call.
378
+ * Supported operators: `$set`, `$rename`, `$unset`, `$inc`, `$mul`, `$min`, `$max`,
379
+ * `$currentDate`, `$addToSet`, `$push`, `$pull`.
380
+ * @returns Promise resolving to the update result.
381
+ *
382
+ * @example
383
+ * ```typescript
384
+ * // Set status to 'archived' for all completed records
385
+ * const result = await base44.entities.MyEntity.updateMany(
386
+ * { status: 'completed' },
387
+ * { $set: { status: 'archived' } }
388
+ * );
389
+ * console.log(`Updated ${result.updated} records`);
390
+ * ```
391
+ *
392
+ * @example
393
+ * ```typescript
394
+ * // Combine multiple operators in a single call
395
+ * const result = await base44.entities.MyEntity.updateMany(
396
+ * { category: 'sales' },
397
+ * { $set: { status: 'done' }, $inc: { view_count: 1 } }
398
+ * );
399
+ * ```
400
+ *
401
+ * @example
402
+ * ```typescript
403
+ * // Handle batched updates for large datasets
404
+ * let hasMore = true;
405
+ * let totalUpdated = 0;
406
+ * while (hasMore) {
407
+ * const result = await base44.entities.MyEntity.updateMany(
408
+ * { status: 'pending' },
409
+ * { $set: { status: 'processed' } }
410
+ * );
411
+ * totalUpdated += result.updated;
412
+ * hasMore = result.has_more;
413
+ * }
414
+ * ```
415
+ */
416
+ updateMany(query: Partial<T>, data: Record<string, Record<string, any>>): Promise<UpdateManyResult>;
417
+ /**
418
+ * Updates multiple records in a single request, each with its own update data.
419
+ *
420
+ * Unlike `updateMany` which applies the same update to all matching records,
421
+ * `bulkUpdate` allows different updates for each record. Each item in the
422
+ * array must include an `id` field identifying which record to update.
423
+ *
424
+ * **Note:** Maximum 500 items per request.
425
+ *
426
+ * @param data - Array of update objects (max 500). Each object must have an `id` field
427
+ * and any number of fields to update.
428
+ * @returns Promise resolving to an array of updated records.
429
+ *
430
+ * @example
431
+ * ```typescript
432
+ * // Update multiple records with different data
433
+ * const updated = await base44.entities.MyEntity.bulkUpdate([
434
+ * { id: 'entity-1', status: 'paid', amount: 999 },
435
+ * { id: 'entity-2', status: 'cancelled' },
436
+ * { id: 'entity-3', name: 'Renamed Item' }
437
+ * ]);
438
+ * ```
439
+ */
440
+ bulkUpdate(data: (Partial<T> & {
441
+ id: string;
442
+ })[]): Promise<T[]>;
332
443
  /**
333
444
  * Imports records from a file.
334
445
  *
@@ -401,17 +512,29 @@ type DynamicEntitiesModule = {
401
512
  * Entities are accessed dynamically using the pattern:
402
513
  * `base44.entities.EntityName.method()`
403
514
  *
404
- * This module is available to use with a client in all three authentication modes:
515
+ * This module is available to use with a client in all authentication modes:
405
516
  *
406
517
  * - **Anonymous or User authentication** (`base44.entities`): Access is scoped to the current user's permissions. Anonymous users can only access public entities, while authenticated users can access entities they have permission to view or modify.
407
518
  * - **Service role authentication** (`base44.asServiceRole.entities`): Operations have elevated admin-level permissions. Can access all entities that the app's admin role has access to.
408
519
  *
520
+ * ## Entity Handlers
521
+ *
522
+ * An entity handler is the object you get when you access an entity through `base44.entities.EntityName`. Every entity in your app automatically gets a handler with CRUD methods for managing records.
523
+ *
524
+ * For example, `base44.entities.Task` is an entity handler for Task records, and `base44.entities.User` is an entity handler for User records. Each handler provides methods like `list()`, `create()`, `update()`, and `delete()`.
525
+ *
526
+ * You don't need to instantiate or import entity handlers. They're automatically available for every entity you create in your app.
527
+ *
409
528
  * ## Built-in User Entity
410
529
  *
411
530
  * Every app includes a built-in `User` entity that stores user account information. This entity has special security rules that can't be changed.
412
531
  *
413
532
  * Regular users can only read and update their own user record. With service role authentication, you can read, update, and delete any user. You can't create users using the entities module. Instead, use the functions of the {@link AuthModule | auth module} to invite or register new users.
414
533
  *
534
+ * ## Generated Types
535
+ *
536
+ * If you're working in a TypeScript project, you can generate types from your entity schemas to get autocomplete and type checking on all entity methods. See the [Dynamic Types](/developers/references/sdk/getting-started/dynamic-types) guide to get started.
537
+ *
415
538
  * @example
416
539
  * ```typescript
417
540
  * // Get all records from the MyEntity entity
@@ -1,11 +1,17 @@
1
1
  /**
2
- * Registry of function names.
3
- * Augment this interface to enable autocomplete for function names.
2
+ * Registry of function names. The [`types generate`](/developers/references/cli/commands/types-generate) command fills this registry, then [`FunctionName`](#functionname) resolves to a union of the keys.
4
3
  */
5
4
  export interface FunctionNameRegistry {
6
5
  }
7
6
  /**
8
- * Function name type - uses registry keys if augmented, otherwise string.
7
+ * Union of all function names from the [`FunctionNameRegistry`](#functionnameregistry). Defaults to `string` when no types have been generated.
8
+ *
9
+ * @example
10
+ * ```typescript
11
+ * // Using generated function name types
12
+ * // With generated types, you get autocomplete on function names
13
+ * await base44.functions.invoke('calculateTotal', { items: ['item1', 'item2'] });
14
+ * ```
9
15
  */
10
16
  export type FunctionName = keyof FunctionNameRegistry extends never ? string : keyof FunctionNameRegistry;
11
17
  /**
@@ -13,10 +19,16 @@ export type FunctionName = keyof FunctionNameRegistry extends never ? string : k
13
19
  *
14
20
  * This module allows you to invoke the custom backend functions defined in the app.
15
21
  *
22
+ * ## Authentication Modes
23
+ *
16
24
  * This module is available to use with a client in all authentication modes:
17
25
  *
18
26
  * - **Anonymous or User authentication** (`base44.functions`): Functions are invoked with the current user's permissions. Anonymous users invoke functions without authentication, while authenticated users invoke functions with their authentication context.
19
27
  * - **Service role authentication** (`base44.asServiceRole.functions`): Functions are invoked with elevated admin-level permissions. The function code receives a request with admin authentication context.
28
+ *
29
+ * ## Generated Types
30
+ *
31
+ * If you're working in a TypeScript project, you can generate types from your backend functions to get autocomplete on function names when calling `invoke()`. See the [Dynamic Types](/developers/references/sdk/getting-started/dynamic-types) guide to get started.
20
32
  */
21
33
  export interface FunctionsModule {
22
34
  /**
@@ -36,7 +48,6 @@ export interface FunctionsModule {
36
48
  * // Basic function call
37
49
  * const result = await base44.functions.invoke('calculateTotal', {
38
50
  * items: ['item1', 'item2'],
39
- * discount: 0.1
40
51
  * });
41
52
  * console.log(result.data.total);
42
53
  * ```
@@ -12,18 +12,25 @@ export type IntegrationEndpointFunction = (data: Record<string, any>) => Promise
12
12
  /**
13
13
  * A package containing integration endpoints.
14
14
  *
15
- * Provides dynamic access to integration endpoints within a package.
16
- * Each endpoint is accessed as a property that returns a function to invoke it.
15
+ * An integration package is a collection of endpoint functions indexed by endpoint name.
16
+ * Both `Core` and `custom` are integration packages that implement this structure.
17
17
  *
18
- * @example
18
+ * @example **Core package**
19
19
  * ```typescript
20
- * // Access endpoints dynamically
21
- * const result = await integrations.Core.SendEmail({
22
- * to: 'user@example.com',
23
- * subject: 'Hello',
24
- * body: 'Message'
20
+ * await base44.integrations.Core.InvokeLLM({
21
+ * prompt: 'Explain quantum computing',
22
+ * model: 'gpt_5'
25
23
  * });
26
24
  * ```
25
+ *
26
+ * @example **custom package**
27
+ * ```typescript
28
+ * await base44.integrations.custom.call(
29
+ * 'github',
30
+ * 'get:/repos/{owner}/{repo}',
31
+ * { pathParams: { owner: 'myorg', repo: 'myrepo' } }
32
+ * );
33
+ * ```
27
34
  */
28
35
  export type IntegrationPackage = {
29
36
  [endpointName: string]: IntegrationEndpointFunction;
@@ -34,6 +41,11 @@ export type IntegrationPackage = {
34
41
  export interface InvokeLLMParams {
35
42
  /** The prompt text to send to the model */
36
43
  prompt: string;
44
+ /** Optionally specify a model to override the app-level model setting for this specific call.
45
+ *
46
+ * Options: `"gpt_5_mini"`, `"gemini_3_flash"`, `"gpt_5"`, `"gemini_3_pro"`, `"claude_sonnet_4_6"`, `"claude_opus_4_6"`
47
+ */
48
+ model?: 'gpt_5_mini' | 'gemini_3_flash' | 'gpt_5' | 'gemini_3_pro' | 'claude_sonnet_4_6' | 'claude_opus_4_6';
37
49
  /** If set to `true`, the LLM will use Google Search, Maps, and News to gather real-time context before answering.
38
50
  * @default false
39
51
  */
@@ -324,6 +336,8 @@ export interface CoreIntegrations {
324
336
  *
325
337
  * 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.
326
338
  *
339
+ * ## Integration Types
340
+ *
327
341
  * There are two types of integrations:
328
342
  *
329
343
  * - **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:
@@ -331,12 +345,14 @@ export interface CoreIntegrations {
331
345
  * base44.integrations.Core.FunctionName(params)
332
346
  * ```
333
347
  *
334
- * - **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:
348
+ * - **Custom workspace integrations** (`custom`): Pre-configured external APIs set up by workspace administrators. Workspace integration calls are proxied through Base44's backend, so credentials are never exposed to the frontend. Access custom workspace integration methods using:
335
349
  * ```
336
350
  * base44.integrations.custom.call(slug, operationId, params)
337
351
  * ```
338
352
  *
339
- * <Info>To call a custom integration, it must be pre-configured by a workspace administrator who imports an OpenAPI specification.</Info>
353
+ * <Info>To call a custom workspace integration, it must be pre-configured by a workspace administrator who imports an OpenAPI specification. Learn more about [custom workspace integrations](/documentation/integrations/managing-workspace-integrations).</Info>
354
+ *
355
+ * ## Authentication Modes
340
356
  *
341
357
  * This module is available to use with a client in all authentication modes:
342
358
  *
@@ -346,18 +362,52 @@ export interface CoreIntegrations {
346
362
  export type IntegrationsModule = {
347
363
  /**
348
364
  * Core package containing built-in Base44 integration functions.
365
+ *
366
+ * @example
367
+ * ```typescript
368
+ * const response = await base44.integrations.Core.InvokeLLM({
369
+ * prompt: 'Explain quantum computing',
370
+ * model: 'gpt_5'
371
+ * });
372
+ * ```
349
373
  */
350
374
  Core: CoreIntegrations;
351
375
  /**
352
- * Custom integrations module for calling pre-configured external APIs.
376
+ * Workspace integrations module for calling pre-configured external APIs.
377
+ *
378
+ * @example
379
+ * ```typescript
380
+ * const result = await base44.integrations.custom.call(
381
+ * 'github',
382
+ * 'get:/repos/{owner}/{repo}',
383
+ * { pathParams: { owner: 'myorg', repo: 'myrepo' } }
384
+ * );
385
+ * ```
353
386
  */
354
387
  custom: CustomIntegrationsModule;
355
388
  } & {
356
389
  /**
357
390
  * Access to additional integration packages.
358
391
  *
359
- * Additional integration packages may be added in the future and will be
360
- * accessible using the same pattern as Core.
392
+ * Allows accessing integration packages as properties. This enables both `Core` and `custom` packages,
393
+ * as well as any future integration packages that may be added.
394
+ *
395
+ * @example **Use Core integrations**
396
+ * ```typescript
397
+ * const response = await base44.integrations.Core.InvokeLLM({
398
+ * prompt: 'Explain quantum computing',
399
+ * model: 'gpt_5'
400
+ * });
401
+ * ```
402
+ *
403
+ * @example **Use custom integrations**
404
+ * ```typescript
405
+ * const result = await base44.integrations.custom.call(
406
+ * 'github',
407
+ * 'get:/repos/{owner}/{repo}',
408
+ * { pathParams: { owner: 'myorg', repo: 'myrepo' } }
409
+ * );
410
+ * ```
361
411
  */
362
412
  [packageName: string]: IntegrationPackage;
363
413
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@base44/sdk",
3
- "version": "0.8.19",
3
+ "version": "0.8.21",
4
4
  "description": "JavaScript SDK for Base44 API",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",