@meuecommerce/frete-adapter-node 0.14.0 → 0.15.0

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createOpenAIBoxDistributor = exports.PgDimensionMemory = exports.DIMENSION_MEMORY_SCHEMA_SQL = exports.createOpenAIResponsesAgentRunner = exports.createOpenAIDimensionEstimator = exports.DIMENSION_PROMPT_VERSION = exports.EnvSecretStore = exports.InMemoryDimensionMemory = exports.InMemorySettingsStore = exports.createCorreiosLabelHttpClient = exports.createCorreiosHttpClient = void 0;
+exports.createOpenAIBoxDistributor = exports.PgDimensionMemory = exports.DIMENSION_MEMORY_SCHEMA_SQL = exports.createOpenAIResponsesAgentRunner = exports.DEFAULT_IMAGE_DETAIL = exports.createOpenAIDimensionEstimator = exports.DIMENSION_PROMPT_VERSION = exports.EnvSecretStore = exports.InMemoryDimensionMemory = exports.InMemorySettingsStore = exports.createCorreiosLabelHttpClient = exports.createCorreiosHttpClient = void 0;
 /**
  * @meuecommerce/frete-adapter-node — Node implementations of @meuecommerce/frete ports.
  *
@@ -21,6 +21,7 @@ var openAIDimensionEstimator_js_1 = require("./openAIDimensionEstimator.js");
 Object.defineProperty(exports, "DIMENSION_PROMPT_VERSION", { enumerable: true, get: function () { return openAIDimensionEstimator_js_1.DIMENSION_PROMPT_VERSION; } });
 Object.defineProperty(exports, "createOpenAIDimensionEstimator", { enumerable: true, get: function () { return openAIDimensionEstimator_js_1.createOpenAIDimensionEstimator; } });
 var openAIResponsesAgentRunner_js_1 = require("./openAIResponsesAgentRunner.js");
+Object.defineProperty(exports, "DEFAULT_IMAGE_DETAIL", { enumerable: true, get: function () { return openAIResponsesAgentRunner_js_1.DEFAULT_IMAGE_DETAIL; } });
 Object.defineProperty(exports, "createOpenAIResponsesAgentRunner", { enumerable: true, get: function () { return openAIResponsesAgentRunner_js_1.createOpenAIResponsesAgentRunner; } });
 var pgDimensionMemory_js_1 = require("./pgDimensionMemory.js");
 Object.defineProperty(exports, "DIMENSION_MEMORY_SCHEMA_SQL", { enumerable: true, get: function () { return pgDimensionMemory_js_1.DIMENSION_MEMORY_SCHEMA_SQL; } });

package/dist/cjs/openAIDimensionEstimator.js

@@ -80,19 +80,6 @@ function descreverProduto(p, i) {
         .join("\n");
     return `${linha}\n${contexto}`;
 }
-/**
- * Uma URL de foto só é aceita se for utilizável como está.
- *
- * `http(s)` e `data:` são o que a API aceita. Qualquer outra coisa — caminho
- * relativo, `wix:image://`, string vazia — faria a requisição inteira ser
- * rejeitada, e com ela os cinco produtos do lote, não só o da foto ruim.
- * Descartar a foto e estimar pelo texto é sempre melhor que perder o lote.
- */
-function fotoUtilizavel(url) {
-    if (!url)
-        return false;
-    return /^https?:\/\//i.test(url) || /^data:image\//i.test(url);
-}
 /**
  * As fotos do lote, na ordem dos produtos, com o índice a que cada uma pertence.
  *
@@ -106,7 +93,7 @@ function fotoUtilizavel(url) {
 function fotosDoLote(products) {
     return products
         .map((p, i) => ({ indice: i + 1, url: p.imageUrl }))
-        .filter((f) => fotoUtilizavel(f.url));
+        .filter((f) => (0, frete_1.usablePhotoUrl)(f.url));
 }
 /** A linha do prompt que amarra cada foto ao produto dela. */
 function descreverFotos(fotos, total) {
@@ -199,7 +186,7 @@ function validateAndOptimize(aiResult, products, boxes) {
     return { products: optimized };
 }
 function createOpenAIDimensionEstimator(options) {
-    const { apiKey, fetch, model = "gpt-4o-mini", temperature = 0.1, apiUrl, timeoutMs, runner } = options;
+    const { apiKey, fetch, model = "gpt-4o-mini", temperature = 0.1, apiUrl, timeoutMs, imageDetail, runner } = options;
     const agent = runner ??
         (0, openAIResponsesAgentRunner_js_1.createOpenAIResponsesAgentRunner)({
             apiKey: apiKey ?? "",
@@ -207,6 +194,7 @@ function createOpenAIDimensionEstimator(options) {
             model,
             ...(apiUrl ? { apiUrl } : {}),
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(imageDetail ? { imageDetail } : {}),
         });
     return {
         async estimate(products, boxes, productSamples = []) {

package/dist/cjs/openAIResponsesAgentRunner.js

@@ -1,8 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IMAGE_DETAIL = void 0;
 exports.extractOutputText = extractOutputText;
 exports.findRefusal = findRefusal;
 exports.createOpenAIResponsesAgentRunner = createOpenAIResponsesAgentRunner;
+/**
+ * `low` de propósito, e é uma escolha de custo medida, não um palpite.
+ *
+ * No gpt-4o-mini a imagem é cobrada por ladrilho de 512px: 2.833 de base mais
+ * 5.667 por ladrilho. Uma foto de produto quadrada, que é o formato padrão da
+ * Wix, vira quatro ladrilhos — 25.501 tokens. Com `low` a conta é fixa em 2.833
+ * **independentemente do tamanho do original**, o que dá 9x menos na parte da
+ * imagem.
+ *
+ * Isso saiu de produção, não de estimativa: o primeiro lote com foto, em
+ * 2026-09-15, gastou 180.113 tokens de entrada para 7 produtos. A fórmula
+ * acima prevê 180.119.
+ *
+ * **O que ainda não foi medido é a qualidade.** Não existe dataset de eval com
+ * foto — o `amostras-lojistas.json` tem nome e dimensões digitadas pelo
+ * lojista, nada de imagem — então qual `detail` estima melhor é pergunta em
+ * aberto. Por isso isto é opção com padrão, e não constante: quando o dataset
+ * com foto existir, comparar os dois é trocar este argumento.
+ */
+exports.DEFAULT_IMAGE_DETAIL = "low";
 /** The model's text, accepting both shapes the Responses API delivers it in. */
 function extractOutputText(json) {
     if (typeof json.output_text === "string" && json.output_text.trim())
@@ -31,7 +52,7 @@ function findRefusal(json) {
     return null;
 }
 function createOpenAIResponsesAgentRunner(options) {
-    const { apiKey, fetch = globalThis.fetch, model: defaultModel = "gpt-4o-mini", apiUrl = "https://api.openai.com/v1/responses", timeoutMs = 20000, } = options;
+    const { apiKey, fetch = globalThis.fetch, model: defaultModel = "gpt-4o-mini", apiUrl = "https://api.openai.com/v1/responses", timeoutMs = 20000, imageDetail = exports.DEFAULT_IMAGE_DETAIL, } = options;
     if (!apiKey)
         throw new Error("createOpenAIResponsesAgentRunner: apiKey is required");
     if (typeof fetch !== "function")
@@ -41,14 +62,19 @@ function createOpenAIResponsesAgentRunner(options) {
             const input = [];
             if (request.system)
                 input.push({ role: "system", content: request.system });
-            // `images` ainda não é usado pelo estimador; quando a fase 2 ligar, o
-            // conteúdo do turno do usuário vira lista em vez de string.
+            // Com imagem o turno do usuário vira lista em vez de string. O `detail`
+            // vai sempre explícito: omiti-lo é o que deixa a OpenAI escolher `high`,
+            // e essa omissão custou 9x na primeira passada em produção.
             if (request.images?.length) {
                 input.push({
                     role: "user",
                     content: [
                         { type: "input_text", text: request.user },
-                        ...request.images.map((url) => ({ type: "input_image", image_url: url })),
+                        ...request.images.map((url) => ({
+                            type: "input_image",
+                            image_url: url,
+                            detail: imageDetail,
+                        })),
                     ],
                 });
             }

package/dist/index.d.ts

@@ -14,10 +14,10 @@ export { InMemoryDimensionMemory } from "./inMemoryDimensionMemory.js";
 export { EnvSecretStore } from "./envSecretStore.js";
 export type { EnvSecretStoreOptions } from "./envSecretStore.js";
 export { DIMENSION_PROMPT_VERSION, createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
-export { createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.js";
+export { DEFAULT_IMAGE_DETAIL, createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.js";
 export { DIMENSION_MEMORY_SCHEMA_SQL, PgDimensionMemory } from "./pgDimensionMemory.js";
 export type { PgDimensionMemoryOptions, SqlClient } from "./pgDimensionMemory.js";
-export type { OpenAIResponsesAgentRunnerOptions } from "./openAIResponsesAgentRunner.js";
+export type { ImageDetail, OpenAIResponsesAgentRunnerOptions } from "./openAIResponsesAgentRunner.js";
 export type { OpenAIDimensionEstimatorOptions } from "./openAIDimensionEstimator.js";
 export { createOpenAIBoxDistributor } from "./openAIBoxDistributor.js";
 export type { OpenAIBoxDistributorOptions } from "./openAIBoxDistributor.js";

package/dist/index.js

@@ -10,6 +10,6 @@ export { InMemorySettingsStore } from "./inMemorySettingsStore.js";
 export { InMemoryDimensionMemory } from "./inMemoryDimensionMemory.js";
 export { EnvSecretStore } from "./envSecretStore.js";
 export { DIMENSION_PROMPT_VERSION, createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
-export { createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.js";
+export { DEFAULT_IMAGE_DETAIL, createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.js";
 export { DIMENSION_MEMORY_SCHEMA_SQL, PgDimensionMemory } from "./pgDimensionMemory.js";
 export { createOpenAIBoxDistributor } from "./openAIBoxDistributor.js";

package/dist/openAIDimensionEstimator.d.ts

@@ -19,6 +19,7 @@
  * (e.g. via a `SecretStore`), keeping secret handling out of this module.
  */
 import type { LlmAgentRunner, ProductDimensionEstimator } from "@meuecommerce/frete";
+import { type ImageDetail } from "./openAIResponsesAgentRunner.js";
 type FetchLike = typeof globalThis.fetch;
 /**
  * Bump whenever the prompt or the schema changes. It is written next to every
@@ -33,6 +34,15 @@ export interface OpenAIDimensionEstimatorOptions {
     temperature?: number;
     apiUrl?: string;
     timeoutMs?: number;
+    /**
+     * Quanto da imagem o modelo olha. Omitido, vale o padrão do runner (`low`).
+     *
+     * Existe aqui, e não só no runner, para que comparar `low` contra `high` num
+     * eval seja trocar um argumento — que é como a pergunta em aberto sobre
+     * qualidade vai ser respondida quando houver dataset com foto. Não tem efeito
+     * nenhum sobre produto sem foto.
+     */
+    imageDetail?: ImageDetail;
     /**
      * Run the call through an existing {@link LlmAgentRunner} instead of building
      * one. Pass it to share a runner across use cases, or to substitute the

package/dist/openAIDimensionEstimator.js

@@ -1,4 +1,4 @@
-import { productNameKey } from "@meuecommerce/frete";
+import { productNameKey, usablePhotoUrl } from "@meuecommerce/frete";
 import { createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.js";
 /**
  * Bump whenever the prompt or the schema changes. It is written next to every
@@ -76,19 +76,6 @@ function descreverProduto(p, i) {
         .join("\n");
     return `${linha}\n${contexto}`;
 }
-/**
- * Uma URL de foto só é aceita se for utilizável como está.
- *
- * `http(s)` e `data:` são o que a API aceita. Qualquer outra coisa — caminho
- * relativo, `wix:image://`, string vazia — faria a requisição inteira ser
- * rejeitada, e com ela os cinco produtos do lote, não só o da foto ruim.
- * Descartar a foto e estimar pelo texto é sempre melhor que perder o lote.
- */
-function fotoUtilizavel(url) {
-    if (!url)
-        return false;
-    return /^https?:\/\//i.test(url) || /^data:image\//i.test(url);
-}
 /**
  * As fotos do lote, na ordem dos produtos, com o índice a que cada uma pertence.
  *
@@ -102,7 +89,7 @@ function fotoUtilizavel(url) {
 function fotosDoLote(products) {
     return products
         .map((p, i) => ({ indice: i + 1, url: p.imageUrl }))
-        .filter((f) => fotoUtilizavel(f.url));
+        .filter((f) => usablePhotoUrl(f.url));
 }
 /** A linha do prompt que amarra cada foto ao produto dela. */
 function descreverFotos(fotos, total) {
@@ -195,7 +182,7 @@ function validateAndOptimize(aiResult, products, boxes) {
     return { products: optimized };
 }
 export function createOpenAIDimensionEstimator(options) {
-    const { apiKey, fetch, model = "gpt-4o-mini", temperature = 0.1, apiUrl, timeoutMs, runner } = options;
+    const { apiKey, fetch, model = "gpt-4o-mini", temperature = 0.1, apiUrl, timeoutMs, imageDetail, runner } = options;
     const agent = runner ??
         createOpenAIResponsesAgentRunner({
             apiKey: apiKey ?? "",
@@ -203,6 +190,7 @@ export function createOpenAIDimensionEstimator(options) {
             model,
             ...(apiUrl ? { apiUrl } : {}),
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(imageDetail ? { imageDetail } : {}),
         });
     return {
         async estimate(products, boxes, productSamples = []) {

package/dist/openAIResponsesAgentRunner.d.ts

@@ -12,12 +12,41 @@
  */
 import type { LlmAgentRunner } from "@meuecommerce/frete";
 type FetchLike = typeof globalThis.fetch;
+/**
+ * Quanto da imagem o modelo olha. Ver {@link DEFAULT_IMAGE_DETAIL}.
+ *
+ * `auto` é o padrão da OpenAI quando o campo não vai, e para foto de produto
+ * ele resolve como `high` — foi assim que o custo apareceu em produção.
+ */
+export type ImageDetail = "low" | "high" | "auto";
+/**
+ * `low` de propósito, e é uma escolha de custo medida, não um palpite.
+ *
+ * No gpt-4o-mini a imagem é cobrada por ladrilho de 512px: 2.833 de base mais
+ * 5.667 por ladrilho. Uma foto de produto quadrada, que é o formato padrão da
+ * Wix, vira quatro ladrilhos — 25.501 tokens. Com `low` a conta é fixa em 2.833
+ * **independentemente do tamanho do original**, o que dá 9x menos na parte da
+ * imagem.
+ *
+ * Isso saiu de produção, não de estimativa: o primeiro lote com foto, em
+ * 2026-09-15, gastou 180.113 tokens de entrada para 7 produtos. A fórmula
+ * acima prevê 180.119.
+ *
+ * **O que ainda não foi medido é a qualidade.** Não existe dataset de eval com
+ * foto — o `amostras-lojistas.json` tem nome e dimensões digitadas pelo
+ * lojista, nada de imagem — então qual `detail` estima melhor é pergunta em
+ * aberto. Por isso isto é opção com padrão, e não constante: quando o dataset
+ * com foto existir, comparar os dois é trocar este argumento.
+ */
+export declare const DEFAULT_IMAGE_DETAIL: ImageDetail;
 export interface OpenAIResponsesAgentRunnerOptions {
     apiKey: string;
     fetch?: FetchLike;
     model?: string;
     apiUrl?: string;
     timeoutMs?: number;
+    /** Ver {@link DEFAULT_IMAGE_DETAIL}. */
+    imageDetail?: ImageDetail;
 }
 interface ResponsesPayload {
     error?: {

package/dist/openAIResponsesAgentRunner.js

@@ -1,3 +1,23 @@
+/**
+ * `low` de propósito, e é uma escolha de custo medida, não um palpite.
+ *
+ * No gpt-4o-mini a imagem é cobrada por ladrilho de 512px: 2.833 de base mais
+ * 5.667 por ladrilho. Uma foto de produto quadrada, que é o formato padrão da
+ * Wix, vira quatro ladrilhos — 25.501 tokens. Com `low` a conta é fixa em 2.833
+ * **independentemente do tamanho do original**, o que dá 9x menos na parte da
+ * imagem.
+ *
+ * Isso saiu de produção, não de estimativa: o primeiro lote com foto, em
+ * 2026-09-15, gastou 180.113 tokens de entrada para 7 produtos. A fórmula
+ * acima prevê 180.119.
+ *
+ * **O que ainda não foi medido é a qualidade.** Não existe dataset de eval com
+ * foto — o `amostras-lojistas.json` tem nome e dimensões digitadas pelo
+ * lojista, nada de imagem — então qual `detail` estima melhor é pergunta em
+ * aberto. Por isso isto é opção com padrão, e não constante: quando o dataset
+ * com foto existir, comparar os dois é trocar este argumento.
+ */
+export const DEFAULT_IMAGE_DETAIL = "low";
 /** The model's text, accepting both shapes the Responses API delivers it in. */
 export function extractOutputText(json) {
     if (typeof json.output_text === "string" && json.output_text.trim())
@@ -26,7 +46,7 @@ export function findRefusal(json) {
     return null;
 }
 export function createOpenAIResponsesAgentRunner(options) {
-    const { apiKey, fetch = globalThis.fetch, model: defaultModel = "gpt-4o-mini", apiUrl = "https://api.openai.com/v1/responses", timeoutMs = 20000, } = options;
+    const { apiKey, fetch = globalThis.fetch, model: defaultModel = "gpt-4o-mini", apiUrl = "https://api.openai.com/v1/responses", timeoutMs = 20000, imageDetail = DEFAULT_IMAGE_DETAIL, } = options;
     if (!apiKey)
         throw new Error("createOpenAIResponsesAgentRunner: apiKey is required");
     if (typeof fetch !== "function")
@@ -36,14 +56,19 @@ export function createOpenAIResponsesAgentRunner(options) {
             const input = [];
             if (request.system)
                 input.push({ role: "system", content: request.system });
-            // `images` ainda não é usado pelo estimador; quando a fase 2 ligar, o
-            // conteúdo do turno do usuário vira lista em vez de string.
+            // Com imagem o turno do usuário vira lista em vez de string. O `detail`
+            // vai sempre explícito: omiti-lo é o que deixa a OpenAI escolher `high`,
+            // e essa omissão custou 9x na primeira passada em produção.
             if (request.images?.length) {
                 input.push({
                     role: "user",
                     content: [
                         { type: "input_text", text: request.user },
-                        ...request.images.map((url) => ({ type: "input_image", image_url: url })),
+                        ...request.images.map((url) => ({
+                            type: "input_image",
+                            image_url: url,
+                            detail: imageDetail,
+                        })),
                     ],
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meuecommerce/frete-adapter-node",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Node implementation of @meuecommerce/frete ports (Correios HTTP client) using global fetch. Used by the Shopify/Fly deployment and the MCP server.",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@meuecommerce/frete": "^0.14.0"
+    "@meuecommerce/frete": "^0.15.0"
   },
   "module": "./dist/index.js",
   "repository": {