@lexnode/legal-data-sdk 1.29.0 → 1.31.0

package/dist/lookup.d.ts

@@ -1,24 +1,32 @@
 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. */
+/**
+ * A consulta em segundo plano, como `GET /v1/processes/lookups/{lookupId}` a
+ * devolve.
+ */
 export type ProcessLookup = Data<"/v1/processes/lookups/{lookupId}", "get">;
+/** O estado da consulta em segundo plano. */
 export type ProcessLookupState = ProcessLookup["status"];
+/** A visão pedida: `PROCESS` (a ficha) ou `SNAPSHOT` (o retrato). */
 export type ProcessLookupView = ProcessLookup["view"];
-/** O que se pede: tribunal, número, visão, espera e a cópia na falha. */
+/**
+ * O pedido de `POST /v1/processes/lookups`: o tribunal, o número, a visão, a
+ * espera pela fonte e se a cópia guardada serve na falha dela.
+ */
 export type ProcessLookupInput = Body<"/v1/processes/lookups", "post">;
-/** A cópia guardada que o 202 entrega enquanto a consulta segue. */
+/**
+ * A cópia guardada, com a data, que a resposta 202 traz quando o pedido tem
+ * `staleOnFailure: true`.
+ */
 export type StaleProcessCopy = NonNullable<CreateData["stale"]>;
-/** O processo entregue na visão pedida: a ficha ou o retrato. */
+/** O processo na visão pedida: a ficha ou o retrato. */
 export type ProcessLookupRead<V extends ProcessLookupView> = V extends "SNAPSHOT" ? NonNullable<CreateData["snapshot"]> : NonNullable<CreateData["process"]>;
+/**
+ * O desfecho de `lookupProcess`: `ready` com o processo em `data`, ou
+ * `pending` com a consulta aberta em `lookup`.
+ */
 export type ProcessLookupOutcome<V extends ProcessLookupView = ProcessLookupView> = {
     kind: "ready";
     /** A ficha ou o retrato, como a leitura direta os devolveria. */
@@ -27,53 +35,138 @@ export type ProcessLookupOutcome<V extends ProcessLookupView = ProcessLookupView
     meta: CreateMeta;
 } | {
     kind: "pending";
-    /** A consulta aberta, a ser acompanhada por `waitForProcessLookup`. */
+    /** A consulta aberta; acompanhe-a com `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.
+ * Lê um processo e diz no tipo se ele veio na hora ou se a leitura seguiu em
+ * segundo plano.
+ *
+ * Chama `POST /v1/processes/lookups`. Com 200, devolve `kind: "ready"` e o
+ * processo em `data`, como a leitura direta o devolveria; com 202, devolve
+ * `kind: "pending"` e a consulta aberta em `lookup`, para acompanhar com
+ * `waitForProcessLookup` ou pelo evento `PROCESS_LOOKUP_COMPLETED`. Uma
+ * consulta aberta não é um processo sem dados. Pedir a mesma leitura de novo
+ * devolve a mesma consulta, então repetir é seguro, e a política de
+ * retentativa, quando ligada, repete esta chamada.
+ *
+ * Lança `LexNodeError` nas recusas da API e `INVALID_RESPONSE` quando o 200
+ * vem sem o processo da visão pedida.
  *
- * 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.
+ * @example
+ * ```ts
+ * const desfecho = await lookupProcess(lexnode, {
+ *   tribunalAlias: "TJSP",
+ *   processNumber: numero,
+ *   view: "SNAPSHOT",
+ * });
+ * if (desfecho.kind === "ready") desfecho.data.movements;
+ * else guardarConsulta(desfecho.lookup.lookupId);
+ * ```
  */
 export declare function lookupProcess<V extends ProcessLookupView>(client: LexNodeClient, input: ProcessLookupInput & {
     view: V;
 }, opts?: CallOptions): Promise<ProcessLookupOutcome<V>>;
+/** As opções de `waitForProcessLookup`. */
 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.
+     * O tempo máximo de espera, em ms, contando as leituras e as retentativas.
+     * Padrão: 60 000. A consulta pode seguir tentando por horas; num ambiente
+     * serverless, escolha um valor que caiba no prazo da sua função.
      */
     budgetMs?: number;
+    /** Cancela a espera; a consulta continua. */
     signal?: AbortSignal;
-    /** Chamado a cada leitura da consulta, para a UI acompanhar. */
-    onState?: (state: ProcessLookupState, lookup: ProcessLookup) => void;
+    /**
+     * Chamada a cada leitura, com o estado, a consulta e o `meta`, por exemplo
+     * para mostrar o progresso.
+     */
+    onState?: (state: ProcessLookupState, lookup: ProcessLookup, meta: Meta<"/v1/processes/lookups/{lookupId}", "get"> & MetaExtras) => void;
+    /** O escritório (sub-tenant) das leituras; veja `CallOptions.officeId`. */
     officeId?: string | null;
 }
 /**
- * Espera a consulta terminar, dentro do orçamento.
+ * Espera a consulta em segundo plano terminar e devolve a consulta terminada:
+ * `SUCCEEDED`, com o processo enquanto o resultado vale; `FAILED`, com
+ * `error`; ou `CANCELED`.
  *
- * 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.
+ * Lê a consulta na hora da próxima tentativa (`nextAttemptAt`), a cada 10 s
+ * enquanto uma tentativa está em curso ou na fila e, quando a leitura é
+ * recusada por vazão, depois do `Retry-After`. Ler a consulta não custa
+ * créditos, mas conta no limite de vazão 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`.
+ * Lança `LexNodeError` `PROCESS_LOOKUP_BUDGET_EXCEEDED` (retentável) quando
+ * `budgetMs` acaba antes do fim, ou assim que a próxima leitura útil cairia
+ * depois dele. A consulta continua: `details.nextReadAt` diz quando vale ler
+ * de novo, e o evento `PROCESS_LOOKUP_COMPLETED` avisa o fim. Repassa as
+ * demais falhas das leituras.
  */
 export declare function waitForProcessLookup(client: LexNodeClient, lookupId: string, options?: WaitForProcessLookupOptions): Promise<ProcessLookup>;
