@meuecommerce/frete-adapter-node 0.1.0

package/dist/correiosHttpClient.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Node implementation of the `CorreiosClient` port using global `fetch`.
+ *
+ * Ports the retry/backoff behavior from the Velo backend:
+ * - `auth-methods.js`  -> `authenticate` (up to 5 tries, fail fast on 4xx)
+ * - `estimate-methods.js` -> `getPrice`/`getTime` (timeout + 2 retries, backoff)
+ *
+ * The only host dependency is `fetch`, injectable for tests.
+ */
+import { type CorreiosClient } from "@meuecommerce/frete";
+type FetchLike = typeof globalThis.fetch;
+export interface CorreiosHttpClientOptions {
+    /** Injectable fetch (defaults to global fetch). */
+    fetch?: FetchLike;
+    /** Correios API base URL (defaults to the production URL). */
+    baseUrl?: string;
+    /** Per-request timeout for price/time calls, ms. Default 20000. */
+    timeoutMs?: number;
+    /** Max attempts for price/time calls. Default 2. */
+    estimateRetries?: number;
+    /** Base backoff between price/time retries, ms. Default 500 (exponential). */
+    estimateRetryDelayMs?: number;
+    /** Max attempts for authentication. Default 5. */
+    authRetries?: number;
+    /** Fixed delay between auth retries, ms. Default 1000. */
+    authRetryDelayMs?: number;
+    logger?: Pick<Console, "warn" | "error" | "log">;
+}
+export declare function createCorreiosHttpClient(options?: CorreiosHttpClientOptions): CorreiosClient;
+export {};

package/dist/correiosHttpClient.js

@@ -0,0 +1,116 @@
+/**
+ * Node implementation of the `CorreiosClient` port using global `fetch`.
+ *
+ * Ports the retry/backoff behavior from the Velo backend:
+ * - `auth-methods.js`  -> `authenticate` (up to 5 tries, fail fast on 4xx)
+ * - `estimate-methods.js` -> `getPrice`/`getTime` (timeout + 2 retries, backoff)
+ *
+ * The only host dependency is `fetch`, injectable for tests.
+ */
+import { correiosApiUrl, } from "@meuecommerce/frete";
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function base64(input) {
+    return Buffer.from(input, "utf-8").toString("base64");
+}
+export function createCorreiosHttpClient(options = {}) {
+    const { fetch = globalThis.fetch, baseUrl = correiosApiUrl, timeoutMs = 20000, estimateRetries = 2, estimateRetryDelayMs = 500, authRetries = 5, authRetryDelayMs = 1000, logger = console, } = options;
+    if (typeof fetch !== "function") {
+        throw new Error("createCorreiosHttpClient: no fetch available (Node 18+ or pass options.fetch)");
+    }
+    /** Run a fetch with a hard timeout + exponential-backoff retry. */
+    async function fetchWithRetry(url, init) {
+        let lastError;
+        for (let attempt = 0; attempt < estimateRetries; 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 === estimateRetries - 1)
+                    break;
+                await sleep(estimateRetryDelayMs * Math.pow(2, attempt));
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        throw lastError;
+    }
+    async function estimate(path, payload, token, tag) {
+        const url = `${baseUrl}${path}`;
+        const init = {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(payload),
+        };
+        const response = await fetchWithRetry(url, init);
+        if (response.status === 401) {
+            throw { status: 401, message: "unauthorized" };
+        }
+        if (response.status !== 200 && response.status !== 206) {
+            // Correios returns a structured error body on bad requests; the domain
+            // layer filters these out by `txErro`, so pass it through unchanged.
+            const json = await response.json().catch(() => ({}));
+            logger.warn(`[${tag}] invalid response. status=${response.status} body=${JSON.stringify(json)}`);
+            return json;
+        }
+        return (await response.json());
+    }
+    return {
+        async authenticate(credentials) {
+            const url = `${baseUrl}/token/v1/autentica/cartaopostagem`;
+            let lastError;
+            for (let attempt = 0; attempt < authRetries; attempt++) {
+                try {
+                    const response = await fetch(url, {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": "application/json",
+                            accept: "application/json",
+                            Authorization: `Basic ${base64(`${credentials.user}:${credentials.apiKey}`)}`,
+                        },
+                        body: JSON.stringify({ numero: credentials.postcard }),
+                    });
+                    // 4xx come from bad credentials/contract, not transient failures —
+                    // fail fast instead of burning retries (and seconds) on them.
+                    if (response.status >= 400 && response.status < 500) {
+                        throw {
+                            status: response.status,
+                            message: response.status === 401
+                                ? "Erro de autenticação nos correios."
+                                : "Não foi possível autenticar o contrato nos Correios.",
+                        };
+                    }
+                    return (await response.json());
+                }
+                catch (error) {
+                    const status = error?.status;
+                    if (typeof status === "number" && status >= 400 && status < 500)
+                        throw error;
+                    lastError = error;
+                    if (attempt < authRetries - 1) {
+                        await sleep(authRetryDelayMs);
+                    }
+                    else {
+                        // apiKey intentionally omitted from logs — it is a secret.
+                        logger.error("[correios.authenticate]:", error, credentials.user, credentials.postcard);
+                        throw error;
+                    }
+                }
+            }
+            throw lastError;
+        },
+        getPrice(payload, token) {
+            return estimate("/preco/v1/nacional", payload, token, "correios.getPrice");
+        },
+        getTime(payload, token) {
+            return estimate("/prazo/v1/nacional", payload, token, "correios.getTime");
+        },
+    };
+}

