@lexnode/legal-data-sdk 1.29.0 → 1.31.0

package/dist/errors.d.ts

@@ -1,29 +1,38 @@
 import type { RateLimitSnapshot } from "./types.js";
 /**
- * Os códigos de recusa que o contrato declara, mais os que este cliente cunha
- * para falhas locais.
+ * Os códigos de erro conhecidos: os que a API responde e os que este pacote
+ * cria para falhas locais (prazo, rede, pedido que não se monta, resposta fora
+ * do formato, orçamento de espera e limite de páginas).
  *
- * 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`).
+ * Use no `switch` sobre `LexNodeError.code`: o autocompletar mostra a lista, e
+ * um código digitado errado não compila. A API pode passar a responder códigos
+ * novos; trate o desconhecido no `default`.
+ *
+ * @example
+ * ```ts
+ * switch (error.code) {
+ *   case "PROCESS_NOT_FOUND":
+ *     return "o processo não existe na fonte";
+ *   case "MOVEMENTS_NOT_AVAILABLE":
+ *     return "o processo existe, mas as movimentações não vieram";
+ *   default:
+ *     throw error;
+ * }
+ * ```
  */
-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", "PROCESS_LOOKUP_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", "PROCESS_LOOKUP_BUDGET_EXCEEDED", "PAGINATION_LIMIT_REACHED"];
+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", "SOURCE_MAINTENANCE", "SYNC_ABANDONED", "UPSTREAM_TIMEOUT", "ACCOUNT_SUSPENDED", "ENTITLEMENT_EXPIRED", "PROJECT_DISABLED", "SUBSCRIPTION_INACTIVE", "MONITOR_ALREADY_EXISTS", "MONITOR_NOT_FOUND", "SEARCH_JOB_NOT_FOUND", "PROCESS_LOOKUP_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", "PROCESS_LOOKUP_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.
+ * Um código de `LEXNODE_ERROR_CODES` ou qualquer outro texto. Os conhecidos
+ * aparecem no autocompletar, e um código novo da API continua compilando.
  */
 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).
+ * A classe do erro: `RETRYABLE` é uma condição passageira (prazo, falha
+ * temporária, limite de vazão), que pode dar certo ao repetir; `TERMINAL` não
+ * melhora com a repetição (validação, autorização, saldo, recurso inexistente).
  */
 export type LexNodeErrorClass = "RETRYABLE" | "TERMINAL";
