plugin-ai-api 1.0.15 → 1.0.21

package/dist/server/plugin.js

@@ -43,8 +43,11 @@ module.exports = __toCommonJS(plugin_exports);
 var import_server = require("@nocobase/server");
 var import_router = require("./routes/router");
 var import_ai_api_config = __toESM(require("./resource/ai-api-config"));
+var import_ai_api_usage_monitor = __toESM(require("./resource/ai-api-usage-monitor"));
 var import_rate_limiter = require("./utils/rate-limiter");
 var import_role_permission = require("./middleware/role-permission");
+var import_validation = require("./validation");
+var import_constants = require("../constants");
 var import_dayjs = __toESM(require("dayjs"));
 var import_utc = __toESM(require("dayjs/plugin/utc"));
 var import_timezone = __toESM(require("dayjs/plugin/timezone"));
@@ -60,10 +63,27 @@ class PluginAiApiServer extends import_server.Plugin {
   async afterAdd() {
   }
   async beforeLoad() {
+    this.app.db.on("aiApiModelPrices.beforeSave", async (model) => {
+      await (0, import_validation.validateModelPrice)(this.db, model);
+    });
+    this.app.db.on("aiApiModelMetadata.beforeSave", (model) => {
+      (0, import_validation.validateModelMetadata)(model);
+    });
+    this.app.db.on("aiApiUserQuotaPolicies.beforeSave", (model) => {
+      (0, import_validation.validateQuotaPolicy)(model);
+    });
   }
   async load() {
+    this.app.use(
+      async (ctx, next) => {
+        if (ctx.path.startsWith(import_router.AI_LLM_PREFIX)) ctx.disableBodyParser = true;
+        await next();
+      },
+      { tag: "aiApiDisableBodyParser", before: "bodyParser" }
+    );
     this.app.use((0, import_router.createAiLlmRouter)(this), { after: "idp-oauth-resource-auth", before: "resourcer" });
     this.app.resourceManager.define(import_ai_api_config.default);
+    this.app.resourceManager.define(import_ai_api_usage_monitor.default);
     this.app.db.on("aiApiRolePermissions.afterSave", (model) => {
       (0, import_role_permission.invalidateRolePermissionCache)(model.get("roleName"));
     });
@@ -71,8 +91,19 @@ class PluginAiApiServer extends import_server.Plugin {
       (0, import_role_permission.invalidateRolePermissionCache)(model.get("roleName"));
     });
     this.app.acl.registerSnippet({
-      name: `pm.${this.name}.configuration`,
-      actions: ["aiApiConfig:*", "aiApiRolePermissions:*"]
+      name: import_constants.AI_API_ACL_SNIPPET,
+      actions: [
+        "aiApiConfig:*",
+        "aiApiRolePermissions:*",
+        "aiApiModelPrices:*",
+        "aiApiModelMetadata:*",
+        "aiApiUserQuotaPolicies:*",
+        "aiApiUserQuotaBuckets:list",
+        "aiApiUserQuotaBuckets:get",
+        "aiApiUsageRecords:list",
+        "aiApiUsageRecords:get",
+        "aiApiUsageMonitor:summary"
+      ]
     });
     this.gcInterval = setInterval(() => this.rateLimiter.gc(), 5 * 60 * 1e3);
     this.gcInterval.unref();
@@ -84,7 +115,9 @@ class PluginAiApiServer extends import_server.Plugin {
         values: {
           defaultAiEmployee: "",
           enabledLlmServices: [],
-          rateLimitPerMinute: 60
+          rateLimitPerMinute: 60,
+          quotaEnabled: false,
+          defaultReservationOutputTokens: 4096
         }
       });
     }

package/dist/server/resource/ai-api-config.js

@@ -29,6 +29,18 @@ __export(ai_api_config_exports, {
   default: () => ai_api_config_default
 });
 module.exports = __toCommonJS(ai_api_config_exports);
