@meuecommerce/frete-adapter-node 0.13.0 → 0.15.0

package/dist/cjs/correiosLabelHttpClient.js

@@ -30,8 +30,23 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function isRetryableLabelMessage(msg) {
     return /consulte novamente|ainda n[ãa]o foi gerado|n[ãa]o (foi )?gerado|PPN-291/i.test(msg);
 }
+/**
+ * A well-formed PDF starts with the `%PDF-` header and ends with the `%%EOF`
+ * trailer. Correios can answer a mid-render poll with a *partial* byte stream
+ * (correct content-type, non-empty body) — accepting that yields the corrupted
+ * label users saw. The Wix/Shopify apps sidestep it by reading the base64 from
+ * JSON (`dados`), which only appears once the render is complete; when we do get
+ * raw bytes we apply the same "only if complete" rule here.
+ */
+function isCompletePdf(buf) {
+    if (buf.length < 100)
+        return false;
+    if (buf.subarray(0, 5).toString("latin1") !== "%PDF-")
+        return false;
+    return buf.subarray(Math.max(0, buf.length - 1024)).toString("latin1").includes("%%EOF");
+}
 function createCorreiosLabelHttpClient(options = {}) {
-    const { fetch = globalThis.fetch, baseUrl = frete_1.correiosApiUrl, timeoutMs = 20000, retries = 2, retryDelayMs = 500, tipoRotulo = "P", downloadPath = "/prepostagem/v1/prepostagens/rotulo/download/assincrono/{idRecibo}", logger = console, } = options;
+    const { fetch = globalThis.fetch, baseUrl = frete_1.correiosApiUrl, timeoutMs = 20000, retries = 2, retryDelayMs = 500, tipoRotulo = "P", formatoRotulo = "EN", downloadPath = "/prepostagem/v1/prepostagens/rotulo/download/assincrono/{idRecibo}", logger = console, } = options;
     if (typeof fetch !== "function") {
         throw new Error("createCorreiosLabelHttpClient: no fetch available (Node 18+ or pass options.fetch)");
     }
@@ -89,7 +104,8 @@ function createCorreiosLabelHttpClient(options = {}) {
             const response = await fetchWithRetry(`${baseUrl}/prepostagem/v1/prepostagens/rotulo/assincrono/pdf`, {
                 method: "POST",
                 headers: authHeaders(token),
-                body: JSON.stringify({ idsPrePostagem: ids, tipoRotulo }),
+                // formatoRotulo mirrors the Wix/Shopify apps — Correios expects it.
+                body: JSON.stringify({ idsPrePostagem: ids, tipoRotulo, formatoRotulo }),
             });
             const json = (await response.json().catch(() => ({})));
             if (!json.idRecibo)
@@ -97,40 +113,46 @@ function createCorreiosLabelHttpClient(options = {}) {
             return { idRecibo: json.idRecibo };
         },
         async downloadLabelPdf(idRecibo, token) {
+            // Mirror the Wix/Shopify apps: plain GET asking for JSON, and the base64
+            // PDF is read from `dados`. Reading JSON (not raw bytes) means we only ever
+            // accept a *complete* PDF — a mid-render poll simply has no `dados` yet, so
+            // we keep polling instead of handing back a corrupted file.
             const path = downloadPath.replace("{idRecibo}", encodeURIComponent(idRecibo));
-            // tipoRotulo is also accepted as a query param on the download (PPN-285).
-            const sep = path.includes("?") ? "&" : "?";
-            const url = `${baseUrl}${path}${sep}tipoRotulo=${encodeURIComponent(tipoRotulo)}`;
-            const response = await fetchWithRetry(url, {
+            const response = await fetchWithRetry(`${baseUrl}${path}`, {
                 method: "GET",
-                headers: { Accept: "application/pdf, application/json", Authorization: `Bearer ${token}` },
+                headers: authHeaders(token),
             });
-            const contentType = response.headers.get("content-type") ?? "";
             // 202 (or 204) = still processing; tell the use case to poll again.
             if (response.status === 202 || response.status === 204)
                 return { ready: false };
-            if (response.status !== 200) {
-                const body = await response.text().catch(() => "");
-                // A retryable business message can arrive with a non-2xx status too.
-                if (isRetryableLabelMessage(body))
-                    return { ready: false };
-                return { ready: false, message: `http_${response.status}: ${body.slice(0, 200)}` };
-            }
-            // Correios may return the PDF as raw bytes (application/pdf) or wrapped in
-            // JSON as base64 (dados/pdf). Handle both.
+            const contentType = response.headers.get("content-type") ?? "";
+            // Correios occasionally answers with raw bytes anyway — accept them only if
+            // they form a complete PDF (%PDF header + %%EOF trailer); otherwise it's a
+            // half-rendered stream, so treat it as not-ready and keep polling.
             if (contentType.includes("application/pdf") || contentType.includes("octet-stream")) {
                 const buf = Buffer.from(await response.arrayBuffer());
-                return buf.length ? { ready: true, pdfBase64: buf.toString("base64") } : { ready: false };
+                return isCompletePdf(buf) ? { ready: true, pdfBase64: buf.toString("base64") } : { ready: false };
+            }
+            // JSON path (the happy path the apps use).
+            const body = await response.text().catch(() => "");
+            let json = {};
+            try {
+                json = body ? JSON.parse(body) : {};
+            }
+            catch {
+                json = {};
             }
-            const json = (await response.json().catch(() => ({})));
             const pdfBase64 = (json.dados ?? json.pdf ?? json.base64 ?? json.arquivo);
             if (pdfBase64)
                 return { ready: true, pdfBase64 };
-            // 200 without a PDF carries a business message (e.g. "status Pendente" or
-            // "ainda não foi gerado, consulte novamente"). Retryable ones → keep polling.
-            const message = typeof json.mensagem === "string" ? json.mensagem : undefined;
-            if (message && isRetryableLabelMessage(message))
+            // No PDF yet. A transient message (PPN-291 / "consulte novamente") → keep
+            // polling; a terminal one (e.g. "status Pendente") → surface it.
+            if (isRetryableLabelMessage(body))
                 return { ready: false };
+            const message = typeof json.mensagem === "string" ? json.mensagem : undefined;
+            if (response.status !== 200) {
+                return { ready: false, message: message ?? `http_${response.status}: ${body.slice(0, 200)}` };
+            }
             return message ? { ready: false, message } : { ready: false };
         },
     };

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

@@ -9,7 +9,7 @@ const openAIResponsesAgentRunner_js_1 = require("./openAIResponsesAgentRunner.js
  * `L3` record so a prompt change can invalidate stale estimates in background
  * instead of at checkout.
  */
-exports.DIMENSION_PROMPT_VERSION = "2026-09-11.responses.v4-indice";
+exports.DIMENSION_PROMPT_VERSION = "2026-09-15.responses.v5-foto";
 /**
  * Strict JSON schema for the response.
  *
@@ -80,7 +80,36 @@ function descreverProduto(p, i) {
         .join("\n");
     return `${linha}\n${contexto}`;
 }
-function createPrompt(products, boxes, samples) {
+/**
+ * As fotos do lote, na ordem dos produtos, com o índice a que cada uma pertence.
+ *
+ * **A ordem é o único vínculo entre foto e produto.** A API recebe uma lista de
+ * imagens sem rótulo: se os produtos 2 e 4 têm foto e os outros não, o modelo vê
+ * duas imagens soltas e nada diz de quem são. Por isso o prompt declara a
+ * correspondência explicitamente (ver {@link descreverFotos}) e esta função
+ * preserva a ordem — trocar as duas coisas de lugar faria o modelo descrever a
+ * caneca olhando para o tapete, e a resposta voltaria com cara de certa.
+ */
+function fotosDoLote(products) {
+    return products
+        .map((p, i) => ({ indice: i + 1, url: p.imageUrl }))
+        .filter((f) => (0, frete_1.usablePhotoUrl)(f.url));
+}
+/** A linha do prompt que amarra cada foto ao produto dela. */
+function descreverFotos(fotos, total) {
+    if (fotos.length === 0)
+        return "";
+    const mapa = fotos.map((f, i) => `a ${i + 1}ª é do produto ${f.indice}`).join(", ");
+    const parcial = fotos.length < total
+        ? ` Os outros ${total - fotos.length} produtos não têm foto — para eles vale só o texto.`
+        : "";
+    return (`\n📷 FOTOS (${fotos.length}, nesta ordem): ${mapa}.${parcial}\n` +
+        `Use a foto sobretudo para os traços do campo attrs — se cede, se empilha, se precisa ir em pé, ` +
+        `se quebra. Para isso ela vale mais que o nome.\n` +
+        `Para os centímetros, desconfie dela: foto sem referência de escala não dá medida. ` +
+        `Peso e nome continuam mandando no tamanho; a foto ajusta a forma.\n`);
+}
+function createPrompt(products, boxes, samples, fotos = []) {
     const box = largestBox(boxes);
     const maxWidth = Math.floor(box.width * 0.8);
     const maxHeight = Math.floor(box.height * 0.8);
@@ -92,6 +121,7 @@ function createPrompt(products, boxes, samples) {
     return (`Você é um especialista em dimensões de produtos brasileiros para e-commerce.\n\n` +
         `🚨 LIMITES FÍSICOS OBRIGATÓRIOS:\n- Largura máxima: ${maxWidth}cm\n- Altura máxima: ${maxHeight}cm\n- Comprimento máximo: ${maxLength}cm\n(Maior caixa: ${box.name ?? "—"})\n\n` +
         `📦 PRODUTOS PARA ESTIMAR:\n${products.map(descreverProduto).join("\n")}\n` +
+        descreverFotos(fotos, products.length) +
         samplesSection +
         `\n🧱 COMO O PRODUTO OCUPA ESPAÇO (campo attrs, um por produto):\n` +
         `- fragile: quebra se levar peso em cima — vidro, cerâmica, garrafa, ovo\n` +
@@ -156,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 ?? "",
@@ -164,16 +194,19 @@ function createOpenAIDimensionEstimator(options) {
             model,
             ...(apiUrl ? { apiUrl } : {}),
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(imageDetail ? { imageDetail } : {}),
         });
     return {
         async estimate(products, boxes, productSamples = []) {
             if (!boxes.length)
                 throw new Error("estimate: no boxes provided");
+            const fotos = fotosDoLote(products);
             const result = await agent.run({
                 task: "estimate-dimensions",
                 promptVersion: exports.DIMENSION_PROMPT_VERSION,
                 system: "Você é um especialista em dimensões de produtos. Use os exemplos personalizados como prioridade máxima quando o nome bater.",
-                user: createPrompt(products, boxes, productSamples),
+                user: createPrompt(products, boxes, productSamples, fotos),
+                ...(fotos.length ? { images: fotos.map((f) => f.url) } : {}),
                 schema: { name: "product_dimensions", schema: DIMENSIONS_SCHEMA },
                 temperature,
             });

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/correiosLabelHttpClient.d.ts

@@ -30,6 +30,8 @@ export interface CorreiosLabelHttpClientOptions {
     retryDelayMs?: number;
     /** Label size sent to Correios: "P" padrão or "R" reduzido. Default "P". */
     tipoRotulo?: string;
+    /** Label layout sent to Correios: "EN" etiqueta or "ET" etiqueta+recibo. Default "EN". */
+    formatoRotulo?: string;
     /**
      * Download endpoint template; `{idRecibo}` is substituted. Default follows the
      * Correios async-download convention. Override if homolog differs.

package/dist/correiosLabelHttpClient.js

@@ -27,8 +27,23 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function isRetryableLabelMessage(msg) {
     return /consulte novamente|ainda n[ãa]o foi gerado|n[ãa]o (foi )?gerado|PPN-291/i.test(msg);
 }
+/**
+ * A well-formed PDF starts with the `%PDF-` header and ends with the `%%EOF`
+ * trailer. Correios can answer a mid-render poll with a *partial* byte stream
+ * (correct content-type, non-empty body) — accepting that yields the corrupted
+ * label users saw. The Wix/Shopify apps sidestep it by reading the base64 from
+ * JSON (`dados`), which only appears once the render is complete; when we do get
+ * raw bytes we apply the same "only if complete" rule here.
+ */
+function isCompletePdf(buf) {
+    if (buf.length < 100)
+        return false;
+    if (buf.subarray(0, 5).toString("latin1") !== "%PDF-")
+        return false;
+    return buf.subarray(Math.max(0, buf.length - 1024)).toString("latin1").includes("%%EOF");
+}
 export function createCorreiosLabelHttpClient(options = {}) {
-    const { fetch = globalThis.fetch, baseUrl = correiosApiUrl, timeoutMs = 20000, retries = 2, retryDelayMs = 500, tipoRotulo = "P", downloadPath = "/prepostagem/v1/prepostagens/rotulo/download/assincrono/{idRecibo}", logger = console, } = options;
+    const { fetch = globalThis.fetch, baseUrl = correiosApiUrl, timeoutMs = 20000, retries = 2, retryDelayMs = 500, tipoRotulo = "P", formatoRotulo = "EN", downloadPath = "/prepostagem/v1/prepostagens/rotulo/download/assincrono/{idRecibo}", logger = console, } = options;
     if (typeof fetch !== "function") {
         throw new Error("createCorreiosLabelHttpClient: no fetch available (Node 18+ or pass options.fetch)");
     }
@@ -86,7 +101,8 @@ export function createCorreiosLabelHttpClient(options = {}) {
             const response = await fetchWithRetry(`${baseUrl}/prepostagem/v1/prepostagens/rotulo/assincrono/pdf`, {
                 method: "POST",
                 headers: authHeaders(token),
-                body: JSON.stringify({ idsPrePostagem: ids, tipoRotulo }),
+                // formatoRotulo mirrors the Wix/Shopify apps — Correios expects it.
+                body: JSON.stringify({ idsPrePostagem: ids, tipoRotulo, formatoRotulo }),
             });
             const json = (await response.json().catch(() => ({})));
             if (!json.idRecibo)
@@ -94,40 +110,46 @@ export function createCorreiosLabelHttpClient(options = {}) {
             return { idRecibo: json.idRecibo };
         },
         async downloadLabelPdf(idRecibo, token) {
+            // Mirror the Wix/Shopify apps: plain GET asking for JSON, and the base64
+            // PDF is read from `dados`. Reading JSON (not raw bytes) means we only ever
+            // accept a *complete* PDF — a mid-render poll simply has no `dados` yet, so
+            // we keep polling instead of handing back a corrupted file.
             const path = downloadPath.replace("{idRecibo}", encodeURIComponent(idRecibo));
-            // tipoRotulo is also accepted as a query param on the download (PPN-285).
-            const sep = path.includes("?") ? "&" : "?";
-            const url = `${baseUrl}${path}${sep}tipoRotulo=${encodeURIComponent(tipoRotulo)}`;
-            const response = await fetchWithRetry(url, {
+            const response = await fetchWithRetry(`${baseUrl}${path}`, {
                 method: "GET",
-                headers: { Accept: "application/pdf, application/json", Authorization: `Bearer ${token}` },
+                headers: authHeaders(token),
             });
-            const contentType = response.headers.get("content-type") ?? "";
             // 202 (or 204) = still processing; tell the use case to poll again.
             if (response.status === 202 || response.status === 204)
                 return { ready: false };
-            if (response.status !== 200) {
-                const body = await response.text().catch(() => "");
-                // A retryable business message can arrive with a non-2xx status too.
-                if (isRetryableLabelMessage(body))
-                    return { ready: false };
-                return { ready: false, message: `http_${response.status}: ${body.slice(0, 200)}` };
-            }
-            // Correios may return the PDF as raw bytes (application/pdf) or wrapped in
-            // JSON as base64 (dados/pdf). Handle both.
+            const contentType = response.headers.get("content-type") ?? "";
+            // Correios occasionally answers with raw bytes anyway — accept them only if
+            // they form a complete PDF (%PDF header + %%EOF trailer); otherwise it's a
+            // half-rendered stream, so treat it as not-ready and keep polling.
             if (contentType.includes("application/pdf") || contentType.includes("octet-stream")) {
                 const buf = Buffer.from(await response.arrayBuffer());
-                return buf.length ? { ready: true, pdfBase64: buf.toString("base64") } : { ready: false };
+                return isCompletePdf(buf) ? { ready: true, pdfBase64: buf.toString("base64") } : { ready: false };
+            }
+            // JSON path (the happy path the apps use).
+            const body = await response.text().catch(() => "");
+            let json = {};
+            try {
+                json = body ? JSON.parse(body) : {};
+            }
+            catch {
+                json = {};
             }
-            const json = (await response.json().catch(() => ({})));
             const pdfBase64 = (json.dados ?? json.pdf ?? json.base64 ?? json.arquivo);
             if (pdfBase64)
                 return { ready: true, pdfBase64 };
-            // 200 without a PDF carries a business message (e.g. "status Pendente" or
-            // "ainda não foi gerado, consulte novamente"). Retryable ones → keep polling.
-            const message = typeof json.mensagem === "string" ? json.mensagem : undefined;
-            if (message && isRetryableLabelMessage(message))
+            // No PDF yet. A transient message (PPN-291 / "consulte novamente") → keep
+            // polling; a terminal one (e.g. "status Pendente") → surface it.
+            if (isRetryableLabelMessage(body))
                 return { ready: false };
+            const message = typeof json.mensagem === "string" ? json.mensagem : undefined;
+            if (response.status !== 200) {
+                return { ready: false, message: message ?? `http_${response.status}: ${body.slice(0, 200)}` };
+            }
             return message ? { ready: false, message } : { ready: false };
         },
     };

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,13 +19,14 @@
  * (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
  * `L3` record so a prompt change can invalidate stale estimates in background
  * instead of at checkout.
  */
-export declare const DIMENSION_PROMPT_VERSION = "2026-09-11.responses.v4-indice";
+export declare const DIMENSION_PROMPT_VERSION = "2026-09-15.responses.v5-foto";
 export interface OpenAIDimensionEstimatorOptions {
     apiKey?: string;
     fetch?: FetchLike;
@@ -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,11 +1,11 @@
-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
  * `L3` record so a prompt change can invalidate stale estimates in background
  * instead of at checkout.
  */
-export const DIMENSION_PROMPT_VERSION = "2026-09-11.responses.v4-indice";
+export const DIMENSION_PROMPT_VERSION = "2026-09-15.responses.v5-foto";
 /**
  * Strict JSON schema for the response.
  *
@@ -76,7 +76,36 @@ function descreverProduto(p, i) {
         .join("\n");
     return `${linha}\n${contexto}`;
 }
-function createPrompt(products, boxes, samples) {
+/**
+ * As fotos do lote, na ordem dos produtos, com o índice a que cada uma pertence.
+ *
+ * **A ordem é o único vínculo entre foto e produto.** A API recebe uma lista de
+ * imagens sem rótulo: se os produtos 2 e 4 têm foto e os outros não, o modelo vê
+ * duas imagens soltas e nada diz de quem são. Por isso o prompt declara a
+ * correspondência explicitamente (ver {@link descreverFotos}) e esta função
+ * preserva a ordem — trocar as duas coisas de lugar faria o modelo descrever a
+ * caneca olhando para o tapete, e a resposta voltaria com cara de certa.
+ */
+function fotosDoLote(products) {
+    return products
+        .map((p, i) => ({ indice: i + 1, url: p.imageUrl }))
+        .filter((f) => usablePhotoUrl(f.url));
+}
+/** A linha do prompt que amarra cada foto ao produto dela. */
+function descreverFotos(fotos, total) {
+    if (fotos.length === 0)
+        return "";
+    const mapa = fotos.map((f, i) => `a ${i + 1}ª é do produto ${f.indice}`).join(", ");
+    const parcial = fotos.length < total
+        ? ` Os outros ${total - fotos.length} produtos não têm foto — para eles vale só o texto.`
+        : "";
+    return (`\n📷 FOTOS (${fotos.length}, nesta ordem): ${mapa}.${parcial}\n` +
+        `Use a foto sobretudo para os traços do campo attrs — se cede, se empilha, se precisa ir em pé, ` +
+        `se quebra. Para isso ela vale mais que o nome.\n` +
+        `Para os centímetros, desconfie dela: foto sem referência de escala não dá medida. ` +
+        `Peso e nome continuam mandando no tamanho; a foto ajusta a forma.\n`);
+}
+function createPrompt(products, boxes, samples, fotos = []) {
     const box = largestBox(boxes);
     const maxWidth = Math.floor(box.width * 0.8);
     const maxHeight = Math.floor(box.height * 0.8);
@@ -88,6 +117,7 @@ function createPrompt(products, boxes, samples) {
     return (`Você é um especialista em dimensões de produtos brasileiros para e-commerce.\n\n` +
         `🚨 LIMITES FÍSICOS OBRIGATÓRIOS:\n- Largura máxima: ${maxWidth}cm\n- Altura máxima: ${maxHeight}cm\n- Comprimento máximo: ${maxLength}cm\n(Maior caixa: ${box.name ?? "—"})\n\n` +
         `📦 PRODUTOS PARA ESTIMAR:\n${products.map(descreverProduto).join("\n")}\n` +
+        descreverFotos(fotos, products.length) +
         samplesSection +
         `\n🧱 COMO O PRODUTO OCUPA ESPAÇO (campo attrs, um por produto):\n` +
         `- fragile: quebra se levar peso em cima — vidro, cerâmica, garrafa, ovo\n` +
@@ -152,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 ?? "",
@@ -160,16 +190,19 @@ export function createOpenAIDimensionEstimator(options) {
             model,
             ...(apiUrl ? { apiUrl } : {}),
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(imageDetail ? { imageDetail } : {}),
         });
     return {
         async estimate(products, boxes, productSamples = []) {
             if (!boxes.length)
                 throw new Error("estimate: no boxes provided");
+            const fotos = fotosDoLote(products);
             const result = await agent.run({
                 task: "estimate-dimensions",
                 promptVersion: DIMENSION_PROMPT_VERSION,
                 system: "Você é um especialista em dimensões de produtos. Use os exemplos personalizados como prioridade máxima quando o nome bater.",
-                user: createPrompt(products, boxes, productSamples),
+                user: createPrompt(products, boxes, productSamples, fotos),
+                ...(fotos.length ? { images: fotos.map((f) => f.url) } : {}),
                 schema: { name: "product_dimensions", schema: DIMENSIONS_SCHEMA },
                 temperature,
             });

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.13.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.13.0"
+    "@meuecommerce/frete": "^0.15.0"
   },
   "module": "./dist/index.js",
   "repository": {