+type ProcessRecoveryMeta = CreateMeta | (Meta<"/v1/processes/lookups/{lookupId}", "get"> & MetaExtras);
+/**
+ * O desfecho de `readProcessWithRecovery`: `ready` com o processo; `pending`
+ * com a consulta aberta, a cópia guardada quando houver e a próxima leitura
+ * útil em `nextReadAt`; ou `failed`, `canceled` e `expired`, com a consulta
+ * terminada sem o processo. Nenhum desses três afirma que o processo não
+ * existe.
+ */
+export type ProcessRecoveryOutcome<V extends ProcessLookupView> = {
+    kind: "ready";
+    data: ProcessLookupRead<V>;
+    lookup: CreateData | ProcessLookup;
+    meta: ProcessRecoveryMeta;
+} | {
+    kind: "pending";
+    lookup: CreateData | ProcessLookup;
+    stale: StaleProcessCopy | null;
+    nextReadAt: string | null;
+} | {
+    kind: "failed" | "canceled" | "expired";
+    lookup: ProcessLookup;
+};
+/**
+ * Lê um processo com recuperação: abre a consulta e, quando ela segue em
+ * segundo plano, acompanha-a por até `completionBudgetMs`.
+ *
+ * `staleOnFailure` é obrigatório: com `true`, você aceita receber, na falha da
+ * fonte, uma cópia guardada anterior a ela — confira a data em
+ * `sourceFetchedAt`. Sem `completionBudgetMs`, ou com 0, devolve na hora o
+ * desfecho da abertura. Ao esgotar o orçamento, devolve `pending` com a mesma
+ * consulta, sem abrir outra nem cancelá-la; continue com
+ * `processLookups.get(lookupId)` ou pelo evento `PROCESS_LOOKUP_COMPLETED`.
+ * Abortar o `signal` interrompe a espera com o motivo do aborto e também não
+ * cancela a consulta.
+ *
+ * Lança `RangeError` quando `completionBudgetMs` é negativo ou não finito, e
+ * `LexNodeError` nas recusas da API.
+ *
+ * @example
+ * ```ts
+ * const leitura = await readProcessWithRecovery(
+ *   lexnode,
+ *   {
+ *     tribunalAlias: "TJSP",
+ *     processNumber,
+ *     view: "PROCESS",
+ *     staleOnFailure: true,
+ *   },
+ *   { completionBudgetMs: 30_000 },
+ * );
+ * if (leitura.kind === "ready") {
+ *   usarProcesso(leitura.data);
+ * } else if (leitura.kind === "pending") {
+ *   guardarConsulta(leitura.lookup.lookupId, leitura.nextReadAt);
+ * }
+ * ```
+ */
+export declare function readProcessWithRecovery<V extends ProcessLookupView>(client: LexNodeClient, input: ProcessLookupInput & {
+    view: V;
+    staleOnFailure: boolean;
+}, options?: CallOptions & {
+    completionBudgetMs?: number;
+    onState?: WaitForProcessLookupOptions["onState"];
+}): Promise<ProcessRecoveryOutcome<V>>;
 export {};

