@base44-preview/sdk 0.8.48-pr.287.fd215cb → 0.8.48-pr.289.b9ea964

package/dist/actor.d.ts

@@ -25,8 +25,8 @@ export interface Storage {
     get<T>(key: string): Promise<T | undefined>;
     put(key: string, value: unknown): Promise<void>;
     delete(key: string): Promise<boolean>;
-    /** Wipe the room's entire persisted storage (match-end cleanup). Safe: a
-     *  later rejoin re-bootstraps exactly like a brand-new room. */
+    /** Wipe the session's entire persisted storage. A later connection starts
+     *  with the same empty storage as a new session. */
     deleteAll(): Promise<void>;
 }
 /**

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from
 export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
 export type { Base44Client, CreateClientAnalyticsConfig, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
 export * from "./types.js";
-export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityAggregateResult, EntityAggregateSpec, EntityDateBucketUnit, EntityDistinctOptions, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityListOptions, EntityPage, EntityRecord, EntityTypeRegistry, EntityUpsertOptions, EntityUpsertResult, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
+export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
 export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
 export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
 export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";

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

@@ -1,9 +1,10 @@
 /**
- * Extend this interface to add typed `subscribe` callbacks and `send` payloads
- * for your deployed Actors.
+ * Maps actor names to their incoming and outgoing message types.
  *
- * This is separate from {@link ActorNameRegistry} (which is auto-generated
- * by `base44 types generate`), so there are no conflicts.
+ * Extend this interface through module augmentation when you want typed actor
+ * messages without generating types with the CLI. For each actor, `toServer`
+ * defines incoming messages that a client sends to the actor. `toClient` defines
+ * outgoing messages that the actor sends to connected clients.
  *
  * @example
  * ```typescript
@@ -20,8 +21,10 @@
 export interface ActorRegistry {
 }
 /**
- * Auto-populated by `base44 types generate` with the names of your deployed actors.
- * Do not edit this interface manually — use {@link ActorRegistry} for message types.
+ * Lists actor names when your project includes types generated by the CLI.
+ *
+ * The generated names provide autocomplete for deployed actors. To define
+ * incoming and outgoing message types manually, augment {@link ActorRegistry}.
  */
 export interface ActorNameRegistry {
 }
@@ -32,71 +35,163 @@ type ToClientFor<N extends string> = N extends keyof ActorRegistry ? ActorRegist
 type ToServerFor<N extends string> = N extends keyof ActorRegistry ? ActorRegistry[N] extends {
     toServer: infer O;
 } ? O : unknown : unknown;
-/** Options for {@link ActorRef.connect}. */
+/**
+ * Options for {@link ActorRef.connect}.
+ */
 export interface ActorConnectOptions {
     /**
-     * The connection id — becomes the actor's `conn.id`. Supply a stable value
-     * (e.g. persisted per tab) so a reconnect reuses the same server-side
-     * identity; omit for an auto-generated per-connection id.
+     * Connection ID that the actor receives as `conn.id`.
+     *
+     * Specify a stable value, such as a value persisted per client, so
+     * reconnections from that client reuse the same connection ID. Omit this property
+     * to generate an ID.
      */
     id?: string;
 }
