@lexnode/legal-data-sdk 1.29.0 → 1.31.0

package/README.md

@@ -5,20 +5,20 @@ processos e movimentações, publicações dos diários oficiais, jurisprudênci
 monitores e webhooks.
 
 O pacote traz **os tipos gerados do contrato OpenAPI** e um **cliente de
-runtime** construído sobre eles: transporte com os cabeçalhos certos, erros
+runtime** construído sobre eles: chamadas com os cabeçalhos certos, erros
 classificados, verificação de assinatura de webhook, espera de busca
-assíncrona, leitura do alcance da fonte e a composição de vigília com vários
+assíncrona, leitura do frescor da fonte e a vigília de um processo para vários
 interessados.
 
 - **Sem dependências de runtime.** `fetch` global e `node:crypto`.
 - **Node >= 20**, ESM.
 
-> ⚠️ **Servidor apenas, e só por TLS.** A credencial é uma chave de **conta**:
-> no browser ela está publicada, e em `http://` ela é lida por quem estiver no
-> caminho — uma `baseUrl` sem https é recusada no construtor (host local é a
-> exceção, para desenvolvimento). 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 pelo cabeçalho `X-Office-Id`.
+> ⚠️ **Só no servidor, e só por TLS.** A credencial é uma chave de **conta**:
+> no browser ela fica exposta, e em `http://` qualquer um no caminho a lê —
+> uma `baseUrl` sem https é recusada no construtor (exceto no host local, para
+> desenvolvimento). 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) pelo cabeçalho `X-Office-Id`.
 
 ## Instalação
 
@@ -34,33 +34,33 @@ import { createLexNodeClient } from "@lexnode/legal-data-sdk";
 const lexnode = createLexNodeClient({
   baseUrl: "https://api.lexnode.com.br",
   apiKey: process.env.LEXNODE_API_KEY!,
-  // Sub-tenant padrão; cada chamada pode trocá-lo.
+  // Escritório padrão; cada chamada pode trocá-lo.
   officeId: "escritorio-01",
   timeoutMs: 30_000,
   userAgent: "meu-app/1.0",
 });
 
 const { data, meta } = await lexnode.processes.get("00012345620268260100", {
-  tribunalAlias: "api_publica_tjsp",
+  tribunalAlias: "TJSP",
 });
 
 console.log(data.formattedNumber, meta.credits, meta.rateLimit?.remaining);
 ```
 
-Toda chamada manda `Authorization: Bearer`, `X-Request-Id`, `X-Trace-Id` e,
-quando há um, `X-Office-Id`; respeita o prazo do cliente **combinado** com o
-`signal` de quem chamou; e devolve `{ data, meta }` tipados pela rota. O `meta`
-é o do contrato mais `status` (o código HTTP) e `rateLimit` (os cabeçalhos
-`RateLimit-*`, lidos **inclusive no sucesso**, e o `Retry-After` da recusa).
+Toda chamada envia `Authorization: Bearer`, `X-Request-Id`, `X-Trace-Id` e,
+quando houver, `X-Office-Id`; respeita o prazo **e** o `signal` que você
+passar, o que vier primeiro; e devolve `{ data, meta }` tipados pela rota. O
+`meta` é o do contrato mais `status` (o código HTTP) e `rateLimit` (os
+cabeçalhos `RateLimit-*`, lidos **também no sucesso**, e o `Retry-After` da
+recusa).
 
-Em `rateLimit`, use `remaining` para desacelerar: `resetSeconds` repete o que o
-cabeçalho `RateLimit-Reset` trouxe, e o motor lhe dá dois sentidos — segundos
-até reabrir na recusa, comprimento da janela (60 s) no sucesso.
+Em `rateLimit`, use `remaining` para desacelerar. `resetSeconds` repete o
+cabeçalho `RateLimit-Reset`, que tem dois sentidos: na recusa, os segundos até
+a janela reabrir; no sucesso, a duração da janela (60 s).
 
 O pacote **não valida a resposta em tempo de execução**: `data` e `meta` chegam
-tipados pelo contrato, e o que garante a correspondência é a versão fixada, não
-uma conferência a cada chamada. Quem precisa de barreira na borda — porque o
-dado alimenta um banco, por exemplo — valida o que consome.
+tipados pelo contrato da versão instalada. Se o dado alimenta um banco, por
+exemplo, valide o que consumir.
 
 ### Métodos nomeados e a chamada genérica
 
@@ -80,8 +80,8 @@ await lexnode.webhooks.unsubscribedEventTypes();
 await lexnode.usage.get();
 ```
 
-Qualquer rota do contrato — inclusive uma que o pacote ainda não batizou — sai
-pela chamada genérica, tipada por `paths`:
+Qualquer rota do contrato, inclusive as que não têm método nomeado, sai pela
+chamada genérica, tipada por `paths`:
 
 ```ts
 const { data } = await lexnode.request("/v1/precedents", "get", {
@@ -91,9 +91,9 @@ const { data } = await lexnode.request("/v1/precedents", "get", {
 
 ### Páginas
 
-O motor pagina de três jeitos (cursor no `meta`, cursor no `data`, e
-página/tamanho ou deslocamento/teto). `paginate` percorre qualquer um deles, com
-teto explícito de páginas — cada página é uma chamada medida:
+A API pagina de três jeitos: cursor no `meta`, cursor no `data`, e página e
+tamanho ou deslocamento e limite. `paginate` percorre qualquer um deles, até
+`maxPages` páginas (padrão 100) — cada página é uma chamada:
 
 ```ts
 import { paginate } from "@lexnode/legal-data-sdk";
