@base44-preview/sdk 0.8.50-pr.292.d7cb5e4 → 0.8.51-pr.293.e71320c

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, 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 { 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.types.d.ts

@@ -33,7 +33,7 @@ export interface AiGatewayModuleConfig {
  * `connection()` hands you a `baseURL` and `token` 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 Chat Completions API and lets you point it at a custom `baseURL`
+ * 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
  * these clients and it works against Base44's gateway exactly as it would
  * against the provider directly, no separate account, API key, or billing
@@ -55,6 +55,15 @@ export interface AiGatewayModuleConfig {
  * Pass `'automatic'` to let Base44 choose one, or pin a specific model such
  * as `'claude_sonnet_4_6'`, `'gpt_5_5'`, or `'gemini_3_1_pro'`.
  *
+ * ## Images
+ *
+ * The gateway also serves OpenAI's image endpoints, `/images/generations`
+ * and `/images/edits`, so you can generate images and edit them using
+ * reference images. Image requests use their own set of models: pass
+ * `'automatic'` to let Base44 choose one, or pin a model such as
+ * `'gemini_3_1_flash_image'` or `'gpt_image_2'`. For request options, the
+ * full model list, and limits, see [Generate images with the AI Gateway](/developers/references/sdk/getting-started/ai-gateway-images).
+ *
  * ## Authentication Modes
  *
  * There's no permission difference between modes. Both just determine which
@@ -145,6 +154,29 @@ export interface AiGatewayModule {
      *
      * await agent.generate({ prompt: `Review this return request: ${JSON.stringify(returnRequest)}` });
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Generate an image
+     * import { createClientFromRequest } from "@base44/sdk";
+     * import { generateImage } from "ai";
+     * import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+     *
+     * // Runs inside a backend function
+     * const base44 = createClientFromRequest(request);
+     * const { baseURL, token } = base44.aiGateway.connection();
+     * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token });
+     *
+     * const { image } = await generateImage({
+     *   model: models.imageModel("automatic"),
+     *   prompt: "A watercolor illustration of a lighthouse at dawn",
+     *   // Base44 options go under the provider name you passed above
+     *   providerOptions: { base44: { aspect_ratio: "16:9" } },
+     * });
+     *
+     * const file = new File([image.uint8Array], "lighthouse.png", { type: image.mediaType });
+     * const { file_url } = await base44.integrations.Core.UploadFile({ file });
+     * ```
      */
     connection(options?: AiGatewayConnectionOptions): AiGatewayConnection;
 }

package/dist/modules/entities.js

@@ -42,8 +42,14 @@ function parseRealtimeMessage(dataStr) {
     }
 }
 const DEFAULT_PAGE_LIMIT = 100;
-function isPageOptions(value) {
-    return typeof value === "object" && value !== null;
+// 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;
 }
 /**
  * Creates a handler for a specific entity.
@@ -73,7 +79,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, shared by list(options) and filter(query, options)
+    // GET /{entity}/v2/list: one cursor page of records or distinct values
     const readPage = (options, query) => {
         const params = {};
         if (query)
@@ -93,15 +99,31 @@ 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) {
-            const [sort, limit, skip, fields] = args;
-            return isPageOptions(sort) ? readPage(sort) : readArray(sort, limit, skip, fields);
+            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);
         },
-        // 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);
+            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);
         },
         // Get entity by ID
         async get(id) {

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

@@ -51,13 +51,14 @@ export interface UpdateManyResult {
     has_more: boolean;
 }
 /**
- * Options object accepted by {@linkcode EntityHandler.list | list()} and
- * {@linkcode EntityHandler.filter | filter()} to read one cursor page.
+ * Options object accepted by {@linkcode EntityHandler.page | page()} to read one cursor page of records.
  *
  * @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. */
@@ -73,14 +74,15 @@ export interface EntityListOptions<T, K extends keyof T = keyof T> {
     fields?: K[];
 }
 /**
- * Options object accepted by {@linkcode EntityHandler.list | list()} and
- * {@linkcode EntityHandler.filter | filter()} to read the distinct values of one field
+ * Options object accepted by {@linkcode EntityHandler.page | page()} 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. */
@@ -89,8 +91,26 @@ export interface EntityDistinctOptions<T, K extends keyof T = keyof T> {
     cursor?: string | null;
 }
 /**
- * One page of records, returned by {@linkcode EntityHandler.list | list()} and
- * {@linkcode EntityHandler.filter | filter()} when called with an options object.
+ * 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()}.
  *
  * @typeParam T - Record type of the items.
  */
@@ -336,17 +356,19 @@ 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, 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.
+     * 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.
      *
      * @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 skip - Number of results to skip for pagination. Defaults to `0`. For loops, use `page()`.
      * @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
@@ -375,25 +397,18 @@ export interface EntityHandler<T = any> {
      *
      * @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' });
+     * // The same arguments as one options object; still an array
+     * const recent = await base44.entities.MyEntity.list({ sort: '-created_date', limit: 10 });
      * ```
      */
     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]>>;
-    list<K extends keyof T = keyof T>(options: EntityListOptions<T, K>): Promise<EntityPage<Pick<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>>>;
     /**
      * Filters records based on a query.
      *
@@ -401,10 +416,13 @@ 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, 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.
+     * 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.
      *
      * @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
@@ -414,9 +432,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`. Deprecated for loops; use a cursor.
+     * @param skip - Number of results to skip for pagination. Defaults to `0`. For loops, use `page()`.
      * @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
@@ -496,15 +514,39 @@ export interface EntityHandler<T = any> {
      *
      * @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 }
-     * );
+     * // 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 });
      * await exportRows(page.items);
      * while (page.has_more) {
-     *   page = await base44.entities.Order.filter({ status: 'open' }, { cursor: page.next_cursor, limit: 1000 });
+     *   page = await base44.entities.Order.page({ cursor: page.next_cursor, limit: 1000 });
      *   await exportRows(page.items);
      * }
      * ```
@@ -512,15 +554,11 @@ export interface EntityHandler<T = any> {
      * @example
      * ```typescript
      * // Distinct values of one field among the matching records
-     * const { items: agents } = await base44.entities.Order.filter(
-     *   { status: 'open' },
-     *   { distinct: 'agent_id' }
-     * );
+     * const { items: agents } = await base44.entities.Order.page({ query: { 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>>>;
+    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>>>;
     /**
      * Gets a single record by ID.
      *

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

@@ -59,8 +59,17 @@ export interface InvokeLLMParams {
  * Parameters for the GenerateImage function.
  */
 export interface GenerateImageParams {
-    /** Description of the image to generate. */
+    /**
+     * Description of the image to generate. When you pass `existing_image_urls`,
+     * describe what to do with the reference images instead.
+     */
     prompt: string;
+    /**
+     * URLs of images to use as references, for example to edit an existing
+     * image, match a style, or add visual context. Images that can't be read are
+     * skipped. If none of them can be read, the request fails.
+     */
+    existing_image_urls?: string[];
 }
 export interface GenerateImageResult {
     /** URL of the generated image. */
@@ -173,12 +182,17 @@ export interface CoreIntegrations {
      */
     InvokeLLM(params: InvokeLLMParams): Promise<string | object>;
     /**
-     * Create AI-generated images from text prompts.
+     * Create AI-generated images from text prompts, optionally guided by reference images.
      *
      * Images are generated as PNG files at approximately 1024px on the shorter side. The
      * exact dimensions vary by aspect ratio.
      *
-     * Prompts that violate the AI provider's content policy will be refused.
+     * Pass `existing_image_urls` to edit an existing image or to guide the result
+     * with reference images. To choose the model, aspect ratio, resolution, or
+     * quality, use the [AI Gateway image endpoints](/developers/references/sdk/getting-started/ai-gateway-images)
+     * instead.
+     *
+     * Prompts that violate the AI provider's content policy are refused.
      *
      * @param params - Parameters for image generation
      * @returns Promise resolving to an object containing the URL of the generated PNG image.
@@ -191,6 +205,15 @@ export interface CoreIntegrations {
      * });
      * console.log(url); // https://...generated_image.png
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Edit an existing image
+     * const {url} = await base44.integrations.Core.GenerateImage({
+     *   prompt: "Replace the background with a sunset beach",
+     *   existing_image_urls: [productPhotoUrl]
+     * });
+     * ```
      */
     GenerateImage(params: GenerateImageParams): Promise<GenerateImageResult>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.50-pr.292.d7cb5e4",
+  "version": "0.8.51-pr.293.e71320c",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",