+/** Os campos com que se cria um `LexNodeError`, por exemplo num teste. */
 export interface LexNodeErrorInit {
     code: LexNodeErrorCode;
     message: string;
@@ -39,56 +48,92 @@ export interface LexNodeErrorInit {
     cause?: unknown;
 }
 /**
- * Toda falha que o cliente produz — do motor, da rede ou do prazo — chega como
- * esta classe.
+ * O erro que toda chamada deste pacote lança: recusa da API, falha de rede,
+ * prazo esgotado, pedido que não se monta e resposta fora do formato da API.
+ *
+ * Decida pelo `code` e pelo `retryable`, nunca pela mensagem. Ao registrar a
+ * falha, guarde o `requestId`: é por ele que o suporte encontra a chamada.
  *
- * 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.
+ * @example
+ * ```ts
+ * try {
+ *   await lexnode.processes.get(numero, { tribunalAlias: "TJSP" });
+ * } catch (error) {
+ *   if (isLexNodeError(error) && error.code === "PROCESS_NOT_FOUND") {
+ *     // o processo não existe na fonte
+ *   }
+ *   throw error;
+ * }
+ * ```
  */
 export declare class LexNodeError extends Error {
     readonly name = "LexNodeError";
-    /** O código do contrato (`RATE_LIMITED`, `PROCESS_NOT_FOUND`, …). */
+    /** O código do erro (`RATE_LIMITED`, `PROCESS_NOT_FOUND`, …). */
     readonly code: LexNodeErrorCode;
-    /** Status HTTP da recusa — ou o que o cliente atribuiu à falha local. */
+    /**
+     * O status HTTP da recusa, ou o atribuído à falha local: 504 no prazo
+     * esgotado, 502 na falha de rede e na resposta fora do formato, 400 no
+     * pedido que não se monta.
+     */
     readonly status: number;
+    /** `RETRYABLE` ou `TERMINAL`. */
     readonly class: LexNodeErrorClass;
+    /** Se repetir a chamada pode dar certo. */
     readonly retryable: boolean;
-    /** Status real da fonte a montante, quando o motor o preservou. */
+    /**
+     * O status HTTP que a fonte respondeu, quando a API o informa; na resposta
+     * fora do formato, o status recebido.
+     */
     readonly upstreamStatus: number | null;
+    /** O `X-Request-Id` da chamada recusada, quando a API o devolveu. */
     readonly requestId: string | null;
-    /** Erros por campo de uma recusa de validação. */
+    /** As mensagens por campo de uma recusa de validação. */
     readonly fieldErrors: Record<string, string[]> | null;
+    /**
+     * Os detalhes da recusa, como o `monitorId` do monitor existente em
+     * `MONITOR_ALREADY_EXISTS`.
+     */
     readonly details: Record<string, unknown> | null;
+    /**
+     * Quantos segundos esperar antes de repetir, quando a recusa ou o cabeçalho
+     * `Retry-After` dizem.
+     */
     readonly retryAfterSeconds: number | null;
+    /** Os cabeçalhos de limite de vazão da resposta recusada, quando vieram. */
     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.
+     * Cria o erro a partir do corpo de erro da API, ou devolve `null` quando o
+     * corpo não traz `error.code`. A classe e o `retryable` vêm do corpo; o
+     * status, da resposta.
      */
     static fromEnvelope(envelope: unknown, status: number, rateLimit: RateLimitSnapshot | null): LexNodeError | null;
-    /** Prazo esgotado antes de a resposta chegar: nada foi decidido, repetir cabe. */
+    /**
+     * O prazo da chamada esgotou antes da resposta: `CLIENT_TIMEOUT`, 504,
+     * retentável.
+     */
     static timeout(timeoutMs: number, cause?: unknown): LexNodeError;
-    /** A requisição não alcançou o motor: DNS, conexão, TLS, socket derrubado. */
+    /**
+     * A chamada não chegou à API — DNS, conexão, TLS ou conexão interrompida:
+     * `CLIENT_NETWORK_ERROR`, 502, retentável.
+     */
     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.
+     * A resposta não veio no formato da API, como a página de erro de um proxy:
+     * `INVALID_RESPONSE`, 502, retentável. O status recebido fica em
+     * `upstreamStatus`, e o início do corpo, na mensagem.
      */
     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.
+     * O pedido não foi enviado porque não se monta — cabeçalho com quebra de
+     * linha ou caractere nulo, corpo que não vira JSON, `baseUrl` inválida ou
+     * sem https: `CLIENT_INVALID_REQUEST`, 400, não retentável. Corrija a
+     * chamada.
      */
     static invalidRequest(message: string, cause?: unknown): LexNodeError;
 }
-/** Guarda de tipo para o `catch`, sem depender do `instanceof` cruzar realms. */
+/**
+ * Diz se o valor é um `LexNodeError`, inclusive quando ele vem de outra cópia
+ * do pacote instalada no projeto, em que o `instanceof` falha.
+ */
 export declare function isLexNodeError(value: unknown): value is LexNodeError;

package/dist/errors.js

@@ -1,13 +1,3 @@
-/**
- * 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 const LEXNODE_ERROR_CODES = [
     "INVALID_MONITOR",
     "TRIBUNAL_NOT_SUPPORTED",
@@ -32,10 +22,9 @@ export const LEXNODE_ERROR_CODES = [
     "UPSTREAM_UNAVAILABLE",
     "DATABASE_TIMEOUT",
     "DATABASE_UNAVAILABLE",
+    "SOURCE_MAINTENANCE",
     "SYNC_ABANDONED",
     "UPSTREAM_TIMEOUT",
-    // Fora da tabela pública, mas na porta do tenant: a credencial recusada pela
-    // própria conta, e o alvo nomeado que não existe (ou já existe).
     "ACCOUNT_SUSPENDED",
     "ENTITLEMENT_EXPIRED",
     "PROJECT_DISABLED",
@@ -48,7 +37,6 @@ export const LEXNODE_ERROR_CODES = [
     "EVENT_NOT_FOUND",
     "TEXT_ALERT_NOT_FOUND",
     "TEXT_SEARCH_NOT_FOUND",
-    // Cunhados aqui: nunca vêm do motor.
     "CLIENT_TIMEOUT",
     "CLIENT_NETWORK_ERROR",
     "CLIENT_INVALID_REQUEST",
@@ -81,26 +69,14 @@ function readFieldErrors(details) {
     }
     return out;
 }
-/**
- * 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 class LexNodeError extends Error {
     name = "LexNodeError";
-    /** O código do contrato (`RATE_LIMITED`, `PROCESS_NOT_FOUND`, …). */
     code;
-    /** Status HTTP da recusa — ou o que o cliente atribuiu à falha local. */
     status;
     class;
     retryable;
-    /** Status real da fonte a montante, quando o motor o preservou. */
     upstreamStatus;
     requestId;
-    /** Erros por campo de uma recusa de validação. */
     fieldErrors;
     details;
     retryAfterSeconds;
@@ -118,10 +94,6 @@ export class LexNodeError extends Error {
         this.retryAfterSeconds = init.retryAfterSeconds ?? null;
         this.rateLimit = init.rateLimit ?? null;
     }
-    /**
-     * 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, status, rateLimit) {
         const body = asRecord(envelope);
         const error = asRecord(body?.error);
@@ -149,7 +121,6 @@ export class LexNodeError extends Error {
             rateLimit,
         });
     }
-    /** Prazo esgotado antes de a resposta chegar: nada foi decidido, repetir cabe. */
     static timeout(timeoutMs, cause) {
         return new LexNodeError({
             code: "CLIENT_TIMEOUT",
@@ -160,7 +131,6 @@ export class LexNodeError extends Error {
             cause,
         });
     }
-    /** A requisição não alcançou o motor: DNS, conexão, TLS, socket derrubado. */
     static network(cause) {
         const detail = cause instanceof Error ? cause.message : String(cause);
         return new LexNodeError({
@@ -172,13 +142,6 @@ export class LexNodeError extends Error {
             cause,
         });
     }
-    /**
-     * 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, raw, rateLimit) {
         return new LexNodeError({
             code: "INVALID_RESPONSE",
@@ -187,20 +150,10 @@ export class LexNodeError extends Error {
             errorClass: "RETRYABLE",
             retryable: true,
             upstreamStatus: status,
-            // O 429 de uma borda ou de um proxy não vem no envelope, mas traz o
-            // `Retry-After` do mesmo jeito — e é por este campo que o recuo decide.
             retryAfterSeconds: rateLimit?.retryAfterSeconds ?? null,
             rateLimit,
         });
     }
-    /**
-     * 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, cause) {
         return new LexNodeError({
             code: "CLIENT_INVALID_REQUEST",
@@ -212,7 +165,6 @@ export class LexNodeError extends Error {
         });
     }
 }
-/** Guarda de tipo para o `catch`, sem depender do `instanceof` cruzar realms. */
 export function isLexNodeError(value) {
     return (value instanceof LexNodeError ||
         (value instanceof Error && value.name === "LexNodeError"));

package/dist/freshness.d.ts

@@ -1,87 +1,134 @@
 /**
- * Até onde a fonte foi lida — o que qualifica um resultado vazio.
- *
- * Um `total: 0` sozinho não distingue "não existe" de "a fonte ainda não
- * indexou". Quem confunde os dois diz ao usuário que o processo não existe e
- * repete a busca, pagando de novo por uma resposta que não pode mudar. O motor
- * publica a data-limite do índice em dois eixos — `updatedThrough` na busca de
- * processo, `lastEditionDate` na leitura do diário — e este módulo é a leitura
- * dos dois pelo mesmo nome.
- *
- * A leitura de UM processo diz também de quando são os dados servidos
- * (`meta.sourceFetchedAt`) e, quando a fonte falhou e o acervo socorreu, que a
- * resposta é a cópia guardada (`meta.lakeRescue`).
+ * O eixo da data-limite: `PROCESS`, da busca de processos
+ * (`sourceIndex.updatedThrough`), ou `PUBLICATION`, das publicações do diário
+ * (`sourceIndex.lastEditionDate`).
  */
 export type FreshnessAxis = "PROCESS" | "PUBLICATION";
+/** Se a resposta declara até quando a fonte foi lida. */
 export type FreshnessState = 
-/** A fonte declarou até quando leu. */
+/** A resposta declara a data-limite. */
 "KNOWN"
-/** A fonte não respondeu à sondagem, ou a resposta não traz o campo. */
+/** A resposta não traz a data-limite. */
  | "INDETERMINATE";
+/** O frescor de uma resposta, como `freshnessOf` o lê. */
 export interface Freshness {
+    /** Se a data-limite é conhecida. */
     state: FreshnessState;
+    /** O eixo da data-limite; `null` quando a resposta não traz `sourceIndex`. */
     axis: FreshnessAxis | null;
     /** A data-limite do índice da fonte, quando declarada. */
     readThrough: Date | null;
-    /** Quando a resposta montou essa data-limite. */
+    /** Quando a API conferiu a data-limite. */
     checkedAt: Date | null;
+    /** O tribunal a que a data-limite se refere. */
     tribunalAlias: string | null;
 }
-/** O retrato completo do frescor de uma resposta. */
+/**
+ * Lê até quando a fonte foi lida, numa resposta de busca de processos ou de
+ * publicações.
+ *
+ * Aceita o envelope inteiro (`{ data, meta }`) ou só o `data`. Devolve o
+ * estado `INDETERMINATE`, sem lançar, quando a resposta não traz a
+ * data-limite.
+ */
 export declare function freshnessOf(result: unknown): Freshness;
-/** A data-limite do índice da fonte, ou `null` quando ela não a declarou. */
+/**
+ * A data-limite do índice da fonte na resposta, ou `null` quando a resposta
+ * não a declara.
+ */
 export declare function readThrough(result: unknown): Date | null;
+/** As opções de `isNotYetIndexed`. */
 export interface NotYetIndexedOptions {
     /**
-     * A data a partir da qual o alvo existiria — a distribuição do processo, o
-     * dia da publicação. Com ela, a resposta deixa de ser um palpite: a fonte
-     * lida só até antes dessa data não pode ter visto o alvo.
+     * A data a partir da qual o alvo existe, como a distribuição do processo ou
+     * o dia da publicação (`Date` ou AAAA-MM-DD). Uma fonte lida só até antes
+     * dela não pode ter visto o alvo.
      */
     since?: Date | string;
 }
 /**
- * Se o vazio desta resposta NÃO prova ausência.
+ * Diz se o vazio desta resposta pode ser só atraso da fonte, e não ausência.
  *
- * Verdadeiro quando a fonte não declarou até onde leu (o estado indeterminado
- * — ausência de campo é estado, nunca erro) ou quando ela leu até antes de
- * `since`. Falso quando há resultado, e falso quando a fonte declarou uma
- * data-limite que cobre o que se perguntou: aí o vazio é resposta.
+ * Devolve `true` quando a resposta vem sem resultados e a fonte não declarou
+ * até onde leu, ou leu só até antes de `since`. Devolve `false` quando há
+ * resultados, ou quando a data-limite declarada alcança `since` ou não há
+ * `since`: aí o vazio é a resposta. Confira isto antes de dizer que um
+ * processo ou uma publicação não existe.
+ *
+ * @example
+ * ```ts
+ * const busca = await lexnode.processes.search({
+ *   tribunalAlias: "TJSP",
+ *   number,
+ * });
+ * if (isNotYetIndexed(busca, { since: "2026-09-15" })) {
+ *   mostrar(describeFreshness(busca)); // "fonte lida até 10/09/2026"
+ * }
+ * ```
  */
 export declare function isNotYetIndexed(result: unknown, options?: NotYetIndexedOptions): boolean;
-/** Por que a fonte não entregou o processo que o acervo socorreu. */
+/**
+ * Por que a fonte processual não entregou o processo, na leitura respondida
+ * com a cópia guardada.
+ */
 export type LakeRescueCause = "UPSTREAM_TIMEOUT" | "UPSTREAM_UNAVAILABLE" | "UPSTREAM_RATE_LIMITED";
 /**
- * A leitura de UM processo cuja fonte falhou e que o motor serviu com a cópia
- * que o acervo guarda.
+ * A leitura de um processo que, na falha da fonte processual, foi respondida
+ * com a cópia guardada. O que andou no processo depois de `sourceFetchedAt`
+ * não está na resposta.
  */
 export interface LakeRescue {
     /**
-     * A causa, pelo código público da taxonomia. Valor novo pode entrar no
-     * contrato; trate o desconhecido como "a fonte falhou".
+     * A causa, pelo código de erro da API. A lista pode crescer; trate um valor
+     * desconhecido como falha da fonte.
      */
     cause: LakeRescueCause | (string & {});
     /**
-     * Quando a cópia servida foi buscada na fonte; nulo na ficha que o controle
-     * de confidencialidade entrega retida, que sai sem a data.
+     * Quando a cópia foi buscada na fonte; `null` na ficha que o controle de
+     * confidencialidade entrega retida, sem a data.
      */
     sourceFetchedAt: Date | null;
-    /** A espera que a fonte pediu, na recusa por volume. */
+    /** Quantos segundos a fonte pediu para esperar, na recusa por volume. */
     retryAfterSeconds: number | null;
 }
 /**
- * O socorro pelo acervo, ou `null` quando a resposta veio da fonte ou do
- * acervo em dia. Aceita o envelope inteiro (`{ data, meta }`) ou o item do
- * lote de retratos; só o `data` não traz a marca.
+ * Diz se a resposta é a cópia guardada servida na falha da fonte e devolve a
+ * causa e a data dela; `null` quando não é.
+ *
+ * Aceita o envelope inteiro (`{ data, meta }`) de `processes.get` e
+ * `processes.snapshot`, ou um item de `processes.snapshotBatch`. Só o `data`
+ * não traz a marca.
+ *
+ * @example
+ * ```ts
+ * const retrato = await lexnode.processes.snapshot(numero, {
+ *   tribunalAlias: "TJSP",
+ *   staleOnFailure: true,
+ * });
+ * const copia = lakeRescueOf(retrato);
+ * if (copia) {
+ *   // o que andou depois de copia.sourceFetchedAt não está na resposta
+ * }
+ * ```
  */
 export declare function lakeRescueOf(result: unknown): LakeRescue | null;
 /**
- * Quando os dados servidos foram buscados na fonte: `meta.sourceFetchedAt` das
- * leituras de um processo, ou a data do item socorrido do lote.
+ * Quando os dados servidos foram buscados na fonte: `meta.sourceFetchedAt` da
+ * ficha e do retrato, ou a data da cópia guardada num item do lote. `null`
+ * quando a resposta não traz a data.
  */
 export declare function sourceFetchedAtOf(result: unknown): Date | null;
 /**
- * Uma frase em pt-BR sobre o frescor da resposta, pronta para a tela: a cópia
- * guardada e o porquê, quando o acervo socorreu a fonte; senão, até onde a
- * fonte foi lida.
+ * Devolve uma frase em português sobre o frescor da resposta, pronta para
+ * mostrar: a data da cópia guardada e o motivo, quando a fonte falhou; senão,
+ * até quando a fonte foi lida.
+ *
+ * @example
+ * ```ts
+ * describeFreshness(retrato);
+ * // "cópia guardada em 26/09/2026, servida porque a fonte não respondeu a tempo"
+ * describeFreshness(busca);
+ * // "fonte lida até 10/09/2026"
+ * ```
  */
 export declare function describeFreshness(result: unknown): string;

package/dist/freshness.js

@@ -1,23 +1,8 @@
-/**
- * Até onde a fonte foi lida — o que qualifica um resultado vazio.
- *
- * Um `total: 0` sozinho não distingue "não existe" de "a fonte ainda não
- * indexou". Quem confunde os dois diz ao usuário que o processo não existe e
- * repete a busca, pagando de novo por uma resposta que não pode mudar. O motor
- * publica a data-limite do índice em dois eixos — `updatedThrough` na busca de
- * processo, `lastEditionDate` na leitura do diário — e este módulo é a leitura
- * dos dois pelo mesmo nome.
- *
- * A leitura de UM processo diz também de quando são os dados servidos
- * (`meta.sourceFetchedAt`) e, quando a fonte falhou e o acervo socorreu, que a
- * resposta é a cópia guardada (`meta.lakeRescue`).
- */
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
         : null;
 }
-/** Aceita o envelope inteiro ou só o `data` — o consumidor tem os dois à mão. */
 function payloadOf(value) {
     const record = asRecord(value);
     if (!record)
@@ -27,15 +12,12 @@ function payloadOf(value) {
 function toDate(value) {
     if (typeof value !== "string" || !value)
         return null;
-    // A data do diário vem como AAAA-MM-DD; lê-la sem fuso a jogaria para o dia
-    // anterior em qualquer máquina a oeste de Greenwich.
     const iso = /^\d{4}-\d{2}-\d{2}$/u.test(value)
         ? `${value}T00:00:00.000Z`
         : value;
     const parsed = new Date(iso);
     return Number.isNaN(parsed.getTime()) ? null : parsed;
 }
-/** O retrato completo do frescor de uma resposta. */
 export function freshnessOf(result) {
     const payload = payloadOf(result);
     const sourceIndex = asRecord(payload?.sourceIndex);
@@ -62,7 +44,6 @@ export function freshnessOf(result) {
             : null,
     };
 }
-/** A data-limite do índice da fonte, ou `null` quando ela não a declarou. */
 export function readThrough(result) {
     return freshnessOf(result).readThrough;
 }
@@ -73,14 +54,6 @@ function hasResults(payload) {
         return true;
     return typeof payload.total === "number" && payload.total > 0;
 }
-/**
- * Se o vazio desta resposta NÃO prova ausência.
- *
- * Verdadeiro quando a fonte não declarou até onde leu (o estado indeterminado
- * — ausência de campo é estado, nunca erro) ou quando ela leu até antes de
- * `since`. Falso quando há resultado, e falso quando a fonte declarou uma
- * data-limite que cobre o que se perguntou: aí o vazio é resposta.
- */
 export function isNotYetIndexed(result, options = {}) {
     const payload = payloadOf(result);
     if (hasResults(payload))
@@ -106,11 +79,6 @@ function toInstant(value) {
     }
     return toDate(value);
 }
-/**
- * A marca do socorro e a data da cópia, onde quer que elas venham: no `meta`
- * do envelope das leituras de um processo, ou no item do lote de retratos,
- * que leva as duas em `lakeRescue`.
- */
 function rescueFieldsOf(result) {
     const record = asRecord(result);
     const meta = asRecord(record?.meta);
@@ -123,11 +91,6 @@ function rescueFieldsOf(result) {
     const itemRescue = asRecord(record?.lakeRescue);
     return { rescue: itemRescue, fetchedAt: itemRescue?.sourceFetchedAt };
 }
-/**
- * O socorro pelo acervo, ou `null` quando a resposta veio da fonte ou do
- * acervo em dia. Aceita o envelope inteiro (`{ data, meta }`) ou o item do
- * lote de retratos; só o `data` não traz a marca.
- */
 export function lakeRescueOf(result) {
     const { rescue, fetchedAt } = rescueFieldsOf(result);
     if (!rescue || typeof rescue.cause !== "string")
@@ -140,10 +103,6 @@ export function lakeRescueOf(result) {
             : null,
     };
 }
-/**
- * Quando os dados servidos foram buscados na fonte: `meta.sourceFetchedAt` das
- * leituras de um processo, ou a data do item socorrido do lote.
- */
 export function sourceFetchedAtOf(result) {
     return toInstant(rescueFieldsOf(result).fetchedAt);
 }
@@ -153,7 +112,6 @@ const BRASILIA_DATE = new Intl.DateTimeFormat("pt-BR", {
     year: "numeric",
     timeZone: "America/Sao_Paulo",
 });
-/** O dia de um instante no horário de Brasília, montado pelas partes. */
 function ddmmaaaaBrasilia(date) {
     const parts = Object.fromEntries(BRASILIA_DATE.formatToParts(date).map((part) => [part.type, part.value]));
     return `${parts.day}/${parts.month}/${parts.year}`;
@@ -168,11 +126,6 @@ function rescueReason(cause) {
         ? RESCUE_REASON[cause]
         : "falhou";
 }
-/**
- * Uma frase em pt-BR sobre o frescor da resposta, pronta para a tela: a cópia
- * guardada e o porquê, quando o acervo socorreu a fonte; senão, até onde a
- * fonte foi lida.
- */
 export function describeFreshness(result) {
     const rescue = lakeRescueOf(result);
     if (rescue) {

package/dist/index.d.ts

@@ -1,12 +1,16 @@
 /**
- * Cliente de runtime e tipos do contrato do motor de dados jurídicos.
+ * Cliente TypeScript da API do LexNode: chamadas tipadas pelo contrato
+ * OpenAPI, erros classificados, verificação de webhook e funções para busca,
+ * leitura de processo, paginação, frescor e vigília.
  *
- * **Servidor apenas.** A credencial é uma chave de CONTA: no browser ela está
- * publicada. 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`.
+ * Use só no servidor. A chave de API é da conta inteira, e no browser ela
+ * fica exposta. Um app com usuários finais chama o próprio backend, e o
+ * backend chama a API, atribuindo cada chamada ao sub-tenant dela (um
+ * escritório, um usuário final) com `officeId` (cabeçalho `X-Office-Id`).
  *
- * Sem dependências de runtime: `fetch` global e `node:crypto`, Node >= 20.
+ * Requer Node 20 ou superior e não tem dependências de runtime.
+ *
+ * @packageDocumentation
  */
 export type * from "../schema.js";
 export { createLexNodeClient } from "./client.js";
@@ -18,8 +22,8 @@ export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, LEXNODE_WEBHOOK_HEADERS, WEBHOOK_EVE
 export type { MonitorSyncFailedPayload, MonitorSyncInstance, MonitorSyncSucceededPayload, PeriodEndingPayload, ProcessInstanceDiscoveredPayload, ProcessInstanceDiscoveredWithheldPayload, ProcessLookupFailedPayload, ProcessLookupSucceededPayload, ProcessMovementCreatedPayload, ProcessMovementInstanceCount, ProcessSourceIndex, PublicationCreatedPayload, PublicationHarvestCompletedPayload, PublicationTextAlertMatch, PublicationTextAlertMatchedPayload, QuotaLowPayload, SubscribableWebhookEventType, SearchJobFailedPayload, SearchJobSucceededPayload, SubscriptionPastDuePayload, SuspensionSignal, UnknownWebhookEvent, VerifyWebhookOptions, WebhookEvent, WebhookEventEnvelope, WebhookEventType, WebhookHeaders, WebhookParseRejection, WebhookParseResult, WebhookRawBody, WebhookRejection, WebhookTestPayload, WebhookVerification, } from "./webhooks.js";
 export { paginate } from "./paginate.js";
 export type { PaginateOptions } from "./paginate.js";
-export { lookupProcess, waitForProcessLookup } from "./lookup.js";
-export type { ProcessLookup, ProcessLookupInput, ProcessLookupOutcome, ProcessLookupRead, ProcessLookupState, ProcessLookupView, StaleProcessCopy, WaitForProcessLookupOptions, } from "./lookup.js";
+export { lookupProcess, waitForProcessLookup, readProcessWithRecovery, } from "./lookup.js";
+export type { ProcessLookup, ProcessLookupInput, ProcessLookupOutcome, ProcessLookupRead, ProcessLookupState, ProcessLookupView, ProcessRecoveryOutcome, StaleProcessCopy, WaitForProcessLookupOptions, } from "./lookup.js";
 export { searchProcesses, waitForSearchJob } from "./search.js";
 export type { ProcessSearchOutcome, ProcessSearchResult, QueuedSearchJob, SearchJob, SearchJobState, WaitForSearchJobOptions, } from "./search.js";
 export { describeFreshness, freshnessOf, isNotYetIndexed, lakeRescueOf, readThrough, sourceFetchedAtOf, } from "./freshness.js";

package/dist/index.js

@@ -1,18 +1,8 @@
-/**
- * Cliente de runtime e tipos do contrato do motor de dados jurídicos.
- *
- * **Servidor apenas.** A credencial é uma chave de CONTA: no browser ela está
- * publicada. 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`, Node >= 20.
- */
 export { createLexNodeClient } from "./client.js";
 export { LEXNODE_ERROR_CODES, LexNodeError, isLexNodeError } from "./errors.js";
 export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, LEXNODE_WEBHOOK_HEADERS, WEBHOOK_EVENT_TYPES, WEBHOOK_TEST_EVENT_TYPE, isKnownWebhookEventType, isReceiverFault, isWebhookTest, parseWebhookEvent, verifyWebhookSignature, webhookRejectionStatus, } from "./webhooks.js";
 export { paginate } from "./paginate.js";
-export { lookupProcess, waitForProcessLookup } from "./lookup.js";
+export { lookupProcess, waitForProcessLookup, readProcessWithRecovery, } from "./lookup.js";
 export { searchProcesses, waitForSearchJob } from "./search.js";
 export { describeFreshness, freshnessOf, isNotYetIndexed, lakeRescueOf, readThrough, sourceFetchedAtOf, } from "./freshness.js";
 export { isFirstAppearance, resubscribeOnFirstAppearance, unwatchProcess, watchProcess, } from "./watch.js";