@base44-preview/sdk 0.8.52-pr.296.452f327 → 0.8.52-pr.297.05dc385

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

@@ -51,15 +51,15 @@ export interface AiGatewayModuleConfig {
  * against the provider directly, no separate account, API key, or billing
  * setup with the underlying model provider required.
  *
- * By default, `connection()` uses the OpenAI-compatible provider. Pass
- * `{ provider: "typesafe" }` to connect to TypeSafe for structured evaluations
- * with `@ai-sdk/typesafe-ai`.
+ * `connection()` takes an optional `provider`, and each provider serves a different API:
+ *
+ * - `openai` (default): OpenAI-compatible chat completions and image endpoints.
+ * - `typesafe`: structured evaluations with the `jev` model.
  *
  * 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.
+ * you enforce your own auth, rate, and spend limits around the call. Which
+ * token it returns depends on the authentication mode, described below.
  *
  * ## OpenAI-compatible models
  *
@@ -76,13 +76,23 @@ export interface AiGatewayModuleConfig {
  * `'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).
  *
+ * ## Structured evaluations
+ *
+ * The `typesafe` provider runs the `jev` evaluation model through
+ * `@ai-sdk/typesafe-ai` and `experimental_evaluate` from the `ai` package,
+ * version 7.0.105 or later. Pass `evaluationModel("jev")`; the gateway rejects
+ * other model IDs, such as `"jev-latest"`. Give it some app state and a set of
+ * questions, each a `choice`, `score`, or `boolean`. Choice and score answers
+ * come back with `probabilities` per option; boolean answers with a single
+ * `probability` of `true`. Use it to classify, score, or route records, then
+ * apply your own thresholds and actions in code.
+ *
  * ## Authentication Modes
  *
- * There's no permission difference between modes. Both just determine which
- * token `connection()` returns:
+ * The mode determines which token `connection()` returns:
  *
  * - **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.
+ * - **Service role authentication** (`base44.asServiceRole.aiGateway`): Returns the service-role token instead. Use it from backend functions: apps that restrict Core integrations, the default for new apps, reject user-token gateway calls on public apps. It also works when there's no signed-in user, such as from a scheduled automation.
  *
  * ## Billing and limits
  *
@@ -111,7 +121,7 @@ export interface AiGatewayModule {
      *
      * // Runs inside a backend function
      * const base44 = createClientFromRequest(request);
-     * const { baseURL, token, headers } = base44.aiGateway.connection();
+     * const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
      * const openai = new OpenAI({ baseURL, apiKey: token, defaultHeaders: headers });
      *
      * const response = await openai.chat.completions.create({
@@ -133,7 +143,7 @@ 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, headers } = base44.aiGateway.connection();
+     * const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
      * // Point any OpenAI-compatible client at `baseURL` with `apiKey: token` and `headers`.
      * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token, headers });
      *
@@ -174,7 +184,7 @@ export interface AiGatewayModule {
      *
      * // Runs inside a backend function
      * const base44 = createClientFromRequest(request);
-     * const { baseURL, token, headers } = base44.aiGateway.connection();
+     * const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection();
      * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token, headers });
      *
      * const { image } = await generateImage({
@@ -187,6 +197,45 @@ export interface AiGatewayModule {
      * const file = new File([image.uint8Array], "lighthouse.png", { type: image.mediaType });
      * const { file_url } = await base44.integrations.Core.UploadFile({ file });
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Route a support ticket with a structured evaluation
+     * import { createClientFromRequest } from "@base44/sdk";
+     * import { experimental_evaluate as evaluate } from "ai";
+     * import { createTypeSafeAi } from "@ai-sdk/typesafe-ai";
+     *
+     * // Runs inside a backend function
+     * const base44 = createClientFromRequest(request);
+     * const { baseURL, token, headers } = base44.asServiceRole.aiGateway.connection({ provider: "typesafe" });
+     * const typesafe = createTypeSafeAi({ baseURL, apiKey: token, headers });
+     *
+     * const { answers, providerMetadata } = await evaluate({
+     *   model: typesafe.evaluationModel("jev"),
+     *   maxRetries: 0, // Avoid automatic replays of billed requests
+     *   state: { message: "Please refund today's duplicate charge." },
+     *   questions: {
+     *     department: {
+     *       type: "choice",
+     *       instructions: "Which team should handle this?",
+     *       criteria: { billing: "Payments and refunds", support: "Other requests" },
+     *     },
+     *     urgency: {
+     *       type: "score",
+     *       instructions: "How urgent is this?",
+     *       criteria: ["No deadline", "Requested today", "Immediate emergency"],
+     *     },
+     *     refund: { type: "boolean", instructions: "Is a refund explicitly requested?" },
+     *   },
+     * });
+     *
+     * // answers.department → { type: "choice", choice: "billing", probabilities: { billing: 0.97, support: 0.03 } }
+     * // answers.urgency    → { type: "score", score: 1.2, probabilities: { 0: 0.1, 1: 0.6, 2: 0.3 } }
+     * // answers.refund     → { type: "boolean", probability: 0.99 }
+     * // Choice and score confidence is in providerMetadata.typesafe.confidence
+     * // Pick your own thresholds and act on them in code
+     * const autoRefund = answers.department.choice === "billing" && answers.refund.probability > 0.9;
+     * ```
      */
     connection(options?: AiGatewayConnectionOptions): AiGatewayConnection;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44-preview/sdk",
-  "version": "0.8.52-pr.296.452f327",
+  "version": "0.8.52-pr.297.05dc385",
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",