add support to augment the types of the sdk

Author: kfirstri

src/index.ts

@@ -36,6 +36,7 @@ export * from "./types.js";
 export type {
   EntitiesModule,
   EntityHandler,
+  EntityTypeRegistry,
   RealtimeEventType,
   RealtimeEvent,
   RealtimeCallback,
@@ -71,10 +72,14 @@ export type {
   CreateFileSignedUrlResult,
 } from "./modules/integrations.types.js";
 
-export type { FunctionsModule } from "./modules/functions.types.js";
+export type {
+  FunctionsModule,
+  FunctionNameRegistry,
+} from "./modules/functions.types.js";
 
 export type {
   AgentsModule,
+  AgentNameRegistry,
   AgentConversation,
   AgentMessage,
   AgentMessageReasoning,

src/modules/agents.types.ts

@@ -2,6 +2,37 @@ import { AxiosInstance } from "axios";
 import { RoomsSocket } from "../utils/socket-utils.js";
 import { ModelFilterParams } from "../types.js";
 
+/**
+ * Registry of agent names.
+ *
+ * This interface is designed to be augmented by generated type declaration files.
+ * When augmented, it enables autocomplete for agent names in methods like `createConversation`.
+ *
+ * @example
+ * ```typescript
+ * // In your generated types.d.ts file:
+ * declare module '@base44/sdk' {
+ *   interface AgentNameRegistry {
+ *     support_agent: true;
+ *     sales_bot: true;
+ *   }
+ * }
+ *
+ * // Then in your code:
+ * await base44.agents.createConversation({
+ *   agent_name: 'support_agent'  // ✅ Autocomplete shows: 'support_agent' | 'sales_bot'
+ * });
+ * ```
+ */
+export interface AgentNameRegistry {}
+
+/**
+ * Agent name type - uses registry keys if augmented, otherwise falls back to string.
+ */
+export type AgentName = keyof AgentNameRegistry extends never
+  ? string
+  : keyof AgentNameRegistry;
+
 /**
  * Reasoning information for an agent message.
  *
@@ -134,8 +165,8 @@ export interface AgentMessage {
  * Parameters for creating a new conversation.
  */
 export interface CreateConversationParams {
-  /** The name of the agent to create a conversation with. */
-  agent_name: string;
+  /** The name of the agent to create a conversation with. When AgentNameRegistry is augmented, provides autocomplete. */
+  agent_name: AgentName;
   /** Optional metadata to attach to the conversation. */
   metadata?: Record<string, any>;
 }
@@ -359,7 +390,7 @@ export interface AgentsModule {
    * Generates a URL that users can use to connect with the agent through WhatsApp.
    * The URL includes authentication if a token is available.
    *
-   * @param agentName - The name of the agent.
+   * @param agentName - The name of the agent. When AgentNameRegistry is augmented, provides autocomplete.
    * @returns WhatsApp connection URL.
    *
    * @example
@@ -370,5 +401,5 @@ export interface AgentsModule {
    * // User can open this URL to start a WhatsApp conversation
    * ```
    */
-  getWhatsAppConnectURL(agentName: string): string;
+  getWhatsAppConnectURL(agentName: AgentName): string;
 }

src/modules/entities.types.ts

@@ -80,6 +80,31 @@ export type SortField<T> =
   | `+${keyof T & string}`
   | `-${keyof T & string}`;
 
+/**
+ * Registry mapping entity names to their TypeScript types.
+ *
+ * This interface is designed to be augmented by generated type declaration files.
+ * When augmented, it enables type-safe entity access throughout your application.
+ *
+ * @example
+ * ```typescript
+ * // In your generated types.d.ts file:
+ * declare module '@base44/sdk' {
+ *   interface EntityTypeRegistry {
+ *     Task: { title: string; completed: boolean };
+ *     User: { email: string; name: string };
+ *   }
+ * }
+ *
+ * // Then in your code:
+ * const task = await base44.entities.Task.create({
+ *   title: 'Buy groceries',  // ✅ Type-checked
+ *   completed: false
+ * });
+ * ```
+ */
+export interface EntityTypeRegistry {}
+
 /**
  * Entity handler providing CRUD operations for a specific entity type.
  *
@@ -382,6 +407,22 @@ export interface EntityHandler<T = any> {
   subscribe(callback: RealtimeCallback<T>): () => void;
 }
 
+/**
+ * Typed entities module - maps registry keys to typed handlers.
+ * Only used when EntityTypeRegistry is augmented.
+ */
+type TypedEntitiesModule = {
+  [K in keyof EntityTypeRegistry]: EntityHandler<EntityTypeRegistry[K]>;
+};
+
+/**
+ * Dynamic entities module - allows any entity name with untyped handler.
+ * Used as fallback and for entities not in the registry.
+ */
+type DynamicEntitiesModule = {
+  [entityName: string]: EntityHandler<any>;
+};
+
 /**
  * Entities module for managing app data.
  *
@@ -391,6 +432,9 @@ export interface EntityHandler<T = any> {
  * Entities are accessed dynamically using the pattern:
  * `base44.entities.EntityName.method()`
  *
+ * When {@link EntityTypeRegistry} is augmented (via generated types.d.ts),
+ * entity access becomes type-safe with autocomplete and type checking.
+ *
  * This module is available to use with a client in all three authentication modes:
  *
  * - **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.
@@ -415,18 +459,4 @@ export interface EntityHandler<T = any> {
  * const allUsers = await base44.asServiceRole.entities.User.list();
  * ```
  */
-export interface EntitiesModule {
-  /**
-   * Access any entity by name.
-   *
-   * Use this to access entities defined in the app.
-   *
-   * @example
-   * ```typescript
-   * // Access entities dynamically
-   * base44.entities.MyEntity
-   * base44.entities.AnotherEntity
-   * ```
-   */
-  [entityName: string]: EntityHandler<any>;
-}
+export type EntitiesModule = TypedEntitiesModule & DynamicEntitiesModule;

src/modules/functions.types.ts

@@ -1,3 +1,34 @@
+/**
+ * Registry of function names.
+ *
+ * This interface is designed to be augmented by generated type declaration files.
+ * When augmented, it enables autocomplete for function names in the `invoke` method.
+ *
+ * @example
+ * ```typescript
+ * // In your generated types.d.ts file:
+ * declare module '@base44/sdk' {
+ *   interface FunctionNameRegistry {
+ *     calculateTotal: true;
+ *     processImage: true;
+ *   }
+ * }
+ *
+ * // Then in your code:
+ * await base44.functions.invoke('calculateTotal', { ... });
+ * //                            ^^^^^^^^^^^^^^^^
+ * //                            ✅ Autocomplete shows: 'calculateTotal' | 'processImage'
+ * ```
+ */
+export interface FunctionNameRegistry {}
+
+/**
+ * Function name type - uses registry keys if augmented, otherwise falls back to string.
+ */
+export type FunctionName = keyof FunctionNameRegistry extends never
+  ? string
+  : keyof FunctionNameRegistry;
+
 /**
  * Functions module for invoking custom backend functions.
  *
@@ -17,7 +48,7 @@ export interface FunctionsModule {
    * the result. If any parameter is a `File` object, the request will automatically be
    * sent as `multipart/form-data`. Otherwise, it will be sent as JSON.
    *
-   * @param functionName - The name of the function to invoke.
+   * @param functionName - The name of the function to invoke. When FunctionNameRegistry is augmented, provides autocomplete.
    * @param data - An object containing named parameters for the function.
    * @returns Promise resolving to the function's response. The `data` property contains the data returned by the function, if there is any.
    *
@@ -46,5 +77,5 @@ export interface FunctionsModule {
    * };
    * ```
    */
-  invoke(functionName: string, data: Record<string, any>): Promise<any>;
+  invoke(functionName: FunctionName, data?: Record<string, any>): Promise<any>;
 }