@meuecommerce/frete-adapter-node 0.12.1 → 0.14.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/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,49 @@ function descreverProduto(p, i) {
         .join("\n");
     return `${linha}\n${contexto}`;
 }
-function createPrompt(products, boxes, samples) {
+/**
+ * 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.
+ *
+ * **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) => fotoUtilizavel(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 +134,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` +
@@ -169,11 +212,13 @@ function createOpenAIDimensionEstimator(options) {
         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/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/openAIDimensionEstimator.d.ts

@@ -25,7 +25,7 @@ type FetchLike = typeof globalThis.fetch;
  * `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;

package/dist/openAIDimensionEstimator.js

@@ -5,7 +5,7 @@ import { createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.j
  * `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,49 @@ function descreverProduto(p, i) {
         .join("\n");
     return `${linha}\n${contexto}`;
 }
-function createPrompt(products, boxes, samples) {
+/**
+ * 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.
+ *
+ * **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) => fotoUtilizavel(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 +130,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` +
@@ -165,11 +208,13 @@ export function createOpenAIDimensionEstimator(options) {
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meuecommerce/frete-adapter-node",
-  "version": "0.12.1",
+  "version": "0.14.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.12.1"
+    "@meuecommerce/frete": "^0.14.0"
   },
   "module": "./dist/index.js",
   "repository": {