-/** Handle for one listener registered via {@link Connection.subscribe}. */
+/**
+ * Represents an outgoing-message listener registered with
+ * {@link Connection.subscribe}.
+ */
 export interface ActorSubscription {
-    /** Remove this listener; other listeners and the socket stay live. */
+    /**
+     * Removes this listener. Other listeners and the socket stay open.
+     *
+     * @example
+     * ```typescript
+     * const sub = conn.subscribe((msg) => console.log(msg));
+     * sub.unsubscribe();
+     * ```
+     */
     unsubscribe(): void;
 }
 /**
- * A live connection to an actor instance, returned by {@link ActorRef.connect}.
- * `subscribe`/`send` are always valid — you only get a `Connection` once the
- * socket has been opened, so there's no pre-connect state to guard against.
+ * Represents a client's WebSocket connection to an actor session.
+ *
+ * {@link ActorRef.connect} returns this object while the socket connects.
+ * The socket buffers messages sent during connection setup until it opens.
  */
 export interface Connection<N extends string = string> {
-    /** The connection id (the value the actor sees as `conn.id`). */
+    /** Connection ID that the actor receives as `conn.id`. */
     readonly id: string;
-    /** Register a message listener. Multiple are allowed; returns a per-listener unsubscribe. */
+    /**
+     * Registers a listener for outgoing messages from the actor.
+     *
+     * You can register multiple listeners on the same connection.
+     *
+     * @param callback - Called with each outgoing message sent to this connection.
+     * @returns A handle you can use to remove this listener without closing the socket.
+     *
+     * @example
+     * ```typescript
+     * const conn = base44.actors.Chat("session-1").connect();
+     * const sub = conn.subscribe((msg) => {
+     *   if (msg.type === "message") console.log(msg.text);
+     * });
+     * ```
+     */
     subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
-    /** Send a message. Buffered by the socket until it's open; dropped after
-     * {@link close}. */
+    /**
+     * Sends an incoming message to the actor.
+     *
+     * The socket buffers messages until it opens. After {@link close}, the socket
+     * drops further sends.
+     *
+     * @param data - Incoming message to send. Typed through {@link ActorRegistry} when configured.
+     *
+     * @example
+     * ```typescript
+     * conn.send({ type: "message", text: "Hello" });
+     * ```
+     */
     send(data: ToServerFor<N>): void;
     /**
-     * Tear down the socket, heartbeat, and all listeners. Safe to call more
-     * than once. A connection also closes itself when it fails permanently —
-     * see {@link ActorRef.connect}.
+     * Closes the connection and removes all listeners.
+     *
+     * Safe to call more than once. A connection also closes itself when it fails
+     * permanently. See {@link ActorRef.connect} for how to open a fresh connection.
+     *
+     * @example
+     * ```typescript
+     * conn.close();
+     * ```
      */
     close(): void;
 }
 /**
- * A handle to one actor instance — `base44.actors.MyActor(id)`. Call
- * {@link connect} to open the socket and get a {@link Connection}.
+ * Represents an actor session selected by actor name and session ID.
+ *
+ * Call {@link connect} to open the WebSocket and get a {@link Connection}.
  */
 export interface ActorRef<N extends string = string> {
     /**
-     * Open the WebSocket and return the {@link Connection}. Idempotent while the
-     * connection is open.
+     * Creates or returns the {@link Connection} for this session.
+     *
+     * Repeated calls return the same connection until it closes. After a permanent
+     * failure, such as a missing actor or denied connection, fix the cause and call
+     * `connect()` again. Add subscriptions to the new connection.
      *
-     * A connection that fails permanently (for example, the actor doesn't exist
-     * or the caller isn't allowed to connect) closes itself and reports the
-     * error to the client's `onError` handler. Call `connect()` again after
-     * fixing the cause to get a fresh {@link Connection}, and re-subscribe.
+     * @param options - Optional connection settings, such as a stable connection ID.
+     * @returns The {@link Connection} for this actor session.
+     *
+     * @example
+     * ```typescript
+     * const conn = base44.actors.Chat("session-1").connect({ id: "tab-abc" });
+     * conn.subscribe((msg) => console.log(msg));
+     * ```
      */
     connect(options?: ActorConnectOptions): Connection<N>;
 }
 /**
- * Client for a single named Actor — call it with an instance id to get an
- * {@link ActorRef}. Typed automatically when the actor is registered in
- * {@link ActorRegistry}.
+ * Selects a session for a named actor.
+ *
+ * Typed automatically when the actor is registered in {@link ActorRegistry} or
+ * {@link ActorNameRegistry}.
  */
 export interface ActorClient<N extends string = string> {
+    /**
+     * Gets a reference to an actor session.
+     *
+     * Clients that specify the same actor name and session ID join the same session.
+     *
+     * @param instanceId - Session ID that identifies which session to connect to.
+     * @returns A reference to the actor session.
+     *
+     * @example
+     * ```typescript
+     * const session = base44.actors.Chat("lobby-1");
+     * const conn = session.connect();
+     * ```
+     */
     (instanceId: string): ActorRef<N>;
 }
 /**
- * The actors module provides access to Cloudflare Durable Object-backed
- * Actors deployed by the Base44 platform.
+ * Provides access to actors and their shared, live sessions.
+ *
+ * Select an actor by name and session ID, then connect a client to the
+ * session. Clients in the same session can exchange realtime messages through the
+ * actor. The client works in the browser and in Node.
+ *
+ * ## Connection flow
+ *
+ * - Connect to a session with `base44.actors.<ActorName>(sessionId).connect()`.
+ * - Subscribe to outgoing messages with {@link Connection.subscribe}.
+ * - Send incoming messages with {@link Connection.send}.
+ * - Close the connection with {@link Connection.close}.
  *
+ * See [Actors Overview](/developers/backend/resources/actors/overview)
+ * for actor concepts and terminology, and the [Actor Class Reference](/developers/backend/resources/actors/reference)
+ * for the backend class API.
+ *
+ * ## Authentication modes
+ *
+ * This module is available in anonymous or user authentication mode
+ * (`base44.actors`). It isn't available with service role authentication. Apps that
+ * require login can reject anonymous connections in the actor's `handleConnect()` method.
+ *
+ * @example
  * ```typescript
- * const conn = base44.actors.MyActor("room-1").connect();
- * const sub = conn.subscribe((msg) => console.log(msg)); // typed via ActorRegistry
+ * const conn = base44.actors.Chat("session-1").connect({ id: "tab-1" });
+ * const sub = conn.subscribe((msg) => console.log(msg));
  * conn.send({ type: "message", text: "hi" });
  * sub.unsubscribe();
  * conn.close();

package/dist/modules/entities.js

@@ -41,10 +41,6 @@ function parseRealtimeMessage(dataStr) {
         return null;
     }
 }
-const DEFAULT_PAGE_LIMIT = 100;
-function isPageOptions(value) {
-    return typeof value === "object" && value !== null;
-}
 /**
  * Creates a handler for a specific entity.
  *
@@ -57,51 +53,34 @@ function isPageOptions(value) {
  */
 function createEntityHandler(axios, appId, entityName, getSocket) {
     const baseURL = `/apps/${appId}/entities/${entityName}`;
-    const fieldsParam = (fields) => Array.isArray(fields) ? fields.join(",") : fields;
-    // GET /{entity}: the array form shared by list() and filter()
-    const readArray = (sort, limit, skip, fields, query) => {
-        const params = {};
-        if (query)
-            params.q = JSON.stringify(query);
-        if (sort)
-            params.sort = sort;
-        if (limit)
-            params.limit = limit;
-        if (skip)
-            params.skip = skip;
-        if (fields)
-            params.fields = fieldsParam(fields);
-        return axios.get(baseURL, { params });
-    };
-    // GET /{entity}/v2/list: one cursor page of records or distinct values, shared by list(options) and filter(query, options)
-    const readPage = (options, query) => {
-        const params = {};
-        if (query)
-            params.q = JSON.stringify(query);
-        params.limit = options.limit || DEFAULT_PAGE_LIMIT;
-        if (options.cursor)
-            params.cursor = options.cursor;
-        if ("distinct" in options) {
-            params.distinct = options.distinct;
-        }
-        else {
-            if (options.sort)
-                params.sort = options.sort;
-            if (options.fields)
-                params.fields = fieldsParam(options.fields);
-        }
-        return axios.get(`${baseURL}/v2/list`, { params });
-    };
     return {
-        // list(sort, limit, skip, fields) returns an array; list(options) returns one cursor page.
-        async list(...args) {
-            const [sort, limit, skip, fields] = args;
-            return isPageOptions(sort) ? readPage(sort) : readArray(sort, limit, skip, fields);
-        },
-        // filter(query, sort, limit, skip, fields) returns an array; filter(query, options) returns one cursor page.
-        async filter(query, ...args) {
-            const [sort, limit, skip, fields] = args;
-            return isPageOptions(sort) ? readPage(sort, query) : readArray(sort, limit, skip, fields, query);
+        // List entities with optional pagination and sorting
+        async list(sort, limit, skip, fields) {
+            const params = {};
+            if (sort)
+                params.sort = sort;
+            if (limit)
+                params.limit = limit;
+            if (skip)
+                params.skip = skip;
+            if (fields)
+                params.fields = Array.isArray(fields) ? fields.join(",") : fields;
+            return axios.get(baseURL, { params });
+        },
+        // Filter entities based on query
+        async filter(query, sort, limit, skip, fields) {
+            const params = {
+                q: JSON.stringify(query),
+            };
+            if (sort)
+                params.sort = sort;
+            if (limit)
+                params.limit = limit;
+            if (skip)
+                params.skip = skip;
+            if (fields)
+                params.fields = Array.isArray(fields) ? fields.join(",") : fields;
+            return axios.get(baseURL, { params });
         },
         // Get entity by ID
         async get(id) {
@@ -131,22 +110,6 @@ function createEntityHandler(axios, appId, entityName, getSocket) {
         async updateMany(query, data) {
             return axios.patch(`${baseURL}/update-many`, { query, data });
         },
-        // Count entities matching a query
-        async count(query) {
-            const params = {};
-            if (query)
-                params.q = JSON.stringify(query);
-            const result = await axios.get(`${baseURL}/count`, { params });
-            return result.count;
-        },
-        // Server-side group-by aggregation
-        async aggregate(spec) {
-            return axios.post(`${baseURL}/aggregate`, spec);
-        },
-        // Create or update by a natural key
-        async upsert(records, options) {
-            return axios.post(`${baseURL}/upsert`, { records, key: options.key });
-        },
         // Update multiple entities by ID, each with its own update data
         async bulkUpdate(data) {
             return axios.put(`${baseURL}/bulk`, data);

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

@@ -50,130 +50,6 @@ export interface UpdateManyResult {
     /** Whether there are more entities matching the query that were not updated in this batch. When `true`, call `updateMany` again with the same query to update the next batch. */
     has_more: boolean;
 }
-/**
- * Options object accepted by {@linkcode EntityHandler.list | list()} and
- * {@linkcode EntityHandler.filter | filter()} to read one cursor page.
- *
- * @typeParam T - Entity record type.
- * @typeParam K - The fields to include in each record.
- */
-export interface EntityListOptions<T, K extends keyof T = keyof T> {
-    /** Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`. */
-    sort?: SortField<T>;
-    /** Maximum number of records per page, up to 5,000. Defaults to 100. */
-    limit?: number;
-    /**
-     * `next_cursor` from the previous page. Omit or pass `null` for the first page.
-     *
-     * The token carries the query, sort and fields of the walk, so a later page needs only
-     * `cursor` and `limit`. Passing a different query, sort or fields with a cursor is an error.
-     */
-    cursor?: string | null;
-    /** Array of field names to include in each record. Defaults to all fields. */
-    fields?: K[];
-}
-/**
- * Options object accepted by {@linkcode EntityHandler.list | list()} and
- * {@linkcode EntityHandler.filter | filter()} to read the distinct values of one field
- * instead of records.
- *
- * @typeParam T - Entity record type.
- * @typeParam K - The field whose distinct values to read.
- */
-export interface EntityDistinctOptions<T, K extends keyof T = keyof T> {
-    /** Field whose distinct values to return, in ascending order. Array fields contribute each element. */
-    distinct: K;
-    /** Maximum number of values per page, up to 1,000. Defaults to 100. */
-    limit?: number;
-    /** `next_cursor` from the previous page. Omit or pass `null` for the first page. The token carries the query and field. */
-    cursor?: string | null;
-}
-/**
- * One page of records, returned by {@linkcode EntityHandler.list | list()} and
- * {@linkcode EntityHandler.filter | filter()} when called with an options object.
- *
- * @typeParam T - Record type of the items.
- */
-export interface EntityPage<T> {
-    /** The page's records in the requested sort order, or the distinct values in ascending order. */
-    items: T[];
-    /** Pass as `cursor` to get the next page. `null` on the last page. */
-    next_cursor: string | null;
-    /** Whether records remain after this page. */
-    has_more: boolean;
-}
-/**
- * Time unit for {@linkcode EntityAggregateSpec.dateBucket | dateBucket}.
- */
-export type EntityDateBucketUnit = "day" | "week" | "month" | "year";
-/**
- * Describes what {@linkcode EntityHandler.aggregate | aggregate()} computes.
- *
- * Name the fields to group by and the measures to compute; the server does the work and
- * returns one row per group. Field names are the entity's own field names.
- *
- * @typeParam T - Entity record type.
- */
-export interface EntityAggregateSpec<T> {
-    /** Filter applied before grouping, in the same form {@linkcode EntityHandler.filter | filter()} accepts. Defaults to all records. */
-    query?: EntityFilterQuery<T>;
-    /** Field, or up to four fields, to group by. Omit to get one total row. */
-    groupBy?: (keyof T & string) | (keyof T & string)[];
-    /** Group by a time bucket of a date field. `created_date` and `updated_date` support every unit; date fields of your schema support `day`, `month` and `year`. */
-    dateBucket?: {
-        field: keyof T & string;
-        unit: EntityDateBucketUnit;
-    };
-    /** Whether to include the number of records per group as `count`. Defaults to `true`. */
-    count?: boolean;
-    /** Field, or fields, to sum. Each appears in the rows as `sum_<field>`. */
-    sum?: (keyof T & string) | (keyof T & string)[];
-    /** Field, or fields, to average. Each appears in the rows as `avg_<field>`. */
-    avg?: (keyof T & string) | (keyof T & string)[];
-    /** Field, or fields, to take the minimum of. Each appears in the rows as `min_<field>`. */
-    min?: (keyof T & string) | (keyof T & string)[];
-    /** Field, or fields, to take the maximum of. Each appears in the rows as `max_<field>`. */
-    max?: (keyof T & string) | (keyof T & string)[];
-    /** Field whose distinct values to count per group, returned as `count_distinct_<field>`. */
-    countDistinct?: keyof T & string;
-    /** Filter on the computed fields, applied after grouping. For example `{ count: { $gt: 1 } }` keeps only duplicated groups. */
-    having?: Record<string, any>;
-    /** Computed or group field to sort the rows by, with a `-` prefix for descending. For example `'-count'`. */
-    sort?: string;
-    /** Maximum number of rows, up to 1,000. Defaults to 1,000. */
-    limit?: number;
-}
-/**
- * Rows returned by {@linkcode EntityHandler.aggregate | aggregate()}.
- */
-export interface EntityAggregateResult {
-    /** One row per group: the group fields by name, then `count`, `sum_<field>`, `avg_<field>`, `min_<field>`, `max_<field>` or `count_distinct_<field>`. */
-    rows: Record<string, any>[];
-    /** `true` when more groups exist than `limit` allowed. */
-    truncated: boolean;
-}
-/**
- * Options for {@linkcode EntityHandler.upsert | upsert()}.
- *
- * @typeParam T - Entity record type.
- */
-export interface EntityUpsertOptions<T> {
-    /** Field, or fields, that identify a record. A record whose key values match an existing record updates it; any other record is created. */
-    key: (keyof T & string) | (keyof T & string)[];
-}
-/**
- * Result returned by {@linkcode EntityHandler.upsert | upsert()}.
- *
- * @typeParam T - Entity record type.
- */
-export interface EntityUpsertResult<T = any> {
-    /** Number of records that were created. */
-    created: number;
-    /** Number of existing records that were updated. */
-    updated: number;
-    /** The written records, created and updated, as they now exist. */
-    records: T[];
-}
 /**
  * Result returned when importing entities from a file.
  *
@@ -335,18 +211,14 @@ export interface EntityHandler<T = any> {
      * Retrieves all records of this type with support for sorting,
      * pagination, and field selection.
      *
-     * **Note:** The maximum limit is 5,000 items per request. To read more than
-     * one page, pass an {@linkcode EntityListOptions | options object} with a
-     * `cursor` instead of `skip`: every page costs the same however deep you are,
-     * and records deleted between pages never shift the boundary. `skip` is kept
-     * for existing code and is deprecated for loops.
+     * **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 `5000`.
-     * @param skip - Number of results to skip for pagination. Defaults to `0`. Deprecated for loops; use a cursor.
+     * @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 with selected fields. When called with an options object, resolves instead to an {@linkcode EntityPage | EntityPage} with `items`, `next_cursor` and `has_more`; with a `distinct` option the items are the field's values.
+     * @returns Promise resolving to an array of records with selected fields.
      *
      * @example
      * ```typescript
@@ -372,39 +244,15 @@ export interface EntityHandler<T = any> {
      * // Get only specific fields
      * const fields = await base44.entities.MyEntity.list('-created_date', 10, 0, ['name', 'status']);
      * ```
-     *
-     * @example
-     * ```typescript
-     * // Walk every record with a cursor. Pass an options object instead of
-     * // positional arguments to get a page with `next_cursor` and `has_more`.
-     * let page = await base44.entities.MyEntity.list({ sort: '-created_date', limit: 1000 });
-     * await exportRows(page.items);
-     * while (page.has_more) {
-     *   page = await base44.entities.MyEntity.list({ cursor: page.next_cursor, limit: 1000 });
-     *   await exportRows(page.items);
-     * }
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Distinct values of one field, instead of records
-     * const { items: categories } = await base44.entities.Product.list({ distinct: 'category' });
-     * ```
      */
     list<K extends keyof T = keyof T>(sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
-    list<K extends keyof T>(options: EntityDistinctOptions<T, K>): Promise<EntityPage<T[K]>>;
-    list<K extends keyof T = keyof T>(options: EntityListOptions<T, K>): Promise<EntityPage<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. To read more than
-     * one page, pass an {@linkcode EntityListOptions | options object} with a
-     * `cursor` instead of `skip`: every page costs the same however deep you are,
-     * and records deleted between pages never shift the boundary. `skip` is kept
-     * for existing code and is deprecated for loops.
+     * **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
@@ -413,10 +261,10 @@ export interface EntityHandler<T = any> {
      * for exact matches, `null` for null values, arrays as shorthand for matching any of the
      * provided values, or documented MongoDB query operators for advanced filtering.
      * @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
-     * @param limit - Maximum number of results to return. Defaults to `5000`.
-     * @param skip - Number of results to skip for pagination. Defaults to `0`. Deprecated for loops; use a cursor.
+     * @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 with selected fields. When called with an options object, resolves instead to an {@linkcode EntityPage | EntityPage} with `items`, `next_cursor` and `has_more`; with a `distinct` option the items are the field's values.
+     * @returns Promise resolving to an array of filtered records with selected fields.
      *
      * @example
      * ```typescript
@@ -493,34 +341,8 @@ export interface EntityHandler<T = any> {
      *   ['name', 'priority']
      * );
      * ```
-     *
-     * @example
-     * ```typescript
-     * // Walk all matching records with a cursor. Pass an options object as the
-     * // second argument to get a page with `next_cursor` and `has_more`.
-     * let page = await base44.entities.Order.filter(
-     *   { status: 'open' },
-     *   { sort: '-created_date', limit: 1000 }
-     * );
-     * await exportRows(page.items);
-     * while (page.has_more) {
-     *   page = await base44.entities.Order.filter({ status: 'open' }, { cursor: page.next_cursor, limit: 1000 });
-     *   await exportRows(page.items);
-     * }
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Distinct values of one field among the matching records
-     * const { items: agents } = await base44.entities.Order.filter(
-     *   { status: 'open' },
-     *   { distinct: 'agent_id' }
-     * );
-     * ```
      */
     filter<K extends keyof T = keyof T>(query: EntityFilterQuery<T>, sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
-    filter<K extends keyof T>(query: EntityFilterQuery<T>, options: EntityDistinctOptions<T, K>): Promise<EntityPage<T[K]>>;
-    filter<K extends keyof T = keyof T>(query: EntityFilterQuery<T>, options: EntityListOptions<T, K>): Promise<EntityPage<Pick<T, K>>>;
     /**
      * Gets a single record by ID.
      *
@@ -727,111 +549,6 @@ export interface EntityHandler<T = any> {
      * ```
      */
     updateMany(query: Partial<T>, data: Record<string, Record<string, any>>): Promise<UpdateManyResult>;
-    /**
-     * Counts the records that match a query.
-     *
-     * Returns the number of records the current user can read, without fetching them.
-     * Use it for totals, badges and "page N of M" instead of listing records and
-     * measuring the array.
-     *
-     * @param query - Filter query, in the same form {@linkcode filter | filter()} accepts. Defaults to all records.
-     * @returns Promise resolving to the number of matching records.
-     *
-     * @example
-     * ```typescript
-     * // How many tasks are still open?
-     * const open = await base44.entities.Task.count({ status: 'open' });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Total records in the entity
-     * const total = await base44.entities.Task.count();
-     * ```
-     */
-    count(query?: EntityFilterQuery<T>): Promise<number>;
-    /**
-     * Computes counts, sums, averages, minimums, maximums or distinct counts, grouped by fields.
-     *
-     * Use it for dashboards, leaderboards and reports instead of loading every record
-     * and adding up in the browser. The server groups the records you can read and
-     * returns one row per group, up to 1,000 rows.
-     *
-     * @param spec - What to group by and what to compute. See {@linkcode EntityAggregateSpec | EntityAggregateSpec}.
-     * @returns Promise resolving to the rows and a `truncated` flag.
-     *
-     * @example
-     * ```typescript
-     * // Sales per agent this month, biggest first
-     * const { rows } = await base44.entities.Sale.aggregate({
-     *   query: { sale_date: { $gte: '2026-09-01' } },
-     *   groupBy: 'agent_id',
-     *   sum: 'amount',
-     *   sort: '-sum_amount'
-     * });
-     * // rows: [{ agent_id: 'a1', count: 42, sum_amount: 18250 }, ...]
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Records created per day
-     * const { rows } = await base44.entities.Visit.aggregate({
-     *   dateBucket: { field: 'created_date', unit: 'day' }
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Find duplicated external ids
-     * const { rows } = await base44.entities.Contact.aggregate({
-     *   groupBy: 'external_id',
-     *   having: { count: { $gt: 1 } }
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Unique visitors per page
-     * const { rows } = await base44.entities.PageView.aggregate({
-     *   groupBy: 'path',
-     *   countDistinct: 'session_id'
-     * });
-     * ```
-     */
-    aggregate(spec: EntityAggregateSpec<T>): Promise<EntityAggregateResult>;
-    /**
-     * Creates or updates records by a key of your own.
-     *
-     * Use this when you sync data from another system: name the field, or fields, that
-     * identify a record, and the server updates the records whose key already exists and
-     * creates the rest, in one call. You no longer need to list existing records to check
-     * for duplicates before writing.
-     *
-     * You can upsert up to 500 records per request. When two records in one call share a
-     * key, the last one wins. Updates merge the given fields into the existing record, like
-     * {@linkcode update | update()}.
-     *
-     * @param records - Array of record data objects. Each must carry a value for every key field.
-     * @param options - The key field or fields. See {@linkcode EntityUpsertOptions | EntityUpsertOptions}.
-     * @returns Promise resolving to the counts and the written records.
-     *
-     * @example
-     * ```typescript
-     * // Sync contacts from a CRM by their CRM id
-     * const result = await base44.entities.Contact.upsert(
-     *   crmContacts.map(c => ({ crm_id: c.id, name: c.name, email: c.email })),
-     *   { key: 'crm_id' }
-     * );
-     * console.log(`${result.created} new, ${result.updated} updated`);
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Compound key
-     * await base44.entities.Inventory.upsert(rows, { key: ['sku', 'warehouse'] });
-     * ```
-     */
-    upsert(records: Partial<T>[], options: EntityUpsertOptions<T>): Promise<EntityUpsertResult<T>>;
     /**
      * Updates the specified records in a single request, each with its own data.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.48-pr.287.fd215cb",
+  "version": "0.8.48-pr.289.b9ea964",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",