@meuecommerce/frete-adapter-node 0.3.0 → 0.4.0

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 : [];
+        },
     };
 }

package/dist/correiosLabelHttpClient.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Node implementation of the `CorreiosLabelClient` port using global `fetch`.
+ *
+ * Mirrors `correiosHttpClient.ts`: same base URL, per-request timeout, and
+ * bounded retry on transient network failures. It stays deliberately thin —
+ * one round-trip per method; the "request PDF then poll" loop lives in the
+ * `generateLabel` use case.
+ *
+ * Endpoints (Correios pré-postagem API):
+ * - `POST /prepostagem/v1/prepostagens`                       — create
+ * - `POST /prepostagem/v1/prepostagens/rotulo/assincrono/pdf` — request async PDF
+ * - `GET  /prepostagem/v1/prepostagens/rotulo/download/assincrono/{idRecibo}` — poll/download
+ *
+ * NOTE: the async download path isn't in the public docs mirror; the default
+ * below is the officially-referenced one and is overridable via `downloadPath`
+ * so it can be corrected against homolog without touching the use case.
+ */
+import { type CorreiosLabelClient } from "@meuecommerce/frete";
+type FetchLike = typeof globalThis.fetch;
+export interface CorreiosLabelHttpClientOptions {
+    /** Injectable fetch (defaults to global fetch). */
+    fetch?: FetchLike;
+    /** Correios API base URL (defaults to the production URL). */
+    baseUrl?: string;
+    /** Per-request timeout, ms. Default 20000. */
+    timeoutMs?: number;
+    /** Max attempts per call. Default 2. */
+    retries?: number;
+    /** Base backoff between retries, ms (exponential). Default 500. */
+    retryDelayMs?: number;
+    /** Label size sent to Correios: "P" padrão or "R" reduzido. Default "P". */
+    tipoRotulo?: string;
+    /**
+     * Download endpoint template; `{idRecibo}` is substituted. Default follows the
+     * Correios async-download convention. Override if homolog differs.
+     */
+    downloadPath?: string;
+    logger?: Pick<Console, "warn" | "error" | "log">;
+}
+export declare function createCorreiosLabelHttpClient(options?: CorreiosLabelHttpClientOptions): CorreiosLabelClient;
+export {};

package/dist/correiosLabelHttpClient.js

