Improve SDK documentation TOC structure and organization (#131)

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 <cursoragent@cursor.com>

Author: wixysam

scripts/mintlify-post-processing/file-processing/file-processing.js

@@ -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;
 }

scripts/mintlify-post-processing/file-processing/styling.css

@@ -59,7 +59,6 @@ export type {
 
 export type {
   IntegrationsModule,
-  IntegrationPackage,
   IntegrationEndpointFunction,
   CoreIntegrations,
   InvokeLLMParams,

src/index.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.

src/modules/agents.types.ts

@@ -83,11 +83,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 {

src/modules/analytics.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 {

src/modules/app-logs.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 {

src/modules/auth.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

src/modules/connectors.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.

src/modules/entities.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.