package/dist/envSecretStore.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `SecretStore` backed by environment variables — the Node/Fly and MCP-server
+ * equivalent of Wix Secrets Manager.
+ *
+ * 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.
+ */
+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?: string;
+}
+export declare class EnvSecretStore implements SecretStore {
+    private readonly env;
+    private readonly prefix;
+    constructor(options?: EnvSecretStoreOptions);
+    private key;
+    getSecret(name: string): Promise<string | null>;
+}

package/dist/envSecretStore.js

@@ -0,0 +1,15 @@
+export class EnvSecretStore {
+    env;
+    prefix;
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.prefix = options.prefix ?? "MEUFRETE_";
+    }
+    key(name) {
+        return this.prefix + name.replace(/[^a-zA-Z0-9]+/g, "_").toUpperCase();
+    }
+    async getSecret(name) {
+        const value = this.env[this.key(name)];
+        return value == null || value === "" ? null : value;
+    }
+}

package/dist/inMemorySettingsStore.d.ts

@@ -0,0 +1,19 @@
+/**
+ * In-memory `SettingsStore` — for local dev, the MCP server's local mode, and
+ * tests. A real deployment swaps this for a Prisma- or wixData-backed store; the
+ * core and the MCP tools don't change.
+ */
+import type { DefaultSettings, MerchantSettings, SettingsStore } from "@meuecommerce/frete";
+export interface InMemorySettingsStoreOptions {
+    defaults: DefaultSettings;
+    merchants?: Record<string, MerchantSettings>;
+}
+export declare class InMemorySettingsStore implements SettingsStore {
+    private readonly defaults;
+    private readonly merchants;
+    constructor(options: InMemorySettingsStoreOptions);
+    /** Add or replace a merchant's settings. */
+    set(instanceId: string, settings: MerchantSettings): void;
+    getMerchantSettings(instanceId: string): Promise<MerchantSettings | null>;
+    getDefaultSettings(): Promise<DefaultSettings>;
+}

package/dist/inMemorySettingsStore.js

@@ -0,0 +1,20 @@
+export class InMemorySettingsStore {
+    defaults;
+    merchants = new Map();
+    constructor(options) {
+        this.defaults = options.defaults;
+        for (const [id, settings] of Object.entries(options.merchants ?? {})) {
+            this.merchants.set(id, settings);
+        }
+    }
+    /** Add or replace a merchant's settings. */
+    set(instanceId, settings) {
+        this.merchants.set(instanceId, settings);
+    }
+    async getMerchantSettings(instanceId) {
+        return this.merchants.get(instanceId) ?? null;
+    }
+    async getDefaultSettings() {
+        return this.defaults;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @meuecommerce/frete-adapter-node — Node implementations of @meuecommerce/frete ports.
+ *
+ * Wraps global `fetch` so the shipping core can run outside Velo: on the
+ * Shopify/Fly deployment today, and the MCP server next.
+ */
+export { createCorreiosHttpClient } from "./correiosHttpClient.js";
+export type { CorreiosHttpClientOptions } from "./correiosHttpClient.js";
+export { InMemorySettingsStore } from "./inMemorySettingsStore.js";
+export type { InMemorySettingsStoreOptions } from "./inMemorySettingsStore.js";
+export { EnvSecretStore } from "./envSecretStore.js";
+export type { EnvSecretStoreOptions } from "./envSecretStore.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @meuecommerce/frete-adapter-node — Node implementations of @meuecommerce/frete ports.
+ *
+ * Wraps global `fetch` so the shipping core can run outside Velo: on the
+ * Shopify/Fly deployment today, and the MCP server next.
+ */
+export { createCorreiosHttpClient } from "./correiosHttpClient.js";
+export { InMemorySettingsStore } from "./inMemorySettingsStore.js";
+export { EnvSecretStore } from "./envSecretStore.js";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@meuecommerce/frete-adapter-node",
+  "version": "0.1.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/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meuecommerce/frete": "^0.1.0"
+  }
+}