@lexnode/legal-data-sdk 1.26.0 → 1.28.0

package/README.md

@@ -73,6 +73,7 @@ await lexnode.publications.list({ oabNumber: "123456", oabState: "SP" });
 await lexnode.monitors.create({ type: "OAB", oabNumber: "123456", oabState: "SP" });
 await lexnode.subscriptions.create({ tribunalAlias, processNumber, externalRef });
 await lexnode.searchJobs.get(jobId);
+await lexnode.processLookups.get(lookupId);
 await lexnode.events.list({ limit: 50 });
 await lexnode.webhooks.endpoints.list();
 await lexnode.webhooks.unsubscribedEventTypes();
@@ -194,12 +195,24 @@ switch (resultado.event.type) {
     break;
   case "PROCESS_MOVEMENT_CREATED":
     resultado.event.payload.externalRef;
+    resultado.event.payload.degree; // o grau do movimento mais recente
+    break;
+  case "PROCESS_INSTANCE_DISCOVERED":
+    // Outro grau do processo apareceu na fonte; o histórico dele está no
+    // retrato, em `instances`. O processo retido vem sem o grau.
+    if (!resultado.event.payload.contentWithheld) {
+      resultado.event.payload.degree;
+    }
     break;
   case "SEARCH_JOB_COMPLETED":
     if (resultado.event.payload.status === "FAILED") {
       resultado.event.payload.error.code;
     }
     break;
+  case "PROCESS_LOOKUP_COMPLETED":
+    // Um ponteiro: 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.
@@ -256,6 +269,94 @@ 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.
+
+**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
+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
+(`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.
+
+```ts
+const { data } = await lexnode.processes.snapshot(numero, { tribunalAlias });
+
+for (const instancia of data.instances) {
+  instancia.degree; // "G1", "G2", "TR"…
+  instancia.primary; // true só na do topo
+  instancia.movements ?? "movimentos nunca capturados";
+}
+```
+
+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.
+
+**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
+em `degrees` o grau — ou os graus, quando o mesmo ato está nos dois documentos
+— que o trouxe, e vem vazio no movimento que nenhuma captura atual traz.
+
+```ts
+const { data } = await lexnode.processes.movements(numero, {
+  tribunalAlias,
+  degree: "G1",
+});
+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.
+
+**`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`.
+
+```ts
+for (const outra of meta.otherInstances ?? []) {
+  // Ex.: { grau: "G1", updatedAt: "2026-04-15T12:00:00.000Z" }
+}
+```
+
+**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.
+
 ## Ler um processo quando a fonte está lenta
 
 A ficha (`processes.get`) vai à fonte processual quando o acervo não tem o
@@ -290,15 +391,15 @@ ou a vigília do processo (`watchProcess`), que consulta em segundo plano.
 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 processo servido é o que a fonte tem, mas
-outra instância do mesmo número — outro grau — pode estar na parte que não
-respondeu. A resposta parcial que não serve o processo — sem ele, ou com uma
-instância diferente da que o acervo já guarda — é 502 `UPSTREAM_UNAVAILABLE`
+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.
 
 ```ts
 if (meta.partialIndex) {
-  // Outro grau deste número, se existir, pode não ter vindo.
+  // Outro grau deste número que o acervo não conhece pode não ter vindo.
 }
 ```
 
@@ -306,21 +407,6 @@ 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
 pausa curta, enquanto a espera couber.
 
-**`meta.otherInstances`: o número tem outro documento na fonte.** A fonte pode
-guardar mais de um documento por número — em geral um por instância (1º grau,
-2º grau, turma recursal…), às vezes dois no mesmo grau —, e o motor serve e
-guarda um só: o de `data`, cujo grau está em `degree`. Quando a resposta da
-fonte trouxe outros, `meta.otherInstances` lista 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.
-
-```ts
-for (const outra of meta.otherInstances ?? []) {
-  // Ex.: { grau: "G1", updatedAt: "2026-04-15T12:00:00.000Z" }
-}
-```
-
 **Agentes têm a espera deles.** No canal para agentes (MCP), as tools
 `ler_processo` e `consultar_processo` escolhem a espera em `maxWaitSeconds`, na
 mesma faixa e com padrão de 120 s; esse canal não passa pelo SDK.
@@ -345,10 +431,13 @@ vez do erro. A resposta diz que é cópia, e de quando:
 
 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, os movimentos são os da
-última vez que o motor buscou o processo, e `sourcePayload` é nulo: o que andou
-depois dessa data não está na resposta. Na ficha guardada, a data vale para os
-dados do processo, e o resumo das publicações (`djen`) é relido na hora.
+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
+`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.
 
 **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
@@ -387,6 +476,87 @@ ativa —, e os demais recebem a falha da fonte, como se não houvesse cópia.
 item socorrido traz `lakeRescue` com a causa e a data, e custa 1 crédito em vez
 de 8.
 
+## Leitura que não coube na espera
+
+Quando a fonte processual não entrega dentro de `waitSeconds`, a ficha e o
+retrato respondem com o erro dela (ou com a cópia guardada, seção anterior).
+`processLookups.create` faz a MESMA leitura, e o que não coube na espera segue
+em segundo plano em vez de virar erro:
+
+- **200**: a leitura coube. `data` é uma consulta `SUCCEEDED` sem consulta
+  aberta (`lookupId` nulo) que traz o processo em `process` (visão
+  `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
+  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.
+
+`lookupProcess` diz, no tipo, qual dos dois desfechos aconteceu, e
+`waitForProcessLookup` espera a consulta terminar:
+
+```ts
+import { lookupProcess, waitForProcessLookup } from "@lexnode/legal-data-sdk";
+
+const desfecho = await lookupProcess(lexnode, {
+  tribunalAlias: "api_publica_tjsp",
+  processNumber: numero,
+  view: "SNAPSHOT",
+});
+
+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.
+  const consulta = await waitForProcessLookup(
+    lexnode,
+    desfecho.lookup.lookupId!,
+    { budgetMs: 10 * 60_000 },
+  );
+  if (consulta.status === "SUCCEEDED" && consulta.snapshot) {
+    consulta.snapshot.movements;
+  }
+}
+```
+
+**Repetir é seguro.** A mesma leitura pedida de novo — mesma conta,
+escritório, processo e visão — devolve a mesma consulta (`deduped: true`), sem
+nova retenção; por isso `processLookups.create` entra na política de
+retentativa como uma leitura. Quando a próxima tentativa agendada está longe, a
+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.
+
+**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.
+
+**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
+aberta sem cobrar — a leitura já cobrou.
+
+**Tetos.** Até 5 consultas abertas por chave e 20 por conta; além disso, a
+falha da fonte volta como a leitura direta a daria. A chave de teste nunca abre
+consulta.
+
 ## Frescor: o `total: 0` qualificado
 
 Um resultado vazio não distingue sozinho "não existe" de "a fonte ainda não

package/dist/client.d.ts

@@ -12,8 +12,9 @@ export interface LexNodeClientOptions {
     officeId?: string;
     /**
      * Prazo de cada chamada, em ms. Padrão: 30 s. A ficha e o retrato de um
-     * processo levam o maior entre este prazo e a espera pela fonte mais 15 s —
-     * `waitSeconds`, ou o padrão de 20 s da API quando ele falta.
+     * processo, e a leitura que segue em segundo plano, levam o maior entre este
+     * prazo e a espera pela fonte mais 15 s — `waitSeconds`, ou o padrão de 20 s
+     * da API quando ele falta.
      */
     timeoutMs?: number;
     /** Transporte alternativo — o `fetch` global é o padrão. */
@@ -71,6 +72,19 @@ export declare function createLexNodeClient(options: LexNodeClientOptions): {
         list: (query?: Query<"/v1/subscriptions", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/subscriptions", "get">>;
         delete: (body: Body<"/v1/subscriptions", "delete">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/subscriptions", "delete">>;
     };
+    processLookups: {
+        /**
+         * A leitura de UM processo que segue em segundo plano quando a fonte não
+         * entrega dentro de `waitSeconds`: 200 com o processo, ou 202 com a
+         * consulta aberta. Repetir é seguro — o motor devolve a consulta já
+         * aberta da mesma leitura em vez de abrir outra —, então a retentativa
+         * vale para ela como para uma leitura.
+         */
+        create: (body: Body<"/v1/processes/lookups", "post">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/lookups", "post">>;
+        get: (lookupId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/lookups/{lookupId}", "get">>;
+        list: (query?: Query<"/v1/processes/lookups", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/lookups", "get">>;
+        cancel: (lookupId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/lookups/{lookupId}/cancel", "post">>;
+    };
     searchJobs: {
         get: (jobId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/search-jobs/{jobId}", "get">>;
         list: (query?: Query<"/v1/search-jobs", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/search-jobs", "get">>;

package/dist/client.js

@@ -18,12 +18,14 @@ 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.
+ * As chamadas em que quem chama escolhe, em `waitSeconds`, quanto o motor
+ * espera pela fonte processual, e onde a espera viaja: na consulta das duas
+ * leituras de UM processo, no corpo da leitura que segue em segundo plano.
  */
-const SOURCE_WAIT_ROUTES = new Set([
-    "get /v1/processes/{processNumber}",
-    "get /v1/processes/{processNumber}/snapshot",
+const SOURCE_WAIT_ROUTES = new Map([
+    ["get /v1/processes/{processNumber}", "query"],
+    ["get /v1/processes/{processNumber}/snapshot", "query"],
+    ["post /v1/processes/lookups", "body"],
 ]);
 /**
  * A espera que o motor aplica a essas leituras quando a chamada não traz
@@ -117,10 +119,14 @@ function appendQuery(url, query) {
  * 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}`))
+function defaultCallTimeoutMs(method, path, carriers, clientTimeoutMs) {
+    const carrier = SOURCE_WAIT_ROUTES.get(`${method} ${path}`);
+    if (!carrier)
         return clientTimeoutMs;
-    const requested = Number(query?.waitSeconds);
+    const source = carriers[carrier];
+    const requested = Number(source && typeof source === "object"
+        ? source.waitSeconds
+        : undefined);
     const waitSeconds = Number.isFinite(requested) && requested > 0
         ? requested
         : SOURCE_WAIT_API_DEFAULT_SECONDS;
@@ -261,7 +267,7 @@ export function createLexNodeClient(options) {
             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);
+            defaultCallTimeoutMs(String(method), String(path), { query: bag.params?.query, body: bag.body }, defaultTimeoutMs);
         const link = linkAbort(timeoutMs, args.signal);
         let response;
         let raw;
@@ -423,6 +429,29 @@ export function createLexNodeClient(options) {
             list: (query, opts = {}) => request("/v1/subscriptions", "get", { params: { query }, ...opts }),
             delete: (body, opts = {}) => request("/v1/subscriptions", "delete", { body, ...opts }),
         },
+        processLookups: {
+            /**
+             * A leitura de UM processo que segue em segundo plano quando a fonte não
+             * entrega dentro de `waitSeconds`: 200 com o processo, ou 202 com a
+             * consulta aberta. Repetir é seguro — o motor devolve a consulta já
+             * aberta da mesma leitura em vez de abrir outra —, então a retentativa
+             * vale para ela como para uma leitura.
+             */
+            create: (body, opts = {}) => request("/v1/processes/lookups", "post", {
+                body,
+                idempotent: true,
+                ...opts,
+            }),
+            get: (lookupId, opts = {}) => request("/v1/processes/lookups/{lookupId}", "get", {
+                params: { path: { lookupId } },
+                ...opts,
+            }),
+            list: (query, opts = {}) => request("/v1/processes/lookups", "get", { params: { query }, ...opts }),
+            cancel: (lookupId, opts = {}) => request("/v1/processes/lookups/{lookupId}/cancel", "post", {
+                params: { path: { lookupId } },
+                ...opts,
+            }),
+        },
         searchJobs: {
             get: (jobId, opts = {}) => request("/v1/search-jobs/{jobId}", "get", {
                 params: { path: { jobId } },

package/dist/errors.d.ts

@@ -9,7 +9,7 @@ import type { RateLimitSnapshot } from "./types.js";
  * 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"];
+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"];
 /**
  * Um código conhecido — ou qualquer outro.
  *

package/dist/errors.js

@@ -43,6 +43,7 @@ export const LEXNODE_ERROR_CODES = [
     "MONITOR_ALREADY_EXISTS",
     "MONITOR_NOT_FOUND",
     "SEARCH_JOB_NOT_FOUND",
+    "PROCESS_LOOKUP_NOT_FOUND",
     "PUBLICATION_NOT_FOUND",
     "EVENT_NOT_FOUND",
     "TEXT_ALERT_NOT_FOUND",
@@ -54,6 +55,7 @@ export const LEXNODE_ERROR_CODES = [
     "CLIENT_MISSING_PATH_PARAM",
     "INVALID_RESPONSE",
     "SEARCH_JOB_BUDGET_EXCEEDED",
+    "PROCESS_LOOKUP_BUDGET_EXCEEDED",
     "PAGINATION_LIMIT_REACHED",
 ];
 const RAW_MESSAGE_MAX_CHARS = 500;

package/dist/index.d.ts

@@ -15,9 +15,11 @@ export { LEXNODE_ERROR_CODES, LexNodeError, isLexNodeError } from "./errors.js";
 export type { LexNodeErrorClass, LexNodeErrorCode, LexNodeErrorInit, } from "./errors.js";
 export type { Body, CallOptions, Data, HttpMethod, LexNodeResult, Meta, MetaExtras, MethodOf, Operation, PathParams, Query, RateLimitSnapshot, RequestArgs, RetryPolicy, } from "./types.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 type { MonitorSyncFailedPayload, MonitorSyncSucceededPayload, PeriodEndingPayload, ProcessMovementCreatedPayload, 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 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 { 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

@@ -12,6 +12,7 @@ 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 { searchProcesses, waitForSearchJob } from "./search.js";
 export { describeFreshness, freshnessOf, isNotYetIndexed, lakeRescueOf, readThrough, sourceFetchedAtOf, } from "./freshness.js";
 export { isFirstAppearance, resubscribeOnFirstAppearance, unwatchProcess, watchProcess, } from "./watch.js";

package/dist/lookup.d.ts

@@ -0,0 +1,79 @@
+import type { LexNodeClient } from "./client.js";
+import type { Body, CallOptions, Data, Meta, MetaExtras } from "./types.js";
+/**
+ * A leitura de UM processo que segue em segundo plano responde de dois jeitos
+ * na MESMA operação: 200 com o processo, quando ele coube na espera, ou 202
+ * com a consulta que segue tentando a fonte sozinha. O discriminador é o
+ * código HTTP, como na busca: a consulta aberta também tem `status`, mas quem
+ * afirma o desfecho da chamada é o 200 ou o 202.
+ */
+type CreateData = Data<"/v1/processes/lookups", "post">;
+type CreateMeta = Meta<"/v1/processes/lookups", "post"> & MetaExtras;
+/** A consulta como a leitura dela a devolve. */
+export type ProcessLookup = Data<"/v1/processes/lookups/{lookupId}", "get">;
+export type ProcessLookupState = ProcessLookup["status"];
+export type ProcessLookupView = ProcessLookup["view"];
+/** O que se pede: tribunal, número, visão, espera e a cópia na falha. */
+export type ProcessLookupInput = Body<"/v1/processes/lookups", "post">;
+/** A cópia guardada que o 202 entrega enquanto a consulta segue. */
+export type StaleProcessCopy = NonNullable<CreateData["stale"]>;
+/** O processo entregue na visão pedida: a ficha ou o retrato. */
+export type ProcessLookupRead<V extends ProcessLookupView> = V extends "SNAPSHOT" ? NonNullable<CreateData["snapshot"]> : NonNullable<CreateData["process"]>;
+export type ProcessLookupOutcome<V extends ProcessLookupView = ProcessLookupView> = {
+    kind: "ready";
+    /** A ficha ou o retrato, como a leitura direta os devolveria. */
+    data: ProcessLookupRead<V>;
+    lookup: CreateData;
+    meta: CreateMeta;
+} | {
+    kind: "pending";
+    /** A consulta aberta, a ser acompanhada por `waitForProcessLookup`. */
+    lookup: CreateData;
+    /** A cópia guardada, com a data, quando pedida em `staleOnFailure`. */
+    stale: StaleProcessCopy | null;
+    meta: CreateMeta;
+};
+/**
+ * Lê um processo e diz, no tipo, qual dos dois desfechos aconteceu.
+ *
+ * Sem isto, o consumidor lê `data.process` num corpo que é uma consulta
+ * aberta e chama de "sem dados" o que é "ainda estou buscando". A mesma
+ * leitura pedida de novo devolve a mesma consulta — repetir é seguro, e o
+ * cliente repete sozinho quando a política de retentativa estiver ligada.
+ */
+export declare function lookupProcess<V extends ProcessLookupView>(client: LexNodeClient, input: ProcessLookupInput & {
+    view: V;
+}, opts?: CallOptions): Promise<ProcessLookupOutcome<V>>;
+export interface WaitForProcessLookupOptions {
+    /**
+     * Teto de espera total, em ms, incluindo as leituras e suas retentativas.
+     * EXPLÍCITO de propósito, como na busca: a consulta
+     * tenta por horas, e um laço sem orçamento gasta a requisição inteira de um
+     * ambiente serverless esperando uma fonte fora do ar.
+     */
+    budgetMs?: number;
+    signal?: AbortSignal;
+    /** Chamado a cada leitura da consulta, para a UI acompanhar. */
+    onState?: (state: ProcessLookupState, lookup: ProcessLookup) => void;
+    officeId?: string | null;
+}
+/**
+ * Espera a consulta terminar, dentro do orçamento.
+ *
+ * Lê a consulta de novo só quando há o que mudar: na hora da próxima tentativa
+ * (`nextAttemptAt`) — antes dela, a leitura devolve o mesmo estado —, a cada
+ * 10 s enquanto uma tentativa está em curso ou espera a vez na fila, e depois
+ * do `Retry-After` quando a própria leitura é recusada por vazão. Leitura não
+ * cobra, mas conta no teto por minuto da chave.
+ *
+ * O estouro do orçamento é um erro PRÓPRIO e retentável
+ * (`PROCESS_LOOKUP_BUDGET_EXCEEDED`): a consulta continua no motor, e quem
+ * espera pode voltar a lê-la depois — `details.nextReadAt` diz quando vale a
+ * pena — ou receber o `PROCESS_LOOKUP_COMPLETED` por webhook e não esperar
+ * nada. Quando a próxima leitura útil cai depois do orçamento, o erro sai na
+ * hora: esperar até o fim dele não mudaria nada. Devolve a consulta
+ * terminada: `SUCCEEDED`, com o processo enquanto o resultado vale; `FAILED`,
+ * com `error`; ou `CANCELED`.
+ */
+export declare function waitForProcessLookup(client: LexNodeClient, lookupId: string, options?: WaitForProcessLookupOptions): Promise<ProcessLookup>;
+export {};