@@ -116,7 +116,7 @@ try {
     error.class;             // "RETRYABLE" | "TERMINAL"
     error.retryable;
     error.status;
-    error.upstreamStatus;    // o status real da fonte, quando preservado
+    error.upstreamStatus;    // o status que a fonte respondeu, quando informado
     error.requestId;         // o que o suporte pede
     error.fieldErrors;       // recusa de validação, por campo
     error.retryAfterSeconds;
@@ -126,17 +126,17 @@ try {
 ```
 
 Prazo esgotado vira `CLIENT_TIMEOUT` (504, retentável); falha de rede vira
-`CLIENT_NETWORK_ERROR` (502, retentável); resposta fora do envelope vira
-`INVALID_RESPONSE` (502) com o corpo cru truncado na mensagem; o que o
-transporte recusa mandar — cabeçalho com quebra de linha, corpo que não
-serializa — vira `CLIENT_INVALID_REQUEST` (400, **não** retentável), porque
-repetir o que nunca saiu não cura.
+`CLIENT_NETWORK_ERROR` (502, retentável); resposta fora do formato da API vira
+`INVALID_RESPONSE` (502), com o início do corpo na mensagem; e o pedido que não
+se monta — cabeçalho com quebra de linha, corpo que não vira JSON — vira
+`CLIENT_INVALID_REQUEST` (400, **não** retentável), porque não chegou a ser
+enviado.
 
 `LEXNODE_ERROR_CODES` traz o catálogo para o `switch`, e `LexNodeErrorCode`
-mantém o autocompletar sem fechar a porta a um código novo. Importa na leitura
-de processo: o motor responde 404 tanto para `PROCESS_NOT_FOUND` (o processo não
-existe na fonte) quanto para `MOVEMENTS_NOT_AVAILABLE` (existe, mas as
-movimentações não vêm) — quem trata os dois igual conta a história errada.
+mantém o autocompletar e aceita um código novo da API. Na leitura de processo
+isso importa: a API responde 404 tanto para `PROCESS_NOT_FOUND` (o processo não
+existe na fonte) quanto para `MOVEMENTS_NOT_AVAILABLE` (ele existe, mas as
+movimentações não vieram) — trate os dois pelo `code`.
 
 ### Retentativa (opcional, desligada por padrão)
 
@@ -148,19 +148,22 @@ const lexnode = createLexNodeClient({
 });
 ```
 
-Repete só o que é `RETRYABLE`, respeitando `Retry-After`. `GET` e `DELETE` são
-repetidos por definição do HTTP. Uma **escrita** só é repetida quando o contrato
-declara a repetição segura — hoje `POST /v1/publications/text-searches`, que usa
-o `requestId` que você fixar como chave de replay — ou quando você mesmo o
-declara na chamada:
+Repete só o que é `RETRYABLE`, respeitando `Retry-After`: quando a recusa pede
+uma espera maior que `maxDelayMs` (8 s por padrão), como a da manutenção
+declarada pela fonte, ela é lançada sem repetição, e `retryAfterSeconds` diz
+quando vale tentar de novo. `GET` e `DELETE` são repetidos por definição do
+HTTP. Uma **escrita** só é repetida quando o contrato declara a repetição
+segura — hoje `POST /v1/publications/text-searches`, que usa o `requestId` que
+você fixar como chave de reenvio — ou quando você mesmo o declara na chamada:
 
 ```ts
 await lexnode.webhooks.endpoints.create(corpo, { idempotent: true });
 ```
 
-A afirmação é sua: sem ela, um `POST` repetido cria um **segundo** recurso — dois
-endpoints para a mesma URL entregam cada evento em dobro, e o segredo do
-primeiro fica órfão. Em toda outra rota o `requestId` é só rastreio.
+A declaração é sua: sem ela, um `POST` repetido cria um **segundo** recurso —
+dois endpoints para a mesma URL entregam cada evento em dobro, e o segredo do
+primeiro se perde. Nas outras rotas, o `requestId` só serve para rastrear a
+chamada.
 
 A exceção é o `UPSTREAM_TIMEOUT` da leitura de um processo, que a política não
 repete — ver [a seção da fonte lenta](#ler-um-processo-quando-a-fonte-está-lenta).
@@ -173,15 +176,16 @@ import {
   webhookRejectionStatus,
 } from "@lexnode/legal-data-sdk";
 
-// O corpo CRU, nunca um JSON reserializado: o digest é sobre os bytes.
+// O corpo como chegou, nunca um JSON serializado de novo: a assinatura vale
+// para os bytes.
 const resultado = parseWebhookEvent(
   rawBody,
   request.headers,
   process.env.LEXNODE_WEBHOOK_SIGNING_SECRET!,
 );
 
-// O status de cada recusa vem junto: um corpo que não se autentica é 401 e não
-// volta; segredo ausente é 503, porque a falha é SUA e o motor precisa insistir.
+// Cada recusa tem o seu status: a assinatura que não confere é 401; o segredo
+// ausente no seu receptor é 503.
 if (!resultado.ok) {
   return reply.status(webhookRejectionStatus(resultado.reason)).send();
 }
@@ -210,22 +214,22 @@ switch (resultado.event.type) {
     }
     break;
   case "PROCESS_LOOKUP_COMPLETED":
-    // Um ponteiro: o processo se lê em payload.pollUrl, sem nova cobrança.
+    // Aponta a consulta: o processo se lê em payload.pollUrl, sem nova cobrança.
     resultado.event.payload.lookupId;
     break;
   case "WEBHOOK_TEST":
-    // A entrega de teste do console. Chega a qualquer endpoint, não se assina
-    // e não se recusa — é ela que valida o receptor antes do primeiro evento.
+    // A entrega de teste (`webhooks.endpoints.test` ou o portal). Chega a
+    // qualquer endpoint sem constar de `eventTypes`; use-a para validar o
+    // receptor antes do primeiro evento.
     break;
   default:
     break;
 }
 ```
 
-O envelope precisa ser endereçável: entrega sem `id` ou sem `occurredAt` é
-recusada como `INVALID_ENVELOPE`. O `id` é a chave de idempotência de todo
-receptor — aceitá-lo vazio faria a primeira entrega ocupar a única vaga de
-deduplicação e todas as seguintes parecerem repetição dela.
+Entrega sem `id` ou sem `occurredAt` é recusada como `INVALID_ENVELOPE`. A
+mesma entrega pode chegar mais de uma vez: use o `id` para descartar a
+repetida.
 
 `WEBHOOK_EVENT_TYPES` é o catálogo **assinável** (o que entra em `eventTypes`
 ao cadastrar um endpoint) e não inclui `WEBHOOK_TEST`, que chega sem ser
@@ -234,22 +238,20 @@ pedido — use `isWebhookTest(event)` para separá-lo.
 `verifyWebhookSignature(rawBody, headers, secret)` faz só a conferência e
 devolve o motivo da recusa (`MISSING_SIGNATURE`, `MALFORMED_SIGNATURE`,
 `TIMESTAMP_MISMATCH`, `TIMESTAMP_OUT_OF_TOLERANCE`, `SIGNATURE_MISMATCH`,
-`RAW_BODY_REQUIRED`), em vez de um `false` que faria vários incidentes
-diferentes virarem a mesma resposta.
+`RAW_BODY_REQUIRED`), para você tratar cada caso.
 
-O corpo entra como `string` ou `Buffer` — os bytes como chegaram. Passar o JSON
-já parseado é recusado como `RAW_BODY_REQUIRED`, e não confundido com
-adulteração: reserializar reordena as chaves e o digest deixa de bater.
+O corpo entra como `string` ou `Buffer`, como chegou. Um objeto já convertido
+de JSON é recusado como `RAW_BODY_REQUIRED`: serializar de novo muda a ordem
+das chaves, e a assinatura deixa de conferir.
 
-A janela de replay e o digest saem do `t` que viaja **dentro** da assinatura; o
-cabeçalho `x-lexnode-timestamp` é redundante e só é conferido quando vem. Um
-receptor escrito à mão que o exigia continua correto — o SDK apenas não faz da
-ausência dele um motivo de recusa, porque ela não prova nada.
+A tolerância do instante e o digest usam o `t` que vem **dentro** da
+assinatura. O cabeçalho `x-lexnode-timestamp` repete esse valor: quando vem,
+precisa ser igual; quando falta, não é motivo de recusa.
 
 ## Busca síncrona ou assíncrona
 
 `POST /v1/processes/search` responde **200** com o resultado pronto ou **202**
-com um trabalho enfileirado. O SDK diz qual foi, no tipo:
+com uma busca enfileirada. O SDK diz qual foi, no tipo:
 
 ```ts
 import { searchProcesses, waitForSearchJob } from "@lexnode/legal-data-sdk";
@@ -259,9 +261,8 @@ const desfecho = await searchProcesses(lexnode, { tribunalAlias, number });
 if (desfecho.kind === "sync") {
   desfecho.result.items;
 } else {
-  // O orçamento é explícito: num ambiente serverless, esperar sem teto gasta
-  // a requisição inteira. Quem integrou por webhook nem espera — recebe o
-  // SEARCH_JOB_COMPLETED.
+  // Espere com orçamento — num ambiente serverless, dentro do prazo da
+  // função — ou receba o SEARCH_JOB_COMPLETED por webhook.
   const job = await waitForSearchJob(lexnode, desfecho.job.jobId, {
     budgetMs: 20_000,
   });
@@ -272,30 +273,30 @@ if (desfecho.kind === "sync") {
 ## Um número, várias instâncias
 
 A fonte processual guarda um documento por instância do processo — 1º grau, 2º
-grau, turma recursal… —, às vezes dois do mesmo grau, e o motor guarda cada um
-na sua instância.
+grau, turma recursal… —, às vezes dois do mesmo grau, e o LexNode guarda cada
+um na sua instância.
 
 **O topo não troca.** O topo da ficha (`data`) e do retrato (`data.process` e
 `data.movements`) é sempre a instância principal do número, com o grau em
 `degree`: a mesma de uma leitura para a outra, qualquer que seja a ordem em que
 a fonte devolve os documentos. Ela só muda quando uma resposta completa da
-fonte pelo número deixa de trazê-la. Quem compara movimentos pela chave não vê
-o histórico de outro grau aparecer como novo no topo — e o topo pode não ser o
+fonte pelo número deixa de trazê-la. Se você compara movimentos pela chave, o
+histórico de outro grau não aparece como novo no topo — e o topo pode não ser o
 grau que anda: o 2º grau guardado primeiro continua no topo enquanto o 1º se
 move.
 
 **Todos os graus em `instances`.** A ficha e o retrato listam em `instances`
-todos os documentos que o motor guarda do número, a principal primeiro
+todos os documentos guardados do número, a principal primeiro
 (`primary: true`). Cada um diz de onde veio nesta resposta (`origin`: `SOURCE`
-quando a fonte o trouxe, `LAKE` quando saiu do acervo), quando foi buscado
-(`fetchedAt`) e desde quando a resposta completa da fonte vem sem ele
-(`absentSince`). No retrato, cada instância traz os movimentos da última captura
-dela, do mais recente ao mais antigo e sem o payload bruto da fonte; a que o
-motor nunca capturou vem com `movementsCaptured: false` e `movements` nulo, nunca
-com lista vazia, que diria que o grau não andou. Todos os documentos levam a
-classificação do número inteiro — basta um em segredo de justiça para todos
-saírem marcados —, e a ficha retida pelo controle de confidencialidade sai sem a
-lista.
+quando a fonte o trouxe, `LAKE` quando veio da cópia guardada), quando foi
+buscado (`fetchedAt`) e desde quando a resposta completa da fonte vem sem ele
+(`absentSince`). No retrato, cada instância traz os movimentos da última
+captura dela, do mais recente ao mais antigo e sem o payload bruto da fonte; a
+instância cujos movimentos nunca foram capturados vem com
+`movementsCaptured: false` e `movements` nulo, nunca com lista vazia, que diria
+que o grau não andou. Todos os documentos levam a classificação do número
+inteiro — basta um em segredo de justiça para todos saírem marcados —, e a
+ficha retida pelo controle de confidencialidade sai sem a lista.
 
 ```ts
 const { data } = await lexnode.processes.snapshot(numero, { tribunalAlias });
@@ -309,9 +310,9 @@ for (const instancia of data.instances) {
 
 No lote (`processes.snapshotBatch`), `instances` traz só o cabeçalho de cada
 documento; os movimentos de cada instância vêm no retrato de um processo. A
-busca por número completo servida do acervo devolve um item por documento que a
-fonte ainda traz do número, a principal primeiro; quando eles não cabem em
-`limit`, a busca vai à fonte, que pagina.
+busca por número completo respondida com os dados guardados devolve um item por
+documento que a fonte ainda traz do número, a principal primeiro; quando eles
+não cabem em `limit`, a busca vai à fonte, que pagina.
 
 **Recorte por grau.** A lista de movimentações aceita `degree` e devolve só os
 movimentos que o documento daquele grau trouxe na última captura; cada item diz
@@ -327,21 +328,21 @@ data.items; // só o que o 1º grau trouxe
 ```
 
 **O grau novo chega num evento só.** Quando outro grau de um processo assinado
-aparece na fonte, o histórico dele entra no acervo sem virar
-`PROCESS_MOVEMENT_CREATED` movimento a movimento: chega um
-`PROCESS_INSTANCE_DISCOVERED`, com o grau, o órgão julgador e as contagens —
-`historyMovementCount` entrou sem aviso próprio, `announcedMovementCount` saiu
-também como movimento novo. O `PROCESS_MOVEMENT_CREATED` diz o grau do
-movimento mais recente (`degree`, `instanceSourceId`) e quantos movimentos novos
-vieram de cada grau (`instances`). Assine os dois: quem assina só o movimento
-não fica sabendo do grau que apareceu.
+aparece na fonte, o histórico dele não sai movimento a movimento em
+`PROCESS_MOVEMENT_CREATED`: chega um `PROCESS_INSTANCE_DISCOVERED`, com o grau,
+o órgão julgador e as contagens — `historyMovementCount` não saiu em aviso
+próprio, `announcedMovementCount` saiu também como movimento novo. O
+`PROCESS_MOVEMENT_CREATED` diz o grau do movimento mais recente (`degree`,
+`instanceSourceId`) e quantos movimentos novos vieram de cada grau
+(`instances`). Assine os dois: só com o movimento, você não fica sabendo do
+grau que apareceu.
 
 **`meta.otherInstances`: o resumo do que veio.** Quando a resposta da fonte traz
 outros documentos do número além da principal, `meta.otherInstances` resume cada
 um com o grau (`grau`), a data em que a fonte o atualizou (`updatedAt`) e o
 órgão julgador (`courtBody`, quando vem). A lista não sai para processo restrito
-e não inclui documento que o motor classificaria como segredo de justiça; os
-documentos inteiros estão em `instances`.
+e não inclui documento em segredo de justiça; os documentos inteiros estão em
+`instances`.
 
 ```ts
 for (const outra of meta.otherInstances ?? []) {
@@ -350,24 +351,24 @@ for (const outra of meta.otherInstances ?? []) {
 ```
 
 **Continuação.** Na API nada é cortado: o retrato traz os movimentos guardados
-de cada instância, e a lista de movimentações lê do acervo, grau a grau, sem ir
-à fonte. No canal para agentes (MCP), `consultar_processo` cabe no teto de uma
-resposta: de cada grau vêm os movimentos mais recentes, o grau que se moveu por
-último primeiro, e a mesma tool com `grau` e `pagina` traz os seguintes do que o
-motor guardou, por 1 crédito e sem ir à fonte — só para quem já leu o processo
-ou o acompanha.
+de cada instância, e a lista de movimentações lê os movimentos guardados, grau a
+grau, sem ir à fonte. No canal para agentes (MCP), que não passa por este
+pacote, `consultar_processo` cabe numa resposta: de cada grau vêm os movimentos
+mais recentes, o grau que se moveu por último primeiro, e a mesma tool com
+`grau` e `pagina` traz os seguintes, por 1 crédito e sem ir à fonte — só para
+quem já leu o processo ou o acompanha.
 
 ## Ler um processo quando a fonte está lenta
 
-A ficha (`processes.get`) vai à fonte processual quando o acervo não tem o
-processo fresco; o retrato (`processes.snapshot`) vai sempre. Os dois só
-recorrem ao acervo quando a fonte falha (seção seguinte). A fonte às vezes leva
-perto de um minuto por consulta. `waitSeconds` diz quanto o motor espera por
-ela: de 10 a 180 segundos, padrão 20 na API.
+A ficha (`processes.get`) vai à fonte processual quando não há uma cópia recente
+guardada; o retrato (`processes.snapshot`) vai sempre. Os dois só respondem com
+a cópia guardada quando a fonte falha (seção seguinte). A fonte às vezes leva
+perto de um minuto por consulta. `waitSeconds` diz quanto a API espera por ela:
+de 10 a 180 segundos, padrão 20.
 
 ```ts
 const { data, meta } = await lexnode.processes.get(numero, {
-  tribunalAlias: "api_publica_tjsp",
+  tribunalAlias: "TJSP",
   waitSeconds: 120,
 });
 ```
@@ -384,27 +385,27 @@ chamada genérica (`request`) nessas duas rotas.
 duas leituras é lentidão da fonte, não ausência do processo, e a política de
 retentativa não o repete: a espera já correu inteira, e repetir na hora a
 dobraria diante da mesma fonte lenta. As outras recusas retentáveis seguem a
-política. Para insistir, a decisão é sua — uma nova chamada com espera maior,
-ou a vigília do processo (`watchProcess`), que consulta em segundo plano.
+política. Para insistir, a decisão é sua — uma nova chamada com espera maior, a
+leitura que segue em segundo plano (`readProcessWithRecovery`, abaixo) ou a
+vigília do processo (`watchProcess`).
 
 **`meta.partialIndex`: o processo veio de parte do índice.** Quando a fonte
 responde com só parte do índice e o processo estava na parte que respondeu, ele
 é servido, e `meta.partialIndex` diz quantas partes falharam (`shardsFailed`),
 de quantas (`shardsTotal`, nulo quando a fonte não as contou) e se o prazo
-interno dela estourou (`timedOut`). O documento que o acervo já guardava e não
-veio sai em `instances` do acervo (`origin: "LAKE"`), com a data dele, e outro
-grau que o acervo não conhece, se existir, pode estar na parte que não
-respondeu. A resposta parcial sem o processo é 502 `UPSTREAM_UNAVAILABLE`
-retentável, nunca 404.
+interno dela estourou (`timedOut`). O documento já guardado que não veio sai em
+`instances` com `origin: "LAKE"` e a data dele, e outro grau ainda não guardado,
+se existir, pode estar na parte que não respondeu. A resposta parcial sem o
+processo é 502 `UPSTREAM_UNAVAILABLE` retentável, nunca 404.
 
 ```ts
 if (meta.partialIndex) {
-  // Outro grau deste número que o acervo não conhece pode não ter vindo.
+  // Um grau deste número ainda não guardado pode não ter vindo.
 }
 ```
 
 Antes de recusar a resposta parcial que veio sem o processo porque partes do
-índice ficaram fora, o motor consulta a fonte de novo — até duas vezes, com uma
+índice ficaram fora, a API consulta a fonte de novo — até duas vezes, com uma
 pausa curta, enquanto a espera couber.
 
 **Agentes têm a espera deles.** No canal para agentes (MCP), as tools
@@ -415,7 +416,7 @@ mesma faixa e com padrão de 120 s; esse canal não passa pelo SDK.
 
 Quando a fonte processual falha — não responde dentro de `waitSeconds`, fica
 indisponível, responde com parte do índice sem poder servir o processo ou pede
-para esperar por volume — e o acervo guarda uma cópia do processo, a ficha
+para esperar por volume — e há uma cópia guardada do processo, a ficha
 (`processes.get`) e o retrato (`processes.snapshot`) respondem com essa cópia em
 vez do erro. A resposta diz que é cópia, e de quando:
 
@@ -423,38 +424,39 @@ vez do erro. A resposta diz que é cópia, e de quando:
   `UPSTREAM_UNAVAILABLE` ou `UPSTREAM_RATE_LIMITED`;
 - `meta.lakeRescue.retryAfterSeconds`, repetido no header `Retry-After`, diz na
   recusa por volume quanto esperar antes de consultar a fonte de novo. É a
-  espera da fonte, não do teto do motor: `meta.rateLimit.retryAfterSeconds`
-  fica `null` no sucesso;
+  espera pedida pela fonte, não pelo limite de vazão da API:
+  `meta.rateLimit.retryAfterSeconds` fica `null` no sucesso;
 - `meta.sourceFetchedAt` diz quando a cópia foi buscada na fonte. Esse campo
-  acompanha toda resposta das duas leituras, socorrida ou não, menos a ficha
-  que o controle de confidencialidade entrega retida, sem o teor.
+  acompanha toda resposta das duas leituras, venha ela da fonte ou da cópia,
+  menos a ficha que o controle de confidencialidade entrega retida, sem o teor.
 
 A cópia custa 1 crédito, na ficha e no retrato. O retrato confere o saldo pelo
 preço cheio, 8, antes de ir à fonte; a ficha confere pelo preço do que
 entregou, depois da leitura. No retrato guardado, cada instância traz os
-movimentos da última vez que o motor a buscou, com a data em
+movimentos da última vez que ela foi buscada, com a data em
 `instances[].fetchedAt`, e `sourcePayload` é nulo: o que andou depois dessas
 datas não está na resposta. O número que a resposta completa mais recente da
-fonte já não trazia em documento nenhum não é socorrido. Na ficha guardada, a
-data vale para os dados do processo, e o resumo das publicações (`djen`) é
-relido na hora.
+fonte já não trazia em documento nenhum não tem cópia servida. Na ficha
+guardada, a data vale para os dados do processo, e o resumo das publicações
+(`djen`) é relido na hora.
 
-**Até que idade.** Sem pedir nada, só a cópia de até 24 h socorre a leitura —
-nessas duas rotas, uma resposta de sucesso já podia ser cópia do acervo dentro
-desse prazo. A cópia de qualquer idade vem com `staleOnFailure: true`:
+**Até que idade.** Sem pedir nada, só a cópia de até 24 h responde na falha da
+fonte — nessas duas rotas, uma resposta de sucesso já pode ser uma cópia
+guardada dentro desse prazo. A cópia de qualquer idade vem com
+`staleOnFailure: true`:
 
 ```ts
 import { describeFreshness, lakeRescueOf } from "@lexnode/legal-data-sdk";
 
 const retrato = await lexnode.processes.snapshot(numero, {
-  tribunalAlias: "api_publica_tjsp",
+  tribunalAlias: "TJSP",
   staleOnFailure: true,
 });
 
-const socorro = lakeRescueOf(retrato);
-if (socorro) {
+const copia = lakeRescueOf(retrato);
+if (copia) {
   // A fonte falhou e isto é a cópia guardada: o que andou depois de
-  // socorro.sourceFetchedAt não está aqui.
+  // copia.sourceFetchedAt não está aqui.
   mostrar(describeFreshness(retrato));
   // "cópia guardada em 26/09/2026, servida porque a fonte não respondeu a tempo"
 }
@@ -465,16 +467,17 @@ if (socorro) {
 devolve a data de qualquer resposta dessas leituras. As duas aceitam o envelope
 inteiro e o item do lote.
 
-**O que não é socorrido.** A resposta da fonte que não traz o processo segue
-404 `PROCESS_NOT_FOUND`, com cópia guardada ou sem ela: é a fonte dizendo que
-não tem o número, e não uma falha dela. A cópia passa pelo mesmo controle de
-confidencialidade da leitura; além de 24 h, só a recebe quem já tem interesse
-registrado no processo — de uma leitura anterior dele ou de uma assinatura
-ativa —, e os demais recebem a falha da fonte, como se não houvesse cópia.
+**Quando a cópia não é servida.** A resposta da fonte que não traz o processo segue 404
+`PROCESS_NOT_FOUND`, com cópia guardada ou sem ela: é a fonte dizendo que não
+tem o número, e não uma falha dela. A cópia passa pelo mesmo controle de
+confidencialidade da leitura; além de 24 h, só a recebe a conta que já tem
+interesse registrado no processo — de uma leitura anterior dele ou de uma
+assinatura ativa —, e as demais recebem a falha da fonte, como se não houvesse
+cópia.
 
-**No lote.** `processes.snapshotBatch` socorre só com a cópia de até 24 h. O
-item socorrido traz `lakeRescue` com a causa e a data, e custa 1 crédito em vez
-de 8.
+**No lote.** `processes.snapshotBatch` só usa a cópia de até 24 h. O item
+respondido com ela traz `lakeRescue`, com a causa e a data, e custa 1 crédito
+em vez de 8.
 
 ## Leitura que não coube na espera
 
@@ -488,13 +491,46 @@ em segundo plano em vez de virar erro:
   `PROCESS`) ou `snapshot` (visão `SNAPSHOT`), com as instâncias do número em
   `instances`, o mesmo `meta` e o mesmo preço da leitura direta;
 - **202**: a fonte falhou — não respondeu a tempo, ficou indisponível ou pediu
-  para esperar —, e o motor abriu uma consulta que tenta sozinha, até 60 s por
-  tentativa, por até 6 h (`giveUpAt`). Nada é cobrado na hora: o preço da
-  leitura fica retido em `creditsReserved`, o máximo que a entrega cobra, e
+  para esperar —, e a API abriu uma consulta que segue tentando sozinha, até
+  60 s por tentativa, por até 6 h (`giveUpAt`). Nada é cobrado na hora: o preço
+  da leitura fica retido em `creditsReserved`, o máximo que a entrega cobra, e
   só é cobrado se o processo vier. Se não vier, a retenção volta;
 - qualquer outra recusa é a da leitura direta: 404 quando a fonte diz não ter o
   processo, 403 no segredo de justiça, 402 sem saldo.
 
+Para uma integração que precisa continuar mesmo quando a fonte demora, use
+`readProcessWithRecovery`. A aceitação da cópia antiga é explícita, e a espera
+total é limitada. O fim da espera devolve `pending`, com a mesma consulta e a
+próxima leitura útil, sem cancelar a consulta nem abrir outra:
+
+```ts
+import { readProcessWithRecovery } from "@lexnode/legal-data-sdk";
+
+const leitura = await readProcessWithRecovery(lexnode, {
+  tribunalAlias: "TJSP",
+  processNumber: numeroDoProcesso,
+  view: "PROCESS",
+  waitSeconds: 5,
+  staleOnFailure: true, // aceita cópia anterior à falha: confira sourceFetchedAt
+}, { completionBudgetMs: 30_000 });
+
+if (leitura.kind === "ready") {
+  usarProcesso(leitura.data, leitura.meta.sourceFetchedAt);
+} else if (leitura.kind === "pending") {
+  guardarConsulta(leitura.lookup.lookupId, leitura.nextReadAt);
+  // leitura.stale, quando presente, conserva a data da cópia.
+  // Continue pelo pollUrl ou pelo webhook PROCESS_LOOKUP_COMPLETED.
+} else {
+  registrarDesfecho(leitura.kind, leitura.lookup.error);
+  // failed, canceled ou expired; nenhum deles afirma que o processo não existe.
+}
+```
+
+Sem `completionBudgetMs`, a função devolve na hora o desfecho da abertura (200
+ou 202). O orçamento cobre só o acompanhamento, e cada chamada mantém o próprio
+prazo. Abortar a espera não cancela a consulta. O custo, o controle de
+confidencialidade e a cobrança única são os de `processLookups.create`.
+
 `lookupProcess` diz, no tipo, qual dos dois desfechos aconteceu, e
 `waitForProcessLookup` espera a consulta terminar:
 
@@ -502,7 +538,7 @@ em segundo plano em vez de virar erro:
 import { lookupProcess, waitForProcessLookup } from "@lexnode/legal-data-sdk";
 
 const desfecho = await lookupProcess(lexnode, {
-  tribunalAlias: "api_publica_tjsp",
+  tribunalAlias: "TJSP",
   processNumber: numero,
   view: "SNAPSHOT",
 });
@@ -510,9 +546,9 @@ const desfecho = await lookupProcess(lexnode, {
 if (desfecho.kind === "ready") {
   desfecho.data.movements; // o retrato, como processes.snapshot o devolveria
 } else {
-  // O orçamento é explícito. A leitura seguinte só acontece na hora da
-  // próxima tentativa (nextAttemptAt): antes dela, o estado não muda. Com
-  // uma tentativa em curso, a consulta é lida de novo a cada 10 s.
+  // Espere com orçamento. A consulta é lida de novo na hora da próxima
+  // tentativa (nextAttemptAt), quando o estado pode mudar, e a cada 10 s
+  // enquanto uma tentativa está em curso.
   const consulta = await waitForProcessLookup(
     lexnode,
     desfecho.lookup.lookupId!,
@@ -532,22 +568,23 @@ chamada repetida tenta a fonte na hora, dentro da espera dela. O tempo
 esgotado da fonte continua sem repetição automática.
 
 **A consulta se lê de graça, por 24 h.** `processLookups.get(lookupId)` custa 0
-e, depois da entrega, traz o processo por 24 h (`resultExpiresAt`), relido do
-acervo e passado de novo pelo controle de confidencialidade: o processo que
-passou a segredo de justiça depois responde 403. O retrato lido da consulta
-traz a instância principal no topo e cada instância com os movimentos da
-última captura dela, e `sourcePayload` é nulo. `processLookups.list` e `processLookups.cancel`
-completam a superfície; o cancelamento devolve a retenção e não gera evento.
-
-**Por webhook, sem esperar nada.** O fim sai em `PROCESS_LOOKUP_COMPLETED`, um
-ponteiro para a consulta que nunca traz o processo; o movimento novo que a
-entrega trouxer chega no `PROCESS_MOVEMENT_CREATED` de sempre.
+e, depois da entrega, traz o processo por 24 h (`resultExpiresAt`), relido e
+passado de novo pelo controle de confidencialidade: o processo que passou a
+segredo de justiça depois responde 403. O retrato lido da consulta traz a
+instância principal no topo e cada instância com os movimentos da última
+captura dela, e `sourcePayload` é nulo. `processLookups.list` e
+`processLookups.cancel` completam a superfície; o cancelamento devolve a
+retenção e não gera evento.
+
+**Por webhook, sem esperar nada.** O fim sai em `PROCESS_LOOKUP_COMPLETED`, que
+aponta a consulta e nunca traz o processo; o movimento novo que a entrega
+trouxer chega no `PROCESS_MOVEMENT_CREATED` de sempre.
 
 **A cópia guardada e a atualização, uma compra só.** Com `staleOnFailure: true`,
-o 202 traz em `stale` a cópia que o acervo guarda, com a data e a causa, por 1
-crédito, e a consulta segue buscando a versão atual. A entrega cobra só o resto
-do preço (`alreadyCharged` diz quanto já foi): as duas juntas custam o mesmo que
-a leitura direta, e a atualização que não vier não cobra mais nada.
+o 202 traz em `stale` a cópia guardada, com a data e a causa, por 1 crédito, e
+a consulta segue buscando a versão atual. A entrega cobra só o resto do preço
+(`alreadyCharged` diz quanto já foi): as duas juntas custam o mesmo que a
+leitura direta, e a atualização que não vier não cobra mais nada.
 
 **A leitura direta fecha a consulta.** A ficha ou o retrato do mesmo processo
 lidos com sucesso por `processes.get` ou `processes.snapshot` fecham a consulta
@@ -560,8 +597,8 @@ consulta.
 ## Frescor: o `total: 0` qualificado
 
 Um resultado vazio não distingue sozinho "não existe" de "a fonte ainda não
-indexou". O motor publica a data-limite do índice; o SDK a lê nos dois eixos
-(processo e diário):
+indexou". A API publica a data-limite do índice da fonte; o SDK a lê nos dois
+eixos (processo e diário):
 
 ```ts
 import {
@@ -577,15 +614,15 @@ if (isNotYetIndexed(busca, { since: "2026-09-15" })) {
   mostrar(describeFreshness(busca)); // "fonte lida até 10/09/2026"
 }
 
-readThrough(busca); // Date | null — null é ESTADO indeterminado, não erro
+readThrough(busca); // Date | null — null quando a resposta não declara a data-limite
 ```
 
 ## Vigília com vários interessados
 
-O motor separa duas primitivas: o **sensor** (`Monitor`), único por alvo na
-conta e com teto, e a **assinatura** (`ProcessSubscription`), única por
-`externalRef`, sem teto e ecoada no aviso. N interessados no mesmo processo são
-um sensor e N assinaturas.
+A vigília de um processo tem duas partes: o **monitor**, que consulta a fonte —
+um por processo na conta, e o plano limita quantos —, e a **assinatura**, que
+recebe o aviso — uma por `externalRef`, sem limite, e o `externalRef` volta no
+evento. N interessados no mesmo processo são um monitor e N assinaturas.
 
 ```ts
 import { unwatchProcess, watchProcess } from "@lexnode/legal-data-sdk";
@@ -594,23 +631,26 @@ const { monitorId, monitorAlreadyExisted, subscription } = await watchProcess(
   lexnode,
   {
     processNumber: "00012345620268260100",
-    tribunalAlias: "api_publica_tjsp",
+    tribunalAlias: "TJSP",
     officeId: "usuario-4711",
     externalRef: "caso-42",
   },
 );
 
-// Um interessado desiste; o sensor continua varrendo para os demais.
+// Um interessado sai; o monitor continua ativo para os demais.
 await unwatchProcess(lexnode, {
   externalRef: "caso-42",
   officeId: "usuario-4711",
 });
 ```
 
-**Limitação conhecida:** uma assinatura criada **antes** de o processo entrar no
-acervo não recebe `PROCESS_MOVEMENT_CREATED` até a primeira aparição do alvo na
-fonte. O contorno é refazer a assinatura quando chegar o
-`MONITOR_SYNC_SUCCEEDED` com `firstAppearance: true`:
+Quando o último interessado sair, remova o monitor com
+`lexnode.monitors.delete(monitorId)`.
+
+**Limitação conhecida:** uma assinatura criada **antes** de o processo aparecer
+na fonte não recebe `PROCESS_MOVEMENT_CREATED` até a primeira aparição dele. O
+contorno é refazer a assinatura quando chegar o `MONITOR_SYNC_SUCCEEDED` com
+`firstAppearance: true`:
 
 ```ts
 import { resubscribeOnFirstAppearance } from "@lexnode/legal-data-sdk";
@@ -620,10 +660,9 @@ await resubscribeOnFirstAppearance(lexnode, evento, [
 ]);
 ```
 
-## Só os tipos
+## Os tipos do contrato
 
-O uso antigo continua valendo — o pacote exporta `paths` e `operations` como
-sempre:
+O pacote exporta `paths` e `operations`, gerados do contrato OpenAPI:
 
 ```ts
 import type { operations, paths } from "@lexnode/legal-data-sdk";
@@ -636,7 +675,7 @@ type Tribunals =
   operations["listTribunals"]["responses"][200]["content"]["application/json"]["data"];
 ```
 
-E os atalhos derivados deles, que o cliente usa internamente:
+E atalhos derivados deles:
 
 ```ts
 import type { Body, Data, Query } from "@lexnode/legal-data-sdk";
@@ -648,11 +687,11 @@ type Tribunais = Data<"/v1/tribunals", "get">;
 
 ## A chave de teste
 
-A chave `lapi_test_` lê o acervo já formado, mas **não consulta a fonte viva nem
-cria trabalho de fundo**: monitor, vigília, colheita e busca assíncrona
-respondem 403 `SANDBOX_UPSTREAM_DISABLED`. Na prática, `watchProcess` e o ramo
-`async` de `searchProcesses` só fecham com chave viva — vale saber antes de
-achar que a integração está errada.
+A chave `lapi_test_` relê o que a conta já buscou com a chave de produção, mas
+**não consulta a fonte nem cria trabalho em segundo plano**: monitor, vigília,
+colheita e busca assíncrona respondem 403 `SANDBOX_UPSTREAM_DISABLED`. Por isso
+`watchProcess` e o ramo `async` de `searchProcesses` só funcionam com a chave
+de produção.
 
 ## Referências