@lexnode/legal-data-sdk 1.27.0 → 1.29.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();
@@ -208,6 +209,10 @@ switch (resultado.event.type) {
       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.
@@ -471,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, MonitorSyncInstance, MonitorSyncSucceededPayload, PeriodEndingPayload, ProcessInstanceDiscoveredPayload, ProcessInstanceDiscoveredWithheldPayload, 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 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 {};

package/dist/lookup.js

@@ -0,0 +1,158 @@
+import { LexNodeError, isLexNodeError } from "./errors.js";
+/** O processo que a consulta entregou, na visão dela, ou nulo. */
+function readOf(lookup, view) {
+    const read = view === "SNAPSHOT" ? lookup.snapshot : lookup.process;
+    return (read ?? null);
+}
+/**
+ * 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 async function lookupProcess(client, input, opts = {}) {
+    const { data, meta } = await client.processLookups.create(input, opts);
+    if (meta.status === 202) {
+        return { kind: "pending", lookup: data, stale: data.stale ?? null, meta };
+    }
+    const read = readOf(data, input.view);
+    if (!read) {
+        throw new LexNodeError({
+            code: "INVALID_RESPONSE",
+            message: `A consulta respondeu ${meta.status} sem o processo da visão ${input.view}.`,
+            status: 502,
+            errorClass: "RETRYABLE",
+            retryable: true,
+            upstreamStatus: meta.status,
+        });
+    }
+    return { kind: "ready", data: read, lookup: data, meta };
+}
+/** Estados em que a consulta não avança mais. */
+const TERMINAL_STATES = new Set(["SUCCEEDED", "FAILED", "CANCELED"]);
+const DEFAULT_BUDGET_MS = 60_000;
+/** A menor espera entre duas leituras, para a próxima tentativa que está perto. */
+const MIN_POLL_INTERVAL_MS = 2_000;
+/**
+ * A espera entre leituras da consulta sem hora futura: a tentativa em curso
+ * (`nextAttemptAt` nulo) ou a vencida que espera a vez na fila. O desfecho
+ * dela sai em até um minuto, e ler a cada poucos segundos só gastaria o teto
+ * por minuto da chave.
+ */
+const IN_FLIGHT_POLL_INTERVAL_MS = 10_000;
+function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        let timer;
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function budgetExceeded(lookupId, budgetMs, state, nextReadAt) {
+    return new LexNodeError({
+        code: "PROCESS_LOOKUP_BUDGET_EXCEEDED",
+        message: `A consulta ${lookupId} não termina dentro do orçamento de ${budgetMs} ms; ela segue tentando no motor.`,
+        status: 504,
+        errorClass: "RETRYABLE",
+        retryable: true,
+        details: {
+            lookupId,
+            status: state,
+            budgetMs,
+            nextReadAt: new Date(nextReadAt).toISOString(),
+        },
+    });
+}
+/**
+ * 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 async function waitForProcessLookup(client, lookupId, options = {}) {
+    const budgetMs = options.budgetMs ?? DEFAULT_BUDGET_MS;
+    const deadline = Date.now() + budgetMs;
+    let lastState = null;
+    const controller = new AbortController();
+    const { signal } = controller;
+    const onCallerAbort = () => controller.abort(options.signal?.reason);
+    if (options.signal?.aborted)
+        onCallerAbort();
+    else
+        options.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    const timer = setTimeout(() => {
+        controller.abort(budgetExceeded(lookupId, budgetMs, lastState, Date.now()));
+    }, Math.max(0, budgetMs));
+    try {
+        for (;;) {
+            signal.throwIfAborted();
+            if (Date.now() >= deadline) {
+                throw budgetExceeded(lookupId, budgetMs, lastState, Date.now());
+            }
+            let nextReadAt;
+            try {
+                const { data } = await client.processLookups.get(lookupId, {
+                    signal,
+                    officeId: options.officeId,
+                });
+                signal.throwIfAborted();
+                if (Date.now() >= deadline) {
+                    throw budgetExceeded(lookupId, budgetMs, lastState, Date.now());
+                }
+                lastState = data.status;
+                options.onState?.(data.status, data);
+                if (TERMINAL_STATES.has(data.status))
+                    return data;
+                const nextAttemptAt = data.nextAttemptAt
+                    ? Date.parse(data.nextAttemptAt)
+                    : Number.NaN;
+                const now = Date.now();
+                nextReadAt =
+                    Number.isFinite(nextAttemptAt) && nextAttemptAt > now
+                        ? Math.max(now + MIN_POLL_INTERVAL_MS, nextAttemptAt)
+                        : now + IN_FLIGHT_POLL_INTERVAL_MS;
+            }
+            catch (error) {
+                signal.throwIfAborted();
+                if (!isLexNodeError(error) ||
+                    !error.retryable ||
+                    error.retryAfterSeconds === null) {
+                    throw error;
+                }
+                nextReadAt = Date.now() + error.retryAfterSeconds * 1_000;
+            }
+            if (nextReadAt >= deadline) {
+                throw budgetExceeded(lookupId, budgetMs, lastState, nextReadAt);
+            }
+            await wait(nextReadAt - Date.now(), signal);
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onCallerAbort);
+    }
+}

package/dist/webhooks.d.ts

@@ -323,6 +323,48 @@ export interface SearchJobFailedPayload {
     };
     pollUrl: string;
 }
+/**
+ * O fim de uma consulta de processo em segundo plano
+ * (`POST /v1/processes/lookups`). É um ponteiro: o processo nunca viaja no
+ * evento — lê-se em `pollUrl`, sem nova cobrança, pelo controle de
+ * confidencialidade de quem lê. O movimento novo que a entrega trouxer chega no
+ * `PROCESS_MOVEMENT_CREATED` de sempre.
+ */
+interface ProcessLookupCompletedBase {
+    lookupId: string;
+    view: "PROCESS" | "SNAPSHOT";
+    tribunalAlias: string;
+    /** Só os 20 dígitos. */
+    processNumber: string;
+    officeId: string | null;
+    traceId: string | null;
+    /** Idas à fonte, a leitura que abriu a consulta incluída. */
+    attempts: number;
+    pollUrl: string;
+}
+export interface ProcessLookupSucceededPayload extends ProcessLookupCompletedBase {
+    status: "SUCCEEDED";
+    /**
+     * Quem entregou: a fonte, o acervo que outra leitura atualizou, ou uma
+     * leitura direta da mesma conta, que já tinha cobrado — então esta não cobra.
+     */
+    satisfiedBy: "SOURCE" | "LAKE" | "DIRECT_READ";
+    creditsCharged: number;
+}
+export interface ProcessLookupFailedPayload extends ProcessLookupCompletedBase {
+    status: "FAILED";
+    satisfiedBy: null;
+    /** A retenção inteira, devolvida ao saldo. */
+    creditsRefunded: number;
+    error: {
+        class: "RETRYABLE" | "TERMINAL";
+        code: string;
+        /** O texto público fixo do código. */
+        message: string;
+        retryable: boolean;
+        upstreamStatus?: number;
+    };
+}
 export interface PublicationTextAlertMatch {
     source: string;
     publicationKey: string;
@@ -379,7 +421,7 @@ type Typed<T extends string, P> = WebhookEventEnvelope & {
     payload: P;
 };
 /** Os tipos do catálogo e a entrega de teste, discriminados por `type`. */
-export type WebhookEvent = Typed<"PROCESS_MOVEMENT_CREATED", ProcessMovementCreatedPayload> | Typed<"PROCESS_INSTANCE_DISCOVERED", ProcessInstanceDiscoveredPayload | ProcessInstanceDiscoveredWithheldPayload> | Typed<"PUBLICATION_CREATED", PublicationCreatedPayload> | Typed<"MONITOR_SYNC_SUCCEEDED", MonitorSyncSucceededPayload> | Typed<"MONITOR_SYNC_FAILED", MonitorSyncFailedPayload> | Typed<"SEARCH_JOB_COMPLETED", SearchJobSucceededPayload | SearchJobFailedPayload> | Typed<"PUBLICATION_TEXT_ALERT_MATCHED", PublicationTextAlertMatchedPayload> | Typed<"PUBLICATION_HARVEST_COMPLETED", PublicationHarvestCompletedPayload> | Typed<"QUOTA_LOW", QuotaLowPayload> | Typed<"PERIOD_ENDING", PeriodEndingPayload> | Typed<"SUBSCRIPTION_PAST_DUE", SubscriptionPastDuePayload> | Typed<"WEBHOOK_TEST", WebhookTestPayload>;
+export type WebhookEvent = Typed<"PROCESS_MOVEMENT_CREATED", ProcessMovementCreatedPayload> | Typed<"PROCESS_INSTANCE_DISCOVERED", ProcessInstanceDiscoveredPayload | ProcessInstanceDiscoveredWithheldPayload> | Typed<"PUBLICATION_CREATED", PublicationCreatedPayload> | Typed<"MONITOR_SYNC_SUCCEEDED", MonitorSyncSucceededPayload> | Typed<"MONITOR_SYNC_FAILED", MonitorSyncFailedPayload> | Typed<"SEARCH_JOB_COMPLETED", SearchJobSucceededPayload | SearchJobFailedPayload> | Typed<"PUBLICATION_TEXT_ALERT_MATCHED", PublicationTextAlertMatchedPayload> | Typed<"PUBLICATION_HARVEST_COMPLETED", PublicationHarvestCompletedPayload> | Typed<"PROCESS_LOOKUP_COMPLETED", ProcessLookupSucceededPayload | ProcessLookupFailedPayload> | Typed<"QUOTA_LOW", QuotaLowPayload> | Typed<"PERIOD_ENDING", PeriodEndingPayload> | Typed<"SUBSCRIPTION_PAST_DUE", SubscriptionPastDuePayload> | Typed<"WEBHOOK_TEST", WebhookTestPayload>;
 /**
  * O evento que o catálogo ainda não descreve.
  *
@@ -402,7 +444,7 @@ export type WebhookEventType = WebhookEvent["type"];
  */
 export declare const WEBHOOK_TEST_EVENT_TYPE: "WEBHOOK_TEST";
 /** Os tipos que se pode ASSINAR ao cadastrar um endpoint. */
-export declare const WEBHOOK_EVENT_TYPES: readonly ["PROCESS_MOVEMENT_CREATED", "PROCESS_INSTANCE_DISCOVERED", "PUBLICATION_CREATED", "MONITOR_SYNC_SUCCEEDED", "MONITOR_SYNC_FAILED", "SEARCH_JOB_COMPLETED", "PUBLICATION_TEXT_ALERT_MATCHED", "PUBLICATION_HARVEST_COMPLETED", "QUOTA_LOW", "PERIOD_ENDING", "SUBSCRIPTION_PAST_DUE"];
+export declare const WEBHOOK_EVENT_TYPES: readonly ["PROCESS_MOVEMENT_CREATED", "PROCESS_INSTANCE_DISCOVERED", "PUBLICATION_CREATED", "MONITOR_SYNC_SUCCEEDED", "MONITOR_SYNC_FAILED", "SEARCH_JOB_COMPLETED", "PUBLICATION_TEXT_ALERT_MATCHED", "PUBLICATION_HARVEST_COMPLETED", "PROCESS_LOOKUP_COMPLETED", "QUOTA_LOW", "PERIOD_ENDING", "SUBSCRIPTION_PAST_DUE"];
 /**
  * O que entra em `eventTypes` ao cadastrar um endpoint. É subconjunto próprio
  * de `WebhookEventType`: mandar a entrega de teste nessa lista é recusa.

package/dist/webhooks.js

@@ -124,6 +124,7 @@ export const WEBHOOK_EVENT_TYPES = [
     "SEARCH_JOB_COMPLETED",
     "PUBLICATION_TEXT_ALERT_MATCHED",
     "PUBLICATION_HARVEST_COMPLETED",
+    "PROCESS_LOOKUP_COMPLETED",
     "QUOTA_LOW",
     "PERIOD_ENDING",
     "SUBSCRIPTION_PAST_DUE",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexnode/legal-data-sdk",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "description": "Cliente TypeScript do LexNode, o motor de dados jur\u00eddicos do Brasil: transporte tipado, erros classificados, verifica\u00e7\u00e3o de webhook e os tipos gerados do contrato OpenAPI.",
   "license": "MIT",
   "homepage": "https://www.lexnode.com.br/docs",