package/dist/lookup.js

@@ -1,17 +1,8 @@
 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) {
@@ -30,17 +21,9 @@ export async function lookupProcess(client, input, opts = {}) {
     }
     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) => {
@@ -75,24 +58,6 @@ function budgetExceeded(lookupId, budgetMs, state, nextReadAt) {
         },
     });
 }
-/**
- * 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;
@@ -115,7 +80,7 @@ export async function waitForProcessLookup(client, lookupId, options = {}) {
             }
             let nextReadAt;
             try {
-                const { data } = await client.processLookups.get(lookupId, {
+                const { data, meta } = await client.processLookups.get(lookupId, {
                     signal,
                     officeId: options.officeId,
                 });
@@ -124,7 +89,7 @@ export async function waitForProcessLookup(client, lookupId, options = {}) {
                     throw budgetExceeded(lookupId, budgetMs, lastState, Date.now());
                 }
                 lastState = data.status;
-                options.onState?.(data.status, data);
+                options.onState?.(data.status, data, meta);
                 if (TERMINAL_STATES.has(data.status))
                     return data;
                 const nextAttemptAt = data.nextAttemptAt
@@ -156,3 +121,64 @@ export async function waitForProcessLookup(client, lookupId, options = {}) {
         options.signal?.removeEventListener("abort", onCallerAbort);
     }
 }
+export async function readProcessWithRecovery(client, input, options = {}) {
+    const budgetMs = options.completionBudgetMs ?? 0;
+    options.signal?.throwIfAborted();
+    if (!Number.isFinite(budgetMs) || budgetMs < 0)
+        throw new RangeError("completionBudgetMs deve ser finito e não negativo.");
+    const initial = await lookupProcess(client, input, options);
+    options.signal?.throwIfAborted();
+    if (initial.kind === "ready")
+        return initial;
+    const pending = {
+        kind: "pending",
+        lookup: initial.lookup,
+        stale: initial.stale,
+        nextReadAt: initial.lookup.nextAttemptAt ?? null,
+    };
+    if (budgetMs === 0)
+        return pending;
+    let latest = initial.lookup;
+    let latestMeta = initial.meta;
+    try {
+        const lookup = await waitForProcessLookup(client, initial.lookup.lookupId, {
+            budgetMs,
+            signal: options.signal,
+            officeId: options.officeId,
+            onState: (state, currentLookup, meta) => {
+                latest = currentLookup;
+                latestMeta = meta;
+                options.onState?.(state, currentLookup, meta);
+            },
+        });
+        if (lookup.status === "FAILED")
+            return { kind: "failed", lookup };
+        if (lookup.status === "CANCELED")
+            return { kind: "canceled", lookup };
+        if (lookup.resultExpired)
+            return { kind: "expired", lookup };
+        const data = readOf(lookup, input.view);
+        if (!data)
+            throw new LexNodeError({
+                code: "INVALID_RESPONSE",
+                message: "Consulta concluída sem o resultado da visão pedida.",
+                status: 502,
+                retryable: true,
+                errorClass: "RETRYABLE",
+            });
+        return { kind: "ready", data, lookup, meta: latestMeta };
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+        if (!isLexNodeError(error) ||
+            error.code !== "PROCESS_LOOKUP_BUDGET_EXCEEDED")
+            throw error;
+        const details = error.details;
+        return {
+            ...pending,
+            lookup: latest,
+            nextReadAt: details?.nextReadAt ?? latest.nextAttemptAt ?? null,
+        };
+    }
+}

package/dist/paginate.d.ts

@@ -1,19 +1,29 @@
 import type { paths } from "../schema.js";
 import type { LexNodeClient } from "./client.js";
 import type { Data, MethodOf, RequestArgs } from "./types.js";
+/** As opções de `paginate`. */
 export interface PaginateOptions {
     /**
-     * Teto de páginas. É EXPLÍCITO de propósito: cada página é uma chamada
-     * medida, e um laço sem teto sobre uma conta grande gasta a franquia inteira
-     * antes de alguém perceber.
+     * O máximo de páginas lidas. Padrão: 100. Cada página é uma chamada, que
+     * conta no limite de vazão e, nas rotas que cobram, nos créditos.
      */
     maxPages?: number;
 }
 /**
- * Percorre uma rota paginada página a página, na forma que ela usa.
+ * Percorre uma rota paginada e entrega o `data` de uma página por vez.
  *
+ * Funciona com as três formas de paginação da API: o cursor em `meta`, o
+ * cursor em `data` e as consultas por página (`page` e `pageSize`) ou por
+ * deslocamento (`offset` e `limit`). Termina na última página ou quando o
+ * cursor se repete.
+ *
+ * Lança `LexNodeError` `PAGINATION_LIMIT_REACHED` (não retentável) ao passar
+ * de `maxPages` — aumente o limite ou restrinja a consulta — e repassa o erro
+ * de qualquer página.
+ *
+ * @example
  * ```ts
- * for await (const page of paginate(client, "/v1/monitors", "get", {})) {
+ * for await (const page of paginate(lexnode, "/v1/monitors", "get", {})) {
  *   for (const monitor of page) console.log(monitor.id);
  * }
  * ```

package/dist/paginate.js

@@ -1,17 +1,4 @@
 import { LexNodeError } from "./errors.js";
-/**
- * O laço de páginas, escrito uma vez.
- *
- * O motor pagina de três jeitos, herdados do que cada superfície precisava: o
- * cursor no `meta` do envelope (rotas cujo `data` é um array), o cursor dentro
- * do `data` (rotas com `items`), e o par página/tamanho ou deslocamento/teto da
- * consulta de acervo. Sem isto, cada consumidor reescreve o mesmo laço três
- * vezes — e o que ele erra é sempre o mesmo: para na primeira página, ou anda
- * para sempre porque o cursor deixou de avançar.
- *
- * O cursor do `meta` não é declarado no contrato gerado (o `meta` daquelas
- * rotas é aberto), então é lido aqui com conferência de tipo em runtime.
- */
 const DEFAULT_MAX_PAGES = 100;
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -26,19 +13,12 @@ function readNumber(bag, key) {
     const value = bag?.[key];
     return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
-/** Quantos itens a página trouxe, para o deslocamento andar pelo que veio. */
 function pageLength(data, payload) {
     if (Array.isArray(data))
         return data.length;
     const items = payload?.items;
     return Array.isArray(items) ? items.length : 0;
 }
-/**
- * A consulta da próxima página, ou `null` quando a última chegou.
- *
- * As três formas são decididas aqui, uma vez, na ordem em que o motor as usa —
- * cursor primeiro, porque é a única que não depende de um `total`.
- */
 function nextQuery(data, meta, query) {
     const payload = asRecord(data);
     const cursor = readCursor(asRecord(meta)) ?? readCursor(payload);
@@ -64,15 +44,6 @@ function nextQuery(data, meta, query) {
     }
     return null;
 }
-/**
- * Percorre uma rota paginada página a página, na forma que ela usa.
- *
- * ```ts
- * for await (const page of paginate(client, "/v1/monitors", "get", {})) {
- *   for (const monitor of page) console.log(monitor.id);
- * }
- * ```
- */
 export async function* paginate(client, path, method, args, options = {}) {
     const maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
     let query = {
@@ -87,7 +58,6 @@ export async function* paginate(client, path, method, args, options = {}) {
         });
         yield data;
         const proxima = nextQuery(data, meta, query);
-        // Cursor que não anda é laço infinito disfarçado de paginação.
         if (!proxima ||
             (proxima.cursor !== undefined && proxima.cursor === visto)) {
             return;

package/dist/search.d.ts

@@ -1,21 +1,22 @@
 import type { LexNodeClient } from "./client.js";
 import type { Body, CallOptions, Data, Meta, MetaExtras } from "./types.js";
-/**
- * A busca de processos responde de dois jeitos na MESMA operação: 200 com o
- * resultado pronto, 202 com um trabalho enfileirado. O discriminador é o
- * código HTTP — o corpo do 202 traz `jobId` e nenhum `items`, mas farejar
- * campos é conclusão por ausência, e o status é a afirmação.
- */
 type SearchData = Data<"/v1/processes/search", "post">;
 type SearchMeta = Meta<"/v1/processes/search", "post"> & MetaExtras;
-/** O resultado já pronto, servido dentro da própria chamada. */
+/** O resultado pronto, que a busca devolve com 200. */
 export type ProcessSearchResult = Extract<SearchData, {
     items: unknown;
 }>;
-/** O trabalho enfileirado, a ser acompanhado por `waitForSearchJob`. */
+/**
+ * A busca enfileirada, que a busca devolve com 202; acompanhe-a com
+ * `waitForSearchJob`.
+ */
 export type QueuedSearchJob = Extract<SearchData, {
     jobId: unknown;
 }>;
+/**
+ * O desfecho de `searchProcesses`: `sync` com o resultado em `result`, ou
+ * `async` com a busca enfileirada em `job`.
+ */
 export type ProcessSearchOutcome = {
     kind: "sync";
     result: ProcessSearchResult;
@@ -25,40 +26,73 @@ export type ProcessSearchOutcome = {
     job: QueuedSearchJob;
     meta: SearchMeta;
 };
-/** O trabalho como a consulta de estado o devolve. */
+/** A busca enfileirada, como `GET /v1/search-jobs/{jobId}` a devolve. */
 export type SearchJob = Data<"/v1/search-jobs/{jobId}", "get">;
+/** O estado da busca enfileirada. */
 export type SearchJobState = SearchJob["status"];
+/** As opções de `waitForSearchJob`. */
 export interface WaitForSearchJobOptions {
     /**
-     * Teto de espera, em ms. É EXPLÍCITO de propósito: num ambiente serverless a
-     * espera consome a franquia da função, e um laço sem orçamento gasta a
-     * requisição inteira antes de o trabalho concluir.
+     * O tempo máximo de espera, em ms. Padrão: 45 000. Num ambiente serverless,
+     * escolha um valor que caiba no prazo da sua função.
      */
     budgetMs?: number;
-    /** Primeira espera entre consultas, em ms; dobra até `maxPollIntervalMs`. */
+    /**
+     * A primeira espera entre leituras, em ms. Padrão: 1 500. Dobra a cada
+     * leitura, até `maxPollIntervalMs`.
+     */
     pollIntervalMs?: number;
+    /** A maior espera entre leituras, em ms. Padrão: 8 000. */
     maxPollIntervalMs?: number;
+    /** Cancela a espera; a busca continua na fila. */
     signal?: AbortSignal;
-    /** Chamado a cada leitura de estado, para a UI acompanhar. */
+    /**
+     * Chamada a cada leitura, com o estado e a busca, por exemplo para mostrar
+     * o progresso.
+     */
     onState?: (state: SearchJobState, job: SearchJob) => void;
+    /** O escritório (sub-tenant) das leituras; veja `CallOptions.officeId`. */
     officeId?: string | null;
 }
 /**
- * Busca processos e diz, no tipo, qual dos dois desfechos aconteceu.
+ * Busca processos e diz no tipo se o resultado veio pronto ou se a busca foi
+ * enfileirada.
+ *
+ * `POST /v1/processes/search` responde 200 com o resultado ou 202 com a busca
+ * enfileirada. O desfecho `sync` traz o resultado em `result`; o `async` traz
+ * a busca em `job`, para acompanhar com `waitForSearchJob` ou pelo evento
+ * `SEARCH_JOB_COMPLETED`. Uma busca enfileirada não é um resultado vazio.
+ * Lança `LexNodeError` nas recusas da API.
  *
- * Sem isto, o consumidor lê `data.items` num corpo que só tem `jobId` e chama
- * de "nenhum resultado" o que é "ainda estou buscando".
+ * @example
+ * ```ts
+ * const desfecho = await searchProcesses(lexnode, {
+ *   tribunalAlias: "TJSP",
+ *   number,
+ * });
+ * if (desfecho.kind === "sync") {
+ *   desfecho.result.items;
+ * } else {
+ *   const job = await waitForSearchJob(lexnode, desfecho.job.jobId, {
+ *     budgetMs: 20_000,
+ *   });
+ *   job.status; // "SUCCEEDED" | "FAILED" | "CANCELED"
+ * }
+ * ```
  */
 export declare function searchProcesses(client: LexNodeClient, body: Body<"/v1/processes/search", "post">, opts?: CallOptions): Promise<ProcessSearchOutcome>;
 /**
- * Espera um trabalho de busca chegar ao fim, com recuo e orçamento.
+ * Espera uma busca enfileirada terminar e devolve a busca em `SUCCEEDED`,
+ * `FAILED` ou `CANCELED`.
  *
- * O estouro do orçamento é um erro PRÓPRIO e retentável: o trabalho continua
- * na fila do motor, e quem espera pode voltar a acompanhá-lo depois — ou
- * receber o `SEARCH_JOB_COMPLETED` por webhook e não esperar nada.
+ * Lê a busca de tempos em tempos, com espera crescente entre as leituras.
+ * Lança `LexNodeError` `SEARCH_JOB_BUDGET_EXCEEDED` (retentável) quando
+ * `budgetMs` acaba antes do fim: a busca continua na fila, e você pode voltar
+ * a lê-la depois ou receber o evento `SEARCH_JOB_COMPLETED`. Repassa os erros
+ * das leituras.
  *
- * Não há o que esperar com chave de teste (`lapi_test_`): ela não enfileira
- * trabalho, e a submissão assíncrona responde 403 `SANDBOX_UPSTREAM_DISABLED`.
+ * Com a chave de teste (`lapi_test_`) não há busca a esperar: a busca
+ * assíncrona responde 403 `SANDBOX_UPSTREAM_DISABLED`.
  */
 export declare function waitForSearchJob(client: LexNodeClient, jobId: string, options?: WaitForSearchJobOptions): Promise<SearchJob>;
 export {};

package/dist/search.js

@@ -1,5 +1,4 @@
 import { LexNodeError } from "./errors.js";
-/** Estados em que o trabalho não avança mais. */
 const TERMINAL_STATES = new Set(["SUCCEEDED", "FAILED", "CANCELED"]);
 const DEFAULT_BUDGET_MS = 45_000;
 const DEFAULT_POLL_INTERVAL_MS = 1_500;
@@ -22,12 +21,6 @@ function wait(ms, signal) {
         signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
-/**
- * Busca processos e diz, no tipo, qual dos dois desfechos aconteceu.
- *
- * Sem isto, o consumidor lê `data.items` num corpo que só tem `jobId` e chama
- * de "nenhum resultado" o que é "ainda estou buscando".
- */
 export async function searchProcesses(client, body, opts = {}) {
     const { data, meta } = await client.processes.search(body, opts);
     if (meta.status === 202) {
@@ -35,16 +28,6 @@ export async function searchProcesses(client, body, opts = {}) {
     }
     return { kind: "sync", result: data, meta };
 }
-/**
- * Espera um trabalho de busca chegar ao fim, com recuo e orçamento.
- *
- * O estouro do orçamento é um erro PRÓPRIO e retentável: o trabalho continua
- * na fila do motor, e quem espera pode voltar a acompanhá-lo depois — ou
- * receber o `SEARCH_JOB_COMPLETED` por webhook e não esperar nada.
- *
- * Não há o que esperar com chave de teste (`lapi_test_`): ela não enfileira
- * trabalho, e a submissão assíncrona responde 403 `SANDBOX_UPSTREAM_DISABLED`.
- */
 export async function waitForSearchJob(client, jobId, options = {}) {
     const budgetMs = options.budgetMs ?? DEFAULT_BUDGET_MS;
     const maxIntervalMs = options.maxPollIntervalMs ?? DEFAULT_MAX_POLL_INTERVAL_MS;