+var import_router = require("../routes/router");
+const DEFAULT_MAX_REQUEST_BODY_MB = 10;
+function coerceMaxRequestBodyMb(value) {
+  const mb = Number(value);
+  if (!Number.isSafeInteger(mb) || mb <= 0) {
+    throw new Error(`maxRequestBodyMb must be a positive integer (1-${import_router.MAX_REQUEST_BODY_MB_LIMIT}).`);
+  }
+  if (mb > import_router.MAX_REQUEST_BODY_MB_LIMIT) {
+    throw new Error(`maxRequestBodyMb cannot exceed ${import_router.MAX_REQUEST_BODY_MB_LIMIT}.`);
+  }
+  return mb;
+}
 const aiApiConfigResource = {
   name: "aiApiConfig",
   actions: {
@@ -42,6 +54,9 @@ const aiApiConfigResource = {
             defaultLlmService: "",
             enabledLlmServices: [],
             rateLimitPerMinute: 60,
+            maxRequestBodyMb: 10,
+            quotaEnabled: false,
+            defaultReservationOutputTokens: 4096,
             options: {}
           }
         });
@@ -61,6 +76,9 @@ const aiApiConfigResource = {
             defaultLlmService: values.defaultLlmService ?? "",
             enabledLlmServices: values.enabledLlmServices ?? [],
             rateLimitPerMinute: values.rateLimitPerMinute ?? 60,
+            maxRequestBodyMb: coerceMaxRequestBodyMb(values.maxRequestBodyMb ?? DEFAULT_MAX_REQUEST_BODY_MB),
+            quotaEnabled: values.quotaEnabled ?? false,
+            defaultReservationOutputTokens: values.defaultReservationOutputTokens ?? 4096,
             options: values.options ?? {}
           }
         });
@@ -71,6 +89,13 @@ const aiApiConfigResource = {
         if (values.defaultLlmService !== void 0) updateData.defaultLlmService = values.defaultLlmService;
         if (values.enabledLlmServices !== void 0) updateData.enabledLlmServices = values.enabledLlmServices;
         if (values.rateLimitPerMinute !== void 0) updateData.rateLimitPerMinute = values.rateLimitPerMinute;
+        if (values.maxRequestBodyMb !== void 0) {
+          updateData.maxRequestBodyMb = coerceMaxRequestBodyMb(values.maxRequestBodyMb);
+        }
+        if (values.quotaEnabled !== void 0) updateData.quotaEnabled = values.quotaEnabled;
+        if (values.defaultReservationOutputTokens !== void 0) {
+          updateData.defaultReservationOutputTokens = values.defaultReservationOutputTokens;
+        }
         if (values.options !== void 0) updateData.options = values.options;
         await config.update(updateData);
       }

package/dist/server/resource/ai-api-usage-monitor.js

