@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 +2 -1
- package/dist/client.types.d.ts +10 -3
- package/dist/index.d.ts +5 -5
- package/dist/modules/agents.types.d.ts +21 -6
- package/dist/modules/analytics.types.d.ts +4 -0
- package/dist/modules/app-logs.types.d.ts +2 -0
- package/dist/modules/auth.js +12 -3
- package/dist/modules/auth.types.d.ts +25 -6
- package/dist/modules/connectors.d.ts +10 -1
- package/dist/modules/connectors.js +51 -2
- package/dist/modules/connectors.types.d.ts +231 -10
- package/dist/modules/entities.js +8 -0
- package/dist/modules/entities.types.d.ts +136 -13
- package/dist/modules/functions.types.d.ts +15 -4
- package/dist/modules/integrations.types.d.ts +63 -13
- package/package.json +1 -1
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({
|
package/dist/client.types.d.ts
CHANGED
|
@@ -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.
|
|
25
|
-
*
|
|
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,
|
|
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
|
-
*
|
|
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
|
-
|
|
316
|
-
|
|
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 {
|
package/dist/modules/auth.js
CHANGED
|
@@ -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
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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'
|
|
181
|
-
* - `'microsoft'
|
|
182
|
-
* - `'facebook'
|
|
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 `'
|
|
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
|
-
* //
|
|
195
|
+
* // Google
|
|
190
196
|
* base44.auth.loginWithProvider('google', window.location.pathname);
|
|
191
197
|
* ```
|
|
192
198
|
*
|
|
193
199
|
* @example
|
|
194
200
|
* ```typescript
|
|
195
|
-
* //
|
|
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
|
-
|
|
12
|
-
|
|
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
|
-
*
|
|
9
|
-
*
|
|
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
|
|
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'`,
|
|
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
|
|
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
|
}
|
package/dist/modules/entities.js
CHANGED
|
@@ -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
|
-
*
|
|
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
|
-
* //
|
|
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
|
|
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
16
|
-
*
|
|
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
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
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.
|
|
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
|
-
*
|
|
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
|
-
*
|
|
360
|
-
*
|
|
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
|
};
|