@base44/sdk 0.8.18 → 0.8.20

package/dist/modules/entities.types.d.ts

@@ -4,12 +4,14 @@
 export type RealtimeEventType = "create" | "update" | "delete";
 /**
  * Payload received when a realtime event occurs.
+ *
+ * @typeParam T - The entity type for the data field. Defaults to `any`.
  */
-export interface RealtimeEvent {
+export interface RealtimeEvent<T = any> {
     /** The type of change that occurred */
     type: RealtimeEventType;
     /** The entity data */
-    data: any;
+    data: T;
     /** The unique identifier of the affected entity */
     id: string;
     /** ISO 8601 timestamp of when the event occurred */
@@ -17,29 +19,127 @@ export interface RealtimeEvent {
 }
 /**
  * Callback function invoked when a realtime event occurs.
+ *
+ * @typeParam T - The entity type for the event data. Defaults to `any`.
+ */
+export type RealtimeCallback<T = any> = (event: RealtimeEvent<T>) => void;
+/**
+ * Result returned when deleting a single entity.
+ */
+export interface DeleteResult {
+    /** Whether the deletion was successful. */
+    success: boolean;
+}
+/**
+ * Result returned when deleting multiple entities.
+ */
+export interface DeleteManyResult {
+    /** Whether the deletion was successful. */
+    success: boolean;
+    /** Number of entities that were deleted. */
+    deleted: number;
+}
+/**
+ * Result returned when importing entities from a file.
+ *
+ * @typeParam T - The entity type for imported records. Defaults to `any`.
+ */
+export interface ImportResult<T = any> {
+    /** Status of the import operation. */
+    status: "success" | "error";
+    /** Details message, e.g., "Successfully imported 3 entities with RLS enforcement". */
+    details: string | null;
+    /** Array of created entity objects when successful, or null on error. */
+    output: T[] | null;
+}
+/**
+ * Sort field type for entity queries.
+ *
+ * Accepts any field name from the entity type with an optional prefix:
+ * - `'+'` prefix or no prefix: ascending sort
+ * - `'-'` prefix: descending sort
+ *
+ * @typeParam T - The entity type to derive sortable fields from.
+ *
+ * @example
+ * ```typescript
+ * // Specify sort direction by prefixing field names with + or -
+ * // Ascending sort
+ * 'created_date'
+ * '+created_date'
+ *
+ * // Descending sort
+ * '-created_date'
+ * ```
  */
-export type RealtimeCallback = (event: RealtimeEvent) => void;
+export type SortField<T> = (keyof T & string) | `+${keyof T & string}` | `-${keyof T & string}`;
 /**
- * Function returned from subscribe, call it to unsubscribe.
+ * Fields added by the server to every entity record, such as `id`, `created_date`, `updated_date`, and `created_by`.
  */
-export type Subscription = () => void;
+interface ServerEntityFields {
+    /** Unique identifier of the record */
+    id: string;
+    /** ISO 8601 timestamp when the record was created */
+    created_date: string;
+    /** ISO 8601 timestamp when the record was last updated */
+    updated_date: string;
+    /** Email of the user who created the record (may be hidden in some responses) */
+    created_by?: string | null;
+    /** ID of the user who created the record */
+    created_by_id?: string | null;
+    /** Whether the record is sample/seed data */
+    is_sample?: boolean;
+}
+/**
+ * Registry mapping entity names to their TypeScript types. The [`types generate`](/developers/references/cli/commands/types-generate) command fills this registry, then [`EntityRecord`](#entityrecord) adds server fields.
+ */
+export interface EntityTypeRegistry {
+}
+/**
+ * Combines the [`EntityTypeRegistry`](#entitytyperegistry) schemas with server fields like `id`, `created_date`, and `updated_date` to give the complete record type for each entity. Use this when you need to type variables holding entity data.
+ *
+ * @example
+ * ```typescript
+ * // Using EntityRecord to get the complete type for an entity
+ * // Combine your schema with server fields (id, created_date, etc.)
+ * type TaskRecord = EntityRecord['Task'];
+ *
+ * const task: TaskRecord = await base44.entities.Task.create({
+ *   title: 'My task',
+ *   status: 'pending'
+ * });
+ *
+ * // Task now includes both your fields and server fields:
+ * console.log(task.id);           // Server field
+ * console.log(task.created_date); // Server field
+ * console.log(task.title);        // Your field
+ * ```
+ */
+export type EntityRecord = {
+    [K in keyof EntityTypeRegistry]: EntityTypeRegistry[K] & ServerEntityFields;
+};
 /**
  * Entity handler providing CRUD operations for a specific entity type.
  *
  * Each entity in the app gets a handler with these methods for managing data.
+ *
+ * @typeParam T - The entity type. Defaults to `any` for backward compatibility.
  */
-export interface EntityHandler {
+export interface EntityHandler<T = any> {
     /**
      * Lists records with optional pagination and sorting.
      *
      * Retrieves all records of this type with support for sorting,
      * pagination, and field selection.
      *
+     * **Note:** The maximum limit is 5,000 items per request.
+     *
+     * @typeParam K - The fields to include in the response. Defaults to all fields.
      * @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
      * @param limit - Maximum number of results to return. Defaults to `50`.
      * @param skip - Number of results to skip for pagination. Defaults to `0`.
      * @param fields - Array of field names to include in the response. Defaults to all fields.
-     * @returns Promise resolving to an array of records.
+     * @returns Promise resolving to an array of records with selected fields.
      *
      * @example
      * ```typescript
@@ -66,13 +166,16 @@ export interface EntityHandler {
      * const fields = await base44.entities.MyEntity.list('-created_date', 10, 0, ['name', 'status']);
      * ```
      */
-    list(sort?: string, limit?: number, skip?: number, fields?: string[]): Promise<any>;
+    list<K extends keyof T = keyof T>(sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
     /**
      * Filters records based on a query.
      *
      * Retrieves records that match specific criteria with support for
      * sorting, pagination, and field selection.
      *
+     * **Note:** The maximum limit is 5,000 items per request.
+     *
+     * @typeParam K - The fields to include in the response. Defaults to all fields.
      * @param query - Query object with field-value pairs. Each key should be a field name
      * from your entity schema, and each value is the criteria to match. Records matching all
      * specified criteria are returned. Field names are case-sensitive.
@@ -80,7 +183,7 @@ export interface EntityHandler {
      * @param limit - Maximum number of results to return. Defaults to `50`.
      * @param skip - Number of results to skip for pagination. Defaults to `0`.
      * @param fields - Array of field names to include in the response. Defaults to all fields.
-     * @returns Promise resolving to an array of filtered records.
+     * @returns Promise resolving to an array of filtered records with selected fields.
      *
      * @example
      * ```typescript
@@ -122,7 +225,7 @@ export interface EntityHandler {
      * );
      * ```
      */
-    filter(query: Record<string, any>, sort?: string, limit?: number, skip?: number, fields?: string[]): Promise<any>;
+    filter<K extends keyof T = keyof T>(query: Partial<T>, sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
     /**
      * Gets a single record by ID.
      *
@@ -138,7 +241,7 @@ export interface EntityHandler {
      * console.log(record.name);
      * ```
      */
-    get(id: string): Promise<any>;
+    get(id: string): Promise<T>;
     /**
      * Creates a new record.
      *
@@ -158,7 +261,7 @@ export interface EntityHandler {
      * console.log('Created record with ID:', newRecord.id);
      * ```
      */
-    create(data: Record<string, any>): Promise<any>;
+    create(data: Partial<T>): Promise<T>;
     /**
      * Updates an existing record.
      *
@@ -187,7 +290,7 @@ export interface EntityHandler {
      * });
      * ```
      */
-    update(id: string, data: Record<string, any>): Promise<any>;
+    update(id: string, data: Partial<T>): Promise<T>;
     /**
      * Deletes a single record by ID.
      *
@@ -200,10 +303,10 @@ export interface EntityHandler {
      * ```typescript
      * // Delete a record
      * const result = await base44.entities.MyEntity.delete('entity-123');
-     * console.log('Deleted:', result);
+     * console.log('Deleted:', result.success);
      * ```
      */
-    delete(id: string): Promise<any>;
+    delete(id: string): Promise<DeleteResult>;
     /**
      * Deletes multiple records matching a query.
      *
@@ -221,10 +324,10 @@ export interface EntityHandler {
      *   status: 'completed',
      *   priority: 'low'
      * });
-     * console.log('Deleted:', result);
+     * console.log('Deleted:', result.deleted);
      * ```
      */
-    deleteMany(query: Record<string, any>): Promise<any>;
+    deleteMany(query: Partial<T>): Promise<DeleteManyResult>;
     /**
      * Creates multiple records in a single request.
      *
@@ -244,7 +347,7 @@ export interface EntityHandler {
      * ]);
      * ```
      */
-    bulkCreate(data: Record<string, any>[]): Promise<any>;
+    bulkCreate(data: Partial<T>[]): Promise<T[]>;
     /**
      * Imports records from a file.
      *
@@ -252,7 +355,7 @@ export interface EntityHandler {
      * The file format should match your entity structure. Requires a browser environment and can't be used in the backend.
      *
      * @param file - File object to import.
-     * @returns Promise resolving to the import result.
+     * @returns Promise resolving to the import result containing status, details, and created records.
      *
      * @example
      * ```typescript
@@ -261,19 +364,27 @@ export interface EntityHandler {
      *   const file = event.target.files?.[0];
      *   if (file) {
      *     const result = await base44.entities.MyEntity.importEntities(file);
-     *     console.log(`Imported ${result.count} records`);
+     *     if (result.status === 'success' && result.output) {
+     *       console.log(`Imported ${result.output.length} records`);
+     *     }
      *   }
      * };
      * ```
      */
-    importEntities(file: File): Promise<any>;
+    importEntities(file: File): Promise<ImportResult<T>>;
     /**
      * Subscribes to realtime updates for all records of this entity type.
      *
-     * Receives notifications whenever any record is created, updated, or deleted.
+     * Establishes a WebSocket connection to receive instant updates when any
+     * record is created, updated, or deleted. Returns an unsubscribe function
+     * to clean up the connection.
      *
-     * @param callback - Function called when an entity changes.
-     * @returns Unsubscribe function to stop listening.
+     * @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.
+     * - `id`: The unique identifier of the affected entity.
+     * - `timestamp`: ISO 8601 timestamp of when the event occurred.
+     * @returns Unsubscribe function to stop receiving updates.
      *
      * @example
      * ```typescript
@@ -282,12 +393,24 @@ export interface EntityHandler {
      *   console.log(`Task ${event.id} was ${event.type}d:`, event.data);
      * });
      *
-     * // Later, unsubscribe
+     * // Later, clean up the subscription
      * unsubscribe();
      * ```
      */
-    subscribe(callback: RealtimeCallback): Subscription;
+    subscribe(callback: RealtimeCallback<T>): () => void;
 }
+/**
+ * Typed entities module - maps registry keys to typed handlers (full record type).
+ */
+type TypedEntitiesModule = {
+    [K in keyof EntityTypeRegistry]: EntityHandler<EntityRecord[K]>;
+};
+/**
+ * Dynamic entities module - allows any entity name with untyped handler.
+ */
+type DynamicEntitiesModule = {
+    [entityName: string]: EntityHandler<any>;
+};
 /**
  * Entities module for managing app data.
  *
@@ -297,17 +420,29 @@ export interface EntityHandler {
  * Entities are accessed dynamically using the pattern:
  * `base44.entities.EntityName.method()`
  *
- * This module is available to use with a client in all three authentication modes:
+ * This module is available to use with a client in all 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.
  * - **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.
  *
  * Regular users can only read and update their own user record. With service role authentication, you can read, update, and delete any user. You can't create users using the entities module. Instead, use the functions of the {@link AuthModule | auth module} to invite or register new users.
  *
+ * ## Generated Types
+ *
+ * If you're working in a TypeScript project, you can generate types from your entity schemas to get autocomplete and type checking on all entity methods. See the [Dynamic Types](/developers/references/sdk/getting-started/dynamic-types) guide to get started.
+ *
  * @example
  * ```typescript
  * // Get all records from the MyEntity entity
@@ -321,18 +456,5 @@ export interface EntityHandler {
  * 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;
-}
+export type EntitiesModule = TypedEntitiesModule & DynamicEntitiesModule;
+export {};

package/dist/modules/functions.types.d.ts

@@ -1,12 +1,34 @@
+/**
+ * Registry of function names. The [`types generate`](/developers/references/cli/commands/types-generate) command fills this registry, then [`FunctionName`](#functionname) resolves to a union of the keys.
+ */
+export interface FunctionNameRegistry {
+}
+/**
+ * Union of all function names from the [`FunctionNameRegistry`](#functionnameregistry). Defaults to `string` when no types have been generated.
+ *
+ * @example
+ * ```typescript
+ * // Using generated function name types
+ * // With generated types, you get autocomplete on function names
+ * await base44.functions.invoke('calculateTotal', { items: ['item1', 'item2'] });
+ * ```
+ */
+export type FunctionName = keyof FunctionNameRegistry extends never ? string : keyof FunctionNameRegistry;
 /**
  * Functions module for invoking custom backend functions.
  *
  * 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.
  * - **Service role authentication** (`base44.asServiceRole.functions`): Functions are invoked with elevated admin-level permissions. The function code receives a request with admin authentication context.
+ *
+ * ## Generated Types
+ *
+ * If you're working in a TypeScript project, you can generate types from your backend functions to get autocomplete on function names when calling `invoke()`. See the [Dynamic Types](/developers/references/sdk/getting-started/dynamic-types) guide to get started.
  */
 export interface FunctionsModule {
     /**
@@ -26,7 +48,6 @@ export interface FunctionsModule {
      * // Basic function call
      * const result = await base44.functions.invoke('calculateTotal', {
      *   items: ['item1', 'item2'],
-     *   discount: 0.1
      * });
      * console.log(result.data.total);
      * ```
@@ -46,5 +67,5 @@ export interface FunctionsModule {
      * };
      * ```
      */
-    invoke(functionName: string, data: Record<string, any>): Promise<any>;
+    invoke(functionName: FunctionName, data?: Record<string, any>): Promise<any>;
 }

package/dist/modules/integrations.types.d.ts

@@ -12,18 +12,25 @@ export type IntegrationEndpointFunction = (data: Record<string, any>) => 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;
@@ -320,43 +327,55 @@ export interface CoreIntegrations {
     CreateFileSignedUrl(params: CreateFileSignedUrlParams): Promise<CreateFileSignedUrlResult>;
 }
 /**
- * Integrations module for calling integration endpoints.
+ * Integrations module for calling integration methods.
+ *
+ * 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:
  *
- * This module provides access to integration endpoints for interacting with external
- * services. Integrations are organized into packages. Base44 provides built-in integrations
- * in the `Core` package.
+ * - **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:
+ *   ```
+ *   base44.integrations.Core.FunctionName(params)
+ *   ```
  *
- * Unlike the connectors module that gives you raw OAuth tokens, integrations provide
- * pre-built functions that Base44 executes on your behalf.
+ * - **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)
+ *   ```
  *
- * Integration endpoints are accessed dynamically using the pattern:
- * `base44.integrations.PackageName.EndpointName(params)`
+ *   <Info>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).</Info>
+ *
+ * ## Authentication Modes
  *
  * This module is available to use with a client in all authentication modes:
  *
- * - **Anonymous or User authentication** (`base44.integrations`): Integration endpoints are invoked with the current user's permissions. Anonymous users invoke endpoints without authentication, while authenticated users invoke endpoints with their authentication context.
- * - **Service role authentication** (`base44.asServiceRole.integrations`): Integration endpoints are invoked with elevated admin-level permissions. The endpoints execute with admin authentication context.
+ * - **Anonymous or User authentication** (`base44.integrations`): Integration methods are invoked with the current user's permissions. Anonymous users invoke methods without authentication, while authenticated users invoke methods with their authentication context.
+ * - **Service role authentication** (`base44.asServiceRole.integrations`): Integration methods are invoked with elevated admin-level permissions. The methods execute with admin authentication context.
  */
 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 workspace-level API integrations.
-     *
-     * Allows calling external APIs that workspace admins have configured
-     * by importing OpenAPI specifications.
+     * Workspace integrations module for calling pre-configured external APIs.
      *
      * @example
      * ```typescript
-     * const response = await base44.integrations.custom.call(
-     *   "github",        // integration slug
-     *   "listIssues",    // operation ID
-     *   {
-     *     pathParams: { owner: "myorg", repo: "myrepo" },
-     *     queryParams: { state: "open" }
-     *   }
+     * const result = await base44.integrations.custom.call(
+     *   'github',
+     *   'get:/repos/{owner}/{repo}',
+     *   { pathParams: { owner: 'myorg', repo: 'myrepo' } }
      * );
      * ```
      */
@@ -365,8 +384,25 @@ export type IntegrationsModule = {
     /**
      * 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;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/sdk",
-  "version": "0.8.18",
+  "version": "0.8.20",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,8 @@
     "docs": "typedoc",
     "prepublishOnly": "npm run build",
     "create-docs": "npm run create-docs:generate && npm run create-docs:process",
-    "push-docs": "node scripts/mintlify-post-processing/push-to-docs-repo.js",
+    "create-docs-local": "npm run create-docs && npm run copy-docs-local",
+    "copy-docs-local": "node scripts/mintlify-post-processing/copy-to-local-docs.js",
     "create-docs:generate": "typedoc",
     "create-docs:process": "node scripts/mintlify-post-processing/file-processing/file-processing.js"
   },