@@ -0,0 +1,86 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ai_api_usage_monitor_exports = {};
+__export(ai_api_usage_monitor_exports, {
+  default: () => ai_api_usage_monitor_default
+});
+module.exports = __toCommonJS(ai_api_usage_monitor_exports);
+var import_sequelize = require("sequelize");
+function buildWhere(ctx) {
+  const params = ctx.action.params;
+  const where = {};
+  const start = typeof params.start === "string" ? new Date(params.start) : void 0;
+  const end = typeof params.end === "string" ? new Date(params.end) : void 0;
+  if (start && !Number.isNaN(start.getTime()) || end && !Number.isNaN(end.getTime())) {
+    const startedAt = {};
+    if (start && !Number.isNaN(start.getTime())) startedAt[import_sequelize.Op.gte] = start;
+    if (end && !Number.isNaN(end.getTime())) startedAt[import_sequelize.Op.lte] = end;
+    where.startedAt = startedAt;
+  }
+  if (params.userId !== void 0 && params.userId !== "") where.userId = params.userId;
+  if (params.resolvedService) where.resolvedService = params.resolvedService;
+  if (params.resolvedModel) where.resolvedModel = params.resolvedModel;
+  if (params.status) where.status = params.status;
+  return where;
+}
+const aiApiUsageMonitorResource = {
+  name: "aiApiUsageMonitor",
+  actions: {
+    async summary(ctx, next) {
+      const model = ctx.db.getCollection("aiApiUsageRecords").model;
+      const where = buildWhere(ctx);
+      const totals = await model.findOne({
+        attributes: [
+          [(0, import_sequelize.fn)("COUNT", (0, import_sequelize.col)("id")), "requestCount"],
+          [(0, import_sequelize.fn)("COALESCE", (0, import_sequelize.fn)("SUM", (0, import_sequelize.col)("inputTokens")), 0), "inputTokens"],
+          [(0, import_sequelize.fn)("COALESCE", (0, import_sequelize.fn)("SUM", (0, import_sequelize.col)("outputTokens")), 0), "outputTokens"],
+          [(0, import_sequelize.fn)("COALESCE", (0, import_sequelize.fn)("SUM", (0, import_sequelize.col)("totalTokens")), 0), "totalTokens"]
+        ],
+        where,
+        raw: true
+      });
+      const costs = await model.findAll({
+        attributes: ["currency", [(0, import_sequelize.fn)("COALESCE", (0, import_sequelize.fn)("SUM", (0, import_sequelize.col)("estimatedCost")), 0), "totalCost"]],
+        where: { ...where, estimatedCost: { [import_sequelize.Op.ne]: null } },
+        group: ["currency"],
+        raw: true
+      });
+      ctx.body = {
+        requestCount: Number((totals == null ? void 0 : totals.requestCount) ?? 0),
+        inputTokens: Number((totals == null ? void 0 : totals.inputTokens) ?? 0),
+        outputTokens: Number((totals == null ? void 0 : totals.outputTokens) ?? 0),
+        totalTokens: Number((totals == null ? void 0 : totals.totalTokens) ?? 0),
+        costsByCurrency: costs.map((item) => ({
+          currency: item.currency || "USD",
+          totalCost: String(item.totalCost ?? 0)
+        }))
+      };
+      await next();
+    }
+  }
+};
+var ai_api_usage_monitor_default = aiApiUsageMonitorResource;

package/dist/server/routes/agent-completions.js

@@ -35,6 +35,7 @@ var import_role_permission = require("../middleware/role-permission");
 var import_streaming = require("../utils/streaming");
 var import_ai_employee_runtime = require("../utils/ai-employee-runtime");
 var import_usage = require("../usage");
+var import_app_observability = require("../utils/app-observability");
 async function handleAgentCompletions(ctx, plugin) {
   var _a;
   const body = ctx.request.body;
@@ -201,74 +202,83 @@ async function handleAgentCompletions(ctx, plugin) {
           ctx.res.write(args[0]);
         }
       };
