From c9b918478fe27720ddcb188b0b8671c8fd5cfcaa Mon Sep 17 00:00:00 2001 From: Sam Markowitz Date: Sun, 22 Feb 2026 13:17:05 +0200 Subject: [PATCH] Improve SDK documentation TOC structure and organization Enhanced the SDK documentation with better TOC visibility and organization: - Added CSS to show depth-2 TOC items (methods) while hiding deeper levels - Grouped type definitions under "Type Definitions" heading for entities, functions, and agents modules - Added "Overview" heading to organize intro sections consistently across modules - Renamed "EntityHandler" section to "Entity Handler Methods" for clarity - Split integrations methods into "Core Integrations Methods" and "Custom Integrations Methods" - Added structured subsections in Overview for all modules: - auth: Features, Authentication Modes - agents: Key Features, Conversation Structure, Authentication Modes - analytics: Best Practices, Authentication Modes - entities: Entity Handlers, Built-in User Entity, Generated Types - integrations: Integration Types, Authentication Modes - functions, connectors, app-logs: Authentication Modes - Updated terminology to use "custom workspace integrations" with link to documentation - Demoted example headings in type definitions to prevent TOC clutter Co-authored-by: Cursor --- .../file-processing/file-processing.js | 553 ++++++++++++++++++ .../file-processing/styling.css | 12 +- src/index.ts | 1 - src/modules/agents.types.ts | 6 + src/modules/analytics.types.ts | 4 + src/modules/app-logs.types.ts | 2 + src/modules/auth.types.ts | 4 + src/modules/connectors.types.ts | 2 + src/modules/entities.types.ts | 8 + src/modules/functions.types.ts | 2 + src/modules/integrations.types.ts | 79 ++- 11 files changed, 648 insertions(+), 25 deletions(-) diff --git a/scripts/mintlify-post-processing/file-processing/file-processing.js b/scripts/mintlify-post-processing/file-processing/file-processing.js index 437639c..3258237 100755 --- a/scripts/mintlify-post-processing/file-processing/file-processing.js +++ b/scripts/mintlify-post-processing/file-processing/file-processing.js @@ -1031,6 +1031,7 @@ function demoteNonCallableHeadings(content) { if (inFence) { continue; } + // Demote ### headings that don't have parentheses (not methods) to #### if (line.startsWith("### ")) { const headingText = line.slice(4).trim(); if (!headingText.includes("(")) { @@ -1038,6 +1039,16 @@ function demoteNonCallableHeadings(content) { modified = true; } } + // Demote ## Example/Examples headings for type definitions to #### + // These appear after type definitions (EntityRecord, SortField, etc.) + // and should not show in TOC + if (line.startsWith("## Example")) { + const headingText = line.slice(3).trim(); + if (headingText === "Example" || headingText === "Examples") { + lines[i] = `#### ${headingText}`; + modified = true; + } + } } return { content: lines.join("\n"), modified }; } @@ -1155,6 +1166,539 @@ function applyTypeDeclarationLinking(dir) { } } +/** + * Group intro sections (like "Built-in User Entity", "Generated Types") under an "Overview" heading + * The Overview heading goes at the top of the page content, and intro paragraph becomes part of Overview + */ +function groupIntroSections(content) { + const lines = content.split("\n"); + let modified = false; + + // Find where to insert "## Overview" - after the frontmatter and initial separator + // Look for the line after the closing --- of frontmatter + let insertIndex = -1; + let inFrontmatter = false; + + for (let i = 0; i < lines.length; i++) { + const line = lines[i].trim(); + + if (line === "---") { + if (!inFrontmatter) { + inFrontmatter = true; + } else { + // Found closing ---, next content line is where we insert + // Skip any *** separators or blank lines + for (let j = i + 1; j < lines.length; j++) { + if (lines[j].trim() !== "" && lines[j].trim() !== "***") { + insertIndex = j; + break; + } + } + break; + } + } + } + + if (insertIndex === -1) { + return { content, modified: false }; + } + + // Find the first main section heading (Methods, EntityHandler, Properties, etc.) + // These mark the end of intro/overview sections + const mainSectionNames = ["Methods", "EntityHandler", "Properties", "Type Definitions"]; + let mainSectionIndex = -1; + + for (let i = insertIndex; i < lines.length; i++) { + const line = lines[i].trim(); + for (const sectionName of mainSectionNames) { + if (line === `## ${sectionName}`) { + mainSectionIndex = i; + break; + } + } + if (mainSectionIndex !== -1) break; + } + + if (mainSectionIndex === -1) { + // No main section found, nothing to group + return { content, modified: false }; + } + + // Find all ## headings between insert point and main section (these are intro sections) + const introHeadingIndices = []; + for (let i = insertIndex; i < mainSectionIndex; i++) { + const line = lines[i].trim(); + if (line.startsWith("## ") && !line.startsWith("### ")) { + introHeadingIndices.push(i); + } + } + + // Insert "## Overview" at the beginning of content + lines.splice(insertIndex, 0, "## Overview", ""); + modified = true; + + // Demote all intro headings from ## to ### (adjust indices after insertion) + for (let i = 0; i < introHeadingIndices.length; i++) { + const adjustedIndex = introHeadingIndices[i] + 2; // +2 because we inserted 2 lines + const line = lines[adjustedIndex]; + if (line.startsWith("## ")) { + lines[adjustedIndex] = "###" + line.slice(2); + } + } + + return { content: lines.join("\n"), modified }; +} + +/** + * Apply intro section grouping to module files + */ +function applyIntroSectionGrouping(dir) { + if (!fs.existsSync(dir)) return; + const entries = fs.readdirSync(dir, { withFileTypes: true }); + for (const entry of entries) { + const entryPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + applyIntroSectionGrouping(entryPath); + } else if ( + entry.isFile() && + (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) + ) { + const content = fs.readFileSync(entryPath, "utf-8"); + const { content: updated, modified } = groupIntroSections(content); + if (modified) { + fs.writeFileSync(entryPath, updated, "utf-8"); + console.log( + `Grouped intro sections: ${path.relative(DOCS_DIR, entryPath)}` + ); + } + } + } +} + +/** + * Group type definition sections under a parent heading + * For entities: EntityRecord, EntityTypeRegistry, SortField + * For functions: FunctionName, FunctionNameRegistry + * For agents: AgentName, AgentNameRegistry + */ +function groupTypeDefinitions(content) { + let modified = false; + + // Define type definition patterns for different modules + const typeGroups = [ + // Entities module + { + types: ["EntityRecord", "EntityTypeRegistry", "SortField"], + indicator: "EntityRecord" + }, + // Functions module + { + types: ["FunctionName", "FunctionNameRegistry"], + indicator: "FunctionName" + }, + // Agents module + { + types: ["AgentName", "AgentNameRegistry"], + indicator: "AgentName" + } + ]; + + // Find which type group exists in this file + let matchedGroup = null; + for (const group of typeGroups) { + if (content.includes(`## ${group.indicator}`)) { + matchedGroup = group; + break; + } + } + + if (!matchedGroup) { + return { content, modified: false }; + } + + // Find the position of the first type definition section + const firstTypeIndex = content.indexOf(`## ${matchedGroup.indicator}`); + if (firstTypeIndex === -1) { + return { content, modified: false }; + } + + // Insert "## Type Definitions" heading before the first type + const beforeTypeDefinitions = content.slice(0, firstTypeIndex); + const typeDefinitionsSection = content.slice(firstTypeIndex); + + // Demote all types in this group from ## to ### + let demotedSection = typeDefinitionsSection; + for (const typeName of matchedGroup.types) { + const regex = new RegExp(`^## ${typeName}$`, "m"); + demotedSection = demotedSection.replace(regex, `### ${typeName}`); + } + + const updatedContent = + beforeTypeDefinitions + + "## Type Definitions\n\n" + + demotedSection; + + return { content: updatedContent, modified: true }; +} + +/** + * Rename and merge method sections for better TOC organization + * - EntityHandler → Entity Handler Methods + * - First ## Methods in integrations → Core Integrations Methods + * - custom-integrations → Custom Integrations Methods + * - Create Type Definitions section with Core, custom, and Indexable + */ +function mergeSectionWithMethods(content, filePath) { + const lines = content.split("\n"); + let modified = false; + const isIntegrations = filePath && filePath.includes("integrations.mdx"); + let firstMethodsFound = false; + + // Storage for extracted content + let coreDescription = null; + let customDescription = null; + let indexableContent = []; + let customIntegrationsModuleDescription = []; + + // First pass: extract type descriptions and remove sections in integrations + if (isIntegrations) { + for (let i = 0; i < lines.length; i++) { + const line = lines[i].trim(); + + // Rename ## Type Declaration to ## Type Definitions + if (line === "## Type Declaration") { + lines[i] = "## Type Definitions"; + modified = true; + } + + // Remove ## Index Signature section (redundant with Indexable in Type Definitions) + if (line === "## Index Signature") { + let endIndex = i + 1; + for (let j = i + 1; j < lines.length; j++) { + const nextLine = lines[j].trim(); + if (nextLine.startsWith("##")) { + endIndex = j; + break; + } + } + lines.splice(i, endIndex - i); + modified = true; + i--; + continue; + } + + // Remove ### Type Declarations and ### CoreIntegrations sections in Overview + if (line === "### Type Declarations" || line === "### CoreIntegrations") { + // Find the end of this section (next ## heading) + let endIndex = i + 1; + for (let j = i + 1; j < lines.length; j++) { + const nextLine = lines[j].trim(); + if (nextLine.startsWith("##")) { + endIndex = j; + break; + } + } + + // Extract coreDescription if this is CoreIntegrations + if (line === "### CoreIntegrations") { + for (let j = i + 1; j < endIndex && j < i + 10; j++) { + const descLine = lines[j].trim(); + if (descLine && descLine !== "***" && !descLine.startsWith("#")) { + coreDescription = descLine; + break; + } + } + } + + // Remove lines from i to endIndex + lines.splice(i, endIndex - i); + modified = true; + i--; + continue; + } + + // Extract and remove #### Core subsection (from old structure) + if (line === "#### Core") { + // Extract description + for (let j = i + 1; j < lines.length && j < i + 10; j++) { + const descLine = lines[j].trim(); + if (descLine && descLine !== ">" && !descLine.startsWith(">") && !descLine.startsWith("#")) { + if (!coreDescription) coreDescription = descLine; + break; + } + } + + // Find end of subsection + let endIndex = i + 1; + for (let j = i + 1; j < lines.length; j++) { + const nextLine = lines[j].trim(); + if (nextLine.startsWith("####") || nextLine.startsWith("##")) { + endIndex = j; + break; + } + } + + lines.splice(i, endIndex - i); + modified = true; + i--; + continue; + } + + // Extract and remove #### custom subsection + if (line === "#### custom") { + // Extract description + for (let j = i + 1; j < lines.length && j < i + 10; j++) { + const descLine = lines[j].trim(); + if (descLine && descLine !== ">" && !descLine.startsWith(">") && !descLine.startsWith("#")) { + customDescription = descLine; + break; + } + } + + // Find end of subsection + let endIndex = i + 1; + for (let j = i + 1; j < lines.length; j++) { + const nextLine = lines[j].trim(); + if (nextLine.startsWith("####") || nextLine.startsWith("##")) { + endIndex = j; + break; + } + } + + lines.splice(i, endIndex - i); + modified = true; + i--; + continue; + } + + // Extract and remove first ### Indexable (in Overview) + if (line === "### Indexable" && indexableContent.length === 0) { + // Extract the entire Indexable section + let endIndex = i + 1; + for (let j = i + 1; j < lines.length; j++) { + const nextLine = lines[j].trim(); + if (nextLine.startsWith("##")) { + endIndex = j; + break; + } + } + + // Save the content (excluding the heading) + indexableContent = lines.slice(i + 1, endIndex); + + // Remove this section + lines.splice(i, endIndex - i); + modified = true; + i--; + continue; + } + + // Extract and remove second ## Indexable (before Custom Integrations Methods) + if (line === "## Indexable") { + // Extract the custom integrations module description that follows + let endIndex = i + 1; + for (let j = i + 1; j < lines.length; j++) { + const nextLine = lines[j].trim(); + if (nextLine.startsWith("###") || nextLine.startsWith("## Methods")) { + endIndex = j; + break; + } + } + + // Extract description lines (skip the duplicate indexable definition) + let foundSeparator = false; + for (let j = i + 1; j < endIndex; j++) { + const descLine = lines[j].trim(); + if (descLine === "***") { + foundSeparator = true; + continue; + } + if (foundSeparator && descLine && !descLine.startsWith(">") && !descLine.startsWith("[")) { + customIntegrationsModuleDescription.push(lines[j]); + } + } + + // Remove this section + lines.splice(i, endIndex - i); + modified = true; + i--; + continue; + } + } + } + + // Second pass: handle method section renaming and add descriptions + for (let i = 0; i < lines.length; i++) { + const line = lines[i].trim(); + + // Handle EntityHandler + Methods → Entity Handler Methods + if (line === "## EntityHandler") { + // Look ahead to find the next ## Methods heading + let methodsIndex = -1; + for (let j = i + 1; j < lines.length; j++) { + const nextLine = lines[j].trim(); + if (nextLine.startsWith("## ")) { + if (nextLine === "## Methods") { + methodsIndex = j; + } + break; + } + } + + if (methodsIndex !== -1) { + lines[i] = "## Entity Handler Methods"; + lines.splice(methodsIndex, 1); + modified = true; + } + } + + // Handle integrations module + if (isIntegrations) { + // First ## Methods → Core Integrations Methods + if (line === "## Methods" && !firstMethodsFound) { + lines[i] = "## Core Integrations Methods"; + firstMethodsFound = true; + modified = true; + + // Add Core description after the heading + if (coreDescription) { + lines.splice(i + 1, 0, "", coreDescription, ""); + } + } + // Remove any remaining ## Methods (after Custom Integrations Methods) + else if (line === "## Methods" && firstMethodsFound) { + // This is a duplicate Methods heading, remove it + lines.splice(i, 1); + modified = true; + i--; + continue; + } + // custom-integrations section + else if (line === "## custom-integrations") { + // Replace with Custom Integrations Methods + lines[i] = "## Custom Integrations Methods"; + modified = true; + + // Add custom integrations module description after the heading + if (customIntegrationsModuleDescription.length > 0) { + lines.splice(i + 1, 0, "", ...customIntegrationsModuleDescription, ""); + } + } + } + } + + // Third pass: Add Type Definitions section at the end for integrations + if (isIntegrations && (coreDescription || customDescription)) { + lines.push(""); + lines.push("## Type Definitions"); + lines.push(""); + + // Add Core + if (coreDescription) { + lines.push("### Core"); + lines.push(""); + lines.push("> **Core**: `CoreIntegrations`"); + lines.push(""); + lines.push(coreDescription); + lines.push(""); + lines.push("#### Example"); + lines.push(""); + lines.push(""); + lines.push(""); + lines.push("```typescript Invoke an LLM"); + lines.push("const response = await base44.integrations.Core.InvokeLLM({"); + lines.push(" prompt: 'Explain quantum computing',"); + lines.push(" model: 'gpt-4'"); + lines.push("});"); + lines.push("```"); + lines.push(""); + lines.push(""); + lines.push(""); + } + + // Add custom + if (customDescription) { + lines.push("### custom"); + lines.push(""); + lines.push("> **custom**: `CustomIntegrationsModule`"); + lines.push(""); + lines.push(customDescription); + lines.push(""); + lines.push("#### Example"); + lines.push(""); + lines.push(""); + lines.push(""); + lines.push("```typescript Call a custom integration"); + lines.push("const result = await base44.integrations.custom.call("); + lines.push(" 'github',"); + lines.push(" 'get:/repos/{owner}/{repo}',"); + lines.push(" { pathParams: { owner: 'myorg', repo: 'myrepo' } }"); + lines.push(");"); + lines.push("```"); + lines.push(""); + lines.push(""); + lines.push(""); + } + + modified = true; + } + + return { content: lines.join("\n"), modified }; +} + +/** + * Apply section + methods merging to relevant files + */ +function applySectionMethodsMerging(dir) { + if (!fs.existsSync(dir)) return; + const entries = fs.readdirSync(dir, { withFileTypes: true }); + for (const entry of entries) { + const entryPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + applySectionMethodsMerging(entryPath); + } else if ( + entry.isFile() && + (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) + ) { + const content = fs.readFileSync(entryPath, "utf-8"); + const { content: updated, modified } = mergeSectionWithMethods(content, entryPath); + if (modified) { + fs.writeFileSync(entryPath, updated, "utf-8"); + console.log( + `Merged section with methods: ${path.relative(DOCS_DIR, entryPath)}` + ); + } + } + } +} + +/** + * Apply type definition grouping to relevant files + */ +function applyTypeDefinitionGrouping(dir) { + if (!fs.existsSync(dir)) return; + const entries = fs.readdirSync(dir, { withFileTypes: true }); + for (const entry of entries) { + const entryPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + applyTypeDefinitionGrouping(entryPath); + } else if ( + entry.isFile() && + (entry.name.endsWith(".mdx") || entry.name.endsWith(".md")) + ) { + // Apply to all files - the function checks internally if it has type definitions + const content = fs.readFileSync(entryPath, "utf-8"); + const { content: updated, modified } = groupTypeDefinitions(content); + if (modified) { + fs.writeFileSync(entryPath, updated, "utf-8"); + console.log( + `Grouped type definitions: ${path.relative(DOCS_DIR, entryPath)}` + ); + } + } + } +} + /** * Remove links to types that are not in the exposed types list. * Converts [TypeName](path) or [`TypeName`](path) to just TypeName or `TypeName`. @@ -1372,6 +1916,15 @@ function main() { applyHeadingDemotion(DOCS_DIR); + // Group intro sections (Built-in User Entity, Generated Types, etc.) under Overview + applyIntroSectionGrouping(DOCS_DIR); + + // Merge section headings with immediately following ## Methods + applySectionMethodsMerging(DOCS_DIR); + + // Group type definitions under a parent heading + applyTypeDefinitionGrouping(DOCS_DIR); + // Link type names in Type Declarations sections to their corresponding headings applyTypeDeclarationLinking(DOCS_DIR); diff --git a/scripts/mintlify-post-processing/file-processing/styling.css b/scripts/mintlify-post-processing/file-processing/styling.css index 87bc800..0b91215 100644 --- a/scripts/mintlify-post-processing/file-processing/styling.css +++ b/scripts/mintlify-post-processing/file-processing/styling.css @@ -117,12 +117,10 @@ a:has(code) { color: #ff8844 !important; /* light orange */ } -/* Hide nested TOC items on interface and type-alias pages */ -body:has([data-page-href*="/content/interfaces/"]) - .toc - li[data-depth]:not([data-depth="1"]), -body:has([data-page-href*="/content/type-aliases/"]) - .toc - li[data-depth]:not([data-depth="1"]) { +/* Show section headings (depth 0) and methods (depth 1), but hide method details (depth 2+) */ +/* This applies to SDK interface and type-alias pages */ + +/* Hide Parameters, Returns, Examples (depth 2) on SDK docs pages */ +.toc li.toc-item[data-depth="2"] { display: none !important; } diff --git a/src/index.ts b/src/index.ts index d772c1a..b95308b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -59,7 +59,6 @@ export type { export type { IntegrationsModule, - IntegrationPackage, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, diff --git a/src/modules/agents.types.ts b/src/modules/agents.types.ts index 5ff55c3..4eab5f3 100644 --- a/src/modules/agents.types.ts +++ b/src/modules/agents.types.ts @@ -183,6 +183,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. @@ -192,12 +194,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. diff --git a/src/modules/analytics.types.ts b/src/modules/analytics.types.ts index 46bb486..a3a7656 100644 --- a/src/modules/analytics.types.ts +++ b/src/modules/analytics.types.ts @@ -83,11 +83,15 @@ export type AnalyticsModuleOptions = { * * Analytics events tracked with this module appear as custom event cards in the [Analytics dashboard](/documentation/performance-and-seo/app-analytics). * + * ## 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 { diff --git a/src/modules/app-logs.types.ts b/src/modules/app-logs.types.ts index ab1b9b7..a9c6e0a 100644 --- a/src/modules/app-logs.types.ts +++ b/src/modules/app-logs.types.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 { diff --git a/src/modules/auth.types.ts b/src/modules/auth.types.ts index 3ced34a..55366ce 100644 --- a/src/modules/auth.types.ts +++ b/src/modules/auth.types.ts @@ -105,6 +105,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 @@ -113,6 +115,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 { diff --git a/src/modules/connectors.types.ts b/src/modules/connectors.types.ts index f25953d..46f9e92 100644 --- a/src/modules/connectors.types.ts +++ b/src/modules/connectors.types.ts @@ -34,6 +34,8 @@ 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. * + * ## Authentication Modes + * * 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. * * ## Dynamic Types diff --git a/src/modules/entities.types.ts b/src/modules/entities.types.ts index 3376ff3..613d554 100644 --- a/src/modules/entities.types.ts +++ b/src/modules/entities.types.ts @@ -460,6 +460,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. diff --git a/src/modules/functions.types.ts b/src/modules/functions.types.ts index 73d9e9d..68fec06 100644 --- a/src/modules/functions.types.ts +++ b/src/modules/functions.types.ts @@ -22,6 +22,8 @@ export type FunctionName = keyof FunctionNameRegistry extends never * * 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. diff --git a/src/modules/integrations.types.ts b/src/modules/integrations.types.ts index 6696fa7..ca42ef0 100644 --- a/src/modules/integrations.types.ts +++ b/src/modules/integrations.types.ts @@ -10,24 +10,31 @@ import { CustomIntegrationsModule } from "./custom-integrations.types.js"; * @returns Promise resolving to the integration endpoint's response. */ export type IntegrationEndpointFunction = ( - data: Record + data: Record, ) => 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; @@ -285,7 +292,7 @@ export interface CoreIntegrations { * ``` */ ExtractDataFromUploadedFile( - params: ExtractDataFromUploadedFileParams + params: ExtractDataFromUploadedFileParams, ): Promise; /** @@ -324,7 +331,7 @@ export interface CoreIntegrations { * ``` */ UploadPrivateFile( - params: UploadPrivateFileParams + params: UploadPrivateFileParams, ): Promise; /** @@ -346,7 +353,7 @@ export interface CoreIntegrations { * ``` */ CreateFileSignedUrl( - params: CreateFileSignedUrlParams + params: CreateFileSignedUrlParams, ): Promise; } @@ -355,6 +362,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: @@ -362,12 +371,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) * ``` * - * To call a custom integration, it must be pre-configured by a workspace administrator who imports an OpenAPI specification. + * 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). + * + * ## Authentication Modes * * This module is available to use with a client in all authentication modes: * @@ -377,19 +388,53 @@ 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; };