Update base44-sdk skill to v0.8.40 2026-07-21 14:25

skills/base44-sdk/SKILL.md

@@ -225,7 +225,8 @@ const base44 = createClient({
 - Send emails → `integrations.Core.SendEmail()`
 - Upload files → `integrations.Core.UploadFile()`
 - Custom APIs → `integrations.custom.call()`
-- App-scoped OAuth (app builder's account) → `asServiceRole.connectors.getConnection()` (backend only)
+- App-scoped OAuth (app builder's account, shared by all users) → `asServiceRole.connectors.getConnection()` (backend only)
+- Per-user OAuth (each app user connects their own account) → `connectors.connectAppUser()` (frontend) + `asServiceRole.connectors.getCurrentAppUserConnection()` (backend)
 
 **Tracking and analytics?**
 - Track custom events → `analytics.track()`

skills/base44-sdk/references/QUICK_REFERENCE.md

@@ -8,7 +8,7 @@ Compact method signatures for all SDK modules. **Verify against this before writ
 
 ```
 loginViaEmailPassword(email, password, turnstileToken?) → Promise<{access_token, user}>
-loginWithProvider('google' | 'microsoft' | 'facebook', fromUrl?) → void
+loginWithProvider('google' | 'microsoft' | 'facebook' | 'apple' | 'sso', fromUrl?) → void
 me() → Promise<User | null>
 updateMe(data) → Promise<User>
 isAuthenticated() → Promise<boolean>
@@ -35,8 +35,8 @@ list(sort?, limit?, skip?, fields?) → Promise<Pick<T, K>[]>
 filter(query, sort?, limit?, skip?, fields?) → Promise<Pick<T, K>[]>
 get(id) → Promise<T>
 update(id, data) → Promise<T>
-updateMany(query, mongoUpdateOp) → Promise<UpdateManyResult>   // e.g. { $set: { field: val } }
-bulkUpdate(dataArray) → Promise<T[]>                           // each item must have id
+updateMany(query, mongoUpdateOp) → Promise<UpdateManyResult>   // e.g. { $set: { field: val } }; batched by 500, check result.has_more
+bulkUpdate(dataArray) → Promise<T[]>                           // each item must have id; max 500 per request
 delete(id) → Promise<DeleteResult>
 deleteMany(query) → Promise<DeleteManyResult>
 importEntities(file) → Promise<ImportResult<T>>                // frontend only
@@ -45,6 +45,8 @@ subscribe(callback) → () => void                               // returns unsu
 
 **Sort:** Use `SortField<T>`: `-fieldName` for descending (e.g., `-created_date`). Max 5,000 per request for list/filter.
 
+**Query operators** (`filter`, `updateMany`, `deleteMany`): `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`, `$regex` (string), `$all`/`$size` (array), `$not`; root-level `$and`/`$or`/`$nor`.
+
 ---
 
 ## Functions (`base44.functions.*`)
@@ -58,10 +60,27 @@ fetch(path, init?) → Promise<Response>   // low-level, for streaming/custom me
 
 ---
 
+## Agents (`base44.agents.*`)
+
+Requires a logged-in user.
+
+```
+createConversation({agent_name, metadata?}) → Promise<Conversation>
+getConversations() → Promise<Conversation[]>
+getConversation(id) → Promise<Conversation>                        // full data, incl. untruncated tool calls
+listConversations({q?, sort?, limit?, skip?, fields?}) → Promise<Conversation[]>
+subscribeToConversation(id, onUpdate?) → () => void                 // realtime; tool call data truncated
+addMessage(conversation, message) → Promise<Message>
+getWhatsAppConnectURL(agentName) → string
+getTelegramConnectURL(agentName) → string
+```
+
+---
+
 ## Integrations (`base44.integrations.Core.*`)
 
 ```
-InvokeLLM({prompt, add_context_from_internet?, response_json_schema?, file_urls?}) → Promise<string | object>
+InvokeLLM({prompt, model?, add_context_from_internet?, response_json_schema?, file_urls?}) → Promise<string | object>  // file_urls and add_context_from_internet are mutually exclusive
 GenerateImage({prompt}) → Promise<{url}>
 SendEmail({to, subject, body, from_name?}) → Promise<any>
 UploadFile({file}) → Promise<{file_url}>
@@ -103,8 +122,6 @@ track({eventName, properties?}) → void
 
 ```
 logUserInApp(pageName) → Promise<void>
-fetchLogs(params?) → Promise<any>
-getStats(params?) → Promise<any>
 ```
 
 ---
@@ -119,15 +136,26 @@ inviteUser(userEmail, role) → Promise<any>    // role: 'user' | 'admin'
 
 ## Service Role Connectors (`base44.asServiceRole.connectors.*`)
 
-**Backend only, service role required.** App-scoped (shared account).
+**Backend only, service role required.**
 
 ```
-getConnection(integrationType) → Promise<{accessToken, connectionConfig}>   // recommended
-getAccessToken(integrationType) → Promise<string>                           // deprecated
+getConnection(integrationType) → Promise<{accessToken, connectionConfig}>            // shared, by integration type (recommended)
+getWorkspaceConnection(connectorId) → Promise<{accessToken, connectionConfig}>       // shared, by workspace connector ID
+getCurrentAppUserConnection(connectorId) → Promise<{accessToken, connectionConfig}>  // per-user; needs createClientFromRequest(req)
+getAccessToken(integrationType) → Promise<string>                                    // deprecated
 ```
 
 **Types:** Run `npx base44 connectors list-available` to see all available integration types.
 
+## App User Connectors (`base44.connectors.*`)
+
+**Frontend.** Per-user OAuth flow (each app user connects their own account).
+
+```
+connectAppUser(connectorId) → Promise<string>   // redirect URL; window.location.href = url
+disconnectAppUser(connectorId) → Promise<void>
+```
+
 ---
 
 ## SSO (`base44.asServiceRole.sso.*`)
@@ -136,6 +164,7 @@ getAccessToken(integrationType) → Promise<string>                           //
 
 ```
 getAccessToken(userId) → Promise<{access_token}>
+getIdToken(userId) → Promise<string>   // stored ID token, not refreshed; needs on-behalf-of token for the same user
 ```
 
 ---

skills/base44-sdk/references/app-logs.md

@@ -12,8 +12,8 @@ Log user activity in your app via `base44.appLogs`.
 | Method | Signature | Description |
 |--------|-----------|-------------|
 | `logUserInApp(pageName)` | `Promise<void>` | Log user activity on a page |
-| `fetchLogs(params?)` | `Promise<any>` | Fetch app logs with optional filter parameters |
-| `getStats(params?)` | `Promise<any>` | Get app usage statistics |
+
+**Note:** the SDK also implements `fetchLogs()` and `getStats()`, but both are marked `@internal` in source — not part of the supported public API, and may change or be removed without notice. View logged activity in the Analytics page of your app dashboard instead.
 
 ## Examples
 
@@ -59,32 +59,6 @@ function handleSettingsChange() {
 }
 ```
 
-### Fetch Logs
-
-```javascript
-// Fetch all logs
-const logs = await base44.appLogs.fetchLogs();
-
-// Fetch logs with filters
-const recentLogs = await base44.appLogs.fetchLogs({
-  limit: 50,
-  page: "/dashboard"
-});
-```
-
-### Get Stats
-
-```javascript
-// Get usage statistics for the app
-const stats = await base44.appLogs.getStats();
-
-// Get stats with date range params
-const weekStats = await base44.appLogs.getStats({
-  from: "2024-01-01",
-  to: "2024-01-07"
-});
-```
-
 ## Notes
 
 - Logs appear in the Analytics page of your app dashboard
@@ -102,19 +76,5 @@ interface AppLogsModule {
    * @returns Promise that resolves when the log is recorded.
    */
   logUserInApp(pageName: string): Promise<void>;
-
-  /**
-   * Fetch app logs with optional filter parameters.
-   * @param params - Optional filter parameters (e.g., limit, page name, date range).
-   * @returns Promise resolving to the logs data.
-   */
-  fetchLogs(params?: Record<string, any>): Promise<any>;
-
-  /**
-   * Get app usage statistics.
-   * @param params - Optional filter parameters (e.g., date range).
-   * @returns Promise resolving to the statistics data.
-   */
-  getStats(params?: Record<string, any>): Promise<any>;
 }
 ```

skills/base44-sdk/references/auth.md

@@ -80,7 +80,7 @@ interface ChangePasswordParams {
 
 ### Provider Type
 ```typescript
-type Provider = 'google' | 'microsoft' | 'facebook';
+type Provider = 'google' | 'microsoft' | 'facebook' | 'apple' | 'sso';
 ```
 
 ---
@@ -92,7 +92,7 @@ type Provider = 'google' | 'microsoft' | 'facebook';
 interface AuthModule {
   // User Info
   me(): Promise<User>;
-  updateMe(data: Partial<Omit<User, 'id' | 'created_date' | 'updated_date' | 'app_id' | 'is_service'>>): Promise<User>;
+  updateMe(data: Record<string, any>): Promise<User>;
   isAuthenticated(): Promise<boolean>;
 
   // Login/Logout
@@ -125,9 +125,9 @@ interface AuthModule {
 |--------|-----------|-------------|-------------|
 | `register()` | `params: RegisterParams` | `Promise<any>` | Create new user account |
 | `loginViaEmailPassword()` | `email: string, password: string, turnstileToken?: string` | `Promise<LoginResponse>` | Authenticate with email/password |
-| `loginWithProvider()` | `provider: Provider, fromUrl?: string` | `void` | Initiate OAuth login flow. Providers: `'google'` (default), `'microsoft'`, `'facebook'` (enable in app settings) |
+| `loginWithProvider()` | `provider: Provider, fromUrl?: string` | `void` | Initiate OAuth login flow. Providers: `'google'` (default), `'microsoft'`, `'facebook'`, `'apple'` (enable in app settings), `'sso'` (enterprise SSO, requires SSO setup) |
 | `me()` | None | `Promise<User>` | Get current authenticated user |
-| `updateMe()` | `data: Partial<User>` | `Promise<User>` | Update current user's profile |
+| `updateMe()` | `data: Record<string, any>` | `Promise<User>` | Update current user's profile |
 | `logout()` | `redirectUrl?: string` | `void` | Redirect to server-side logout (clears HTTP-only cookies and session), then to redirectUrl or current URL |
 | `redirectToLogin()` | `nextUrl: string` | `void` | ⚠️ **Avoid** - Prefer custom login UI with `loginViaEmailPassword()` or `loginWithProvider()` |
 | `isAuthenticated()` | None | `Promise<boolean>` | Check if user is logged in |
@@ -215,7 +215,7 @@ try {
 
 ### Login with OAuth Provider
 
-Supported providers: `'google'` (enabled by default), `'microsoft'`, and `'facebook'`. Enable Microsoft or Facebook in your app's authentication settings before using them.
+Supported providers: `'google'` (enabled by default), `'microsoft'`, `'facebook'`, `'apple'`, and `'sso'` (enterprise SSO). Enable Microsoft, Facebook, Apple, or SSO in your app's authentication settings before using them. Requires a browser environment.
 
 ```javascript
 // Redirect to Google OAuth
@@ -224,11 +224,17 @@ base44.auth.loginWithProvider('google');
 // Redirect to Google OAuth and return to current page after
 base44.auth.loginWithProvider('google', window.location.href);
 
-// Microsoft or Facebook (enable in app settings first)
+// Microsoft, Facebook, or Apple (enable in app settings first)
 base44.auth.loginWithProvider('microsoft');
 base44.auth.loginWithProvider('facebook', '/dashboard');
+base44.auth.loginWithProvider('apple', '/dashboard');
+
+// Enterprise SSO (set up an SSO provider in app settings first)
+base44.auth.loginWithProvider('sso', '/dashboard');
 ```
 
+**Inside an iframe:** if the app is embedded in an iframe, `loginWithProvider()` doesn't do a full-page redirect. It opens a centered popup instead, waits for the popup to `postMessage` back an `access_token` (and optionally `is_new_user`), then navigates the top-level window to `fromUrl` with those values appended as query params. Outside an iframe, it's a plain `window.location.href` redirect.
+
 ### Get Current User
 
 ```javascript
@@ -589,17 +595,22 @@ Configure authentication providers in your app dashboard:
 - **Google** - OAuth authentication
 - **Microsoft** - OAuth authentication
 - **Facebook** - OAuth authentication
+- **Apple** - Sign in with Apple
 
 **SSO Providers (Elite Plan):**
 - **Okta**
 - **Azure AD**
 - **GitHub**
 
+Note: the SDK always passes the single provider value `'sso'` for `loginWithProvider()` regardless of which enterprise SSO provider is configured in your app's authentication settings — the specific provider (Okta, Azure AD, GitHub, etc.) is a dashboard configuration detail, not a separate SDK parameter.
+
 ### Using OAuth Providers
 
 - **Google** – enabled by default.
 - **Microsoft** – enable in your app's authentication settings before use.
 - **Facebook** – enable in your app's authentication settings before use.
+- **Apple** – enable in your app's authentication settings before use.
+- **SSO** – set up an SSO provider in your app's authentication settings before use.
 
 ```javascript
 // Initiate OAuth login flow
@@ -608,7 +619,7 @@ base44.auth.loginWithProvider('google');
 // Return to specific page after authentication
 base44.auth.loginWithProvider('microsoft', '/dashboard');
 
-// Supported values: 'google', 'microsoft', 'facebook'
+// Supported values: 'google', 'microsoft', 'facebook', 'apple', 'sso'
 ```
 
 ---

skills/base44-sdk/references/base44-agents.md

@@ -9,7 +9,7 @@ AI agent conversations and messages via `base44.agents`.
 ## Contents
 - [Concepts](#concepts)
 - [Methods](#methods)
-- [Examples](#examples) (Create, Get Conversations, List, Subscribe, Send Message, WhatsApp)
+- [Examples](#examples) (Create, Get Conversations, List, Subscribe, Send Message, WhatsApp, Telegram)
 - [Message Structure](#message-structure)
 - [Conversation Structure](#conversation-structure)
 - [Common Patterns](#common-patterns)
@@ -30,6 +30,7 @@ AI agent conversations and messages via `base44.agents`.
 | `subscribeToConversation(id, onUpdate?)` | `() => void` | Realtime updates via WebSocket; tool call data truncated (returns unsubscribe function) |
 | `addMessage(conversation, message)` | `Promise<Message>` | Send a message |
 | `getWhatsAppConnectURL(agentName)` | `string` | Get WhatsApp connection URL for agent |
+| `getTelegramConnectURL(agentName)` | `string` | Get Telegram connection URL for agent |
 
 ## Examples
 
@@ -125,6 +126,14 @@ const whatsappUrl = base44.agents.getWhatsAppConnectURL("support-agent");
 console.log(whatsappUrl);
 ```
 
+### Get Telegram Connection URL
+
+```javascript
+const telegramUrl = base44.agents.getTelegramConnectURL("support-agent");
+// Returns URL for users to connect with agent via Telegram
+console.log(telegramUrl);
+```
+
 ## Message Structure
 
 ```javascript
@@ -136,13 +145,14 @@ console.log(whatsappUrl);
 
   // Optional fields
   reasoning: {
-    content: "Agent's reasoning process",
-    timing: 1500
+    start_date: "2024-01-15T10:29:58Z",
+    end_date: "2024-01-15T10:30:00Z",
+    content: "Agent's reasoning process"
   },
   tool_calls: [{
     name: "search",
-    arguments: { query: "weather" },
-    result: { ... },
+    arguments_string: '{"query":"weather"}',
+    results: "...",
     status: "success"
   }],
   file_urls: ["https://..."],
@@ -295,7 +305,7 @@ interface AgentMessageToolCall {
   /** Arguments passed to the tool as JSON string. */
   arguments_string: string;
   /** Status of the tool call. */
-  status: "running" | "success" | "error" | "stopped";
+  status: "running" | "success" | "error" | "stopped" | "waiting_for_user_input";
   /** Results from the tool call. */
   results?: string;
 }
@@ -384,5 +394,8 @@ interface AgentsModule {
 
   /** Gets WhatsApp connection URL for an agent. */
   getWhatsAppConnectURL(agentName: AgentName): string;
+
+  /** Gets Telegram connection URL for an agent. */
+  getTelegramConnectURL(agentName: AgentName): string;
 }
 ```

skills/base44-sdk/references/client.md

@@ -137,8 +137,12 @@ base44.functions     // Backend function invocation
 base44.integrations  // Third-party services
 base44.users         // User invitations
 
+// Backend only
+base44.aiGateway     // Connect an OpenAI-compatible SDK to Base44's AI gateway (see ai-gateway.md)
+
 // Service role only (backend)
 base44.asServiceRole.agents
+base44.asServiceRole.aiGateway
 base44.asServiceRole.appLogs
 base44.asServiceRole.connectors  // App-scoped OAuth tokens (ConnectorsModule)
 base44.asServiceRole.entities
@@ -185,6 +189,7 @@ useEffect(() => {
 createClient({
   appId: "your-app-id",      // Required: MUST use 'appId' (not 'clientId' or 'id')
   token: "jwt-token",        // Optional: pre-set auth token
+  serverUrl: "https://base44.app", // Optional: defaults to "https://base44.app"; point at a local dev server if needed
   options: {                 // Optional: configuration options
     onError: (error) => {}   // Optional: global error handler (must be in options)
   }
@@ -206,6 +211,8 @@ interface CreateClientConfig {
   appId: string;
   /** User authentication token. Used to authenticate as a specific user. */
   token?: string;
+  /** Base URL of the Base44 server to point the SDK at (e.g. for local development). @defaultValue "https://base44.app" */
+  serverUrl?: string;
   /** @internal Service role token; only set automatically in Base44-hosted backend functions. */
   serviceToken?: string;
   /** Additional client options. */
@@ -238,6 +245,8 @@ interface Base44Client {
   functions: FunctionsModule;
   /** Integrations module for calling pre-built integration methods. */
   integrations: IntegrationsModule;
+  /** Connect an OpenAI-compatible SDK to Base44's AI gateway (backend only). */
+  aiGateway: AiGatewayModule;
 
   /** Cleanup function to disconnect WebSocket connections. */
   cleanup(): void;
@@ -257,6 +266,7 @@ interface Base44Client {
     entities: EntitiesModule;
     functions: FunctionsModule;
     integrations: IntegrationsModule;
+    aiGateway: AiGatewayModule;
     /** SSO token generation for users. */
     sso: SsoModule;
     cleanup(): void;