@meuecommerce/frete-adapter-node 0.3.1 → 0.4.0

package/dist/cjs/correiosHttpClient.js

@@ -115,5 +115,36 @@ function createCorreiosHttpClient(options = {}) {
         getTime(payload, token) {
             return estimate("/prazo/v1/nacional", payload, token, "correios.getTime");
         },
+        async track(codes, token) {
+            if (!codes.length)
+                return [];
+            // SRO Rastro takes the codes as repeated `codigosObjetos` query params and
+            // `resultado=T` for the full event history (vs. `U` for the latest only).
+            // The language MUST go in the `Accept-Language` header (pt-BR/en/es-ES) —
+            // an `idioma` query param is rejected with SRO-018.
+            const params = new URLSearchParams();
+            for (const code of codes)
+                params.append("codigosObjetos", code);
+            params.append("resultado", "T");
+            const url = `${baseUrl}${frete_1.correiosSroPath}?${params.toString()}`;
+            const response = await fetchWithRetry(url, {
+                method: "GET",
+                headers: {
+                    Accept: "application/json",
+                    "Accept-Language": "pt-BR",
+                    Authorization: `Bearer ${token}`,
+                },
+            });
+            if (response.status === 401) {
+                throw { status: 401, message: "unauthorized" };
+            }
+            if (response.status !== 200) {
+                const json = await response.json().catch(() => ({}));
+                logger.warn(`[correios.track] invalid response. status=${response.status} body=${JSON.stringify(json)}`);
+                return [];
+            }
+            const body = (await response.json());
+            return Array.isArray(body?.objetos) ? body.objetos : [];
+        },
     };
 }

package/dist/cjs/correiosLabelHttpClient.js

