docs(ai-gateway): publish AI Gateway module reference

scripts/mintlify-post-processing/types-to-delete-after-processing.json

@@ -1,4 +1,5 @@
 [
+  "AiGatewayConnection",
   "DeleteManyResult",
   "DeleteResult",
   "ImportResult",

scripts/mintlify-post-processing/types-to-expose.json

@@ -2,6 +2,8 @@
   "AgentName",
   "AgentNameRegistry",
   "AgentsModule",
+  "AiGatewayConnection",
+  "AiGatewayModule",
   "AnalyticsModule",
   "AppLogsModule",
   "AuthModule",

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,28 +27,75 @@ 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 {
   /**
    * Gets the connection details for the Base44 AI Gateway.
    *
    * 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";