@base44-preview/sdk 0.8.51-pr.293.e71320c → 0.8.52-pr.286.2dbb896

package/README.md

@@ -151,3 +151,13 @@ npm run create-docs
 cd docs
 mintlify dev
 ```
+
+### Platform browser subscriptions
+
+The separate `@base44/sdk/platform/client` entry point watches public builder
+updates for up to eight apps over the platform socket. It supports typed events,
+a snapshot on every join and bounded delivery, using a socket-session token your
+backend opens with its workspace key.
+See [setup, public contract and recovery](platform-docs/client.md) and the
+[TypeScript example](examples/platform-client.ts). White-label sockets must be enabled
+for the workspace; never use an API key in the browser.

package/dist/client.js

@@ -77,6 +77,12 @@ export function createClient(config) {
         ...optionalHeaders,
         "X-App-Id": String(appId),
     };
+    // Base44-State is the platform's signed proof that the caller passed the
+    // workspace IP allowlist; the gateway checks it like any other app route.
+    const stateHeader = optionalHeaders === null || optionalHeaders === void 0 ? void 0 : optionalHeaders["Base44-State"];
+    const aiGatewayHeaders = stateHeader
+        ? { "Base44-State": stateHeader }
+        : {};
     const functionHeaders = functionsVersion
         ? {
             ...headers,
@@ -187,7 +193,12 @@ export function createClient(config) {
             serverUrl,
             token,
         }),
-        aiGateway: createAiGatewayModule({ serverUrl, token, appId }),
+        aiGateway: createAiGatewayModule({
+            serverUrl,
+            token,
+            appId,
+            headers: aiGatewayHeaders,
+        }),
         appLogs: createAppLogsModule(axiosClient, appId),
         app: createAppModule(axiosClient, appId),
         users: createUsersModule(axiosClient, appId),
@@ -234,7 +245,12 @@ export function createClient(config) {
             serverUrl,
             token,
         }),
-        aiGateway: createAiGatewayModule({ serverUrl, token: serviceToken, appId }),
+        aiGateway: createAiGatewayModule({
+            serverUrl,
+            token: serviceToken,
+            appId,
+            headers: aiGatewayHeaders,
+        }),
         appLogs: createAppLogsModule(serviceRoleAxiosClient, appId),
         cleanup: () => {
             if (socket) {

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, EntityArrayOptions, EntityPage, EntityRecord, EntityTypeRegistry, EntityUpsertOptions, EntityUpsertResult, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.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 { 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/ai-gateway.d.ts

@@ -1,2 +1,2 @@
 import { AiGatewayModule, AiGatewayModuleConfig } from "./ai-gateway.types.js";
-export declare function createAiGatewayModule({ serverUrl, token, appId, }: AiGatewayModuleConfig): AiGatewayModule;
+export declare function createAiGatewayModule({ serverUrl, token, appId, headers, }: AiGatewayModuleConfig): AiGatewayModule;

package/dist/modules/ai-gateway.js

@@ -3,7 +3,7 @@ const PROVIDER_PATHS = {
     openai: "openai",
     typesafe: "typesafe",
 };
-export function createAiGatewayModule({ serverUrl, token, appId, }) {
+export function createAiGatewayModule({ serverUrl, token, appId, headers = {}, }) {
     const connection = ({ provider = "openai" } = {}) => {
         var _a;
         if (!Object.prototype.hasOwnProperty.call(PROVIDER_PATHS, provider)) {
@@ -13,6 +13,7 @@ export function createAiGatewayModule({ serverUrl, token, appId, }) {
         return {
             baseURL: `${serverUrl}/api/apps/${appId}/ai/${providerPath}/v1`,
             token: (_a = token !== null && token !== void 0 ? token : getAccessToken()) !== null && _a !== void 0 ? _a : "",
+            headers: { ...headers },
         };
     };
     return {

package/dist/modules/ai-gateway.types.d.ts

@@ -9,6 +9,16 @@ export interface AiGatewayConnection {
      * unauthenticated.
      */
     token: string;
+    /**
+     * Extra headers to send with every gateway request. Pass them to your client's
+     * header option, such as `defaultHeaders` for the `openai` SDK and TanStack AI,
+     * or `headers` for the Vercel AI SDK.
+     *
+     * On a client from {@linkcode createClientFromRequest | createClientFromRequest()},
+     * this carries the signed `Base44-State` the platform attached to the request,
+     * which a workspace IP allowlist requires. Otherwise it's empty.
+     */
+    headers: Record<string, string>;
 }
 /** Options for selecting an AI Gateway provider. */
 export interface AiGatewayConnectionOptions {
@@ -26,12 +36,14 @@ export interface AiGatewayModuleConfig {
     token?: string;
     /** Application ID */
     appId: string;
+    /** Platform headers to forward on gateway requests */
+    headers?: Record<string, string>;
 }
 /**
  * AI Gateway module for calling Base44's managed AI models from your own code.
  *
- * `connection()` hands you a `baseURL` and `token` that authenticate as your
- * Base44 app. An OpenAI-compatible client is any library, such as the `openai`
+ * `connection()` hands you a `baseURL`, `token`, and `headers` that
+ * authenticate as your Base44 app. An OpenAI-compatible client is any library, such as the `openai`
  * SDK or the Vercel AI SDK, that has the same request and response format
  * as OpenAI's API and lets you point it at a custom `baseURL`
  * instead of OpenAI's own servers. Pass `connection()`'s values to one of
@@ -80,18 +92,16 @@ export interface AiGatewayModuleConfig {
  * app until the quota resets. A request is rejected before the model runs if
  * the app is out of credits. If you need to cap usage per user, build that
  * check yourself, for example by tracking calls per user in your own entity.
- *
- * Streaming responses aren't supported yet, so leave `stream` unset on your requests.
  */
 export interface AiGatewayModule {
     /**
      * Gets the connection details for the Base44 AI Gateway.
      *
-     * Returns the `baseURL` and `token` to pass to the selected provider client.
+     * Returns the `baseURL`, `token`, and `headers` to pass to the selected provider client.
      *
      * @param options - Provider selection. Omit it to use the OpenAI-compatible gateway.
      *
-     * @returns The gateway {@linkcode AiGatewayConnection | connection} (`baseURL` and `token`).
+     * @returns The gateway {@linkcode AiGatewayConnection | connection} (`baseURL`, `token`, and `headers`).
      *
      * @example
      * ```typescript
