@base44-preview/sdk 0.8.19-pr.129.4c7e3bb → 0.8.19-pr.130.1534b73

package/dist/client.js

@@ -3,7 +3,7 @@ import { createEntitiesModule } from "./modules/entities.js";
 import { createIntegrationsModule } from "./modules/integrations.js";
 import { createAuthModule } from "./modules/auth.js";
 import { createSsoModule } from "./modules/sso.js";
-import { createConnectorsModule } from "./modules/connectors.js";
+import { createConnectorsModule, createUserConnectorsModule, } from "./modules/connectors.js";
 import { getAccessToken } from "./utils/auth-utils.js";
 import { createFunctionsModule } from "./modules/functions.js";
 import { createAgentsModule } from "./modules/agents.js";
@@ -108,12 +108,14 @@ export function createClient(config) {
         serverUrl,
     });
     const userModules = {
+        axiosClient,
         entities: createEntitiesModule({
             axios: axiosClient,
             appId,
             getSocket,
         }),
         integrations: createIntegrationsModule(axiosClient, appId),
+        connectors: createUserConnectorsModule(axiosClient, appId),
         auth: userAuthModule,
         functions: createFunctionsModule(functionsAxiosClient, appId),
         agents: createAgentsModule({
@@ -139,6 +141,7 @@ export function createClient(config) {
         },
     };
     const serviceRoleModules = {
+        axiosClient: serviceRoleAxiosClient,
         entities: createEntitiesModule({
             axios: serviceRoleAxiosClient,
             appId,

package/dist/client.types.d.ts

@@ -1,8 +1,9 @@
+import type { AxiosInstance } from "axios";
 import type { EntitiesModule } from "./modules/entities.types.js";
 import type { IntegrationsModule } from "./modules/integrations.types.js";
 import type { AuthModule } from "./modules/auth.types.js";
 import type { SsoModule } from "./modules/sso.types.js";
-import type { ConnectorsModule } from "./modules/connectors.types.js";
+import type { ConnectorsModule, UserConnectorsModule } from "./modules/connectors.types.js";
 import type { FunctionsModule } from "./modules/functions.types.js";
 import type { AgentsModule } from "./modules/agents.types.js";
 import type { AppLogsModule } from "./modules/app-logs.types.js";
@@ -82,6 +83,10 @@ export interface Base44Client {
     appLogs: AppLogsModule;
     /** {@link AuthModule | Auth module} for user authentication and management. */
     auth: AuthModule;
+    /** The underlying Axios instance used for API requests. Useful for making custom API calls with the same authentication and configuration as the SDK. */
+    axiosClient: AxiosInstance;
+    /** {@link UserConnectorsModule | Connectors module} for end-user OAuth flows. */
+    connectors: UserConnectorsModule;
     /** {@link EntitiesModule | Entities module} for CRUD operations on your data models. */
     entities: EntitiesModule;
     /** {@link FunctionsModule | Functions module} for invoking custom backend functions. */
@@ -117,6 +122,8 @@ export interface Base44Client {
     readonly asServiceRole: {
         /** {@link AgentsModule | Agents module} with elevated permissions. */
         agents: AgentsModule;
+        /** The underlying Axios instance used for service role API requests. Useful for making custom API calls with service role authentication. */
+        axiosClient: AxiosInstance;
         /** {@link AppLogsModule | App logs module} with elevated permissions. */
         appLogs: AppLogsModule;
         /** {@link ConnectorsModule | Connectors module} for OAuth token retrieval. */

package/dist/index.d.ts

@@ -6,11 +6,11 @@ export type { Base44Client, CreateClientConfig, CreateClientOptions, Base44Error
 export * from "./types.js";
 export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, } from "./modules/entities.types.js";
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
-export type { IntegrationsModule, IntegrationPackage, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
+export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
 export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";
 export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
 export type { AppLogsModule } from "./modules/app-logs.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
-export type { ConnectorsModule } from "./modules/connectors.types.js";
+export type { ConnectorsModule, UserConnectorsModule, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";
 export type { GetAccessTokenOptions, SaveAccessTokenOptions, RemoveAccessTokenOptions, GetLoginUrlOptions, } from "./utils/auth-utils.types.js";

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

@@ -170,6 +170,8 @@ export interface AgentsModuleConfig {
  * send messages, and subscribe to realtime updates. Conversations can be used
  * for chat interfaces, support systems, or any interactive AI app.
  *
+ * ## Key Features
+ *
  * The agents module enables you to:
  *
  * - **Create conversations** with agents defined in the app.
@@ -179,12 +181,16 @@ export interface AgentsModuleConfig {
  * - **Attach metadata** to conversations for tracking context, categories, priorities, or linking to external systems.
  * - **Generate WhatsApp connection URLs** for users to interact with agents through WhatsApp.
  *
+ * ## Conversation Structure
+ *
  * The agents module operates with a two-level hierarchy:
  *
  * 1. **Conversations**: Top-level containers that represent a dialogue with a specific agent. Each conversation has a unique ID, is associated with an agent by name, and belongs to the user who created it. Conversations can include optional metadata for tracking app-specific context like ticket IDs, categories, or custom fields.
  *
  * 2. **Messages**: Individual exchanges within a conversation. Each message has a role, content, and optional metadata like token usage, tool calls, file attachments, and reasoning information. Messages are stored as an array within their parent conversation.
  *
+ * ## Authentication Modes
+ *
  * This module is available to use with a client in all authentication modes:
  *
  * - **Anonymous or User authentication** (`base44.agents`): Access is scoped to the current user's permissions. Users must be authenticated to create and access conversations.

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

@@ -74,11 +74,15 @@ export type AnalyticsModuleOptions = {
  *
  * <Note> Analytics events tracked with this module appear as custom event cards in the [Analytics dashboard](/documentation/performance-and-seo/app-analytics).</Note>
  *
+ * ## Best Practices
+ *
  * When tracking events:
  *
  * - Choose clear, descriptive event names in snake_case like `signup_button_click` or `purchase_completed` rather than generic names like `click`.
  * - Include relevant context in your properties such as identifiers like `product_id`, measurements like `price`, and flags like `is_first_purchase`.
  *
+ * ## Authentication Modes
+ *
  * This module is only available in user authentication mode (`base44.analytics`).
  */
 export interface AnalyticsModule {

package/dist/modules/app-logs.types.d.ts

@@ -3,6 +3,8 @@
  *
  * This module provides a method to log user activity. The logs are reflected in the Analytics page in the app dashboard.
  *
+ * ## Authentication Modes
+ *
  * This module is available to use with a client in all authentication modes.
  */
 export interface AppLogsModule {

package/dist/modules/auth.js

@@ -37,9 +37,18 @@ export function createAuthModule(axios, functionsAxiosClient, appId, options) {
         loginWithProvider(provider, fromUrl = "/") {
             // Build the full redirect URL
             const redirectUrl = new URL(fromUrl, window.location.origin).toString();
-            // Build the provider login URL (google is the default, so no provider path needed)
-            const providerPath = provider === "google" ? "" : `/${provider}`;
-            const loginUrl = `${options.appBaseUrl}/api/apps/auth${providerPath}/login?app_id=${appId}&from_url=${encodeURIComponent(redirectUrl)}`;
+            const queryParams = `app_id=${appId}&from_url=${encodeURIComponent(redirectUrl)}`;
+            // SSO uses a different URL structure with appId in the path
+            let authPath;
+            if (provider === "sso") {
+                authPath = `/apps/${appId}/auth/sso/login`;
+            }
+            else {
+                // Google is the default provider, so no provider path segment needed
+                const providerPath = provider === "google" ? "" : `/${provider}`;
+                authPath = `/apps/auth${providerPath}/login`;
+            }
+            const loginUrl = `${options.appBaseUrl}/api${authPath}?${queryParams}`;
             // Redirect to the provider login page
             window.location.href = loginUrl;
         },

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

@@ -96,6 +96,8 @@ export interface AuthModuleOptions {
 /**
  * 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.
  *
+ * ## Features
+ *
  * This module provides comprehensive authentication functionality including:
  * - Email/password login and registration
  * - Token management
@@ -104,6 +106,8 @@ export interface AuthModuleOptions {
  * - OTP verification
  * - User invitations
  *
+ * ## Authentication Modes
+ *
  * The auth module is only available in user authentication mode (`base44.auth`).
  */
 export interface AuthModule {
@@ -181,8 +185,9 @@ export interface AuthModule {
      * - `'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.
      * - `'facebook'` - {@link https://developers.facebook.com/docs/facebook-login | Facebook Login}. Enable Facebook in your app's authentication settings before using.
      * - `'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.
+     * - `'sso'` - Enterprise SSO. Enable SSO in your app's authentication settings before using this provider.
      *
-     * @param provider - The authentication provider to use: `'google'`, `'microsoft'`, `'facebook'`, or `'apple'`.
+     * @param provider - The authentication provider to use: `'google'`, `'microsoft'`, `'facebook'`, `'apple'`, or `'sso'`.
      * @param fromUrl - URL to redirect to after successful authentication. Defaults to `'/'`.
      *
      * @example
@@ -202,6 +207,12 @@ export interface AuthModule {
      * // Apple
      * base44.auth.loginWithProvider('apple', '/dashboard');
      * ```
+     *
+     * @example
+     * ```typescript
+     * // SSO
+     * base44.auth.loginWithProvider('sso', '/dashboard');
+     * ```
      */
     loginWithProvider(provider: string, fromUrl?: string): void;
     /**

package/dist/modules/connectors.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from "axios";
-import { ConnectorsModule } from "./connectors.types.js";
+import { ConnectorsModule, UserConnectorsModule } from "./connectors.types.js";
 /**
  * Creates the Connectors module for the Base44 SDK.
  *
@@ -9,3 +9,12 @@ import { ConnectorsModule } from "./connectors.types.js";
  * @internal
  */
 export declare function createConnectorsModule(axios: AxiosInstance, appId: string): ConnectorsModule;
+/**
+ * Creates the user-scoped Connectors module (end-user OAuth flows).
+ *
+ * @param axios - Axios instance (user-scoped client)
+ * @param appId - Application ID
+ * @returns User connectors module with end-user OAuth methods
+ * @internal
+ */
+export declare function createUserConnectorsModule(axios: AxiosInstance, appId: string): UserConnectorsModule;

package/dist/modules/connectors.js

@@ -20,3 +20,38 @@ export function createConnectorsModule(axios, appId) {
         },
     };
 }
+/**
+ * Creates the user-scoped Connectors module (end-user OAuth flows).
+ *
+ * @param axios - Axios instance (user-scoped client)
+ * @param appId - Application ID
+ * @returns User connectors module with end-user OAuth methods
+ * @internal
+ */
+export function createUserConnectorsModule(axios, appId) {
+    return {
+        // @ts-expect-error Return type mismatch - implementation returns object, interface expects string
+        async getEndUserAccessToken(integrationType) {
+            if (!integrationType || typeof integrationType !== "string") {
+                throw new Error("Integration type is required and must be a string");
+            }
+            const response = await axios.get(`/apps/${appId}/end-user-auth/tokens/${integrationType}`);
+            // @ts-expect-error
+            return response.access_token;
+        },
+        async connectEndUser(integrationType) {
+            if (!integrationType || typeof integrationType !== "string") {
+                throw new Error("Integration type is required and must be a string");
+            }
+            const response = await axios.post(`/apps/${appId}/end-user-auth/initiate`, { integration_type: integrationType });
+            // @ts-expect-error
+            return response.redirect_url;
+        },
+        async disconnectEndUser(integrationType) {
+            if (!integrationType || typeof integrationType !== "string") {
+                throw new Error("Integration type is required and must be a string");
+            }
+            await axios.delete(`/apps/${appId}/end-user-auth/${integrationType}`);
+        },
+    };
+}

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

@@ -21,7 +21,13 @@ export interface ConnectorAccessTokenResponse {
     access_token: string;
 }
 /**
- * Connectors module for managing OAuth tokens for external services.
+ * Response from the connectors initiate endpoint.
+ */
+export interface ConnectorInitiateResponse {
+    redirect_url: string;
+}
+/**
+ * Connectors module for managing app-scoped OAuth tokens for external services.
  *
  * This module allows you to retrieve OAuth access tokens for external services that the app has connected to. Connectors are app-scoped. When an app builder connects an integration like Google Calendar or Slack, all users of the app share that same connection.
  *
@@ -30,7 +36,7 @@ export interface ConnectorAccessTokenResponse {
  * the API calls you make. This is useful when you need custom API interactions that aren't
  * covered by Base44's pre-built integrations.
  *
- * 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.
+ * This module is only available via `base44.asServiceRole.connectors`.
  *
  * ## Dynamic Types
  *
@@ -82,3 +88,75 @@ export interface ConnectorsModule {
      */
     getAccessToken(integrationType: ConnectorIntegrationType): Promise<string>;
 }
+/**
+ * User-scoped connectors module for managing end-user OAuth connections.
+ *
+ * This module provides methods for end-user OAuth flows: initiating an OAuth connection,
+ * retrieving the end user's access token, and disconnecting the end user's connection.
+ *
+ * Unlike {@link ConnectorsModule | ConnectorsModule} which manages app-scoped tokens,
+ * this module manages tokens scoped to individual end users.
+ *
+ * Available via `base44.connectors`.
+ *
+ * ## Dynamic Types
+ *
+ * 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. See the [Dynamic Types](/developers/references/sdk/getting-started/dynamic-types) guide to get started.
+ */
+export interface UserConnectorsModule {
+    /**
+     * Retrieves an OAuth access token for an end user's connection to a specific external integration.
+     *
+     * Returns the OAuth token string that belongs to the currently authenticated end user
+     * for the specified external service.
+     *
+     * @param integrationType - The type of integration, such as `'googlecalendar'`, `'slack'`, or `'github'`.
+     * @returns Promise resolving to the access token string.
+     *
+     * @example
+     * ```typescript
+     * // Get the end user's Google Calendar token
+     * const token = await base44.connectors.getEndUserAccessToken('googlecalendar');
+     *
+     * const response = await fetch('https://www.googleapis.com/calendar/v3/calendars/primary/events', {
+     *   headers: { 'Authorization': `Bearer ${token}` }
+     * });
+     * ```
+     */
+    getEndUserAccessToken(integrationType: ConnectorIntegrationType): Promise<string>;
+    /**
+     * Initiates the end-user OAuth flow for a specific external integration type.
+     *
+     * Returns a redirect URL that the end user should be navigated to in order to
+     * authenticate with the external service.
+     *
+     * @param integrationType - The type of integration, such as `'googlecalendar'`, `'slack'`, or `'github'`.
+     * @returns Promise resolving to the redirect URL string.
+     *
+     * @example
+     * ```typescript
+     * // Start Google Calendar OAuth for the end user
+     * const redirectUrl = await base44.connectors.connectEndUser('googlecalendar');
+     *
+     * // Redirect the user to the OAuth provider
+     * window.location.href = redirectUrl;
+     * ```
+     */
+    connectEndUser(integrationType: ConnectorIntegrationType): Promise<string>;
+    /**
+     * Disconnects an end user's OAuth connection for a specific external integration type.
+     *
+     * Removes the stored OAuth credentials for the currently authenticated end user's
+     * connection to the specified external service.
+     *
+     * @param integrationType - The type of integration to disconnect, such as `'googlecalendar'`, `'slack'`, or `'github'`.
+     * @returns Promise resolving when the connection has been removed.
+     *
+     * @example
+     * ```typescript
+     * // Disconnect the end user's Google Calendar connection
+     * await base44.connectors.disconnectEndUser('googlecalendar');
+     * ```
+     */
+    disconnectEndUser(integrationType: ConnectorIntegrationType): Promise<void>;
+}

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

@@ -425,6 +425,14 @@ type DynamicEntitiesModule = {
  * - **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.
  * - **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.
  *
+ * ## Entity Handlers
+ *
+ * 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.
+ *
+ * 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()`.
+ *
+ * You don't need to instantiate or import entity handlers. They're automatically available for every entity you create in your app.
+ *
  * ## Built-in User Entity
  *
  * Every app includes a built-in `User` entity that stores user account information. This entity has special security rules that can't be changed.

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

@@ -19,6 +19,8 @@ export type FunctionName = keyof FunctionNameRegistry extends never ? string : k
  *
  * This module allows you to invoke the custom backend functions defined in the app.
  *
+ * ## Authentication Modes
+ *
  * This module is available to use with a client in all authentication modes:
  *
  * - **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.

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

@@ -12,18 +12,25 @@ export type IntegrationEndpointFunction = (data: Record<string, any>) => Promise
 /**
  * A package containing integration endpoints.
  *
- * Provides dynamic access to integration endpoints within a package.
- * Each endpoint is accessed as a property that returns a function to invoke it.
+ * An integration package is a collection of endpoint functions indexed by endpoint name.
+ * Both `Core` and `custom` are integration packages that implement this structure.
  *
- * @example
+ * @example **Core package**
  * ```typescript
- * // Access endpoints dynamically
- * const result = await integrations.Core.SendEmail({
- *   to: 'user@example.com',
- *   subject: 'Hello',
- *   body: 'Message'
+ * await base44.integrations.Core.InvokeLLM({
+ *   prompt: 'Explain quantum computing',
+ *   model: 'gpt-4'
  * });
  * ```
+ *
+ * @example **custom package**
+ * ```typescript
+ * await base44.integrations.custom.call(
+ *   'github',
+ *   'get:/repos/{owner}/{repo}',
+ *   { pathParams: { owner: 'myorg', repo: 'myrepo' } }
+ * );
+ * ```
  */
 export type IntegrationPackage = {
     [endpointName: string]: IntegrationEndpointFunction;
@@ -324,6 +331,8 @@ export interface CoreIntegrations {
  *
  * 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.
  *
+ * ## Integration Types
+ *
  * There are two types of integrations:
  *
  * - **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 +340,14 @@ export interface CoreIntegrations {
  *   base44.integrations.Core.FunctionName(params)
  *   ```
  *
- * - **Custom integrations** (`custom`): Pre-configured external APIs. Custom integration calls are proxied through Base44's backend, so credentials are never exposed to the frontend. Access custom integration methods using:
+ * - **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:
  *   ```
  *   base44.integrations.custom.call(slug, operationId, params)
  *   ```
  *
- *   <Info>To call a custom integration, it must be pre-configured by a workspace administrator who imports an OpenAPI specification.</Info>
+ *   <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>
+ *
+ * ## Authentication Modes
  *
  * This module is available to use with a client in all authentication modes:
  *
@@ -346,18 +357,52 @@ export interface CoreIntegrations {
 export type IntegrationsModule = {
     /**
      * Core package containing built-in Base44 integration functions.
+     *
+     * @example
+     * ```typescript
+     * const response = await base44.integrations.Core.InvokeLLM({
+     *   prompt: 'Explain quantum computing',
+     *   model: 'gpt-4'
+     * });
+     * ```
      */
     Core: CoreIntegrations;
     /**
-     * Custom integrations module for calling pre-configured external APIs.
+     * Workspace integrations module for calling pre-configured external APIs.
+     *
+     * @example
+     * ```typescript
+     * const result = await base44.integrations.custom.call(
+     *   'github',
+     *   'get:/repos/{owner}/{repo}',
+     *   { pathParams: { owner: 'myorg', repo: 'myrepo' } }
+     * );
+     * ```
      */
     custom: CustomIntegrationsModule;
 } & {
     /**
      * Access to additional integration packages.
      *
-     * Additional integration packages may be added in the future and will be
-     * accessible using the same pattern as Core.
+     * Allows accessing integration packages as properties. This enables both `Core` and `custom` packages,
+     * as well as any future integration packages that may be added.
+     *
+     * @example **Use Core integrations**
+     * ```typescript
+     * const response = await base44.integrations.Core.InvokeLLM({
+     *   prompt: 'Explain quantum computing',
+     *   model: 'gpt-4'
+     * });
+     * ```
+     *
+     * @example **Use custom integrations**
+     * ```typescript
+     * const result = await base44.integrations.custom.call(
+     *   'github',
+     *   'get:/repos/{owner}/{repo}',
+     *   { pathParams: { owner: 'myorg', repo: 'myrepo' } }
+     * );
+     * ```
      */
     [packageName: string]: IntegrationPackage;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.19-pr.129.4c7e3bb",
+  "version": "0.8.19-pr.130.1534b73",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",