@@ -0,0 +1,134 @@
+/**
+ * Node implementation of the `CorreiosLabelClient` port using global `fetch`.
+ *
+ * Mirrors `correiosHttpClient.ts`: same base URL, per-request timeout, and
+ * bounded retry on transient network failures. It stays deliberately thin —
+ * one round-trip per method; the "request PDF then poll" loop lives in the
+ * `generateLabel` use case.
+ *
+ * Endpoints (Correios pré-postagem API):
+ * - `POST /prepostagem/v1/prepostagens`                       — create
+ * - `POST /prepostagem/v1/prepostagens/rotulo/assincrono/pdf` — request async PDF
+ * - `GET  /prepostagem/v1/prepostagens/rotulo/download/assincrono/{idRecibo}` — poll/download
+ *
+ * NOTE: the async download path isn't in the public docs mirror; the default
+ * below is the officially-referenced one and is overridable via `downloadPath`
+ * so it can be corrected against homolog without touching the use case.
+ */
+import { correiosApiUrl, } from "@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);
+}
+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;
+    if (typeof fetch !== "function") {
+        throw new Error("createCorreiosLabelHttpClient: no fetch available (Node 18+ or pass options.fetch)");
+    }
+    async function fetchWithRetry(url, init) {
+        let lastError;
+        for (let attempt = 0; attempt < retries; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                return await fetch(url, { ...init, signal: controller.signal });
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt === retries - 1)
+                    break;
+                await sleep(retryDelayMs * Math.pow(2, attempt));
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        throw lastError;
+    }
+    function authHeaders(token) {
+        return {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            Authorization: `Bearer ${token}`,
+        };
+    }
+    return {
+        async createPrepostagem(payload, token) {
+            const response = await fetchWithRetry(`${baseUrl}/prepostagem/v1/prepostagens`, {
+                method: "POST",
+                headers: authHeaders(token),
+                body: JSON.stringify(payload),
+            });
+            // Correios returns a structured error body (with the failure reason) on 4xx;
+            // the use case filters by `txErro`, so pass it through rather than throwing.
+            const json = (await response.json().catch(() => ({})));
+            if (response.status !== 200 && response.status !== 201) {
+                logger.warn(`[correios.createPrepostagem] status=${response.status} body=${JSON.stringify(json)}`);
+                if (!json.txErro)
+                    json.txErro = `http_${response.status}`;
+            }
+            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",
+                headers: authHeaders(token),
+                body: JSON.stringify({ idsPrePostagem: ids, tipoRotulo }),
+            });
+            const json = (await response.json().catch(() => ({})));
+            if (!json.idRecibo)
+                throw new Error(`requestLabelPdf: no idRecibo (status=${response.status})`);
+            return { idRecibo: json.idRecibo };
+        },
+        async downloadLabelPdf(idRecibo, token) {
+            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, {
+                method: "GET",
+                headers: { Accept: "application/pdf, application/json", Authorization: `Bearer ${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.
+            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 };
+            }
+            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))
+                return { ready: false };
+            return message ? { ready: false, message } : { ready: false };
+        },
+    };
+}

package/dist/envSecretStore.d.ts

@@ -4,13 +4,13 @@
  *
  * Secret names are normalized to an env-var convention: uppercased with
  * non-alphanumerics turned into underscores, plus an optional prefix. So
- * `getSecret("backfill_secret")` reads `MEUFRETE_BACKFILL_SECRET` by default.
+ * `getSecret("backfill_secret")` reads `FRETE_BACKFILL_SECRET` by default.
  */
 import type { SecretStore } from "@meuecommerce/frete";
 export interface EnvSecretStoreOptions {
     /** Env source (defaults to process.env). */
     env?: Record<string, string | undefined>;
-    /** Prefix applied to normalized names. Default "MEUFRETE_". Pass "" for none. */
+    /** Prefix applied to normalized names. Default "FRETE_". Pass "" for none. */
     prefix?: string;
 }
 export declare class EnvSecretStore implements SecretStore {

package/dist/envSecretStore.js

@@ -3,7 +3,7 @@ export class EnvSecretStore {
     prefix;
     constructor(options = {}) {
         this.env = options.env ?? process.env;
-        this.prefix = options.prefix ?? "MEUFRETE_";
+        this.prefix = options.prefix ?? "FRETE_";
     }
     key(name) {
         return this.prefix + name.replace(/[^a-zA-Z0-9]+/g, "_").toUpperCase();

package/dist/inMemoryDimensionMemory.d.ts

@@ -0,0 +1,10 @@
+import type { DimensionMemory, DimensionMemoryEntry, DimensionRecord, ProductIdentity } from "@meuecommerce/frete";
+export declare class InMemoryDimensionMemory implements DimensionMemory {
+    private readonly records;
+    constructor(seed?: DimensionMemoryEntry[]);
+    /** How many products the memory holds. For tests and local inspection. */
+    get size(): number;
+    get(identities: ProductIdentity[]): Promise<Map<string, DimensionRecord>>;
+    set(entries: DimensionMemoryEntry[]): Promise<void>;
+    invalidate(identities: ProductIdentity[]): Promise<void>;
+}

package/dist/inMemoryDimensionMemory.js

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+import { canOverwrite, productKey } from "@meuecommerce/frete";
+export 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 = 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 = 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 && !canOverwrite(existing.source, record.source))
+                continue;
+            this.records.set(key.value, record);
+        }
+    }
+    async invalidate(identities) {
+        for (const identity of identities) {
+            const key = productKey(identity);
+            if (key)
+                this.records.delete(key.value);
+        }
+    }
+}

package/dist/index.d.ts

@@ -6,11 +6,18 @@
  */
 export { createCorreiosHttpClient } from "./correiosHttpClient.js";
 export type { CorreiosHttpClientOptions } from "./correiosHttpClient.js";
+export { createCorreiosLabelHttpClient } from "./correiosLabelHttpClient.js";
+export type { CorreiosLabelHttpClientOptions } from "./correiosLabelHttpClient.js";
 export { InMemorySettingsStore } from "./inMemorySettingsStore.js";
 export type { InMemorySettingsStoreOptions } from "./inMemorySettingsStore.js";
+export { InMemoryDimensionMemory } from "./inMemoryDimensionMemory.js";
 export { EnvSecretStore } from "./envSecretStore.js";
 export type { EnvSecretStoreOptions } from "./envSecretStore.js";
-export { createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
+export { DIMENSION_PROMPT_VERSION, createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
+export { 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 { OpenAIDimensionEstimatorOptions } from "./openAIDimensionEstimator.js";
 export { createOpenAIBoxDistributor } from "./openAIBoxDistributor.js";
 export type { OpenAIBoxDistributorOptions } from "./openAIBoxDistributor.js";

package/dist/index.js

@@ -5,7 +5,11 @@
  * Shopify/Fly deployment today, and the MCP server next.
  */
 export { createCorreiosHttpClient } from "./correiosHttpClient.js";
+export { createCorreiosLabelHttpClient } from "./correiosLabelHttpClient.js";
 export { InMemorySettingsStore } from "./inMemorySettingsStore.js";
+export { InMemoryDimensionMemory } from "./inMemoryDimensionMemory.js";
 export { EnvSecretStore } from "./envSecretStore.js";
-export { createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
+export { DIMENSION_PROMPT_VERSION, createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
+export { createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.js";
+export { DIMENSION_MEMORY_SCHEMA_SQL, PgDimensionMemory } from "./pgDimensionMemory.js";
 export { createOpenAIBoxDistributor } from "./openAIBoxDistributor.js";

package/dist/openAIDimensionEstimator.d.ts

@@ -1,24 +1,44 @@
 /**
- * `ProductDimensionEstimator` implemented with the OpenAI chat-completions API.
+ * `ProductDimensionEstimator` implemented with the OpenAI Responses API and a
+ * strict structured output.
  *
  * Ports the dimension-estimation path from the Velo `openAI/` modules:
- * - `ai-tools.js`      -> the `estimate_dimensions` tool + request/response handling
+ * - `ai-tools.js`      -> request/response handling (was a forced tool call)
  * - `prompt-methods.js`-> `createDimensionEstimationPrompt`
  * - `box-methods.js`   -> `validateAndOptimizeDimensions` (post-process AI output)
  *
+ * Why the move off chat-completions with a forced tool call: a tool call is a
+ * request for a shape, not a guarantee of one — the arguments still arrive as a
+ * string that can be truncated or malformed, which is why the old code had to
+ * `JSON.parse` and hope. `text.format` with `strict: true` makes the schema a
+ * constraint on decoding instead, so a missing field or an extra one cannot
+ * come back at all.
+ *
  * `fetch` is injectable (defaults to global fetch) so this also runs under Velo
  * with `wix-fetch` passed in. The API key is passed in — the caller resolves it
  * (e.g. via a `SecretStore`), keeping secret handling out of this module.
  */
-import type { ProductDimensionEstimator } from "@meuecommerce/frete";
+import type { LlmAgentRunner, ProductDimensionEstimator } from "@meuecommerce/frete";
 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-04.responses.v1";
 export interface OpenAIDimensionEstimatorOptions {
-    apiKey: string;
+    apiKey?: string;
     fetch?: FetchLike;
     model?: string;
     temperature?: number;
     apiUrl?: string;
     timeoutMs?: number;
+    /**
+     * 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
+     * transport in tests; omit it and one is created from `apiKey`.
+     */
+    runner?: LlmAgentRunner;
 }
 export declare function createOpenAIDimensionEstimator(options: OpenAIDimensionEstimatorOptions): ProductDimensionEstimator;
 export {};