@@ -101,8 +111,8 @@ export interface AiGatewayModule {
      *
      * // Runs inside a backend function
      * const base44 = createClientFromRequest(request);
-     * const { baseURL, token } = base44.aiGateway.connection();
-     * const openai = new OpenAI({ baseURL, apiKey: token });
+     * const { baseURL, token, headers } = base44.aiGateway.connection();
+     * const openai = new OpenAI({ baseURL, apiKey: token, defaultHeaders: headers });
      *
      * const response = await openai.chat.completions.create({
      *   model: "automatic",
@@ -123,9 +133,9 @@ export interface AiGatewayModule {
      * // Runs inside a backend function, reviewing a return request
      * const base44 = createClientFromRequest(request);
      * const returnRequest = await base44.entities.ReturnRequest.get(returnId);
-     * const { baseURL, token } = base44.aiGateway.connection();
-     * // Point any OpenAI-compatible client at `baseURL` with `apiKey: token`.
-     * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token });
+     * const { baseURL, token, headers } = base44.aiGateway.connection();
+     * // Point any OpenAI-compatible client at `baseURL` with `apiKey: token` and `headers`.
+     * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token, headers });
      *
      * const agent = new ToolLoopAgent({
      *   model: models("automatic"),
@@ -164,8 +174,8 @@ export interface AiGatewayModule {
      *
      * // Runs inside a backend function
      * const base44 = createClientFromRequest(request);
-     * const { baseURL, token } = base44.aiGateway.connection();
-     * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token });
+     * const { baseURL, token, headers } = base44.aiGateway.connection();
+     * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token, headers });
      *
      * const { image } = await generateImage({
      *   model: models.imageModel("automatic"),

package/dist/modules/entities.js

@@ -42,14 +42,8 @@ function parseRealtimeMessage(dataStr) {
     }
 }
 const DEFAULT_PAGE_LIMIT = 100;
-// Keys of the object form of list()/filter(). An object passed to list() with none of them is a filter query.
-const ARRAY_OPTION_KEYS = ["sort", "limit", "skip", "fields", "filter", "query"];
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-// Code written for 0.8.49 reads a page from list()/filter() with a cursor or distinct option; keep it working.
-function isPageRequest(value) {
-    return "cursor" in value || "distinct" in value;
+function isPageOptions(value) {
+    return typeof value === "object" && value !== null;
 }
 /**
  * Creates a handler for a specific entity.
@@ -79,7 +73,7 @@ function createEntityHandler(axios, appId, entityName, getSocket) {
             params.fields = fieldsParam(fields);
         return axios.get(baseURL, { params });
     };
-    // GET /{entity}/v2/list: one cursor page of records or distinct values
+    // 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)
@@ -99,31 +93,15 @@ function createEntityHandler(axios, appId, entityName, getSocket) {
         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) {
-            var _a;
-            const [first, ...rest] = args;
-            if (!isPlainObject(first))
-                return readArray(first, ...rest);
-            if (isPageRequest(first))
-                return readPage(first, first.query);
-            if (Object.keys(first).some((key) => ARRAY_OPTION_KEYS.includes(key))) {
-                return readArray(first.sort, first.limit, first.skip, first.fields, (_a = first.filter) !== null && _a !== void 0 ? _a : first.query);
-            }
-            // The object took sort's slot: list({}, 5) means limit 5; list({ email }, '-created_date', 100) follows filter()'s order.
-            return typeof rest[0] === "string"
-                ? readArray(rest[0], rest[1], rest[2], rest[3], first)
-                : readArray(undefined, rest[0], rest[1], rest[2], first);
+            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 [second, ...rest] = args;
-            if (!isPlainObject(second))
-                return readArray(second, rest[0], rest[1], rest[2], query);
-            if (isPageRequest(second))
-                return readPage(second, query);
-            return readArray(second.sort, second.limit, second.skip, second.fields, query);
-        },
-        async page(options = {}) {
-            return readPage(options, options.query);
+            const [sort, limit, skip, fields] = args;
+            return isPageOptions(sort) ? readPage(sort, query) : readArray(sort, limit, skip, fields, query);
         },
         // Get entity by ID
         async get(id) {

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

@@ -51,14 +51,13 @@ export interface UpdateManyResult {
     has_more: boolean;
 }
 /**
- * Options object accepted by {@linkcode EntityHandler.page | page()} to read one cursor page of records.
+ * 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> {
-    /** Filter for the records, in the same form as {@linkcode EntityHandler.filter | filter()}'s query. Defaults to all records. */
-    query?: EntityFilterQuery<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. */
@@ -74,15 +73,14 @@ export interface EntityListOptions<T, K extends keyof T = keyof T> {
     fields?: K[];
 }
 /**
- * Options object accepted by {@linkcode EntityHandler.page | page()} to read the distinct values of one field
+ * 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> {
-    /** Filter for the records whose values are read. Defaults to all records. */
-    query?: EntityFilterQuery<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. */
@@ -91,26 +89,8 @@ export interface EntityDistinctOptions<T, K extends keyof T = keyof T> {
     cursor?: string | null;
 }
 /**
- * Options object accepted by {@linkcode EntityHandler.list | list()} and
- * {@linkcode EntityHandler.filter | filter()} in place of positional arguments. Both still return an array.
- *
- * @typeParam T - Entity record type.
- * @typeParam K - The fields to include in each record.
- */
-export interface EntityArrayOptions<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 to return. Defaults to `5000`. */
-    limit?: number;
-    /** Number of records to skip. Defaults to `0`. For loops over many records, use {@linkcode EntityHandler.page | page()}. */
-    skip?: number;
-    /** Array of field names to include in each record. Defaults to all fields. */
-    fields?: K[];
-    /** Filter for the records. Only read by `list()`; `filter()` takes its query as the first argument. */
-    filter?: EntityFilterQuery<T>;
-}
-/**
- * One page of records, returned by {@linkcode EntityHandler.page | page()}.
+ * 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.
  */
@@ -356,19 +336,17 @@ export interface EntityHandler<T = any> {
      * pagination, and field selection.
      *
      * **Note:** The maximum limit is 5,000 items per request. To read more than
-     * one page, use {@linkcode EntityHandler.page | page()} with a cursor instead of
-     * `skip`: every page costs the same however deep you are, and records deleted
-     * between pages never shift the boundary.
-     *
-     * The arguments can also be passed as one {@linkcode EntityArrayOptions | options object}
-     * (`{ sort, limit, skip, fields, filter }`); the result is still an array.
+     * 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.
      *
      * @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`. For loops, use `page()`.
+     * @param skip - Number of results to skip for pagination. Defaults to `0`. Deprecated for loops; use a cursor.
      * @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.
+     * @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.
      *
      * @example
      * ```typescript
@@ -397,18 +375,25 @@ export interface EntityHandler<T = any> {
      *
      * @example
      * ```typescript
-     * // The same arguments as one options object; still an array
-     * const recent = await base44.entities.MyEntity.list({ sort: '-created_date', limit: 10 });
+     * // 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 = keyof T>(options: EntityArrayOptions<T, K>): Promise<Pick<T, K>[]>;
-    /** @deprecated Use {@linkcode EntityHandler.page | page()}. */
     list<K extends keyof T>(options: EntityDistinctOptions<T, K>): Promise<EntityPage<T[K]>>;
-    /** @deprecated Use {@linkcode EntityHandler.page | page()}. */
-    list<K extends keyof T = keyof T>(options: EntityListOptions<T, K> & {
-        cursor: string | null;
-    }): Promise<EntityPage<Pick<T, K>>>;
+    list<K extends keyof T = keyof T>(options: EntityListOptions<T, K>): Promise<EntityPage<Pick<T, K>>>;
     /**
      * Filters records based on a query.
      *
@@ -416,13 +401,10 @@ export interface EntityHandler<T = any> {
      * sorting, pagination, and field selection.
      *
      * **Note:** The maximum limit is 5,000 items per request. To read more than
-     * one page, use {@linkcode EntityHandler.page | page()} with a cursor instead of
-     * `skip`: every page costs the same however deep you are, and records deleted
-     * between pages never shift the boundary.
-     *
-     * The arguments after the query can also be passed as one
-     * {@linkcode EntityArrayOptions | options object} (`{ sort, limit, skip, fields }`);
-     * the result is still an array.
+     * 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.
      *
      * @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
@@ -432,9 +414,9 @@ export interface EntityHandler<T = any> {
      * 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`. For loops, use `page()`.
+     * @param skip - Number of results to skip for pagination. Defaults to `0`. Deprecated for loops; use a cursor.
      * @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.
+     * @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.
      *
      * @example
      * ```typescript
@@ -514,39 +496,15 @@ export interface EntityHandler<T = any> {
      *
      * @example
      * ```typescript
-     * // Sort and limit as an options object; still an array
-     * const open = await base44.entities.Order.filter({ status: 'open' }, { sort: '-created_date', limit: 20 });
-     * ```
-     */
-    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 = keyof T>(query: EntityFilterQuery<T>, options: EntityArrayOptions<T, K>): Promise<Pick<T, K>[]>;
-    /** @deprecated Use {@linkcode EntityHandler.page | page()}. */
-    filter<K extends keyof T>(query: EntityFilterQuery<T>, options: EntityDistinctOptions<T, K>): Promise<EntityPage<T[K]>>;
-    /** @deprecated Use {@linkcode EntityHandler.page | page()}. */
-    filter<K extends keyof T = keyof T>(query: EntityFilterQuery<T>, options: EntityListOptions<T, K> & {
-        cursor: string | null;
-    }): Promise<EntityPage<Pick<T, K>>>;
-    /**
-     * Reads one page of records, or of one field's distinct values, with a cursor.
-     *
-     * Use it for "load more", infinite scroll and exports. Every page costs the same
-     * however deep you are, records deleted between pages never shift the boundary,
-     * and records that share a sort value are each returned once. Pass `next_cursor`
-     * from one page as `cursor` on the next; the token carries the query, sort and
-     * fields, so a later page needs only `cursor` and `limit`. Stop when `has_more`
-     * is false. Every page holds `limit` items except the last.
-     *
-     * @typeParam K - The fields to include in each record, or the field whose values to read.
-     * @param options - `{ query, sort, limit, fields, cursor }` for records, or `{ query, distinct, limit, cursor }` for distinct values.
-     * @returns Promise resolving to an {@linkcode EntityPage | EntityPage} with `items`, `next_cursor` and `has_more`.
-     *
-     * @example
-     * ```typescript
-     * // Walk all matching records
-     * let page = await base44.entities.Order.page({ query: { status: 'open' }, sort: '-created_date', limit: 1000 });
+     * // 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.page({ cursor: page.next_cursor, limit: 1000 });
+     *   page = await base44.entities.Order.filter({ status: 'open' }, { cursor: page.next_cursor, limit: 1000 });
      *   await exportRows(page.items);
      * }
      * ```
@@ -554,11 +512,15 @@ export interface EntityHandler<T = any> {
      * @example
      * ```typescript
      * // Distinct values of one field among the matching records
-     * const { items: agents } = await base44.entities.Order.page({ query: { status: 'open' }, distinct: 'agent_id' });
+     * const { items: agents } = await base44.entities.Order.filter(
+     *   { status: 'open' },
+     *   { distinct: 'agent_id' }
+     * );
      * ```
      */
-    page<K extends keyof T>(options: EntityDistinctOptions<T, K>): Promise<EntityPage<T[K]>>;
-    page<K extends keyof T = keyof T>(options?: EntityListOptions<T, K>): Promise<EntityPage<Pick<T, K>>>;
+    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.
      *

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

@@ -127,7 +127,7 @@ export interface UploadPrivateFileResult {
 export interface CreateFileSignedUrlParams {
     /** URI of the uploaded private file. */
     file_uri: string;
-    /** How long the signed URL should be valid for, in seconds.
+    /** How long the signed URL should be valid for, in seconds. Must be between `60` (1 minute) and `3600` (1 hour).
      * @default 300 (5 minutes)
      */
     expires_in?: number;
@@ -352,7 +352,7 @@ export interface CoreIntegrations {
      * // Create a signed URL for a private file
      * const { signed_url } = await base44.integrations.Core.CreateFileSignedUrl({
      *   file_uri: "private/user123/document.pdf",
-     *   expires_in: 7200 // URL expires in 2 hours
+     *   expires_in: 1800 // URL expires in 30 minutes
      * });
      * console.log(signed_url); // https://...?signature=...
      * ```

package/dist/platform/client/client.d.ts

@@ -0,0 +1,9 @@
+import type { PlatformClientOptions } from "./client.types.js";
+import type { BuilderModule } from "./modules/builder.types.js";
+/** Browser platform client. Construction creates no sockets, timers or network requests. */
+export declare class Base44PlatformClient {
+    /** Lazy builder subscriptions with independent session lifecycles. */
+    readonly builder: BuilderModule;
+    /** Configure shared service/auth settings; each module initializes its own resources. */
+    constructor(options: PlatformClientOptions);
+}

package/dist/platform/client/client.js

@@ -0,0 +1,12 @@
+import { createBuilder } from "./modules/builder.js";
+/** Browser platform client. Construction creates no sockets, timers or network requests. */
+export class Base44PlatformClient {
+    /** Configure shared service/auth settings; each module initializes its own resources. */
+    constructor(options) {
+        const url = new URL(options.serverUrl);
+        if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+            throw new TypeError("serverUrl must be an HTTP(S) origin without credentials, path, query or fragment");
+        }
+        this.builder = Object.freeze(createBuilder({ ...options, serverUrl: url.origin }));
+    }
+}

package/dist/platform/client/client.types.d.ts

@@ -0,0 +1,12 @@
+/** Shared configuration for browser platform modules. Never supply an API key. */
+export interface PlatformClientOptions {
+    /** Origin of the platform service, e.g. https://base44.app. No path/query/credentials. */
+    serverUrl: string;
+    /**
+     * Return a socket-session token from your backend, which opens the session with its
+     * workspace key (`POST /api/service/socket-sessions`) for the apps this page watches.
+     * Called when a builder session first connects, and again only after the server
+     * rejects or expires the current session. Sessions last one hour.
+     */
+    getSessionToken: () => string | Promise<string>;
+}

package/dist/platform/client/client.types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/client/errors.d.ts

@@ -0,0 +1,10 @@
+import type { PlatformSocketErrorCode } from "./errors.types.js";
+/** Sanitized failure. Original session-token provider, handler and server exceptions are not retained. */
+export declare class PlatformSocketError extends Error {
+    /** Stable machine-readable category. */
+    readonly code: PlatformSocketErrorCode;
+    /** Associated app, when the server identifies a valid room. */
+    readonly appId?: string;
+    /** Create a sanitized error with no credential-bearing cause or payload. */
+    constructor(code: PlatformSocketErrorCode, appId?: string);
+}

package/dist/platform/client/errors.js

@@ -0,0 +1,10 @@
+/** Sanitized failure. Original session-token provider, handler and server exceptions are not retained. */
+export class PlatformSocketError extends Error {
+    /** Create a sanitized error with no credential-bearing cause or payload. */
+    constructor(code, appId) {
+        super(`Platform socket: ${code}`);
+        this.name = "PlatformSocketError";
+        this.code = code;
+        this.appId = appId;
+    }
+}

package/dist/platform/client/errors.types.d.ts

@@ -0,0 +1,2 @@
+/** Server refusals and client transport/processing failures. */
+export type PlatformSocketErrorCode = "connection_denied" | "connection_failed" | "session_unavailable" | "session_replaced" | "access_denied" | "access_revoked" | "snapshot_unavailable" | "subscription_limit" | "delivery_overflow" | "protocol_error" | "handler_failed" | "client_closed";

package/dist/platform/client/errors.types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/client/index.d.ts

@@ -0,0 +1,7 @@
+/** Browser platform modules, separate from the runtime and server SDKs. */
+export { Base44PlatformClient } from "./client.js";
+export { PlatformSocketError } from "./errors.js";
+export type { PlatformSocketErrorCode } from "./errors.types.js";
+export type { PlatformClientOptions } from "./client.types.js";
+export type { BuilderModule, BuilderInitOptions, BuilderSession, PlatformSubscription, SubscriptionOptions } from "./modules/builder.types.js";
+export type { AppUpdate, AppStatus, ChatMessage, MessageParams, ToolCall, ToolDisplayProjection, ToolQuestionOption, ToolQuestion, ToolQuestionArguments, ToolSecretField, ToolSecretArguments, ToolPackageOperation, ToolPackageArguments, ToolPlanUpdate, ToolPlanArguments, ToolPrdArguments, ToolMediaArguments, ToolMediaResult, ToolQuestionAnswer, ToolQuestionInput, ToolOutcome, ToolGuardApproval, ToolResult, QueueItem, QueueUpdate, TaskUpdate, ImageReady, Directive, PlatformEventMap, PlatformEvent, Snapshot } from "./modules/builder.events.types.js";

package/dist/platform/client/index.js

@@ -0,0 +1,3 @@
+/** Browser platform modules, separate from the runtime and server SDKs. */
+export { Base44PlatformClient } from "./client.js";
+export { PlatformSocketError } from "./errors.js";

package/dist/platform/client/modules/builder-protocol.d.ts

@@ -0,0 +1,11 @@
+import type { PlatformEvent, PlatformEventMap, Snapshot } from "./builder.events.types.js";
+export declare const eventNames: readonly ["update_model", "directive", "queue_update", "task_update", "image_ready"];
+/** Error frames that name an app room. */
+export declare const roomErrorCodes: readonly ["access_denied", "access_revoked", "snapshot_unavailable"];
+export declare const appPattern: RegExp;
+export declare const roomFor: (appId: string) => string;
+export declare function object(value: unknown): Record<string, unknown>;
+export declare function string(value: unknown): string;
+export declare function appFromRoom(value: unknown): string | undefined;
+export declare function decode(type: keyof PlatformEventMap, appId: string, raw: unknown): PlatformEvent;
+export declare function decodeSnapshot(raw: unknown): Snapshot;

package/dist/platform/client/modules/builder-protocol.js

@@ -0,0 +1,32 @@
+export const eventNames = ["update_model", "directive", "queue_update", "task_update", "image_ready"];
+/** Error frames that name an app room. */
+export const roomErrorCodes = ["access_denied", "access_revoked", "snapshot_unavailable"];
+export const appPattern = /^[a-f0-9]{24}$/;
+export const roomFor = (appId) => `/apps/${appId}`;
+export function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Invalid frame");
+    return value;
+}
+export function string(value) {
+    if (typeof value !== "string" || !value)
+        throw new Error("Invalid string");
+    return value;
+}
+export function appFromRoom(value) {
+    return typeof value === "string" && /^\/apps\/[a-f0-9]{24}$/.test(value) ? value.slice(6) : undefined;
+}
+export function decode(type, appId, raw) {
+    const frame = object(raw);
+    const wrapped = type === "update_model" || type === "task_update" || type === "image_ready";
+    const data = wrapped ? object(JSON.parse(string(frame.data))) : frame;
+    // Payload schemas are owned by the service; only decode/validate the transport envelope here.
+    return { type, appId, data };
+}
+export function decodeSnapshot(raw) {
+    const frame = object(raw);
+    if (!appFromRoom(frame.room) || !Array.isArray(frame.messages) || (frame.status !== null && typeof frame.status !== "object")) {
+        throw new Error("Invalid snapshot");
+    }
+    return frame;
+}