-      ctx.res.write = (data) => {
+      const processSseFrame = (frame) => {
         var _a2;
-        pendingSse += typeof data === "string" ? data : data.toString("utf8");
-        const frames = pendingSse.split("\n\n");
-        pendingSse = frames.pop() || "";
-        for (const frame of frames) {
-          for (const line of frame.split("\n")) {
-            const trimmed = line.trim();
-            if (!trimmed.startsWith("data: ")) continue;
-            const jsonStr = trimmed.substring(6);
-            if (!jsonStr) continue;
-            try {
-              const event = JSON.parse(jsonStr);
-              if (event.type === "content" && event.body) {
+        for (const line of frame.split("\n")) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith("data: ")) continue;
+          const jsonStr = trimmed.substring(6);
+          if (!jsonStr) continue;
+          try {
+            const event = JSON.parse(jsonStr);
+            if (event.type === "content" && event.body) {
+              (0, import_app_observability.markAiApiFirstProviderOutput)(ctx);
+              originalWrite(
+                (0, import_openai_format.formatSSE)(
+                  (0, import_openai_format.toOpenAIStreamChunk)({
+                    id: completionId,
+                    model: body.model,
+                    delta: { content: String(event.body) }
+                  })
+                )
+              );
+            } else if (event.type === "tool_call_chunks" && Array.isArray(event.body)) {
+              const chunks = toOpenAIToolCallChunks(event.body);
+              if (chunks.length) {
+                (0, import_app_observability.markAiApiFirstProviderOutput)(ctx);
+                sawToolCalls = true;
                 originalWrite(
                   (0, import_openai_format.formatSSE)(
                     (0, import_openai_format.toOpenAIStreamChunk)({
                       id: completionId,
                       model: body.model,
-                      delta: { content: String(event.body) }
+                      delta: { tool_calls: chunks }
                     })
                   )
                 );
-              } else if (event.type === "tool_call_chunks" && Array.isArray(event.body)) {
-                const chunks = toOpenAIToolCallChunks(event.body);
-                if (chunks.length) {
-                  sawToolCalls = true;
-                  originalWrite(
-                    (0, import_openai_format.formatSSE)(
-                      (0, import_openai_format.toOpenAIStreamChunk)({
-                        id: completionId,
-                        model: body.model,
-                        delta: { tool_calls: chunks }
-                      })
-                    )
-                  );
-                }
-              } else if (!sawToolCalls && event.type === "tool_calls" && Array.isArray((_a2 = event.body) == null ? void 0 : _a2.toolCalls)) {
-                const chunks = toOpenAIToolCallChunks(event.body.toolCalls);
-                if (chunks.length) {
-                  sawToolCalls = true;
-                  originalWrite(
-                    (0, import_openai_format.formatSSE)(
-                      (0, import_openai_format.toOpenAIStreamChunk)({
-                        id: completionId,
-                        model: body.model,
-                        delta: { tool_calls: chunks }
-                      })
-                    )
-                  );
-                }
-              } else if (event.type === "error" && event.body) {
+              }
+            } else if (!sawToolCalls && event.type === "tool_calls" && Array.isArray((_a2 = event.body) == null ? void 0 : _a2.toolCalls)) {
+              const chunks = toOpenAIToolCallChunks(event.body.toolCalls);
+              if (chunks.length) {
+                (0, import_app_observability.markAiApiFirstProviderOutput)(ctx);
+                sawToolCalls = true;
                 originalWrite(
-                  (0, import_openai_format.formatSSE)({
-                    error: {
-                      message: String(event.body),
-                      type: "server_error",
-                      code: "agent_error"
-                    }
-                  })
+                  (0, import_openai_format.formatSSE)(
+                    (0, import_openai_format.toOpenAIStreamChunk)({
+                      id: completionId,
+                      model: body.model,
+                      delta: { tool_calls: chunks }
+                    })
+                  )
                 );
               }
-            } catch {
+            } else if (event.type === "error" && event.body) {
+              originalWrite(
+                (0, import_openai_format.formatSSE)({
+                  error: {
+                    message: String(event.body),
+                    type: "server_error",
+                    code: "agent_error"
+                  }
+                })
+              );
             }
+          } catch {
           }
         }
+      };
+      ctx.res.write = (data) => {
+        pendingSse += typeof data === "string" ? data : data.toString("utf8");
+        const frames = pendingSse.split("\n\n");
+        pendingSse = frames.pop() || "";
+        for (const frame of frames) processSseFrame(frame);
         return true;
       };
+      const flushPendingSse = () => {
+        if (!pendingSse.trim()) return;
+        processSseFrame(pendingSse);
+        pendingSse = "";
+      };
       try {
         const aiEmployee = new AIEmployee(
           (0, import_ai_employee_runtime.createAIEmployeeOptions)(ctx, employeeRecord, sessionId, {
@@ -291,6 +301,7 @@ async function handleAgentCompletions(ctx, plugin) {
         ctx.req.off("aborted", abortAgent);
         ctx.res.off("close", abortAgent);
         if (streamSucceeded && !ctx.res.destroyed) {
+          flushPendingSse();
           originalWrite(
             (0, import_openai_format.formatSSE)(
               (0, import_openai_format.toOpenAIStreamChunk)({

package/dist/server/routes/auth.js

@@ -57,7 +57,17 @@ async function authenticateBearer(ctx) {
         const rolesRepository2 = ctx.db.getRepository("users.roles", ctx.state.currentUser.id);
         const roles2 = await rolesRepository2.find({ fields: ["name"] });
         const roleNames2 = roles2.map((role) => role.name);
-        ctx.state.currentRole = roleNames2.includes(requestedRole) ? requestedRole : roleNames2[0];
+        if (requestedRole && !roleNames2.includes(requestedRole)) {
+          ctx.status = 403;
+          ctx.body = (0, import_openai_format.toOpenAIError)(
+            403,
+            `Requested role '${requestedRole}' is not assigned to this user`,
+            "permission_denied",
+            "role_not_permitted"
+          );
+          return false;
+        }
+        ctx.state.currentRole = requestedRole || roleNames2[0];
         ctx.state.currentRoles = ctx.state.currentRole ? [ctx.state.currentRole] : roleNames2;
       }
       return true;

package/dist/server/routes/chat-completions.js

@@ -27,8 +27,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var chat_completions_exports = {};
 __export(chat_completions_exports, {
   applyProviderRequestParameters: () => applyProviderRequestParameters,
+  findContentBlockProblem: () => findContentBlockProblem,
+  findMessageProblem: () => findMessageProblem,
   getProviderRequestParameters: () => getProviderRequestParameters,
-  handleChatCompletions: () => handleChatCompletions
+  handleChatCompletions: () => handleChatCompletions,
+  normalizeMessageContent: () => normalizeMessageContent
 });
 module.exports = __toCommonJS(chat_completions_exports);
 var import_openai_format = require("../utils/openai-format");
@@ -36,6 +39,8 @@ var import_resolve_service = require("../utils/resolve-service");
 var import_streaming = require("../utils/streaming");
 var import_role_permission = require("../middleware/role-permission");
 var import_usage = require("../usage");
+var import_billing = require("../billing");
+var import_app_observability = require("../utils/app-observability");
 async function handleChatCompletions(ctx, plugin) {
   var _a;
   const body = ctx.request.body;
@@ -49,6 +54,28 @@ async function handleChatCompletions(ctx, plugin) {
     ctx.body = (0, import_openai_format.toOpenAIError)(400, "'messages' must be a non-empty array", "invalid_request_error", "missing_messages");
     return;
   }
+  const messageProblem = findMessageProblem(body.messages);
+  if (messageProblem) {
+    ctx.status = 400;
+    ctx.body = (0, import_openai_format.toOpenAIError)(
+      400,
+      `Invalid messages[${messageProblem.index}]: ${messageProblem.reason}.`,
+      "invalid_request_error",
+      "invalid_message"
+    );
+    return;
+  }
+  const blockProblem = findContentBlockProblem(body.messages);
+  if (blockProblem) {
+    ctx.status = 400;
+    ctx.body = (0, import_openai_format.toOpenAIError)(
+      400,
+      `Invalid content block in messages[${blockProblem.index}]: ${blockProblem.reason}.`,
+      "invalid_request_error",
+      "invalid_content_block"
+    );
+    return;
+  }
   if (body.n !== void 0 && body.n !== null && body.n !== 1) {
     ctx.status = 400;
     ctx.body = (0, import_openai_format.toOpenAIError)(
@@ -111,6 +138,7 @@ async function handleChatCompletions(ctx, plugin) {
       ctx.body = (0, import_openai_format.toOpenAIError)(500, `Provider '${service.provider}' not registered`, "server_error");
       return;
     }
+    await (0, import_billing.prepareLlmBilling)(ctx, resolved);
     const providerRequestParameters = getProviderRequestParameters(body);
     const modelOptions = {
       model: modelId,
@@ -155,7 +183,7 @@ async function handleChatCompletions(ctx, plugin) {
     }
     const langchainMessages = messages.map((msg) => {
       const role = msg.role === "assistant" ? "ai" : msg.role;
-      const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);
+      const content = normalizeMessageContent(msg.content);
       if (msg.role === "assistant" && msg.tool_calls) {
         return {
           role,
@@ -173,6 +201,7 @@ async function handleChatCompletions(ctx, plugin) {
     const baseModel = provider.createModel();
     applyProviderRequestParameters(baseModel, providerRequestParameters);
     const chatModel = bindRequestTools(baseModel, body.tools, body.tool_choice, providerRequestParameters);
+    (0, import_billing.markLlmProviderAttempted)(ctx);
     if (stream) {
       await handleStreamingCompletion(
         ctx,
@@ -195,8 +224,15 @@ async function handleChatCompletions(ctx, plugin) {
   } catch (err) {
     ctx.log.error("AI API chat completions error:", err);
     if (!ctx.res.headersSent) {
-      ctx.status = 500;
-      ctx.body = (0, import_openai_format.toOpenAIError)(500, getErrorMessage(err, "Internal server error"), "server_error");
+      const isQuotaError = err instanceof import_billing.AiApiQuotaError;
+      ctx.status = isQuotaError ? 429 : 500;
+      if (isQuotaError) ctx.set("X-RateLimit-Reason", err.code);
+      ctx.body = (0, import_openai_format.toOpenAIError)(
+        ctx.status,
+        getErrorMessage(err, "Internal server error"),
+        isQuotaError ? "quota_error" : "server_error",
+        isQuotaError ? err.code : void 0
+      );
     }
   }
 }
@@ -258,6 +294,7 @@ async function handleStreamingCompletion(ctx, chatModel, messages, completionId,
         content = (textPart == null ? void 0 : textPart.text) || "";
       }
       if (content) {
+        (0, import_app_observability.markAiApiFirstProviderOutput)(ctx);
         await (0, import_streaming.writeResponse)(
           ctx,
           (0, import_openai_format.formatSSE)(
@@ -271,6 +308,7 @@ async function handleStreamingCompletion(ctx, chatModel, messages, completionId,
       }
       const toolCallChunks = normalizeToolCallChunks(chunk.tool_call_chunks);
       if (toolCallChunks.length) {
+        (0, import_app_observability.markAiApiFirstProviderOutput)(ctx);
         finishReason = "tool_calls";
         await (0, import_streaming.writeResponse)(
           ctx,
@@ -297,6 +335,7 @@ async function handleStreamingCompletion(ctx, chatModel, messages, completionId,
     (0, import_usage.setAiApiUsageResult)(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
     ctx.state.aiApiStreamResult = { succeeded: true, id: completionId };
   } catch (err) {
+    const cancelled = (0, import_streaming.isClientDisconnected)(ctx, err);
     ctx.log.error("AI API streaming error:", err);
     if (!ctx.res.destroyed && !ctx.res.writableEnded) {
       await (0, import_streaming.writeResponse)(
@@ -310,7 +349,11 @@ async function handleStreamingCompletion(ctx, chatModel, messages, completionId,
       );
     }
     (0, import_usage.setAiApiUsageResult)(ctx, usage, { gatewayResponseId: completionId, providerRequestId });
-    ctx.state.aiApiStreamResult = { succeeded: false, id: completionId, errorCode: "stream_error" };
+    ctx.state.aiApiStreamResult = {
+      succeeded: false,
+      id: completionId,
+      errorCode: cancelled ? "client_disconnected" : "stream_error"
+    };
   } finally {
     requestAbort.dispose();
     if (!ctx.res.writableEnded && !ctx.res.destroyed) ctx.res.end();
@@ -319,6 +362,111 @@ async function handleStreamingCompletion(ctx, chatModel, messages, completionId,
 function getErrorMessage(error, fallback) {
   return error instanceof Error && error.message ? error.message : fallback;
 }
+const SUPPORTED_CONTENT_BLOCK_TYPES = /* @__PURE__ */ new Set(["text", "image_url"]);
+const BASE64_DATA_URL_PATTERN = /^data:(\w+\/\w+);base64,([A-Za-z0-9+/]+=*)$/;
+function isDecodableBase64(payload) {
+  try {
+    return Buffer.from(payload, "base64").toString("base64") === payload;
+  } catch {
+    return false;
+  }
+}
+const SUPPORTED_MESSAGE_ROLES = /* @__PURE__ */ new Set(["system", "developer", "user", "human", "assistant", "ai", "tool"]);
+function findMessageProblem(messages) {
+  for (const [index, message] of messages.entries()) {
+    if (!isRecord(message)) return { index, reason: "each message must be an object" };
+    const role = typeof message.role === "string" ? message.role : void 0;
+    if (!role) return { index, reason: "each message requires a string 'role' field" };
+    if (!SUPPORTED_MESSAGE_ROLES.has(role)) {
+      return {
+        index,
+        reason: `role '${role}' is not supported \u2014 use one of ${[...SUPPORTED_MESSAGE_ROLES].join(", ")}`
+      };
+    }
+    if (role === "tool" && typeof message.tool_call_id !== "string") {
+      return { index, reason: "a 'tool' message requires a string 'tool_call_id' field" };
+    }
+    const { content } = message;
+    const hasToolCalls = Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
+    if (content === void 0 || content === null) {
+      if ((role === "assistant" || role === "ai") && hasToolCalls) continue;
+      return { index, reason: "each message requires a 'content' field" };
+    }
+    if (typeof content !== "string" && !Array.isArray(content)) {
+      return { index, reason: "'content' must be a string or an array of content blocks" };
+    }
+  }
+  return void 0;
+}
+function findContentBlockProblem(messages) {
+  for (const [index, message] of messages.entries()) {
+    const content = isRecord(message) ? message.content : void 0;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (typeof block === "string") continue;
+      const reason = describeContentBlockProblem(block);
+      if (reason) return { index, reason };
+    }
+  }
+  return void 0;
+}
+function describeContentBlockProblem(block) {
+  if (!isRecord(block)) return "each content block must be an object";
+  const type = typeof block.type === "string" ? block.type : void 0;
+  if (!type) return "each content block requires a 'type' field";
+  if (!SUPPORTED_CONTENT_BLOCK_TYPES.has(type)) {
+    return `content block type '${type}' is not supported \u2014 this gateway forwards 'text' and 'image_url' only. Send documents as text, or inline them as an 'image_url' data URL if the model reads images`;
+  }
+  if (type === "text") {
+    return typeof block.text === "string" ? void 0 : "a 'text' block requires a string 'text' field";
+  }
+  return describeImageUrlProblem(block.image_url);
+}
+function describeImageUrlProblem(imageUrl) {
+  const url = typeof imageUrl === "string" ? imageUrl : isRecord(imageUrl) ? imageUrl.url : void 0;
+  if (typeof url !== "string" || url === "") {
+    return "an 'image_url' block requires a non-empty 'image_url.url' string";
+  }
+  if (url.startsWith("data:")) {
+    const match = BASE64_DATA_URL_PATTERN.exec(url);
+    if (!match) {
+      return `malformed base64 data URL. Expected 'data:<mime-type>;base64,<base64>' with standard base64 (no whitespace or URL-safe characters)`;
+    }
+    const mimeType = match[1].toLowerCase();
+    if (!mimeType.startsWith("image/")) {
+      return `data URL MIME type '${mimeType}' is not an image. Only 'image/*' data URLs are forwarded, because providers reject or ignore other types on an 'image_url' block`;
+    }
+    if (!isDecodableBase64(match[2])) {
+      return `base64 payload is not decodable. Check the padding and length \u2014 the data must be a multiple of 4 characters with at most two trailing '='`;
+    }
+    return void 0;
+  }
+  let protocol;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    return `'${url}' is not a valid URL. Use an http(s) URL or a base64 data URL`;
+  }
+  if (protocol !== "http:" && protocol !== "https:") {
+    return `URL protocol '${protocol}' is not supported. Use an http(s) URL or a base64 data URL`;
+  }
+  return void 0;
+}
+function normalizeMessageContent(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map((block) => {
+      if (typeof block === "string") return { type: "text", text: block };
+      const record = block;
+      if ((record == null ? void 0 : record.type) === "image_url" && typeof record.image_url === "string") {
+        return { ...record, image_url: { url: record.image_url } };
+      }
+      return record;
+    });
+  }
+  if (content === null || content === void 0) return "";
+  return JSON.stringify(content);
+}
 const GATEWAY_MANAGED_PARAMETERS = /* @__PURE__ */ new Set(["model", "messages", "tools", "tool_choice", "stream", "n"]);
 function getProviderRequestParameters(body) {
   return Object.fromEntries(
@@ -389,6 +537,9 @@ function serializeToolArguments(value) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   applyProviderRequestParameters,
+  findContentBlockProblem,
+  findMessageProblem,
   getProviderRequestParameters,
-  handleChatCompletions
+  handleChatCompletions,
+  normalizeMessageContent
 });