@@ -20,6 +20,16 @@ exports.createCorreiosLabelHttpClient = createCorreiosLabelHttpClient;
  */
 const frete_1 = require("@meuecommerce/frete");
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Some Correios label messages are transient: the pré-postagem is fine and the
+ * PDF is still being produced, so a later poll succeeds (e.g. PPN-291 "O rótulo
+ * ainda não foi gerado. Por favor, consulte novamente."). Distinguish those from
+ * terminal ones — notably PPN-288 "status Pendente" — which won't clear by
+ * polling and must be surfaced. Retryable → keep polling; terminal → `message`.
+ */
+function isRetryableLabelMessage(msg) {
+    return /consulte novamente|ainda n[ãa]o foi gerado|n[ãa]o (foi )?gerado|PPN-291/i.test(msg);
+}
 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;
     if (typeof fetch !== "function") {
@@ -69,6 +79,12 @@ function createCorreiosLabelHttpClient(options = {}) {
             }
             return json;
         },
+        async getPrepostagemStatus(id, token) {
+            const response = await fetchWithRetry(`${baseUrl}/prepostagem/v2/prepostagens?id=${encodeURIComponent(id)}&page=0&size=1`, { method: "GET", headers: authHeaders(token) });
+            const json = (await response.json().catch(() => ({})));
+            const item = Array.isArray(json.itens) ? json.itens[0] : undefined;
+            return item ?? null;
+        },
         async requestLabelPdf(ids, token) {
             const response = await fetchWithRetry(`${baseUrl}/prepostagem/v1/prepostagens/rotulo/assincrono/pdf`, {
                 method: "POST",
@@ -95,6 +111,9 @@ function createCorreiosLabelHttpClient(options = {}) {
                 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
@@ -107,8 +126,11 @@ function createCorreiosLabelHttpClient(options = {}) {
             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").
+            // 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))
+                return { ready: false };
             return message ? { ready: false, message } : { ready: false };
         },
     };

package/dist/cjs/inMemoryDimensionMemory.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryDimensionMemory = void 0;
+/**
+ * In-memory `DimensionMemory` — local dev, the MCP server's local mode, and
+ * tests. Production swaps it for the Postgres-backed one; the core does not
+ * change.
+ *
+ * It enforces the layer rule rather than just storing what it is given: an
+ * agent guess (`L3`) must never overwrite what the merchant declared (`L0`).
+ * Putting that here as well as in the Postgres implementation is deliberate —
+ * it is a property of the memory, not of one backend, and the tests that pin it
+ * run against this one.
+ */
+const frete_1 = require("@meuecommerce/frete");
+class InMemoryDimensionMemory {
+    records = new Map();
+    constructor(seed = []) {
+        // O seed passa pela mesma regra de camada que uma escrita normal.
+        void this.set(seed);
+    }
+    /** How many products the memory holds. For tests and local inspection. */
+    get size() {
+        return this.records.size;
+    }
+    async get(identities) {
+        const found = new Map();
+        for (const identity of identities) {
+            const key = (0, frete_1.productKey)(identity);
+            if (!key)
+                continue;
+            const record = this.records.get(key.value);
+            if (record)
+                found.set(key.value, record);
+        }
+        return found;
+    }
+    async set(entries) {
+        for (const { identity, record } of entries) {
+            const key = (0, frete_1.productKey)(identity);
+            // Sem chave derivável não há o que gravar: inventar uma faria produtos
+            // sem relação compartilharem entrada.
+            if (!key)
+                continue;
+            const existing = this.records.get(key.value);
+            if (existing && !(0, frete_1.canOverwrite)(existing.source, record.source))
+                continue;
+            this.records.set(key.value, record);
+        }
+    }
+    async invalidate(identities) {
+        for (const identity of identities) {
+            const key = (0, frete_1.productKey)(identity);
+            if (key)
+                this.records.delete(key.value);
+        }
+    }
+}
+exports.InMemoryDimensionMemory = InMemoryDimensionMemory;

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createOpenAIBoxDistributor = exports.createOpenAIDimensionEstimator = exports.EnvSecretStore = exports.InMemorySettingsStore = exports.createCorreiosHttpClient = void 0;
+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;
 /**
  * @meuecommerce/frete-adapter-node — Node implementations of @meuecommerce/frete ports.
  *
@@ -9,11 +9,21 @@ exports.createOpenAIBoxDistributor = exports.createOpenAIDimensionEstimator = ex
  */
 var correiosHttpClient_js_1 = require("./correiosHttpClient.js");
 Object.defineProperty(exports, "createCorreiosHttpClient", { enumerable: true, get: function () { return correiosHttpClient_js_1.createCorreiosHttpClient; } });
+var correiosLabelHttpClient_js_1 = require("./correiosLabelHttpClient.js");
+Object.defineProperty(exports, "createCorreiosLabelHttpClient", { enumerable: true, get: function () { return correiosLabelHttpClient_js_1.createCorreiosLabelHttpClient; } });
 var inMemorySettingsStore_js_1 = require("./inMemorySettingsStore.js");
 Object.defineProperty(exports, "InMemorySettingsStore", { enumerable: true, get: function () { return inMemorySettingsStore_js_1.InMemorySettingsStore; } });
+var inMemoryDimensionMemory_js_1 = require("./inMemoryDimensionMemory.js");
+Object.defineProperty(exports, "InMemoryDimensionMemory", { enumerable: true, get: function () { return inMemoryDimensionMemory_js_1.InMemoryDimensionMemory; } });
 var envSecretStore_js_1 = require("./envSecretStore.js");
 Object.defineProperty(exports, "EnvSecretStore", { enumerable: true, get: function () { return envSecretStore_js_1.EnvSecretStore; } });
 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, "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; } });
+Object.defineProperty(exports, "PgDimensionMemory", { enumerable: true, get: function () { return pgDimensionMemory_js_1.PgDimensionMemory; } });
 var openAIBoxDistributor_js_1 = require("./openAIBoxDistributor.js");
 Object.defineProperty(exports, "createOpenAIBoxDistributor", { enumerable: true, get: function () { return openAIBoxDistributor_js_1.createOpenAIBoxDistributor; } });

package/dist/cjs/openAIDimensionEstimator.js

@@ -1,31 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIMENSION_PROMPT_VERSION = void 0;
 exports.createOpenAIDimensionEstimator = createOpenAIDimensionEstimator;
-const ESTIMATE_DIMENSIONS_TOOL = {
-    type: "function",
-    function: {
-        name: "estimate_dimensions",
-        description: "Estima dimensões de produtos PRESERVANDO os nomes exatos fornecidos",
-        parameters: {
-            type: "object",
-            properties: {
-                products: {
-                    type: "array",
-                    items: {
-                        type: "object",
-                        properties: {
-                            name: { type: "string" },
-                            length: { type: "number", description: "Comprimento em cm" },
-                            width: { type: "number", description: "Largura em cm" },
-                            height: { type: "number", description: "Altura em cm" },
-                        },
-                        required: ["name", "length", "width", "height"],
-                    },
+const openAIResponsesAgentRunner_js_1 = require("./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.
+ */
+exports.DIMENSION_PROMPT_VERSION = "2026-09-04.responses.v1";
+/**
+ * Strict JSON schema for the response.
+ *
+ * `strict: true` has two requirements that are easy to miss and reject the
+ * whole request when absent: every object needs `additionalProperties: false`,
+ * and `required` has to list every property — optional fields are not allowed.
+ */
+const DIMENSIONS_SCHEMA = {
+    type: "object",
+    properties: {
+        products: {
+            type: "array",
+            description: "Uma entrada por produto pedido, na mesma ordem.",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "O nome EXATO recebido, sem reescrever" },
+                    length: { type: "number", description: "Comprimento em cm" },
+                    width: { type: "number", description: "Largura em cm" },
+                    height: { type: "number", description: "Altura em cm" },
                 },
+                required: ["name", "length", "width", "height"],
+                additionalProperties: false,
             },
-            required: ["products"],
         },
     },
+    required: ["products"],
+    additionalProperties: false,
 };
 function largestBox(boxes) {
     return boxes.reduce((largest, current) => current.width * current.height * current.length > largest.width * largest.height * largest.length ? current : largest);
@@ -43,8 +54,7 @@ function createPrompt(products, boxes, samples) {
         `🚨 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((p, i) => `${i + 1}. ${p.name} - ${p.quantity}x (${p.weight}kg cada)`).join("\n")}\n` +
         samplesSection +
-        `\n⚠️ REGRAS: respeite os limites; preserve os nomes EXATOS; retorne length×width×height em cm.\n` +
-        `Responda usando a função 'estimate_dimensions'.`);
+        `\n⚠️ REGRAS: respeite os limites; preserve os nomes EXATOS; retorne length×width×height em cm.`);
 }
 /** Apply the largest-box physical limits + a minimum-volume floor to AI output. */
 function validateAndOptimize(aiResult, products, boxes) {
@@ -79,52 +89,32 @@ function validateAndOptimize(aiResult, products, boxes) {
     return { products: optimized };
 }
 function createOpenAIDimensionEstimator(options) {
-    const { apiKey, fetch = globalThis.fetch, model = "gpt-4o-mini", temperature = 0.1, apiUrl = "https://api.openai.com/v1/chat/completions", timeoutMs = 20000, } = options;
-    if (!apiKey)
-        throw new Error("createOpenAIDimensionEstimator: apiKey is required");
-    if (typeof fetch !== "function")
-        throw new Error("createOpenAIDimensionEstimator: no fetch available");
+    const { apiKey, fetch, model = "gpt-4o-mini", temperature = 0.1, apiUrl, timeoutMs, runner } = options;
+    const agent = runner ??
+        (0, openAIResponsesAgentRunner_js_1.createOpenAIResponsesAgentRunner)({
+            apiKey: apiKey ?? "",
+            ...(fetch ? { fetch } : {}),
+            model,
+            ...(apiUrl ? { apiUrl } : {}),
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
     return {
         async estimate(products, boxes, productSamples = []) {
             if (!boxes.length)
                 throw new Error("estimate: no boxes provided");
-            const body = {
-                model,
-                messages: [
-                    {
-                        role: "system",
-                        content: "Você é um especialista em dimensões de produtos. Use os exemplos personalizados como prioridade máxima quando o nome bater.",
-                    },
-                    { role: "user", content: createPrompt(products, boxes, productSamples) },
-                ],
-                tools: [ESTIMATE_DIMENSIONS_TOOL],
-                tool_choice: { type: "function", function: { name: "estimate_dimensions" } },
+            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),
+                schema: { name: "product_dimensions", schema: DIMENSIONS_SCHEMA },
                 temperature,
-            };
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), timeoutMs);
-            let response;
-            try {
-                response = await fetch(apiUrl, {
-                    method: "POST",
-                    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
-                    body: JSON.stringify(body),
-                    signal: controller.signal,
-                });
+            });
+            if (!Array.isArray(result.output?.products)) {
+                throw new Error("Resposta da IA sem a lista de produtos");
             }
-            finally {
-                clearTimeout(timer);
-            }
-            if (!response.ok)
-                throw new Error(`OpenAI API Error: ${response.status} ${response.statusText}`);
-            const json = (await response.json());
-            if (json.error)
-                throw new Error(`OpenAI Error: ${json.error.message}`);
-            const args = json.choices?.[0]?.message?.tool_calls?.[0]?.function?.arguments;
-            if (!args)
-                throw new Error("IA não conseguiu estimar dimensões dos produtos");
-            const parsed = JSON.parse(args);
-            return validateAndOptimize(parsed, products, boxes);
+            const validated = validateAndOptimize(result.output, products, boxes);
+            return result.usage ? { ...validated, usage: result.usage } : validated;
         },
     };
 }

package/dist/cjs/openAIResponsesAgentRunner.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractOutputText = extractOutputText;
+exports.findRefusal = findRefusal;
+exports.createOpenAIResponsesAgentRunner = createOpenAIResponsesAgentRunner;
+/** 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())
+        return json.output_text;
+    const parts = [];
+    for (const item of json.output ?? []) {
+        for (const content of item.content ?? []) {
+            if (typeof content.text === "string")
+                parts.push(content.text);
+        }
+    }
+    return parts.join("").trim();
+}
+/**
+ * A refusal is a *successful* response in which the model declined to fill the
+ * schema. Without this check it would read as empty text and be reported as
+ * "the model could not answer", hiding the real reason.
+ */
+function findRefusal(json) {
+    for (const item of json.output ?? []) {
+        for (const content of item.content ?? []) {
+            if (typeof content.refusal === "string" && content.refusal)
+                return content.refusal;
+        }
+    }
+    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;
+    if (!apiKey)
+        throw new Error("createOpenAIResponsesAgentRunner: apiKey is required");
+    if (typeof fetch !== "function")
+        throw new Error("createOpenAIResponsesAgentRunner: no fetch available");
+    return {
+        async run(request) {
+            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.
+            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 })),
+                    ],
+                });
+            }
+            else {
+                input.push({ role: "user", content: request.user });
+            }
+            const body = {
+                model: defaultModel,
+                input,
+                text: {
+                    format: {
+                        type: "json_schema",
+                        name: request.schema.name,
+                        strict: true,
+                        schema: request.schema.schema,
+                    },
+                },
+            };
+            if (request.temperature !== undefined)
+                body.temperature = request.temperature;
+            if (request.maxOutputTokens !== undefined)
+                body.max_output_tokens = request.maxOutputTokens;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            let response;
+            try {
+                response = await fetch(apiUrl, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!response.ok)
+                throw new Error(`OpenAI API Error: ${response.status} ${response.statusText}`);
+            const json = (await response.json());
+            if (json.error)
+                throw new Error(`OpenAI Error: ${json.error.message}`);
+            const refusal = findRefusal(json);
+            if (refusal)
+                throw new Error(`OpenAI recusou a resposta de ${request.task}: ${refusal}`);
+            const text = extractOutputText(json);
+            if (!text)
+                throw new Error(`Resposta vazia da IA para ${request.task}`);
+            let output;
+            try {
+                output = JSON.parse(text);
+            }
+            catch {
+                throw new Error(`Resposta da IA para ${request.task} não é JSON válido`);
+            }
+            const model = json.model ?? defaultModel;
+            const usage = json.usage
+                ? {
+                    model,
+                    ...(typeof json.usage.input_tokens === "number" ? { inputTokens: json.usage.input_tokens } : {}),
+                    ...(typeof json.usage.output_tokens === "number" ? { outputTokens: json.usage.output_tokens } : {}),
+                }
+                : undefined;
+            // Sempre 1 nesta fase: a repescagem por falha de validação é o próximo
+            // passo, e é ela que vai fazer este número variar.
+            return usage ? { output, usage, model, attempts: 1 } : { output, model, attempts: 1 };
+        },
+    };
+}

