@meuecommerce/frete-adapter-node 0.3.1 → 0.4.1

package/dist/pgDimensionMemory.js

@@ -0,0 +1,157 @@
+/**
+ * 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.
+ */
+import { MEMORY_LAYER_ORDER, canOverwrite, productKey } from "@meuecommerce/frete";
+export const 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 = 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 ? 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,
+    };
+}
+export class PgDimensionMemory {
+    sql;
+    constructor(options) {
+        this.sql = options.sql;
+    }
+    /** Idempotent — safe to call on every boot. */
+    async migrate() {
+        await this.sql.query(DIMENSION_MEMORY_SCHEMA_SQL);
+    }
+    async get(identities) {
+        const keys = identities.flatMap((identity) => {
+            const key = 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 = 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 = 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;
+    }
+}
+/** Re-exported so callers can reason about precedence without importing core. */
+export { canOverwrite };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meuecommerce/frete-adapter-node",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "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.3.1"
+    "@meuecommerce/frete": "^0.4.1"
   },
   "module": "./dist/index.js",
   "repository": {
@@ -39,5 +39,8 @@
     "url": "git+https://github.com/devstudio163/frete.git",
     "directory": "packages/adapter-node"
   },
-  "homepage": "https://github.com/devstudio163/frete"
+  "homepage": "https://github.com/devstudio163/frete",
+  "devDependencies": {
+    "pg-mem": "^3.0.14"
+  }
 }