@neetru/sdk 3.2.3 → 3.4.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) {
@@ -368,6 +384,7 @@ var init_resilient_pool = __esm({
 
 // 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) {
@@ -399,6 +416,10 @@ var init_lease = __esm({
     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;
@@ -410,6 +431,12 @@ var init_lease = __esm({
        * `_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;
@@ -419,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() {
@@ -457,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();
@@ -480,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;
@@ -487,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({}));
           }
@@ -547,6 +577,71 @@ var init_lease = __esm({
           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.
        *
@@ -630,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);
@@ -705,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) {
@@ -759,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,
@@ -787,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
   );
@@ -796,6 +963,7 @@ 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";
@@ -1416,6 +1584,7 @@ function toTicket(raw) {
   if (typeof r.id !== "string") {
     throw new exports.NeetruError("invalid_response", "Ticket missing id");
   }
+  const firstAttachment = Array.isArray(r.attachments) && typeof r.attachments[0] === "string" ? r.attachments[0] : void 0;
   return {
     id: r.id,
     subject: typeof r.subject === "string" ? r.subject : "",
@@ -1424,9 +1593,28 @@ function toTicket(raw) {
     status: VALID_STATUSES.includes(r.status) ? r.status : "open",
     createdAt: typeof r.createdAt === "string" ? r.createdAt : (/* @__PURE__ */ new Date()).toISOString(),
     updatedAt: typeof r.updatedAt === "string" ? r.updatedAt : void 0,
-    productSlug: typeof r.productId === "string" ? r.productId : typeof r.productSlug === "string" ? r.productSlug : void 0
+    productSlug: typeof r.productId === "string" ? r.productId : typeof r.productSlug === "string" ? r.productSlug : void 0,
+    pageUrl: typeof r.pageUrl === "string" ? r.pageUrl : null,
+    screenshotUrl: typeof r.screenshotUrl === "string" ? r.screenshotUrl : firstAttachment ?? null,
+    resolvedAt: typeof r.resolvedAt === "string" ? r.resolvedAt : null,
+    resolvedNotifiedAt: typeof r.resolvedNotifiedAt === "string" ? r.resolvedNotifiedAt : null,
+    satisfactionAttempts: typeof r.satisfactionAttempts === "number" && Number.isFinite(r.satisfactionAttempts) ? r.satisfactionAttempts : 0,
+    lastSatisfactionAttemptAt: typeof r.lastSatisfactionAttemptAt === "string" ? r.lastSatisfactionAttemptAt : null,
+    satisfiedAt: typeof r.satisfiedAt === "string" ? r.satisfiedAt : null,
+    rating: typeof r.rating === "number" && Number.isFinite(r.rating) ? r.rating : null,
+    satisfactionComment: typeof r.satisfactionComment === "string" ? r.satisfactionComment : null
   };
 }
+function assertTicketId(ticketId) {
+  if (!ticketId || typeof ticketId !== "string") {
+    throw new exports.NeetruError("validation_failed", "ticketId is required");
+  }
+}
+function assertValidComment(comment) {
+  if (typeof comment === "string" && comment.length > 2e3) {
+    throw new exports.NeetruError("validation_failed", "comment max 2000 chars");
+  }
+}
 function resolveProductId(config, ...candidates) {
   for (const c of candidates) {
     if (typeof c === "string" && c.length > 0) {
@@ -1483,6 +1671,15 @@ function createSupportNamespace(config) {
       if (input.metadata && typeof input.metadata === "object") {
         body.metadata = input.metadata;
       }
+      if (typeof input.pageUrl === "string") {
+        body.pageUrl = input.pageUrl;
+      }
+      if (typeof input.screenshotBase64 === "string") {
+        body.screenshotBase64 = input.screenshotBase64;
+      }
+      if (typeof input.consoleLogs === "string") {
+        body.consoleLogs = input.consoleLogs;
+      }
       const raw = await httpRequest(config, {
         method: "POST",
         path: "/api/sdk/v1/support/tickets",
@@ -1508,6 +1705,74 @@ function createSupportNamespace(config) {
       });
       const list = Array.isArray(raw) ? raw : raw && typeof raw === "object" && "tickets" in raw ? raw.tickets ?? [] : [];
       return list.map(toTicket);
+    },
+    /**
+     * 3.4: marca a notificação de resolução como vista (`resolvedNotifiedAt`,
+     * idempotente no Core). Endpoint canonical:
+     * `POST /api/sdk/v1/support/tickets/{id}/resolved-seen`.
+     */
+    async markResolvedSeen(ticketId) {
+      assertTicketId(ticketId);
+      await httpRequest(config, {
+        method: "POST",
+        path: `/api/sdk/v1/support/tickets/${encodeURIComponent(ticketId)}/resolved-seen`,
+        requireAuth: true
+      });
+    },
+    /**
+     * 3.4: registra uma tentativa de exibição do modal de satisfação
+     * (`satisfactionAttempts += 1`). Chamar no SHOW do modal, não na
+     * resposta. Endpoint canonical:
+     * `POST /api/sdk/v1/support/tickets/{id}/satisfaction-attempt`.
+     */
+    async recordSatisfactionAttempt(ticketId) {
+      assertTicketId(ticketId);
+      await httpRequest(config, {
+        method: "POST",
+        path: `/api/sdk/v1/support/tickets/${encodeURIComponent(ticketId)}/satisfaction-attempt`,
+        requireAuth: true
+      });
+    },
+    /**
+     * 3.4: envia (ou pula) a avaliação de satisfação (CSAT 1-5). Endpoint
+     * canonical: `POST /api/sdk/v1/support/tickets/{id}/satisfaction`.
+     */
+    async submitSatisfaction(input) {
+      if (!input || typeof input !== "object") {
+        throw new exports.NeetruError("validation_failed", "input is required");
+      }
+      assertTicketId(input.ticketId);
+      if (input.rating !== null && input.rating !== void 0) {
+        if (!Number.isInteger(input.rating) || input.rating < 1 || input.rating > 5) {
+          throw new exports.NeetruError("validation_failed", "rating must be an integer 1-5 or null");
+        }
+      }
+      assertValidComment(input.comment);
+      await httpRequest(config, {
+        method: "POST",
+        path: `/api/sdk/v1/support/tickets/${encodeURIComponent(input.ticketId)}/satisfaction`,
+        body: {
+          rating: input.rating ?? null,
+          comment: input.comment ?? null,
+          skipped: input.skipped
+        },
+        requireAuth: true
+      });
+    },
+    /**
+     * 3.4: contesta um ticket resolvido — reabre e zera o ciclo de
+     * satisfação/notificação. Endpoint canonical:
+     * `POST /api/sdk/v1/support/tickets/{id}/contest`.
+     */
+    async contestTicket(ticketId, opts) {
+      assertTicketId(ticketId);
+      assertValidComment(opts?.comment);
+      await httpRequest(config, {
+        method: "POST",
+        path: `/api/sdk/v1/support/tickets/${encodeURIComponent(ticketId)}/contest`,
+        body: { comment: opts?.comment ?? void 0 },
+        requireAuth: true
+      });
     }
   };
 }
@@ -4939,7 +5204,20 @@ function buildTicketProvider(config, opts) {
     return ticket;
   };
 }
+var _hasWarnedMissingDbId = false;
+function warnMissingDbIdOnce(config, dbOpts) {
+  if (_hasWarnedMissingDbId) return;
+  if (dbOpts.dbId) return;
+  if (config.env === "prod") return;
+  if (typeof window === "undefined") return;
+  if (typeof console === "undefined" || typeof console.warn !== "function") return;
+  _hasWarnedMissingDbId = true;
+  console.warn(
+    "[neetru/sdk] client.db sem `dbId` expl\xEDcito: escritas client-side (add/set/update/remove/list) caem no datastore gen\xE9rico do Core, escopado por tenant/produto (header x-neetru-tenant) \u2014 `dbId` s\xF3 nomeia o cache offline LOCAL (IndexedDB), n\xE3o roteia nem escopa nada no servidor. Veja o JSDoc de NeetruDbOptions.dbId."
+  );
+}
 function createNeetruDb(config, dbOpts = {}) {
+  warnMissingDbIdOnce(config, dbOpts);
   let resolvedTransport;
   if (dbOpts.transport !== void 0) {
     resolvedTransport = dbOpts.transport;
@@ -5758,6 +6036,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");
@@ -5765,17 +6236,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) {
@@ -5800,17 +6280,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) {
@@ -6237,7 +6727,18 @@ var MockSupport = class {
       severity: input.severity ?? "normal",
       status: "open",
       createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      productSlug: input.productSlug
+      productSlug: input.productSlug,
+      // 3.4 (product-feedback): espelha o contrato — campos novos nullable,
+      // populados a partir do input quando fornecidos.
+      pageUrl: typeof input.pageUrl === "string" ? input.pageUrl : null,
+      screenshotUrl: typeof input.screenshotBase64 === "string" ? input.screenshotBase64 : null,
+      resolvedAt: null,
+      resolvedNotifiedAt: null,
+      satisfactionAttempts: 0,
+      lastSatisfactionAttemptAt: null,
+      satisfiedAt: null,
+      rating: null,
+      satisfactionComment: null
     };
     this._tickets.push(ticket);
     return ticket;
@@ -6248,6 +6749,62 @@ var MockSupport = class {
     }
     return [...this._tickets];
   }
+  _find(ticketId) {
+    if (!ticketId || typeof ticketId !== "string") {
+      throw new exports.NeetruError("validation_failed", "ticketId is required");
+    }
+    const ticket = this._tickets.find((t) => t.id === ticketId);
+    if (!ticket) {
+      throw new exports.NeetruError("not_found", `ticket ${ticketId} not found`);
+    }
+    return ticket;
+  }
+  /** 3.4: espelha `markResolvedSeen` — idempotente (só seta se ainda null). */
+  async markResolvedSeen(ticketId) {
+    const ticket = this._find(ticketId);
+    if (ticket.resolvedNotifiedAt === null) {
+      ticket.resolvedNotifiedAt = (/* @__PURE__ */ new Date()).toISOString();
+    }
+  }
+  /** 3.4: espelha `recordSatisfactionAttempt` — incrementa contador. */
+  async recordSatisfactionAttempt(ticketId) {
+    const ticket = this._find(ticketId);
+    ticket.satisfactionAttempts += 1;
+    ticket.lastSatisfactionAttemptAt = (/* @__PURE__ */ new Date()).toISOString();
+  }
+  /** 3.4: espelha `submitSatisfaction` — terminal, seta `satisfiedAt`. */
+  async submitSatisfaction(input) {
+    if (!input || typeof input !== "object") {
+      throw new exports.NeetruError("validation_failed", "input is required");
+    }
+    if (input.rating !== null && input.rating !== void 0) {
+      if (!Number.isInteger(input.rating) || input.rating < 1 || input.rating > 5) {
+        throw new exports.NeetruError("validation_failed", "rating must be an integer 1-5 or null");
+      }
+    }
+    if (typeof input.comment === "string" && input.comment.length > 2e3) {
+      throw new exports.NeetruError("validation_failed", "comment max 2000 chars");
+    }
+    const ticket = this._find(input.ticketId);
+    ticket.satisfiedAt = (/* @__PURE__ */ new Date()).toISOString();
+    ticket.rating = input.rating ?? null;
+    ticket.satisfactionComment = input.comment ?? null;
+  }
+  /** 3.4: espelha `contestTicket` — reabre e zera o ciclo de satisfação. */
+  async contestTicket(ticketId, opts) {
+    if (typeof opts?.comment === "string" && opts.comment.length > 2e3) {
+      throw new exports.NeetruError("validation_failed", "comment max 2000 chars");
+    }
+    const ticket = this._find(ticketId);
+    ticket.status = "open";
+    ticket.resolvedAt = null;
+    ticket.resolvedNotifiedAt = null;
+    ticket.satisfactionAttempts = 0;
+    ticket.lastSatisfactionAttemptAt = null;
+    ticket.satisfiedAt = null;
+    ticket.rating = null;
+    ticket.satisfactionComment = null;
+  }
   /** Test helper. */
   __reset() {
     this._tickets = [];
@@ -6593,9 +7150,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) {
@@ -6607,7 +7170,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" }],
@@ -7278,7 +7841,7 @@ function createNeetruClient(config = {}) {
 init_errors();
 init_db_errors();
 init_http();
-var VERSION = "3.2.3";
+var VERSION = "3.4.0";
 
 exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
 exports.DEV_FIXTURE_USER = DEV_FIXTURE_USER;