@lexnode/legal-data-sdk 1.0.0 → 1.24.0

package/dist/client.js

@@ -0,0 +1,476 @@
+import { randomUUID } from "node:crypto";
+import { LexNodeError } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RETRY_BASE_DELAY_MS = 500;
+const DEFAULT_RETRY_MAX_DELAY_MS = 8_000;
+/** Métodos cuja repetição não cria nada de novo, por definição do HTTP. */
+const IDEMPOTENT_METHODS = new Set(["get", "delete"]);
+/**
+ * As escritas cuja repetição o CONTRATO declara segura, com o `X-Request-Id`
+ * fixado pelo chamador.
+ *
+ * Só uma rota trata esse cabeçalho como chave de replay; nas demais ele é
+ * rastreio, e repetir cria um segundo recurso — dois endpoints de webhook para
+ * a mesma URL entregam cada evento em dobro, e o segredo do primeiro fica
+ * órfão. Por isso a decisão é pela ROTA, nunca pela presença de um id.
+ */
+const REQUEST_ID_IDEMPOTENT_WRITES = new Set([
+    "post /v1/publications/text-searches",
+]);
+/**
+ * As leituras de UM processo em que quem chama escolhe, em `waitSeconds`,
+ * quanto o motor espera pela fonte processual.
+ */
+const SOURCE_WAIT_ROUTES = new Set([
+    "get /v1/processes/{processNumber}",
+    "get /v1/processes/{processNumber}/snapshot",
+]);
+/**
+ * A espera que o motor aplica a essas leituras quando a chamada não traz
+ * `waitSeconds`: o padrão do parâmetro no contrato.
+ */
+const SOURCE_WAIT_API_DEFAULT_SECONDS = 20;
+/**
+ * O que a chamada espera além da espera do motor: na ficha, até 10 s de
+ * enriquecimento depois da fonte, e a rede.
+ */
+const SOURCE_WAIT_MARGIN_MS = 15_000;
+/** O que um valor de cabeçalho não pode conter: `fetch` recusa montá-lo. */
+const FORBIDDEN_HEADER_CHARS = /[\r\n\0]/u;
+/** Hosts em que falar claro é desenvolvimento, não credencial exposta. */
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+/**
+ * A chave é de CONTA e viaja em todo pedido: sem TLS ela vai em texto claro
+ * para quem estiver no caminho. É a mesma recusa que o motor aplica à própria
+ * URL de produção — só o host local fica de fora, porque ali não há caminho.
+ */
+function requireSecureBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch (cause) {
+        throw LexNodeError.invalidRequest(`baseUrl inválida: ${baseUrl}`, cause);
+    }
+    if (parsed.protocol !== "https:" && !LOCAL_HOSTS.has(parsed.hostname)) {
+        throw LexNodeError.invalidRequest(`baseUrl precisa ser https: a chave de conta não trafega em claro (${baseUrl}).`);
+    }
+}
+function readHeaderNumber(headers, name) {
+    const raw = headers.get(name);
+    if (raw === null)
+        return null;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * O teto por minuto sai em TODA resposta autenticada, não só na recusa. Lê-lo
+ * no sucesso é o que permite ao consumidor desacelerar ANTES de bater no 429.
+ */
+function readRateLimit(headers) {
+    const limit = readHeaderNumber(headers, "RateLimit-Limit");
+    const remaining = readHeaderNumber(headers, "RateLimit-Remaining");
+    const resetSeconds = readHeaderNumber(headers, "RateLimit-Reset");
+    const retryAfterSeconds = readHeaderNumber(headers, "Retry-After");
+    if (limit === null &&
+        remaining === null &&
+        resetSeconds === null &&
+        retryAfterSeconds === null) {
+        return null;
+    }
+    return { limit, remaining, resetSeconds, retryAfterSeconds };
+}
+function fillPath(template, params) {
+    return template.replace(/\{([^}]+)\}/gu, (_match, name) => {
+        const value = params?.[name];
+        if (value === undefined || value === null || value === "") {
+            throw new LexNodeError({
+                code: "CLIENT_MISSING_PATH_PARAM",
+                message: `A rota ${template} exige o parâmetro de caminho "${name}".`,
+                status: 400,
+                errorClass: "TERMINAL",
+                retryable: false,
+            });
+        }
+        return encodeURIComponent(String(value));
+    });
+}
+function appendQuery(url, query) {
+    if (!query)
+        return;
+    for (const [key, value] of Object.entries(query)) {
+        const entries = (Array.isArray(value) ? value : [value]).filter((entry) => entry !== undefined && entry !== null);
+        for (const entry of entries) {
+            url.searchParams.append(key, entry instanceof Date ? entry.toISOString() : String(entry));
+        }
+    }
+}
+/**
+ * O prazo da chamada que não trouxe `timeoutMs` próprio.
+ *
+ * Numa leitura que espera pela fonte, o motor pode levar a espera inteira
+ * antes de responder — a de `waitSeconds` ou, sem ele, a padrão da API: o
+ * prazo cobre essa espera mais a margem e nunca fica abaixo do prazo do
+ * cliente. Nas outras rotas, vale o prazo do cliente.
+ */
+function defaultCallTimeoutMs(method, path, query, clientTimeoutMs) {
+    if (!SOURCE_WAIT_ROUTES.has(`${method} ${path}`))
+        return clientTimeoutMs;
+    const requested = Number(query?.waitSeconds);
+    const waitSeconds = Number.isFinite(requested) && requested > 0
+        ? requested
+        : SOURCE_WAIT_API_DEFAULT_SECONDS;
+    return Math.max(clientTimeoutMs, waitSeconds * 1_000 + SOURCE_WAIT_MARGIN_MS);
+}
+/**
+ * Junta o prazo do cliente ao `signal` de quem chamou.
+ *
+ * Os dois abortam a mesma requisição, e trocar um pelo outro perde metade do
+ * controle: sem o prazo, uma chamada sem resposta fica pendurada; sem o sinal
+ * de quem chamou, o cancelamento da requisição de cima não alcança a de baixo.
+ * O motivo do aborto é preservado para o prazo virar 504 e o cancelamento de
+ * fora continuar sendo cancelamento.
+ */
+function linkAbort(timeoutMs, caller) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    const onCallerAbort = () => controller.abort(caller?.reason);
+    if (caller) {
+        if (caller.aborted)
+            controller.abort(caller.reason);
+        else
+            caller.addEventListener("abort", onCallerAbort, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        get timedOut() {
+            return timedOut;
+        },
+        dispose() {
+            clearTimeout(timer);
+            caller?.removeEventListener("abort", onCallerAbort);
+        },
+    };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        let timer;
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Se vale repetir esta chamada.
+ *
+ * A classe do erro diz se a condição passa sozinha; o método e a ROTA dizem se
+ * repetir é seguro. Uma escrita fora da lista só é repetida quando quem chama
+ * declara `idempotent: true` — quem conhece o próprio uso pode afirmar o que o
+ * contrato não afirma, mas a afirmação é dele, e explícita.
+ *
+ * O tempo esgotado da fonte (`UPSTREAM_TIMEOUT`) numa leitura que espera por
+ * ela não se repete: o motor já esperou tudo o que a chamada pediu, e repetir
+ * na hora dobra a espera diante da mesma fonte lenta. As demais recusas
+ * retentáveis dessas leituras seguem a política.
+ */
+function mayRetry(error, method, path, options) {
+    if (!(error instanceof LexNodeError) || !error.retryable)
+        return false;
+    if (error.code === "UPSTREAM_TIMEOUT" &&
+        SOURCE_WAIT_ROUTES.has(`${method} ${path}`)) {
+        return false;
+    }
+    if (IDEMPOTENT_METHODS.has(method))
+        return true;
+    if (options.idempotent === true)
+        return true;
+    return (Boolean(options.requestId) &&
+        REQUEST_ID_IDEMPOTENT_WRITES.has(`${method} ${path}`));
+}
+function retryDelayMs(policy, attempt, error) {
+    if (error.retryAfterSeconds !== null && error.retryAfterSeconds >= 0) {
+        return Math.min(error.retryAfterSeconds * 1_000, policy.maxDelayMs);
+    }
+    return Math.min(policy.baseDelayMs * 2 ** (attempt - 1), policy.maxDelayMs);
+}
+/**
+ * O cliente de runtime do motor de dados jurídicos.
+ *
+ * **Servidor apenas, e só por TLS.** A credencial é de CONTA: uma chave no
+ * browser é uma chave publicada, e uma chave em `http://` é uma chave lida por
+ * quem estiver no caminho — `baseUrl` sem https é recusada aqui, exceto em
+ * host local. Um app com usuários finais fala com o próprio backend, e é o
+ * backend que fala com o motor — atribuindo cada chamada ao seu sub-tenant por
+ * `X-Office-Id`.
+ *
+ * Sem dependências de runtime: `fetch` global e `node:crypto`.
+ */
+export function createLexNodeClient(options) {
+    requireSecureBaseUrl(options.baseUrl);
+    const baseUrl = options.baseUrl.replace(/\/+$/u, "");
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const defaultTimeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    async function attempt(path, method, args, ids) {
+        const bag = args;
+        const url = new URL(`${baseUrl}${fillPath(String(path), bag.params?.path)}`);
+        appendQuery(url, bag.params?.query);
+        const officeId = args.officeId === undefined ? options.officeId : args.officeId;
+        const headers = {
+            authorization: `Bearer ${options.apiKey}`,
+            accept: "application/json",
+            "x-request-id": ids.requestId,
+            "x-trace-id": ids.traceId,
+        };
+        if (officeId)
+            headers["x-office-id"] = officeId;
+        if (options.userAgent)
+            headers["user-agent"] = options.userAgent;
+        if (bag.body !== undefined)
+            headers["content-type"] = "application/json";
+        // Cabeçalho e corpo são montados ANTES de abrir o socket: o que o
+        // transporte recusa montar é defeito do pedido, não falha passageira de
+        // rede, e repetir o que nunca saiu só gasta as tentativas.
+        for (const [name, value] of Object.entries(headers)) {
+            if (FORBIDDEN_HEADER_CHARS.test(value)) {
+                throw LexNodeError.invalidRequest(`O cabeçalho ${name} tem quebra de linha ou caractere nulo.`);
+            }
+        }
+        let payload;
+        try {
+            payload = bag.body === undefined ? undefined : JSON.stringify(bag.body);
+        }
+        catch (error) {
+            throw LexNodeError.invalidRequest("O corpo da chamada não é serializável em JSON.", error);
+        }
+        const timeoutMs = args.timeoutMs ??
+            defaultCallTimeoutMs(String(method), String(path), bag.params?.query, defaultTimeoutMs);
+        const link = linkAbort(timeoutMs, args.signal);
+        let response;
+        let raw;
+        let rateLimit;
+        try {
+            response = await doFetch(url.toString(), {
+                method: String(method).toUpperCase(),
+                headers,
+                body: payload,
+                signal: link.signal,
+                // O contrato não redireciona; seguir um 30x entregaria ao consumidor o
+                // corpo de outro host como se fosse a resposta do motor.
+                redirect: "error",
+            });
+            rateLimit = readRateLimit(response.headers);
+            // A leitura do corpo fica DENTRO do prazo: um corpo que trava depois dos
+            // cabeçalhos pendura a chamada por tempo indefinido se o vínculo já tiver
+            // sido desfeito aqui.
+            raw = await response.text();
+        }
+        catch (error) {
+            if (link.timedOut)
+                throw LexNodeError.timeout(timeoutMs, error);
+            // Cancelamento de quem chamou não é falha da API: sobe como veio.
+            if (args.signal?.aborted)
+                throw error;
+            throw LexNodeError.network(error);
+        }
+        finally {
+            link.dispose();
+        }
+        let parsed;
+        try {
+            parsed = raw ? JSON.parse(raw) : null;
+        }
+        catch {
+            throw LexNodeError.invalidResponse(response.status, raw, rateLimit);
+        }
+        if (!response.ok) {
+            const envelope = LexNodeError.fromEnvelope(parsed, response.status, rateLimit);
+            throw (envelope ??
+                LexNodeError.invalidResponse(response.status, raw, rateLimit));
+        }
+        const body = parsed;
+        if (!body || typeof body !== "object" || !("data" in body)) {
+            throw LexNodeError.invalidResponse(response.status, raw, rateLimit);
+        }
+        return {
+            data: body.data,
+            meta: {
+                ...body.meta,
+                status: response.status,
+                rateLimit,
+            },
+        };
+    }
+    /**
+     * A chamada genérica, tipada pela rota e pelo método do contrato.
+     *
+     * Uma função cobre a superfície inteira: rota nova ou campo novo no
+     * `openapi.json` chega tipado sem uma linha a mais aqui. Os métodos nomeados
+     * abaixo só dão nome ao que um consumidor usa todo dia.
+     */
+    async function request(path, method, args) {
+        const requestId = args.requestId ?? `req_${randomUUID()}`;
+        const traceId = args.traceId ?? `trc_${randomUUID()}`;
+        const policy = args.retry ?? options.retry;
+        const attempts = Math.max(1, policy?.attempts ?? 1);
+        const delays = {
+            baseDelayMs: policy?.baseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS,
+            maxDelayMs: policy?.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS,
+        };
+        let round = 1;
+        for (;;) {
+            try {
+                return await attempt(path, method, args, { requestId, traceId });
+            }
+            catch (error) {
+                const last = round >= attempts;
+                if (last ||
+                    !mayRetry(error, String(method), String(path), {
+                        requestId: args.requestId,
+                        idempotent: args.idempotent,
+                    })) {
+                    throw error;
+                }
+                await sleep(retryDelayMs(delays, round, error), args.signal);
+                round += 1;
+            }
+        }
+    }
+    return {
+        request,
+        tribunals: {
+            list: (query, opts = {}) => request("/v1/tribunals", "get", { params: { query }, ...opts }),
+        },
+        processes: {
+            search: (body, opts = {}) => request("/v1/processes/search", "post", { body, ...opts }),
+            get: (processNumber, query, opts = {}) => request("/v1/processes/{processNumber}", "get", {
+                params: { path: { processNumber }, query },
+                ...opts,
+            }),
+            movements: (processNumber, query, opts = {}) => request("/v1/processes/{processNumber}/movements", "get", {
+                params: { path: { processNumber }, query },
+                ...opts,
+            }),
+            snapshot: (processNumber, query, opts = {}) => request("/v1/processes/{processNumber}/snapshot", "get", {
+                params: { path: { processNumber }, query },
+                ...opts,
+            }),
+            related: (processNumber, query, opts = {}) => request("/v1/processes/{processNumber}/related", "get", {
+                params: { path: { processNumber }, query },
+                ...opts,
+            }),
+            snapshotBatch: (body, opts = {}) => request("/v1/processes/snapshot-batch", "post", { body, ...opts }),
+        },
+        publications: {
+            list: (query, opts = {}) => request("/v1/publications", "get", { params: { query }, ...opts }),
+            read: (publicationKey, opts = {}) => request("/v1/publications/{publicationKey}", "get", {
+                params: { path: { publicationKey } },
+                ...opts,
+            }),
+            textSearch: (body, opts = {}) => request("/v1/publications/text-searches", "post", { body, ...opts }),
+            textAlerts: {
+                create: (body, opts = {}) => request("/v1/publications/text-alerts", "post", { body, ...opts }),
+                list: (query, opts = {}) => request("/v1/publications/text-alerts", "get", {
+                    params: { query },
+                    ...opts,
+                }),
+                delete: (alertId, opts = {}) => request("/v1/publications/text-alerts/{alertId}", "delete", {
+                    params: { path: { alertId } },
+                    ...opts,
+                }),
+            },
+        },
+        monitors: {
+            create: (body, opts = {}) => request("/v1/monitors", "post", { body, ...opts }),
+            list: (query, opts = {}) => request("/v1/monitors", "get", { params: { query }, ...opts }),
+            get: (monitorId, opts = {}) => request("/v1/monitors/{monitorId}", "get", {
+                params: { path: { monitorId } },
+                ...opts,
+            }),
+            update: (monitorId, body, opts = {}) => request("/v1/monitors/{monitorId}", "patch", {
+                params: { path: { monitorId } },
+                body,
+                ...opts,
+            }),
+            delete: (monitorId, opts = {}) => request("/v1/monitors/{monitorId}", "delete", {
+                params: { path: { monitorId } },
+                ...opts,
+            }),
+            sync: (monitorId, opts = {}) => request("/v1/monitors/{monitorId}/sync", "post", {
+                params: { path: { monitorId } },
+                ...opts,
+            }),
+        },
+        subscriptions: {
+            create: (body, opts = {}) => request("/v1/subscriptions", "post", { body, ...opts }),
+            list: (query, opts = {}) => request("/v1/subscriptions", "get", { params: { query }, ...opts }),
+            delete: (body, opts = {}) => request("/v1/subscriptions", "delete", { body, ...opts }),
+        },
+        searchJobs: {
+            get: (jobId, opts = {}) => request("/v1/search-jobs/{jobId}", "get", {
+                params: { path: { jobId } },
+                ...opts,
+            }),
+            list: (query, opts = {}) => request("/v1/search-jobs", "get", { params: { query }, ...opts }),
+            cancel: (jobId, opts = {}) => request("/v1/search-jobs/{jobId}/cancel", "post", {
+                params: { path: { jobId } },
+                ...opts,
+            }),
+        },
+        events: {
+            list: (query, opts = {}) => request("/v1/events", "get", { params: { query }, ...opts }),
+            get: (eventId, opts = {}) => request("/v1/events/{eventId}", "get", {
+                params: { path: { eventId } },
+                ...opts,
+            }),
+        },
+        usage: {
+            get: (query, opts = {}) => request("/v1/usage", "get", { params: { query }, ...opts }),
+        },
+        webhooks: {
+            endpoints: {
+                list: (query, opts = {}) => request("/v1/webhooks/endpoints", "get", {
+                    params: { query },
+                    ...opts,
+                }),
+                create: (body, opts = {}) => request("/v1/webhooks/endpoints", "post", { body, ...opts }),
+                update: (endpointId, body, opts = {}) => request("/v1/webhooks/endpoints/{endpointId}", "patch", {
+                    params: { path: { endpointId } },
+                    body,
+                    ...opts,
+                }),
+                delete: (endpointId, opts = {}) => request("/v1/webhooks/endpoints/{endpointId}", "delete", {
+                    params: { path: { endpointId } },
+                    ...opts,
+                }),
+                test: (endpointId, opts = {}) => request("/v1/webhooks/endpoints/{endpointId}/test", "post", {
+                    params: { path: { endpointId } },
+                    ...opts,
+                }),
+                rotateSecret: (endpointId, opts = {}) => request("/v1/webhooks/endpoints/{endpointId}/rotate-secret", "post", {
+                    params: { path: { endpointId } },
+                    ...opts,
+                }),
+            },
+            deliveries: (query, opts = {}) => request("/v1/webhooks/deliveries", "get", {
+                params: { query },
+                ...opts,
+            }),
+            health: (opts = {}) => request("/v1/webhooks/health", "get", { ...opts }),
+            unsubscribedEventTypes: (opts = {}) => request("/v1/webhooks/unsubscribed-event-types", "get", { ...opts }),
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,94 @@
+import type { RateLimitSnapshot } from "./types.js";
+/**
+ * Os códigos de recusa que o contrato declara, mais os que este cliente cunha
+ * para falhas locais.
+ *
+ * Existe para o `switch` do consumidor ter autocompletar e para o erro de
+ * digitação virar erro de compilação: o motor responde 404 tanto para
+ * `PROCESS_NOT_FOUND` quanto para `MOVEMENTS_NOT_AVAILABLE`, e quem distingue
+ * os dois por literal redigitado descobre o engano em produção. A lista é
+ * fechada para o que se conhece e aberta para o que vier (ver `LexNodeError`).
+ */
+export declare const LEXNODE_ERROR_CODES: readonly ["INVALID_MONITOR", "TRIBUNAL_NOT_SUPPORTED", "PERSONAL_DOCUMENT_QUERY_NOT_ALLOWED", "VALIDATION_ERROR", "UNAUTHORIZED", "QUOTA_EXCEEDED", "INSUFFICIENT_SCOPE", "LGPD_FORBIDDEN", "PLAN_FEATURE_NOT_INCLUDED", "SUB_TENANT_LIMIT_EXCEEDED", "SANDBOX_UPSTREAM_DISABLED", "MOVEMENTS_NOT_AVAILABLE", "PRECEDENT_NOT_FOUND", "PROCESS_NOT_FOUND", "RESOURCE_NOT_FOUND", "RESOURCE_CONFLICT", "QUERY_TOO_BROAD", "RATE_LIMITED", "UPSTREAM_RATE_LIMITED", "INTERNAL_ERROR", "UPSTREAM_UNAVAILABLE", "DATABASE_TIMEOUT", "DATABASE_UNAVAILABLE", "SYNC_ABANDONED", "UPSTREAM_TIMEOUT", "ACCOUNT_SUSPENDED", "ENTITLEMENT_EXPIRED", "PROJECT_DISABLED", "SUBSCRIPTION_INACTIVE", "MONITOR_ALREADY_EXISTS", "MONITOR_NOT_FOUND", "SEARCH_JOB_NOT_FOUND", "PUBLICATION_NOT_FOUND", "EVENT_NOT_FOUND", "TEXT_ALERT_NOT_FOUND", "TEXT_SEARCH_NOT_FOUND", "CLIENT_TIMEOUT", "CLIENT_NETWORK_ERROR", "CLIENT_INVALID_REQUEST", "CLIENT_MISSING_PATH_PARAM", "INVALID_RESPONSE", "SEARCH_JOB_BUDGET_EXCEEDED", "PAGINATION_LIMIT_REACHED"];
+/**
+ * Um código conhecido — ou qualquer outro.
+ *
+ * O `string & {}` mantém o autocompletar da lista sem fechar a porta: um código
+ * novo do motor continua chegando ao `catch` em vez de quebrar a compilação de
+ * quem já integrou.
+ */
+export type LexNodeErrorCode = (typeof LEXNODE_ERROR_CODES)[number] | (string & {});
+/**
+ * A classificação que o motor carimba em toda recusa: `RETRYABLE` é condição
+ * passageira (prazo, 5xx, teto de vazão), `TERMINAL` é o que repetir não cura
+ * (validação, autorização, cota, alvo inexistente).
+ */
+export type LexNodeErrorClass = "RETRYABLE" | "TERMINAL";
+export interface LexNodeErrorInit {
+    code: LexNodeErrorCode;
+    message: string;
+    status: number;
+    errorClass: LexNodeErrorClass;
+    retryable: boolean;
+    requestId?: string | null;
+    upstreamStatus?: number | null;
+    fieldErrors?: Record<string, string[]> | null;
+    details?: Record<string, unknown> | null;
+    retryAfterSeconds?: number | null;
+    rateLimit?: RateLimitSnapshot | null;
+    cause?: unknown;
+}
+/**
+ * Toda falha que o cliente produz — do motor, da rede ou do prazo — chega como
+ * esta classe.
+ *
+ * Um único tipo para o `catch` do consumidor: ele decide por `retryable` e
+ * `code`, não por farejar a forma do que caiu. `requestId` vem junto porque é
+ * o que o suporte pede; perdê-lo transforma um incidente rastreável num relato.
+ */
+export declare class LexNodeError extends Error {
+    readonly name = "LexNodeError";
+    /** O código do contrato (`RATE_LIMITED`, `PROCESS_NOT_FOUND`, …). */
+    readonly code: LexNodeErrorCode;
+    /** Status HTTP da recusa — ou o que o cliente atribuiu à falha local. */
+    readonly status: number;
+    readonly class: LexNodeErrorClass;
+    readonly retryable: boolean;
+    /** Status real da fonte a montante, quando o motor o preservou. */
+    readonly upstreamStatus: number | null;
+    readonly requestId: string | null;
+    /** Erros por campo de uma recusa de validação. */
+    readonly fieldErrors: Record<string, string[]> | null;
+    readonly details: Record<string, unknown> | null;
+    readonly retryAfterSeconds: number | null;
+    readonly rateLimit: RateLimitSnapshot | null;
+    constructor(init: LexNodeErrorInit);
+    /**
+     * A recusa como o motor a descreveu. A classe e o `retryable` saem do corpo
+     * quando ele os traz; o status é o da resposta, que é o que de fato chegou.
+     */
+    static fromEnvelope(envelope: unknown, status: number, rateLimit: RateLimitSnapshot | null): LexNodeError | null;
+    /** Prazo esgotado antes de a resposta chegar: nada foi decidido, repetir cabe. */
+    static timeout(timeoutMs: number, cause?: unknown): LexNodeError;
+    /** A requisição não alcançou o motor: DNS, conexão, TLS, socket derrubado. */
+    static network(cause: unknown): LexNodeError;
+    /**
+     * Respondeu, mas não no envelope do contrato — proxy, página de erro, HTML.
+     *
+     * 502 porque o que quebrou está no caminho, não no pedido; o status real
+     * sobrevive em `upstreamStatus`, e a mensagem carrega o corpo cru truncado,
+     * que é a única pista de quem respondeu.
+     */
+    static invalidResponse(status: number, raw: string, rateLimit: RateLimitSnapshot | null): LexNodeError;
+    /**
+     * O pedido não chegou a sair: cabeçalho que o `fetch` recusa montar, corpo
+     * que não serializa.
+     *
+     * TERMINAL de propósito. Repetir o que o transporte barrou antes de abrir o
+     * socket não tem como dar certo, e classificá-lo como falha de rede manda o
+     * consumidor gastar as tentativas num defeito do próprio código.
+     */
+    static invalidRequest(message: string, cause?: unknown): LexNodeError;
+}
+/** Guarda de tipo para o `catch`, sem depender do `instanceof` cruzar realms. */
+export declare function isLexNodeError(value: unknown): value is LexNodeError;