@neetru/sdk 3.2.2 → 3.3.0

package/dist/index.cjs

@@ -21,12 +21,22 @@ var init_errors = __esm({
       code;
       status;
       requestId;
-      constructor(code, message, status, requestId) {
+      /**
+       * Motivo semântico opcional propagado pelo Core no corpo do erro (campo
+       * `reason` no TOPO do body, fora de `error`). Usado principalmente pelo 503
+       * de lease de DB, onde `reason` discrimina o estado do ambiente
+       * (`suspended` | `archived` | `revoked` | `provisioning` | `degraded` |
+       * `no_route` | `expired`). Camadas superiores (ex.: `db/sql`) mapeiam isso
+       * para um `NeetruDbErrorCode` mais específico (recuperável vs não).
+       */
+      reason;
+      constructor(code, message, status, requestId, reason) {
         super(message);
         this.name = "NeetruError";
         this.code = code;
         this.status = status;
         this.requestId = requestId;
+        this.reason = reason;
         Object.setPrototypeOf(this, _NeetruError.prototype);
       }
     };
@@ -197,16 +207,22 @@ async function httpRequest(config, opts) {
     const body = await safeJson(res);
     let code = statusToCode(res.status);
     let message = `HTTP ${res.status}`;
-    if (body && typeof body === "object" && "error" in body) {
+    let reason;
+    if (body && typeof body === "object") {
       const errField = body.error;
       if (typeof errField === "string") {
         message = errField;
       } else if (errField && typeof errField === "object") {
         if (typeof errField.code === "string") code = errField.code;
         if (typeof errField.message === "string") message = errField.message;
+        if (typeof errField.reason === "string") reason = errField.reason;
+      } else {
+        if (typeof body.code === "string") code = body.code;
+        if (typeof body.message === "string") message = body.message;
       }
+      if (typeof body.reason === "string") reason = body.reason;
     }
-    const err = new exports.NeetruError(code, message, res.status, requestId);
+    const err = new exports.NeetruError(code, message, res.status, requestId, reason);
     lastError = err;
     const isRetryable = RETRYABLE_CODES.has(code);
     if (isRetryable && attempt < maxRetries) {
@@ -277,8 +293,98 @@ var init_db_errors = __esm({
   }
 });
 
+// src/db/sql/resilient-pool.ts
+function isResilientPool(x) {
+  return typeof x === "object" && x !== null && x[RESILIENT_POOL_BRAND] === true;
+}
+function isConnectionEstablishmentError(err) {
+  const code = err && typeof err === "object" && "code" in err ? err.code : void 0;
+  if (code === "ECONNREFUSED" || code === "ETIMEDOUT" || code === "ENOTFOUND" || code === "EHOSTUNREACH" || code === "EAI_AGAIN") {
+    return true;
+  }
+  if (typeof code === "string") {
+    const upper = code.toUpperCase();
+    if (upper === "CERT_HAS_EXPIRED" || upper.startsWith("ERR_SSL") || upper.startsWith("ERR_TLS") || upper.includes("CERTIFICATE_EXPIRED")) {
+      return true;
+    }
+  }
+  const rawMessage = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  const message = rawMessage.toLowerCase();
+  if (message.length === 0) return false;
+  if (message.includes("certificate expired") || message.includes("certificate has expired") || message.includes("cert_has_expired") || message.includes("alert certificate expired") || message.includes("err_ssl") || message.includes("sslv3 alert") || message.includes("tlsv1 alert")) {
+    return true;
+  }
+  if (message.includes("econnrefused") || message.includes("etimedout") || message.includes("enotfound") || message.includes("ehostunreach") || message.includes("getaddrinfo")) {
+    return true;
+  }
+  return false;
+}
+function createResilientPool(initialInner) {
+  const state = { current: initialInner };
+  let reLease = null;
+  const controls = {
+    __neetruSwapInner(newInner) {
+      const old = state.current;
+      state.current = newInner;
+      return old;
+    },
+    __neetruGetInner() {
+      return state.current;
+    },
+    __neetruSetReLease(fn) {
+      reLease = fn;
+    }
+  };
+  const invokeQuery = (pool, args) => pool.query(...args);
+  const wrappedQuery = (...args) => {
+    if (args.length > 0 && typeof args[args.length - 1] === "function") {
+      return invokeQuery(state.current, args);
+    }
+    return (async () => {
+      try {
+        return await invokeQuery(state.current, args);
+      } catch (err) {
+        const fn = reLease;
+        if (fn === null || !isConnectionEstablishmentError(err)) {
+          throw err;
+        }
+        try {
+          await fn();
+        } catch {
+          throw err;
+        }
+        return await invokeQuery(state.current, args);
+      }
+    })();
+  };
+  const target = Object.create(Object.getPrototypeOf(initialInner));
+  const proxy = new Proxy(target, {
+    get(_t, prop) {
+      if (prop === RESILIENT_POOL_BRAND) return true;
+      if (prop === "__neetruSwapInner") return controls.__neetruSwapInner;
+      if (prop === "__neetruGetInner") return controls.__neetruGetInner;
+      if (prop === "__neetruSetReLease") return controls.__neetruSetReLease;
+      if (prop === "query") return wrappedQuery;
+      if (prop === "constructor") {
+        return state.current.constructor;
+      }
+      const current = state.current;
+      const value = Reflect.get(current, prop, current);
+      return typeof value === "function" ? value.bind(current) : value;
+    }
+  });
+  return proxy;
+}
+var RESILIENT_POOL_BRAND;
+var init_resilient_pool = __esm({
+  "src/db/sql/resilient-pool.ts"() {
+    RESILIENT_POOL_BRAND = /* @__PURE__ */ Symbol.for("neetru.sdk.resilientPool");
+  }
+});
+
 // src/db/sql/lease.ts
 function hasConnectionChanged(oldLease, newLease) {
+  if (!oldLease) return true;
   return oldLease.leaseId !== newLease.leaseId || oldLease.credentialVersion !== newLease.credentialVersion || oldLease.host !== newLease.host || oldLease.port !== newLease.port || oldLease.dbName !== newLease.dbName || oldLease.user !== newLease.user || oldLease.password !== newLease.password || oldLease.sslca !== newLease.sslca || oldLease.clientCert !== newLease.clientCert || oldLease.clientKey !== newLease.clientKey;
 }
 function mapPoolError(err) {
@@ -306,14 +412,31 @@ var RENEWAL_THRESHOLD, MIN_RENEWAL_DELAY_MS, SqlLeaseManager;
 var init_lease = __esm({
   "src/db/sql/lease.ts"() {
     init_db_errors();
+    init_resilient_pool();
     RENEWAL_THRESHOLD = 0.8;
     MIN_RENEWAL_DELAY_MS = 3e4;
     SqlLeaseManager = class {
+      /**
+       * Lease atual. `null` no modo LAZY antes da 1ª query (o 1º lease é adiado —
+       * ver `_ensureInitialLease`). Após a 1ª aquisição, sempre não-nulo.
+       */
       _lease;
       _pool;
       _orm;
       _renewalTimer = null;
       _closed = false;
+      /**
+       * Promessa de re-lease REATIVO em voo — coalesce chamadas concorrentes
+       * (N queries falhando ao mesmo tempo disparam UM único re-lease). Ver
+       * `_reactiveReLease`.
+       */
+      _reLeaseInFlight = null;
+      /**
+       * Promessa da aquisição do LEASE INICIAL em voo (modo lazy) — coalesce as
+       * N primeiras queries concorrentes num único fetch. `null` quando não há
+       * aquisição inicial pendente. Ver `_ensureInitialLease`.
+       */
+      _initInFlight = null;
       _deps;
       constructor(lease, pool, orm, deps) {
         this._lease = lease;
@@ -323,7 +446,7 @@ var init_lease = __esm({
           ...deps,
           now: deps.now ?? (() => Date.now())
         };
-        this._scheduleRenewal();
+        if (this._lease) this._scheduleRenewal();
       }
       // ─── Superfície pública (NeetruSqlClient) ──────────────────────────────────
       get orm() {
@@ -361,6 +484,7 @@ var init_lease = __esm({
        * usa `MIN_RENEWAL_DELAY_MS` como fallback seguro.
        */
       _calcRenewalDelayMs() {
+        if (!this._lease) return MIN_RENEWAL_DELAY_MS;
         const expiresAtMs = Date.parse(this._lease.expiresAt);
         if (!Number.isFinite(expiresAtMs)) return MIN_RENEWAL_DELAY_MS;
         const now = this._deps.now();
@@ -384,6 +508,8 @@ var init_lease = __esm({
       }
       async _doRenew() {
         if (this._closed) return;
+        const currentLease = this._lease;
+        if (!currentLease) return;
         try {
           const withDb = (o) => {
             if (this._deps.database !== void 0) o.database = this._deps.database;
@@ -391,7 +517,7 @@ var init_lease = __esm({
           };
           let newLease;
           try {
-            newLease = await this._deps.fetchLease(withDb({ leaseId: this._lease.leaseId }));
+            newLease = await this._deps.fetchLease(withDb({ leaseId: currentLease.leaseId }));
           } catch (renewErr) {
             newLease = await this._deps.fetchLease(withDb({}));
           }
@@ -408,6 +534,114 @@ var init_lease = __esm({
         }
         this._scheduleRenewal();
       }
+      // ─── Re-lease REATIVO (P1.5) ───────────────────────────────────────────────
+      /**
+       * Recuperação REATIVA: chamado pelo wrapper resiliente (`resilient-pool.ts`)
+       * quando uma query plana falha num erro de ESTABELECIMENTO de conexão (cert
+       * mTLS expirado no meio de uma request, ou timer de renovação que não
+       * disparou). Emite um lease NOVO e faz o swap do pool interno do wrapper com
+       * o certificado fresco; o wrapper então re-tenta a query 1x no pool novo.
+       *
+       * Vai DIRETO ao lease novo (sem `leaseId`) — a conexão falhou porque o
+       * certificado do lease atual está ruim, então `renew` (que depende do lease
+       * antigo estar vivo) não é o caminho mais robusto. Emitir do zero é o que já
+       * cura o death-spiral no caminho proativo (ver `_doRenew`).
+       *
+       * Coalesce concorrência: N queries falhando ao mesmo tempo compartilham UM
+       * único re-lease (não N leases). Após o swap, cada query re-tenta no pool
+       * vigente.
+       *
+       * NÃO engole erro: se o re-lease falhar, propaga — o wrapper então relança o
+       * erro ORIGINAL da query pro consumer.
+       */
+      async _reactiveReLease() {
+        if (this._closed) {
+          throw new exports.NeetruDbError(
+            "db_unavailable",
+            "SqlLeaseManager foi fechado \u2014 re-lease reativo abortado."
+          );
+        }
+        if (this._reLeaseInFlight !== null) return this._reLeaseInFlight;
+        const run = (async () => {
+          const withDb = (o) => {
+            if (this._deps.database !== void 0) o.database = this._deps.database;
+            return o;
+          };
+          const fresh = await this._deps.fetchLease(withDb({}));
+          await this._swapPool(fresh);
+        })();
+        this._reLeaseInFlight = run;
+        try {
+          await run;
+        } finally {
+          this._reLeaseInFlight = null;
+        }
+      }
+      // ─── Lease INICIAL lazy (motor de ambientes suspenso) ──────────────────────
+      /**
+       * Adquire o LEASE INICIAL sob demanda (modo lazy). Chamado pelo pool "adiado"
+       * (`createDeferredPool`) na 1ª query/transação — nunca no boot do módulo.
+       *
+       * Fluxo:
+       *   1. Se já há lease (`_lease != null`), devolve o pool REAL interno vigente
+       *      (idempotente — chamadas após a 1ª aquisição são no-op de fetch).
+       *   2. Busca o 1º lease no Core (com `database` se houver — contrato C-H).
+       *   3. Cria o pool REAL e faz o swap no wrapper resiliente (`__neetruSwapInner`)
+       *      pra que as queries seguintes passem direto pelo pool real.
+       *   4. Agenda a renovação proativa (só a partir daqui — antes não havia lease).
+       *
+       * Coalesce concorrência: N primeiras queries compartilham UM único fetch
+       * (`_initInFlight`). Se a aquisição FALHA (ex.: ambiente suspenso →
+       * `db_suspended`, ou Core fora → `db_unavailable`), o erro propaga pra query
+       * que a disparou e `_initInFlight` é limpo — a PRÓXIMA query re-tenta (o
+       * ambiente pode ter voltado). NÃO derruba o processo nem o import do módulo.
+       */
+      async _ensureInitialLease() {
+        if (this._closed) {
+          throw new exports.NeetruDbError(
+            "db_unavailable",
+            "SqlLeaseManager foi fechado \u2014 aquisi\xE7\xE3o de lease inicial abortada."
+          );
+        }
+        if (this._lease) {
+          return isResilientPool(this._pool) ? this._pool.__neetruGetInner() : this._pool;
+        }
+        if (this._initInFlight !== null) return this._initInFlight;
+        const run = (async () => {
+          let lease;
+          try {
+            lease = this._deps.database !== void 0 ? await this._deps.fetchLease({ database: this._deps.database }) : await this._deps.fetchLease();
+          } catch (err) {
+            if (err instanceof exports.NeetruDbError) throw err;
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new exports.NeetruDbError("db_unavailable", `Falha ao obter lease inicial: ${msg}`);
+          }
+          let realPool;
+          try {
+            realPool = this._deps.createPool(lease);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new exports.NeetruDbError("db_unavailable", `Falha ao abrir pool: ${msg}`);
+          }
+          if (isResilientPool(this._pool)) {
+            const old = this._pool.__neetruSwapInner(realPool);
+            void old.end().catch(() => {
+            });
+          } else {
+            this._pool = realPool;
+          }
+          this._lease = lease;
+          this._scheduleRenewal();
+          return realPool;
+        })();
+        this._initInFlight = run;
+        try {
+          return await run;
+        } catch (err) {
+          this._initInFlight = null;
+          throw err;
+        }
+      }
       /**
        * Hot-swap do pool: cria pool novo, atualiza ponteiros, drena pool antigo.
        *
@@ -419,6 +653,13 @@ var init_lease = __esm({
           return;
         }
         const newPool = this._deps.createPool(newLease);
+        if (isResilientPool(this._pool)) {
+          const oldInner = this._pool.__neetruSwapInner(newPool);
+          this._lease = newLease;
+          void oldInner.end().catch(() => {
+          });
+          return;
+        }
         const newOrm = this._deps.createDrizzle(newPool, this._deps.schema);
         const oldPool = this._pool;
         this._lease = newLease;
@@ -484,10 +725,19 @@ function createHttpLeaseFetcher(config) {
         retries: 2
       });
     } catch (err) {
+      const verb = isRenewal ? "renovar" : "obter";
       const msg = err instanceof Error ? err.message : String(err);
+      const reason = err instanceof exports.NeetruError ? err.reason : void 0;
+      if (reason === "suspended" || reason === "archived" || reason === "revoked") {
+        const human = reason === "suspended" ? "ambiente suspenso \u2014 a m\xE1quina que o servia parou; ser\xE1 religado quando o ambiente voltar" : reason === "archived" ? "ambiente arquivado \u2014 este banco foi arquivado e n\xE3o aceita mais conex\xF5es" : "lease revogado \u2014 as credenciais deste ambiente foram revogadas pelo Core";
+        throw new exports.NeetruDbError(
+          "db_suspended",
+          `Falha ao ${verb} lease SQL: ${human} (reason=${reason}).`
+        );
+      }
       throw new exports.NeetruDbError(
         "db_unavailable",
-        `Falha ao ${isRenewal ? "renovar" : "obter"} lease SQL: ${msg}`
+        `Falha ao ${verb} lease SQL: ${msg}`
       );
     }
     return parseLease(raw);
@@ -559,8 +809,64 @@ async function createDrizzleHandle(pool, schema) {
   );
   return drizzle(pool, { schema });
 }
+function createDeferredPool(poolPrototype, ensureRealPool) {
+  let real = null;
+  let inflight = null;
+  const getReal = () => {
+    if (real) return Promise.resolve(real);
+    if (!inflight) {
+      inflight = ensureRealPool().then((p) => {
+        real = p;
+        inflight = null;
+        return p;
+      }).catch((e) => {
+        inflight = null;
+        throw e;
+      });
+    }
+    return inflight;
+  };
+  const deferred = {
+    async query(...args) {
+      const p = await getReal();
+      return p.query(...args);
+    },
+    async connect(...args) {
+      const p = await getReal();
+      return p.connect(...args);
+    },
+    async end() {
+      if (real) await real.end();
+    }
+  };
+  if (poolPrototype) {
+    Object.setPrototypeOf(deferred, poolPrototype);
+  }
+  return deferred;
+}
 async function createSqlClientWithDeps(deps, options) {
   const depsWithDb = options?.database !== void 0 ? { ...deps, database: options.database } : deps;
+  if (depsWithDb.lazy) {
+    let managerRef = null;
+    const deferred = createDeferredPool(depsWithDb.poolPrototype ?? null, () => {
+      if (!managerRef) {
+        throw new exports.NeetruDbError("db_unavailable", "SQL client n\xE3o inicializado (manager ausente).");
+      }
+      return managerRef._ensureInitialLease();
+    });
+    const pool2 = createResilientPool(deferred);
+    let orm2;
+    try {
+      orm2 = depsWithDb.createDrizzle(pool2, depsWithDb.schema);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new exports.NeetruDbError("db_unavailable", `Falha ao criar handle Drizzle: ${msg}`);
+    }
+    const manager2 = new SqlLeaseManager(null, pool2, orm2, depsWithDb);
+    managerRef = manager2;
+    pool2.__neetruSetReLease(() => manager2._reactiveReLease());
+    return manager2;
+  }
   let lease;
   try {
     if (options?.database !== void 0) {
@@ -573,23 +879,26 @@ async function createSqlClientWithDeps(deps, options) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new exports.NeetruDbError("db_unavailable", `Falha ao obter lease inicial: ${msg}`);
   }
-  let pool;
+  let innerPool;
   try {
-    pool = depsWithDb.createPool(lease);
+    innerPool = depsWithDb.createPool(lease);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new exports.NeetruDbError("db_unavailable", `Falha ao abrir pool: ${msg}`);
   }
+  const pool = createResilientPool(innerPool);
   let orm;
   try {
     orm = depsWithDb.createDrizzle(pool, depsWithDb.schema);
   } catch (err) {
-    await pool.end().catch(() => {
+    await innerPool.end().catch(() => {
     });
     const msg = err instanceof Error ? err.message : String(err);
     throw new exports.NeetruDbError("db_unavailable", `Falha ao criar handle Drizzle: ${msg}`);
   }
-  return new SqlLeaseManager(lease, pool, orm, depsWithDb);
+  const manager = new SqlLeaseManager(lease, pool, orm, depsWithDb);
+  pool.__neetruSetReLease(() => manager._reactiveReLease());
+  return manager;
 }
 async function createSqlClientFromConfig(config, schema, options) {
   const fetchLease = createHttpLeaseFetcher(config);
@@ -610,8 +919,8 @@ async function createSqlClientFromConfig(config, schema, options) {
       `[client.db.sql] requer pg + drizzle-orm como peerDependencies do servidor. Instale: npm install pg drizzle-orm. (${err.message})`
     );
   }
+  const Pool = pgMod.Pool ?? pgMod.default?.Pool;
   const createPool = (lease) => {
-    const Pool = pgMod.Pool ?? pgMod.default?.Pool;
     const ssl = lease.sslca ? {
       ca: lease.sslca,
       cert: lease.clientCert ?? void 0,
@@ -638,7 +947,14 @@ async function createSqlClientFromConfig(config, schema, options) {
       fetchLease,
       createPool,
       createDrizzle,
-      schema
+      schema,
+      // Lease inicial LAZY (motor de ambientes suspenso): `client.db.sql()` não
+      // pode explodir o `import` do módulo do produto quando o ambiente está
+      // suspenso/arquivado no boot. O 1º lease é adiado pra 1ª query.
+      lazy: true,
+      // Placeholder pré-1ª-query herda `pg.Pool.prototype` pra `instanceof Pool`
+      // valer no wrapper resiliente (transações Drizzle PASS-THROUGH seguras).
+      poolPrototype: Pool?.prototype ?? null
     },
     options
   );
@@ -647,7 +963,9 @@ var LEASE_ENDPOINT, LEASE_RENEW_ENDPOINT;
 var init_sql_client = __esm({
   "src/db/sql/sql-client.ts"() {
     init_db_errors();
+    init_errors();
     init_lease();
+    init_resilient_pool();
     LEASE_ENDPOINT = "/api/sdk/v1/db/lease";
     LEASE_RENEW_ENDPOINT = "/api/sdk/v1/db/lease/renew";
   }
@@ -5608,6 +5926,199 @@ init_errors();
 init_http();
 var AI_CHAT_PATH = "/api/sdk/v1/ai/chat";
 var AI_NONSTREAM_TIMEOUT_MS = 12e4;
+var MAX_TEXT_PART_LEN = 32768;
+var MAX_CONTENT_PARTS = 32;
+var MAX_DATA_URL_LEN = 4194304;
+var MAX_HTTPS_URL_LEN = 2048;
+var DATA_IMAGE_URL_RE = /^data:image\/(?:png|jpe?g|gif|webp);base64,[A-Za-z0-9+/]+={0,2}$/;
+var HTTPS_URL_RE = /^https:\/\/[^\s]+$/;
+var IMAGE_DETAIL_VALUES = /* @__PURE__ */ new Set(["low", "high", "auto"]);
+var AI_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant"]);
+var MAX_MESSAGES = 100;
+var MAX_MODEL_LEN = 128;
+var MAX_TOKENS_CAP = 32768;
+var MIN_TEMPERATURE = 0;
+var MAX_TEMPERATURE = 2;
+var MAX_TOTAL_CONTENT_PARTS = 200;
+var MAX_TOTAL_IMAGES = 20;
+var MAX_TOTAL_IMAGE_BYTES = 12 * 1024 * 1024;
+var MAX_SCHEMA_JSON_LEN = 5e4;
+var MAX_SCHEMA_DEPTH = 16;
+var MAX_SCHEMA_KEYS = 500;
+var FORBIDDEN_SCHEMA_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var RESPONSE_FORMAT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+function fail(msg) {
+  throw new exports.NeetruError("validation_failed", msg);
+}
+function isStrictBase64Payload(b64) {
+  if (b64.length === 0 || b64.length % 4 !== 0) return false;
+  const pad = b64.endsWith("==") ? 2 : b64.endsWith("=") ? 1 : 0;
+  const body = pad > 0 ? b64.slice(0, b64.length - pad) : b64;
+  return !body.includes("=");
+}
+function dataUrlDecodedBytes(url) {
+  const comma = url.indexOf(",");
+  if (comma === -1) return 0;
+  const b64 = url.slice(comma + 1);
+  const pad = b64.endsWith("==") ? 2 : b64.endsWith("=") ? 1 : 0;
+  return Math.max(0, Math.floor(b64.length * 3 / 4) - pad);
+}
+function checkAggregateMultimodalLimits(messages) {
+  let totalParts = 0;
+  let totalImages = 0;
+  let totalImageBytes = 0;
+  for (const m of messages) {
+    const content = m?.content;
+    if (!Array.isArray(content)) continue;
+    for (const part of content) {
+      totalParts++;
+      if (totalParts > MAX_TOTAL_CONTENT_PARTS) {
+        return `ai: total content parts exceeds ${MAX_TOTAL_CONTENT_PARTS} per request`;
+      }
+      if (part && typeof part === "object" && part.type === "image_url") {
+        totalImages++;
+        if (totalImages > MAX_TOTAL_IMAGES) {
+          return `ai: total images exceeds ${MAX_TOTAL_IMAGES} per request`;
+        }
+        const url = part.image_url?.url;
+        if (typeof url === "string" && url.startsWith("data:")) {
+          totalImageBytes += dataUrlDecodedBytes(url);
+          if (totalImageBytes > MAX_TOTAL_IMAGE_BYTES) {
+            return `ai: aggregate image bytes exceeds ${MAX_TOTAL_IMAGE_BYTES} per request`;
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+function validateStructuredSchema(schema) {
+  if (schema === void 0) return null;
+  if (schema === null || typeof schema !== "object") {
+    return "ai: responseFormat json_schema.schema must be an object";
+  }
+  let serialized;
+  try {
+    serialized = JSON.stringify(schema);
+  } catch {
+    return "ai: responseFormat json_schema.schema is not serializable";
+  }
+  if (serialized === void 0) return "ai: responseFormat json_schema.schema is invalid";
+  if (serialized.length > MAX_SCHEMA_JSON_LEN) {
+    return `ai: responseFormat json_schema.schema exceeds ${MAX_SCHEMA_JSON_LEN} serialized chars`;
+  }
+  let keyCount = 0;
+  const walk = (node, depth) => {
+    if (depth > MAX_SCHEMA_DEPTH) {
+      return `ai: responseFormat json_schema.schema exceeds max depth ${MAX_SCHEMA_DEPTH}`;
+    }
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        const e = walk(item, depth + 1);
+        if (e) return e;
+      }
+      return null;
+    }
+    if (node && typeof node === "object") {
+      for (const key of Object.getOwnPropertyNames(node)) {
+        if (FORBIDDEN_SCHEMA_KEYS.has(key)) {
+          return `ai: responseFormat json_schema.schema has forbidden key: ${key}`;
+        }
+        keyCount++;
+        if (keyCount > MAX_SCHEMA_KEYS) {
+          return `ai: responseFormat json_schema.schema exceeds ${MAX_SCHEMA_KEYS} keys`;
+        }
+        const e = walk(node[key], depth + 1);
+        if (e) return e;
+      }
+    }
+    return null;
+  };
+  return walk(schema, 0);
+}
+function validateImageUrl(url) {
+  if (typeof url !== "string" || url.length === 0) {
+    fail("ai: image_url.url must be a non-empty string");
+  }
+  const u = url;
+  if (u.startsWith("data:")) {
+    if (u.length > MAX_DATA_URL_LEN) fail(`ai: image_url.url (data:) exceeds ${MAX_DATA_URL_LEN} chars`);
+    if (!DATA_IMAGE_URL_RE.test(u)) {
+      fail("ai: image_url.url data: must be data:image/<png|jpeg|jpg|gif|webp>;base64,<...>");
+    }
+    const b64 = u.slice(u.indexOf(",") + 1);
+    if (!isStrictBase64Payload(b64)) {
+      fail("ai: image_url.url data: has invalid base64 (length/padding)");
+    }
+    return;
+  }
+  if (u.startsWith("https://")) {
+    if (u.length > MAX_HTTPS_URL_LEN) fail(`ai: image_url.url (https:) exceeds ${MAX_HTTPS_URL_LEN} chars`);
+    if (!HTTPS_URL_RE.test(u)) fail("ai: image_url.url https: is invalid");
+    return;
+  }
+  fail("ai: image_url.url must be a data:image/...;base64 or https:// URL (other schemes are rejected)");
+}
+function validateAiContent(content, role) {
+  if (typeof content === "string") {
+    if (content.length === 0) fail("ai: message content string must be non-empty");
+    if (content.length > MAX_TEXT_PART_LEN) fail(`ai: message content exceeds ${MAX_TEXT_PART_LEN} chars`);
+    return;
+  }
+  if (!Array.isArray(content) || content.length === 0) {
+    fail("ai: message content must be a non-empty string or array of parts");
+  }
+  if (content.length > MAX_CONTENT_PARTS) fail(`ai: message content has more than ${MAX_CONTENT_PARTS} parts`);
+  for (const part of content) {
+    if (!part || typeof part !== "object") fail("ai: each content part must be an object");
+    const type = part.type;
+    if (type === "text") {
+      const text = part.text;
+      if (typeof text !== "string" || text.length === 0) fail("ai: text part must have non-empty { text: string }");
+      if (text.length > MAX_TEXT_PART_LEN) fail(`ai: text part exceeds ${MAX_TEXT_PART_LEN} chars`);
+    } else if (type === "image_url") {
+      if (role !== "user") {
+        fail(`ai: image_url is only allowed in role 'user' messages (got '${role}')`);
+      }
+      const iu = part.image_url;
+      if (!iu || typeof iu !== "object") fail("ai: image_url part must have { image_url: { url } }");
+      validateImageUrl(iu.url);
+      const detail = iu.detail;
+      if (detail !== void 0 && (typeof detail !== "string" || !IMAGE_DETAIL_VALUES.has(detail))) {
+        fail("ai: image_url.detail must be 'low' | 'high' | 'auto'");
+      }
+    } else {
+      fail("ai: content part type must be 'text' or 'image_url'");
+    }
+  }
+}
+function validateResponseFormat(rf) {
+  if (!rf || typeof rf !== "object") fail("ai: responseFormat must be an object");
+  const type = rf.type;
+  if (type === "text" || type === "json_object") return;
+  if (type === "json_schema") {
+    const js = rf.json_schema;
+    if (!js || typeof js !== "object") fail("ai: responseFormat json_schema requires { json_schema: { name } }");
+    const jso = js;
+    const name = jso.name;
+    if (typeof name !== "string" || name.length === 0) fail("ai: responseFormat json_schema.name is required");
+    if (name.length > 64) fail("ai: responseFormat json_schema.name exceeds 64 chars");
+    if (!RESPONSE_FORMAT_NAME_RE.test(name)) fail("ai: responseFormat json_schema.name must match a-zA-Z0-9_-");
+    if (jso.description !== void 0) {
+      if (typeof jso.description !== "string") fail("ai: responseFormat json_schema.description must be a string");
+      if (jso.description.length > 1e3) fail("ai: responseFormat json_schema.description exceeds 1000 chars");
+    }
+    if (jso.strict !== void 0 && typeof jso.strict !== "boolean") {
+      fail("ai: responseFormat json_schema.strict must be a boolean");
+    }
+    if (jso.schema !== void 0) {
+      const err = validateStructuredSchema(jso.schema);
+      if (err) fail(err);
+    }
+    return;
+  }
+  fail("ai: responseFormat.type must be 'text' | 'json_object' | 'json_schema'");
+}
 function resolveAiBody(config, opts, stream) {
   if (!opts || typeof opts !== "object") {
     throw new exports.NeetruError("validation_failed", "ai: options object is required");
@@ -5615,17 +6126,26 @@ function resolveAiBody(config, opts, stream) {
   if (typeof opts.model !== "string" || opts.model.length === 0) {
     throw new exports.NeetruError("validation_failed", "ai: model is required");
   }
+  if (opts.model.length > MAX_MODEL_LEN) {
+    throw new exports.NeetruError("validation_failed", `ai: model exceeds ${MAX_MODEL_LEN} chars`);
+  }
   if (!Array.isArray(opts.messages) || opts.messages.length === 0) {
     throw new exports.NeetruError("validation_failed", "ai: messages must be a non-empty array");
   }
+  if (opts.messages.length > MAX_MESSAGES) {
+    throw new exports.NeetruError("validation_failed", `ai: messages exceeds ${MAX_MESSAGES} per request`);
+  }
   for (const m of opts.messages) {
-    if (!m || typeof m !== "object" || typeof m.role !== "string" || m.role.length === 0 || typeof m.content !== "string") {
+    if (!m || typeof m !== "object" || typeof m.role !== "string" || !AI_ROLES.has(m.role)) {
       throw new exports.NeetruError(
         "validation_failed",
-        "ai: each message must be { role: string, content: string }"
+        "ai: each message role must be 'system' | 'user' | 'assistant'"
       );
     }
+    validateAiContent(m.content, m.role);
   }
+  const aggErr = checkAggregateMultimodalLimits(opts.messages);
+  if (aggErr) throw new exports.NeetruError("validation_failed", aggErr);
   const productId = opts.productId ?? config.productId;
   const tenantId = opts.tenantId ?? config.tenantId;
   if (!productId) {
@@ -5650,17 +6170,27 @@ function resolveAiBody(config, opts, stream) {
     stream
   };
   if (opts.maxTokens !== void 0) {
-    if (!Number.isInteger(opts.maxTokens) || opts.maxTokens <= 0) {
-      throw new exports.NeetruError("validation_failed", "ai: maxTokens must be a positive integer");
+    if (!Number.isInteger(opts.maxTokens) || opts.maxTokens <= 0 || opts.maxTokens > MAX_TOKENS_CAP) {
+      throw new exports.NeetruError(
+        "validation_failed",
+        `ai: maxTokens must be a positive integer <= ${MAX_TOKENS_CAP}`
+      );
     }
     body.maxTokens = opts.maxTokens;
   }
   if (opts.temperature !== void 0) {
-    if (typeof opts.temperature !== "number" || !Number.isFinite(opts.temperature)) {
-      throw new exports.NeetruError("validation_failed", "ai: temperature must be a finite number");
+    if (typeof opts.temperature !== "number" || !Number.isFinite(opts.temperature) || opts.temperature < MIN_TEMPERATURE || opts.temperature > MAX_TEMPERATURE) {
+      throw new exports.NeetruError(
+        "validation_failed",
+        `ai: temperature must be a finite number between ${MIN_TEMPERATURE} and ${MAX_TEMPERATURE}`
+      );
     }
     body.temperature = opts.temperature;
   }
+  if (opts.responseFormat !== void 0) {
+    validateResponseFormat(opts.responseFormat);
+    body.responseFormat = opts.responseFormat;
+  }
   return body;
 }
 async function safeJson2(res) {
@@ -6443,9 +6973,15 @@ var MockDb = class {
 };
 var MockAi = class {
   _calls = [];
+  /** Extrai texto de um content string OU array multimodal (imagens ignoradas). */
+  _contentToText(content) {
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) return "";
+    return content.filter((p) => !!p && p.type === "text").map((p) => p.text).join(" ");
+  }
   _reply(opts) {
     const last = [...opts.messages].reverse().find((m) => m.role === "user") ?? opts.messages[opts.messages.length - 1];
-    const content = last?.content ?? "";
+    const content = this._contentToText(last?.content);
     return content ? `mock-reply: ${content}` : "mock-reply";
   }
   async chat(opts) {
@@ -6457,7 +6993,7 @@ var MockAi = class {
     }
     this._calls.push({ model: opts.model, messages: opts.messages, stream: false });
     const text = this._reply(opts);
-    const promptTokens = opts.messages.reduce((n, m) => n + (m.content?.length ?? 0), 0);
+    const promptTokens = opts.messages.reduce((n, m) => n + this._contentToText(m.content).length, 0);
     const completionTokens = text.length;
     return {
       choices: [{ message: { role: "assistant", content: text }, finish_reason: "stop" }],
@@ -7128,7 +7664,7 @@ function createNeetruClient(config = {}) {
 init_errors();
 init_db_errors();
 init_http();
-var VERSION = "3.2.2";
+var VERSION = "3.3.0";
 
 exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
 exports.DEV_FIXTURE_USER = DEV_FIXTURE_USER;