package/dist/cjs/pgDimensionMemory.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canOverwrite = exports.PgDimensionMemory = exports.DIMENSION_MEMORY_SCHEMA_SQL = void 0;
+/**
+ * Postgres-backed `DimensionMemory` — the production counterpart of
+ * {@link InMemoryDimensionMemory}.
+ *
+ * Two rules from the port are enforced here in SQL rather than in application
+ * code, because the memory is written from more than one place (the quote path,
+ * the label feedback, the dashboard) and a check that lives in one caller is a
+ * check that the next caller forgets:
+ *
+ * - **A weaker layer never overwrites a stronger one.** The upsert carries the
+ *   layer's rank and only updates when the incoming rank is at least as strong,
+ *   so an agent estimate racing with a merchant's correction loses regardless of
+ *   which arrives last.
+ * - **One round trip per cart.** `get` takes every product at once, because a
+ *   query per line item is exactly what makes a hot path slow.
+ *
+ * The client is the structural {@link SqlClient} rather than a `pg` import, so
+ * this package gains no runtime dependency and the tests can run real SQL
+ * against pg-mem with no network.
+ *
+ * Lookups expand to `IN ($1, $2, …)` instead of the more idiomatic
+ * `= ANY($1)`. Real Postgres accepts both, but pg-mem silently returns zero
+ * rows for the array form, and running the tests against real SQL is worth more
+ * than the tidier query — a cart is a handful of line items, so the parameter
+ * count is not a concern. Revisit if this is ever used for bulk reads.
+ */
+const frete_1 = require("@meuecommerce/frete");
+Object.defineProperty(exports, "canOverwrite", { enumerable: true, get: function () { return frete_1.canOverwrite; } });
+exports.DIMENSION_MEMORY_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS dimension_memory (
+  key             TEXT PRIMARY KEY,
+  instance_id     TEXT NOT NULL,
+  length_cm       DOUBLE PRECISION NOT NULL,
+  width_cm        DOUBLE PRECISION NOT NULL,
+  height_cm       DOUBLE PRECISION NOT NULL,
+  attrs           JSONB,
+  confidence      DOUBLE PRECISION NOT NULL,
+  source          TEXT NOT NULL,
+  layer_rank      INTEGER NOT NULL,
+  prompt_version  TEXT,
+  model           TEXT,
+  updated_at      TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX IF NOT EXISTS dimension_memory_instance_idx ON dimension_memory (instance_id);
+`;
+/** Lower rank = stronger layer, matching `MEMORY_LAYER_ORDER`. */
+function layerRank(layer) {
+    const rank = frete_1.MEMORY_LAYER_ORDER.indexOf(layer);
+    // Uma camada desconhecida é tratada como a mais fraca possível, em vez de
+    // virar -1 e passar por cima de tudo.
+    return rank === -1 ? frete_1.MEMORY_LAYER_ORDER.length : rank;
+}
+/** `$1, $2, …` para `count` parâmetros. */
+function placeholders(count) {
+    return Array.from({ length: count }, (_, i) => `$${i + 1}`).join(", ");
+}
+/** `DOUBLE PRECISION` chega como string em alguns drivers. */
+function num(value) {
+    return typeof value === "number" ? value : Number(value);
+}
+function toRecord(row) {
+    const updatedAt = row.updated_at instanceof Date ? row.updated_at.toISOString() : String(row.updated_at);
+    return {
+        dims: { length: num(row.length_cm), width: num(row.width_cm), height: num(row.height_cm) },
+        ...(row.attrs ? { attrs: row.attrs } : {}),
+        confidence: num(row.confidence),
+        source: row.source,
+        ...(row.prompt_version ? { promptVersion: row.prompt_version } : {}),
+        ...(row.model ? { model: row.model } : {}),
+        updatedAt,
+    };
+}
+class PgDimensionMemory {
+    sql;
+    constructor(options) {
+        this.sql = options.sql;
+    }
+    /** Idempotent — safe to call on every boot. */
+    async migrate() {
+        await this.sql.query(exports.DIMENSION_MEMORY_SCHEMA_SQL);
+    }
+    async get(identities) {
+        const keys = identities.flatMap((identity) => {
+            const key = (0, frete_1.productKey)(identity);
+            return key ? [key.value] : [];
+        });
+        const found = new Map();
+        if (keys.length === 0)
+            return found;
+        const { rows } = await this.sql.query(`SELECT key, length_cm, width_cm, height_cm, attrs, confidence, source, prompt_version, model, updated_at
+         FROM dimension_memory
+        WHERE key IN (${placeholders(keys.length)})`, keys);
+        for (const row of rows)
+            found.set(row.key, toRecord(row));
+        return found;
+    }
+    async set(entries) {
+        const values = [];
+        const tuples = [];
+        for (const { identity, record } of entries) {
+            const key = (0, frete_1.productKey)(identity);
+            // Sem chave derivável não há o que gravar: inventar uma faria produtos
+            // sem relação compartilharem entrada.
+            if (!key)
+                continue;
+            const base = values.length;
+            values.push(key.value, identity.instanceId, record.dims.length, record.dims.width, record.dims.height, record.attrs ? JSON.stringify(record.attrs) : null, record.confidence, record.source, layerRank(record.source), record.promptVersion ?? null, record.model ?? null, record.updatedAt);
+            const p = (offset) => `$${base + offset}`;
+            tuples.push(`(${p(1)}, ${p(2)}, ${p(3)}, ${p(4)}, ${p(5)}, ${p(6)}::jsonb, ${p(7)}, ${p(8)}, ${p(9)}, ${p(10)}, ${p(11)}, ${p(12)}::timestamptz)`);
+        }
+        if (tuples.length === 0)
+            return;
+        await this.sql.query(`INSERT INTO dimension_memory
+         (key, instance_id, length_cm, width_cm, height_cm, attrs, confidence, source, layer_rank, prompt_version, model, updated_at)
+       VALUES ${tuples.join(", ")}
+       ON CONFLICT (key) DO UPDATE SET
+         length_cm      = EXCLUDED.length_cm,
+         width_cm       = EXCLUDED.width_cm,
+         height_cm      = EXCLUDED.height_cm,
+         attrs          = EXCLUDED.attrs,
+         confidence     = EXCLUDED.confidence,
+         source         = EXCLUDED.source,
+         layer_rank     = EXCLUDED.layer_rank,
+         prompt_version = EXCLUDED.prompt_version,
+         model          = EXCLUDED.model,
+         updated_at     = EXCLUDED.updated_at
+       WHERE EXCLUDED.layer_rank <= dimension_memory.layer_rank`, values);
+    }
+    async invalidate(identities) {
+        const keys = identities.flatMap((identity) => {
+            const key = (0, frete_1.productKey)(identity);
+            return key ? [key.value] : [];
+        });
+        if (keys.length === 0)
+            return;
+        await this.sql.query(`DELETE FROM dimension_memory WHERE key IN (${placeholders(keys.length)})`, keys);
+    }
+    /**
+     * Drop agent estimates produced by an older prompt.
+     *
+     * Only touches `L3`: what the merchant declared and what a real label proved
+     * do not go stale because we changed a prompt. Meant to run in background
+     * after a prompt bump — never on the quote path.
+     */
+    async invalidateStaleEstimates(currentPromptVersion) {
+        const { rows } = await this.sql.query(`DELETE FROM dimension_memory
+        WHERE source = 'L3' AND (prompt_version IS NULL OR prompt_version <> $1)
+        RETURNING key`, [currentPromptVersion]);
+        return rows.length;
+    }
+    /** Forget everything for one merchant — uninstall, or a support reset. */
+    async forgetInstance(instanceId) {
+        const { rows } = await this.sql.query(`DELETE FROM dimension_memory WHERE instance_id = $1 RETURNING key`, [instanceId]);
+        return rows.length;
+    }
+}
+exports.PgDimensionMemory = PgDimensionMemory;

package/dist/correiosHttpClient.js

@@ -7,7 +7,7 @@
  *
  * The only host dependency is `fetch`, injectable for tests.
  */
-import { correiosApiUrl, } from "@meuecommerce/frete";
+import { correiosApiUrl, correiosSroPath, } from "@meuecommerce/frete";
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function base64(input) {
     return Buffer.from(input, "utf-8").toString("base64");
@@ -112,5 +112,36 @@ export function createCorreiosHttpClient(options = {}) {
         getTime(payload, token) {
             return estimate("/prazo/v1/nacional", payload, token, "correios.getTime");
         },
+        async track(codes, token) {
+            if (!codes.length)
+                return [];
+            // SRO Rastro takes the codes as repeated `codigosObjetos` query params and
+            // `resultado=T` for the full event history (vs. `U` for the latest only).
+            // The language MUST go in the `Accept-Language` header (pt-BR/en/es-ES) —
+            // an `idioma` query param is rejected with SRO-018.
+            const params = new URLSearchParams();
+            for (const code of codes)
+                params.append("codigosObjetos", code);
+            params.append("resultado", "T");
+            const url = `${baseUrl}${correiosSroPath}?${params.toString()}`;
+            const response = await fetchWithRetry(url, {
+                method: "GET",
+                headers: {
+                    Accept: "application/json",
+                    "Accept-Language": "pt-BR",
+                    Authorization: `Bearer ${token}`,
+                },
+            });
+            if (response.status === 401) {
+                throw { status: 401, message: "unauthorized" };
+            }
+            if (response.status !== 200) {
+                const json = await response.json().catch(() => ({}));
+                logger.warn(`[correios.track] invalid response. status=${response.status} body=${JSON.stringify(json)}`);
+                return [];
+            }
+            const body = (await response.json());
+            return Array.isArray(body?.objetos) ? body.objetos : [];
+        },
     };
 }