From 5d42360afacb2114b8eafc7c99d7470c558c9fc2 Mon Sep 17 00:00:00 2001 From: Sam Markowitz Date: Thu, 15 Jan 2026 12:27:55 +0200 Subject: [PATCH 1/4] Add analytics module documentation --- .../file-processing/file-processing.js | 1 + .../types-to-expose.json | 1 + src/client.types.ts | 39 ++++---- src/modules/analytics.types.ts | 92 ++++++++++++++++++- 4 files changed, 108 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 67f7cbd..06de994 100755 --- a/scripts/mintlify-post-processing/file-processing/file-processing.js +++ b/scripts/mintlify-post-processing/file-processing/file-processing.js @@ -35,6 +35,7 @@ const PANELS_ENABLED = process.env.MINTLIFY_INCLUDE_PANELS === "true"; const MODULE_RENAMES = { AgentsModule: "agents", + AnalyticsModule: "analytics", AppLogsModule: "app-logs", AuthModule: "auth", ConnectorsModule: "connectors", diff --git a/scripts/mintlify-post-processing/types-to-expose.json b/scripts/mintlify-post-processing/types-to-expose.json index 49e790d..3bbdb35 100644 --- a/scripts/mintlify-post-processing/types-to-expose.json +++ b/scripts/mintlify-post-processing/types-to-expose.json @@ -1,5 +1,6 @@ [ "AgentsModule", + "AnalyticsModule", "AppLogsModule", "AuthModule", "ConnectorsModule", diff --git a/src/client.types.ts b/src/client.types.ts index e115cdb..d5a83df 100644 --- a/src/client.types.ts +++ b/src/client.types.ts @@ -77,23 +77,20 @@ export interface CreateClientConfig { * Provides access to all SDK modules for interacting with the app. */ export interface Base44Client { - /** {@link EntitiesModule | Entities module} for CRUD operations on your data models. */ - entities: EntitiesModule; - /** {@link IntegrationsModule | Integrations module} for calling pre-built integration endpoints. */ - integrations: IntegrationsModule; - /** {@link AuthModule | Auth module} for user authentication and management. */ - auth: AuthModule; - /** {@link FunctionsModule | Functions module} for invoking custom backend functions. */ - functions: FunctionsModule; /** {@link AgentsModule | Agents module} for managing AI agent conversations. */ agents: AgentsModule; + /** {@link AnalyticsModule | Analytics module} for tracking custom events in your app. */ + analytics: AnalyticsModule; /** {@link AppLogsModule | App logs module} for tracking app usage. */ appLogs: AppLogsModule; - /** - * {@link AnalyticsModule | Analytics module} for tracking app usage. - * @internal - */ - analytics: AnalyticsModule; + /** {@link AuthModule | Auth module} for user authentication and management. */ + auth: AuthModule; + /** {@link EntitiesModule | Entities module} for CRUD operations on your data models. */ + entities: EntitiesModule; + /** {@link FunctionsModule | Functions module} for invoking custom backend functions. */ + functions: FunctionsModule; + /** {@link IntegrationsModule | Integrations module} for calling pre-built integration endpoints. */ + integrations: IntegrationsModule; /** Cleanup function to disconnect WebSocket connections. Call when you're done with the client. */ cleanup: () => void; @@ -120,22 +117,22 @@ export interface Base44Client { * @throws {Error} When accessed without providing a serviceToken during client creation */ readonly asServiceRole: { + /** {@link AgentsModule | Agents module} with elevated permissions. */ + agents: AgentsModule; + /** {@link AppLogsModule | App logs module} with elevated permissions. */ + appLogs: AppLogsModule; + /** {@link ConnectorsModule | Connectors module} for OAuth token retrieval. */ + connectors: ConnectorsModule; /** {@link EntitiesModule | Entities module} with elevated permissions. */ entities: EntitiesModule; + /** {@link FunctionsModule | Functions module} with elevated permissions. */ + functions: FunctionsModule; /** {@link IntegrationsModule | Integrations module} with elevated permissions. */ integrations: IntegrationsModule; /** {@link SsoModule | SSO module} for generating SSO tokens. * @internal */ sso: SsoModule; - /** {@link ConnectorsModule | Connectors module} for OAuth token retrieval. */ - connectors: ConnectorsModule; - /** {@link FunctionsModule | Functions module} with elevated permissions. */ - functions: FunctionsModule; - /** {@link AgentsModule | Agents module} with elevated permissions. */ - agents: AgentsModule; - /** {@link AppLogsModule | App logs module} with elevated permissions. */ - appLogs: AppLogsModule; /** Cleanup function to disconnect WebSocket connections. */ cleanup: () => void; }; diff --git a/src/modules/analytics.types.ts b/src/modules/analytics.types.ts index e0f29e3..e29ba5e 100644 --- a/src/modules/analytics.types.ts +++ b/src/modules/analytics.types.ts @@ -1,9 +1,39 @@ +/** + * Properties for analytics events. + * + * Key-value pairs with additional event data. Values can be strings, numbers, booleans, or null. + */ export type TrackEventProperties = { [key: string]: string | number | boolean | null | undefined; }; +/** + * Parameters for tracking an analytics event. + */ export type TrackEventParams = { + /** + * Name of the event to track. + * + * Use descriptive names like `button_click`, `form_submit`, or `purchase_completed`. + */ eventName: string; + /** + * Optional key-value pairs with additional event data. + * + * Values can be strings, numbers, booleans, or null. + * + * @example + * ```typescript + * base44.analytics.track({ + * eventName: 'add_to_cart', + * properties: { + * product_id: 'prod_123', + * price: 29.99, + * quantity: 2 + * } + * }); + * ``` + */ properties?: TrackEventProperties; }; @@ -47,8 +77,62 @@ export type AnalyticsModuleOptions = { }; /** - * @internal + * Analytics module for tracking custom events in your app. + * + * Use this module to track specific user actions that appear as custom event cards in your [Analytics dashboard](/documentation/performance-and-seo/app-analytics). Track things like button clicks, form submissions, purchases, and feature usage. + * + * 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`. + * + * This module is only available in user authentication mode (`base44.analytics`). + * + * ## Built-in vs Custom Analytics + * + * Your Analytics dashboard shows two types of data: + * + * **Built-in metrics:** + * - Total visits, unique visitors, visit duration, and live visitors. + * - Breakdown cards for country, device, operating system, and referrer. + * + * These begin tracking automatically when {@linkcode createClient | createClient()} is called and continue tracking until the client is cleaned up. + * + * **Custom events:** + * - Each event you track with `track()` appears as its own card in the dashboard. + * - Use these to measure specific actions that matter to your app. + * + * These are tracked when you call the `track()` method. */ -export type AnalyticsModule = { - track: (params: TrackEventParams) => void; -}; +export interface AnalyticsModule { + /** + * Tracks a custom event that appears as a card in your Analytics dashboard. + * + * Each unique event name becomes its own card showing total count and trends over time. This method returns immediately and events are sent in batches in the background. + * + * @param params - Event parameters. + * @param params.eventName - Name of the event. This becomes the card title in your dashboard. Use descriptive names like `'signup_button_click'` or `'purchase_completed'`. + * @param params.properties - Optional data to attach to the event. You can filter and analyze events by these properties in the dashboard. + * + * @example Track a button click + * ```typescript + * // Track a button click + * base44.analytics.track({ + * eventName: 'signup_button_click' + * }); + * ``` + * + * @example Track with properties + * ```typescript + * // Track with properties + * base44.analytics.track({ + * eventName: 'add_to_cart', + * properties: { + * product_id: 'prod_123', + * product_name: 'Premium Widget', + * price: 29.99, + * quantity: 2, + * is_first_purchase: true + * } + * }); + * ``` + */ + track(params: TrackEventParams): void; +} From 1239f9e28556b5062aaf60f5952f5f1e9f4c26c3 Mon Sep 17 00:00:00 2001 From: Sam Markowitz Date: Thu, 15 Jan 2026 12:39:56 +0200 Subject: [PATCH 2/4] Mark internal methods, fix App ID naming --- src/modules/auth.types.ts | 1 + src/modules/entities.types.ts | 1 + src/modules/integrations.types.ts | 2 ++ 3 files changed, 4 insertions(+) diff --git a/src/modules/auth.types.ts b/src/modules/auth.types.ts index 8795693..1390535 100644 --- a/src/modules/auth.types.ts +++ b/src/modules/auth.types.ts @@ -190,6 +190,7 @@ export interface AuthModule { * * Initiates OAuth/SSO login flow with providers like Google, Microsoft, etc. Requires a browser environment and can't be used in the backend. * + * @internal * @param provider - Name of the supported authentication provider (e.g., 'google', 'microsoft'). * @param fromUrl - URL to redirect to after successful authentication. Defaults to '/'. * diff --git a/src/modules/entities.types.ts b/src/modules/entities.types.ts index 58c03c7..21d4c34 100644 --- a/src/modules/entities.types.ts +++ b/src/modules/entities.types.ts @@ -293,6 +293,7 @@ export interface EntityHandler { * record is created, updated, or deleted. Returns an unsubscribe function * to clean up the connection. * + * @internal * @param callback - Callback function called when an entity changes. The callback receives an event object with the following properties: * - `type`: The type of change that occurred - `'create'`, `'update'`, or `'delete'`. * - `data`: The entity data after the change. diff --git a/src/modules/integrations.types.ts b/src/modules/integrations.types.ts index 6696fa7..5a8be7e 100644 --- a/src/modules/integrations.types.ts +++ b/src/modules/integrations.types.ts @@ -382,6 +382,8 @@ export type IntegrationsModule = { /** * Custom integrations module for calling pre-configured external APIs. + * + * @internal */ custom: CustomIntegrationsModule; } & { From 7fa0f9b9d1daa0c081095d8e835dad935c28abf9 Mon Sep 17 00:00:00 2001 From: Sam Markowitz Date: Tue, 20 Jan 2026 10:40:11 +0200 Subject: [PATCH 3/4] address review comments --- src/modules/analytics.types.ts | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/src/modules/analytics.types.ts b/src/modules/analytics.types.ts index e29ba5e..46bb486 100644 --- a/src/modules/analytics.types.ts +++ b/src/modules/analytics.types.ts @@ -79,27 +79,16 @@ export type AnalyticsModuleOptions = { /** * Analytics module for tracking custom events in your app. * - * Use this module to track specific user actions that appear as custom event cards in your [Analytics dashboard](/documentation/performance-and-seo/app-analytics). Track things like button clicks, form submissions, purchases, and feature usage. + * Use this module to track specific user actions. Track things like button clicks, form submissions, purchases, and feature usage. * - * 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`. + * Analytics events tracked with this module appear as custom event cards in the [Analytics dashboard](/documentation/performance-and-seo/app-analytics). * - * This module is only available in user authentication mode (`base44.analytics`). - * - * ## Built-in vs Custom Analytics - * - * Your Analytics dashboard shows two types of data: + * When tracking events: * - * **Built-in metrics:** - * - Total visits, unique visitors, visit duration, and live visitors. - * - Breakdown cards for country, device, operating system, and referrer. + * - 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`. * - * These begin tracking automatically when {@linkcode createClient | createClient()} is called and continue tracking until the client is cleaned up. - * - * **Custom events:** - * - Each event you track with `track()` appears as its own card in the dashboard. - * - Use these to measure specific actions that matter to your app. - * - * These are tracked when you call the `track()` method. + * This module is only available in user authentication mode (`base44.analytics`). */ export interface AnalyticsModule { /** From 11445219cd8e8bdfd0f2bcf87d936242cda65876 Mon Sep 17 00:00:00 2001 From: Sam Markowitz Date: Tue, 20 Jan 2026 10:52:06 +0200 Subject: [PATCH 4/4] Remove @internal from subscribe and custom integrations --- src/modules/entities.types.ts | 1 - src/modules/integrations.types.ts | 2 -- 2 files changed, 3 deletions(-) diff --git a/src/modules/entities.types.ts b/src/modules/entities.types.ts index 21d4c34..58c03c7 100644 --- a/src/modules/entities.types.ts +++ b/src/modules/entities.types.ts @@ -293,7 +293,6 @@ export interface EntityHandler { * record is created, updated, or deleted. Returns an unsubscribe function * to clean up the connection. * - * @internal * @param callback - Callback function called when an entity changes. The callback receives an event object with the following properties: * - `type`: The type of change that occurred - `'create'`, `'update'`, or `'delete'`. * - `data`: The entity data after the change. diff --git a/src/modules/integrations.types.ts b/src/modules/integrations.types.ts index 5a8be7e..6696fa7 100644 --- a/src/modules/integrations.types.ts +++ b/src/modules/integrations.types.ts @@ -382,8 +382,6 @@ export type IntegrationsModule = { /** * Custom integrations module for calling pre-configured external APIs. - * - * @internal */ custom: CustomIntegrationsModule; } & {