From 886e3147dc36e59b1c3f84c559e0b08a0b6a01e4 Mon Sep 17 00:00:00 2001 From: sam-prais Date: Tue, 14 Jul 2026 11:58:08 +0300 Subject: [PATCH 1/4] docs(ai-gateway): publish AI Gateway module reference The AI Gateway module's JSDoc was already updated in #226, but the types were never added to the docs pipeline whitelist, so the module never appeared in the generated SDK reference. Add AiGatewayModule and AiGatewayConnection to the docs pipeline, and rewrite the JSDoc for reference quality: explain what an OpenAI-compatible client is, clarify that the credit quota is shared across all app users (not per-user), link to the current model list, and split the growing intro into Models / Authentication Modes / Billing and limits sections. --- .../types-to-delete-after-processing.json | 1 + .../types-to-expose.json | 2 + src/modules/ai-gateway.types.ts | 79 +++++++++++++++---- 3 files changed, 66 insertions(+), 16 deletions(-) diff --git a/scripts/mintlify-post-processing/types-to-delete-after-processing.json b/scripts/mintlify-post-processing/types-to-delete-after-processing.json index dc7283e0..5083520f 100644 --- a/scripts/mintlify-post-processing/types-to-delete-after-processing.json +++ b/scripts/mintlify-post-processing/types-to-delete-after-processing.json @@ -1,4 +1,5 @@ [ + "AiGatewayConnection", "DeleteManyResult", "DeleteResult", "ImportResult", diff --git a/scripts/mintlify-post-processing/types-to-expose.json b/scripts/mintlify-post-processing/types-to-expose.json index e90bfd28..b5f8c2c0 100644 --- a/scripts/mintlify-post-processing/types-to-expose.json +++ b/scripts/mintlify-post-processing/types-to-expose.json @@ -2,6 +2,8 @@ "AgentName", "AgentNameRegistry", "AgentsModule", + "AiGatewayConnection", + "AiGatewayModule", "AnalyticsModule", "AppLogsModule", "AuthModule", diff --git a/src/modules/ai-gateway.types.ts b/src/modules/ai-gateway.types.ts index 3b4857ef..3db9ccfd 100644 --- a/src/modules/ai-gateway.types.ts +++ b/src/modules/ai-gateway.types.ts @@ -1,13 +1,13 @@ /** - * A connection to the Base44 AI Gateway. - * - * Contains the base URL and bearer token to use with any OpenAI-compatible - * client pointed at the Base44 AI Gateway. + * Connection details for the Base44 AI Gateway. */ export interface AiGatewayConnection { - /** Base URL of the gateway's OpenAI-compatible endpoint. */ + /** Base URL of the gateway's OpenAI-compatible Chat Completions endpoint. */ baseURL: string; - /** Bearer token used to authenticate requests to the gateway. */ + /** + * Bearer token that authenticates the request. Empty string when the caller is + * unauthenticated. + */ token: string; } @@ -27,13 +27,47 @@ export interface AiGatewayModuleConfig { /** * AI Gateway module for calling Base44's managed AI models from your own code. * - * The gateway exposes an OpenAI-compatible Chat Completions endpoint, so any - * OpenAI-compatible SDK works against it: - * - Build custom AI agents or call models directly from your backend code - * - Uses your app's models, billing, and credit quota, no API key to manage + * `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` + * 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 + * setup with the underlying model provider required. + * + * Call `connection()` from a backend function rather than the browser. That's + * where you can wire tools that read and write your app's own entities and + * business logic without shipping that logic to the client. It also keeps the + * gateway token out of the browser, where it could be stolen and used to + * spend against your app's shared credit quota. + * + * ## Models + * + * Build AI agents or call models directly from your app's backend functions. + * Pass `'automatic'` to let Base44 choose a model, or pin a specific one such + * as `'claude_sonnet_4_6'`, `'claude_opus_4_8'`, `'gpt_5_5'`, or + * `'gemini_3_1_pro'`. + * + * See the [`model` options on `InvokeLLM`](/developers/references/sdk/docs/type-aliases/integrations#invokellm) + * for the current set of models you can use. + * + * ## Authentication Modes + * + * This module is available to use with a client in all authentication modes: + * + * - **Anonymous or User authentication** (`base44.aiGateway`): The gateway connection is scoped to the current user's permissions. + * - **Service role authentication** (`base44.asServiceRole.aiGateway`): The gateway connection uses the service role for backend code that needs elevated permissions. + * + * ## Billing and limits * - * Available in user authentication mode (`base44.aiGateway`) and with the - * service-role token via `base44.asServiceRole.aiGateway`. + * Requests are billed to your app's credit quota, which is the same shared + * quota your app's built-in AI features use, and isn't split per user. If the + * app runs out of credits, the gateway stops working for every user of the + * app until the quota resets. A request is rejected before the model runs if + * the app is out of credits. + * + * Streaming responses aren't supported yet, so leave `stream` unset on your requests. */ export interface AiGatewayModule { /** @@ -41,14 +75,27 @@ export interface AiGatewayModule { * * Returns the `baseURL` and `token` to pass to any OpenAI-compatible client. * - * The `token` is the current caller's bearer token: the app user's token for - * `base44.aiGateway`, or the service-role token for `base44.asServiceRole.aiGateway`. - * When the caller is unauthenticated, `token` is an empty string. - * * @returns The gateway {@linkcode AiGatewayConnection | connection} (`baseURL` and `token`). * * @example * ```typescript + * // Call a model directly with the OpenAI SDK, inside a backend function + * import OpenAI from "openai"; + * + * const { baseURL, token } = base44.aiGateway.connection(); + * const openai = new OpenAI({ baseURL, apiKey: token }); + * + * const response = await openai.chat.completions.create({ + * model: "automatic", + * messages: [{ role: "user", content: "Summarize this week's top support tickets." }], + * }); + * + * console.log(response.choices[0].message.content); + * ``` + * + * @example + * ```typescript + * // Review a return request with a tool-using agent, inside a backend function * import { ToolLoopAgent, tool, stepCountIs, hasToolCall } from "ai"; * import { createOpenAICompatible } from "@ai-sdk/openai-compatible"; * import { z } from "zod"; From ac4b657c0d9927abcf3b9954affd0834172253d4 Mon Sep 17 00:00:00 2001 From: sam-prais Date: Wed, 15 Jul 2026 11:49:27 +0300 Subject: [PATCH 2/4] docs(ai-gateway): fix review feedback on rationale and examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Correct the misleading security claim that calling from a backend function keeps the token out of the browser — it's the same session token already used for every other SDK call. The real reason to use a backend function is code integrity: your instructions, tools, and business logic stay server-side where you can enforce your own auth, rate, and spend limits. Also show where the base44 client comes from in both examples (createClientFromRequest), instead of using a bare base44 with no indication of its origin. --- src/modules/ai-gateway.types.ts | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/modules/ai-gateway.types.ts b/src/modules/ai-gateway.types.ts index 3db9ccfd..b1ef1350 100644 --- a/src/modules/ai-gateway.types.ts +++ b/src/modules/ai-gateway.types.ts @@ -37,10 +37,11 @@ export interface AiGatewayModuleConfig { * setup with the underlying model provider required. * * Call `connection()` from a backend function rather than the browser. That's - * where you can wire tools that read and write your app's own entities and - * business logic without shipping that logic to the client. It also keeps the - * gateway token out of the browser, where it could be stolen and used to - * spend against your app's shared credit quota. + * where your instructions, tools, and business logic stay server-side, where + * users can't inspect or tamper with them, and where you can enforce your own + * auth checks, rate limits, or spend limits around the call. `token` is the + * caller's own session token, the same one the SDK already uses for every + * other call, so calling from the browser doesn't expose anything new. * * ## Models * @@ -80,8 +81,10 @@ export interface AiGatewayModule { * @example * ```typescript * // Call a model directly with the OpenAI SDK, inside a backend function + * import { createClientFromRequest } from "@base44/sdk"; * import OpenAI from "openai"; * + * const base44 = createClientFromRequest(request); * const { baseURL, token } = base44.aiGateway.connection(); * const openai = new OpenAI({ baseURL, apiKey: token }); * @@ -96,11 +99,13 @@ export interface AiGatewayModule { * @example * ```typescript * // Review a return request with a tool-using agent, inside a backend function + * import { createClientFromRequest } from "@base44/sdk"; * import { ToolLoopAgent, tool, stepCountIs, hasToolCall } from "ai"; * import { createOpenAICompatible } from "@ai-sdk/openai-compatible"; * import { z } from "zod"; * - * const request = await base44.entities.ReturnRequest.get(returnId); + * 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 }); @@ -115,7 +120,7 @@ export interface AiGatewayModule { * description: "This customer's past orders, optionally filtered by status", * inputSchema: z.object({ status: z.string().optional() }), * execute: ({ status }) => { - * const query = { customer_email: request.customer_email }; + * const query = { customer_email: returnRequest.customer_email }; * if (status) query.status = status; * return base44.entities.Order.filter(query, "-created_date", 50); * }, @@ -130,7 +135,7 @@ export interface AiGatewayModule { * stopWhen: [stepCountIs(8), hasToolCall("submitVerdict")], * }); * - * await agent.generate({ prompt: `Review this return request: ${JSON.stringify(request)}` }); + * await agent.generate({ prompt: `Review this return request: ${JSON.stringify(returnRequest)}` }); * ``` */ connection(): AiGatewayConnection; From 10158f401d30bdc5eb8594ceb2417394e1e018ca Mon Sep 17 00:00:00 2001 From: sam-prais Date: Wed, 15 Jul 2026 13:50:09 +0300 Subject: [PATCH 3/4] docs(ai-gateway): remove gated model from suggested list claude_opus_4_8 is behind a feature flag and not open to users yet. --- src/modules/ai-gateway.types.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/modules/ai-gateway.types.ts b/src/modules/ai-gateway.types.ts index b1ef1350..b45f5943 100644 --- a/src/modules/ai-gateway.types.ts +++ b/src/modules/ai-gateway.types.ts @@ -47,8 +47,7 @@ export interface AiGatewayModuleConfig { * * Build AI agents or call models directly from your app's backend functions. * Pass `'automatic'` to let Base44 choose a model, or pin a specific one such - * as `'claude_sonnet_4_6'`, `'claude_opus_4_8'`, `'gpt_5_5'`, or - * `'gemini_3_1_pro'`. + * as `'claude_sonnet_4_6'`, `'gpt_5_5'`, or `'gemini_3_1_pro'`. * * See the [`model` options on `InvokeLLM`](/developers/references/sdk/docs/type-aliases/integrations#invokellm) * for the current set of models you can use. From ef6fb20fddb5877993300468ec58ef3102d9468d Mon Sep 17 00:00:00 2001 From: sam-prais Date: Thu, 16 Jul 2026 11:20:58 +0300 Subject: [PATCH 4/4] docs(ai-gateway): address review feedback on tone, accuracy, and example length Tighten the backend-function rationale, merge the redundant Models intro sentence into the model-options pointer, correct the Authentication Modes section (no permission difference between modes, just which token is returned), note that per-user usage limits are left to the caller to build, and shorten both example tab titles. --- src/modules/ai-gateway.types.ts | 34 ++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/src/modules/ai-gateway.types.ts b/src/modules/ai-gateway.types.ts index b45f5943..c94fac71 100644 --- a/src/modules/ai-gateway.types.ts +++ b/src/modules/ai-gateway.types.ts @@ -36,28 +36,25 @@ export interface AiGatewayModuleConfig { * against the provider directly, no separate account, API key, or billing * setup with the underlying model provider required. * - * Call `connection()` from a backend function rather than the browser. That's - * where your instructions, tools, and business logic stay server-side, where - * users can't inspect or tamper with them, and where you can enforce your own - * auth checks, rate limits, or spend limits around the call. `token` is the - * caller's own session token, the same one the SDK already uses for every - * other call, so calling from the browser doesn't expose anything new. + * Call `connection()` from a backend function rather than the browser. This + * keeps your instructions, tools, and business logic server-side, and lets + * you enforce your own auth, rate, and spend limits around the call. The + * `token` it returns is the caller's regular session token, the same one + * used for every other SDK call. * * ## Models * - * Build AI agents or call models directly from your app's backend functions. - * Pass `'automatic'` to let Base44 choose a model, or pin a specific one such + * You can use any of the [models available through `InvokeLLM`](/developers/references/sdk/docs/type-aliases/integrations#invokellm). + * 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'`. * - * See the [`model` options on `InvokeLLM`](/developers/references/sdk/docs/type-aliases/integrations#invokellm) - * for the current set of models you can use. - * * ## Authentication Modes * - * This module is available to use with a client in all authentication modes: + * There's no permission difference between modes. Both just determine which + * token `connection()` returns: * - * - **Anonymous or User authentication** (`base44.aiGateway`): The gateway connection is scoped to the current user's permissions. - * - **Service role authentication** (`base44.asServiceRole.aiGateway`): The gateway connection uses the service role for backend code that needs elevated permissions. + * - **User authentication** (`base44.aiGateway`): Returns the signed-in app user's token. + * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the service-role token instead, for calling the gateway when there's no signed-in user, such as from a scheduled automation. * * ## Billing and limits * @@ -65,7 +62,8 @@ export interface AiGatewayModuleConfig { * quota your app's built-in AI features use, and isn't split per user. If the * app runs out of credits, the gateway stops working for every user of the * app until the quota resets. A request is rejected before the model runs if - * the app is out of credits. + * 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. */ @@ -79,10 +77,11 @@ export interface AiGatewayModule { * * @example * ```typescript - * // Call a model directly with the OpenAI SDK, inside a backend function + * // Call a model directly * import { createClientFromRequest } from "@base44/sdk"; * import OpenAI from "openai"; * + * // Runs inside a backend function * const base44 = createClientFromRequest(request); * const { baseURL, token } = base44.aiGateway.connection(); * const openai = new OpenAI({ baseURL, apiKey: token }); @@ -97,12 +96,13 @@ export interface AiGatewayModule { * * @example * ```typescript - * // Review a return request with a tool-using agent, inside a backend function + * // Use a tool-calling agent * import { createClientFromRequest } from "@base44/sdk"; * import { ToolLoopAgent, tool, stepCountIs, hasToolCall } from "ai"; * import { createOpenAICompatible } from "@ai-sdk/openai-compatible"; * import { z } from "zod"; * + * // 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();