@lexnode/legal-data-sdk 1.0.0 → 1.24.0

package/dist/errors.js

@@ -0,0 +1,217 @@
+/**
+ * Os códigos de recusa que o contrato declara, mais os que este cliente cunha
+ * para falhas locais.
+ *
+ * Existe para o `switch` do consumidor ter autocompletar e para o erro de
+ * digitação virar erro de compilação: o motor responde 404 tanto para
+ * `PROCESS_NOT_FOUND` quanto para `MOVEMENTS_NOT_AVAILABLE`, e quem distingue
+ * os dois por literal redigitado descobre o engano em produção. A lista é
+ * fechada para o que se conhece e aberta para o que vier (ver `LexNodeError`).
+ */
+export const LEXNODE_ERROR_CODES = [
+    "INVALID_MONITOR",
+    "TRIBUNAL_NOT_SUPPORTED",
+    "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",
+    // Fora da tabela pública, mas na porta do tenant: a credencial recusada pela
+    // própria conta, e o alvo nomeado que não existe (ou já existe).
+    "ACCOUNT_SUSPENDED",
+    "ENTITLEMENT_EXPIRED",
+    "PROJECT_DISABLED",
+    "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",
+    // Cunhados aqui: nunca vêm do motor.
+    "CLIENT_TIMEOUT",
+    "CLIENT_NETWORK_ERROR",
+    "CLIENT_INVALID_REQUEST",
+    "CLIENT_MISSING_PATH_PARAM",
+    "INVALID_RESPONSE",
+    "SEARCH_JOB_BUDGET_EXCEEDED",
+    "PAGINATION_LIMIT_REACHED",
+];
+const RAW_MESSAGE_MAX_CHARS = 500;
+function truncate(value) {
+    return value.length <= RAW_MESSAGE_MAX_CHARS
+        ? value
+        : `${value.slice(0, RAW_MESSAGE_MAX_CHARS - 3)}...`;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function readFieldErrors(details) {
+    const bag = asRecord(details?.fieldErrors);
+    if (!bag)
+        return null;
+    const out = {};
+    for (const [field, messages] of Object.entries(bag)) {
+        if (Array.isArray(messages)) {
+            out[field] = messages.map((entry) => String(entry));
+        }
+    }
+    return out;
+}
+/**
+ * Toda falha que o cliente produz — do motor, da rede ou do prazo — chega como
+ * esta classe.
+ *
+ * Um único tipo para o `catch` do consumidor: ele decide por `retryable` e
+ * `code`, não por farejar a forma do que caiu. `requestId` vem junto porque é
+ * o que o suporte pede; perdê-lo transforma um incidente rastreável num relato.
+ */
+export class LexNodeError extends Error {
+    name = "LexNodeError";
+    /** O código do contrato (`RATE_LIMITED`, `PROCESS_NOT_FOUND`, …). */
+    code;
+    /** Status HTTP da recusa — ou o que o cliente atribuiu à falha local. */
+    status;
+    class;
+    retryable;
+    /** Status real da fonte a montante, quando o motor o preservou. */
+    upstreamStatus;
+    requestId;
+    /** Erros por campo de uma recusa de validação. */
+    fieldErrors;
+    details;
+    retryAfterSeconds;
+    rateLimit;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? {} : { cause: init.cause });
+        this.code = init.code;
+        this.status = init.status;
+        this.class = init.errorClass;
+        this.retryable = init.retryable;
+        this.upstreamStatus = init.upstreamStatus ?? null;
+        this.requestId = init.requestId ?? null;
+        this.fieldErrors = init.fieldErrors ?? null;
+        this.details = init.details ?? null;
+        this.retryAfterSeconds = init.retryAfterSeconds ?? null;
+        this.rateLimit = init.rateLimit ?? null;
+    }
+    /**
+     * A recusa como o motor a descreveu. A classe e o `retryable` saem do corpo
+     * quando ele os traz; o status é o da resposta, que é o que de fato chegou.
+     */
+    static fromEnvelope(envelope, status, rateLimit) {
+        const body = asRecord(envelope);
+        const error = asRecord(body?.error);
+        if (!error || typeof error.code !== "string")
+            return null;
+        const details = asRecord(error.details);
+        const retryAfter = details?.retryAfterSeconds;
+        return new LexNodeError({
+            code: error.code,
+            message: typeof error.message === "string" && error.message
+                ? error.message
+                : `A API respondeu ${status}.`,
+            status,
+            errorClass: error.class === "RETRYABLE" ? "RETRYABLE" : "TERMINAL",
+            retryable: typeof error.retryable === "boolean"
+                ? error.retryable
+                : error.class === "RETRYABLE",
+            requestId: typeof error.requestId === "string" ? error.requestId : null,
+            upstreamStatus: typeof error.upstreamStatus === "number" ? error.upstreamStatus : null,
+            fieldErrors: readFieldErrors(details),
+            details,
+            retryAfterSeconds: typeof retryAfter === "number"
+                ? retryAfter
+                : (rateLimit?.retryAfterSeconds ?? null),
+            rateLimit,
+        });
+    }
+    /** Prazo esgotado antes de a resposta chegar: nada foi decidido, repetir cabe. */
+    static timeout(timeoutMs, cause) {
+        return new LexNodeError({
+            code: "CLIENT_TIMEOUT",
+            message: `A API não respondeu em ${timeoutMs} ms.`,
+            status: 504,
+            errorClass: "RETRYABLE",
+            retryable: true,
+            cause,
+        });
+    }
+    /** A requisição não alcançou o motor: DNS, conexão, TLS, socket derrubado. */
+    static network(cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        return new LexNodeError({
+            code: "CLIENT_NETWORK_ERROR",
+            message: `Não foi possível alcançar a API: ${truncate(detail)}`,
+            status: 502,
+            errorClass: "RETRYABLE",
+            retryable: true,
+            cause,
+        });
+    }
+    /**
+     * Respondeu, mas não no envelope do contrato — proxy, página de erro, HTML.
+     *
+     * 502 porque o que quebrou está no caminho, não no pedido; o status real
+     * sobrevive em `upstreamStatus`, e a mensagem carrega o corpo cru truncado,
+     * que é a única pista de quem respondeu.
+     */
+    static invalidResponse(status, raw, rateLimit) {
+        return new LexNodeError({
+            code: "INVALID_RESPONSE",
+            message: `Resposta fora do envelope da API (HTTP ${status}): ${truncate(raw)}`,
+            status: 502,
+            errorClass: "RETRYABLE",
+            retryable: true,
+            upstreamStatus: status,
+            // O 429 de uma borda ou de um proxy não vem no envelope, mas traz o
+            // `Retry-After` do mesmo jeito — e é por este campo que o recuo decide.
+            retryAfterSeconds: rateLimit?.retryAfterSeconds ?? null,
+            rateLimit,
+        });
+    }
+    /**
+     * O pedido não chegou a sair: cabeçalho que o `fetch` recusa montar, corpo
+     * que não serializa.
+     *
+     * TERMINAL de propósito. Repetir o que o transporte barrou antes de abrir o
+     * socket não tem como dar certo, e classificá-lo como falha de rede manda o
+     * consumidor gastar as tentativas num defeito do próprio código.
+     */
+    static invalidRequest(message, cause) {
+        return new LexNodeError({
+            code: "CLIENT_INVALID_REQUEST",
+            message,
+            status: 400,
+            errorClass: "TERMINAL",
+            retryable: false,
+            cause,
+        });
+    }
+}
+/** Guarda de tipo para o `catch`, sem depender do `instanceof` cruzar realms. */
+export function isLexNodeError(value) {
+    return (value instanceof LexNodeError ||
+        (value instanceof Error && value.name === "LexNodeError"));
+}

package/dist/freshness.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Até onde a fonte foi lida — o que qualifica um resultado vazio.
+ *
+ * Um `total: 0` sozinho não distingue "não existe" de "a fonte ainda não
+ * indexou". Quem confunde os dois diz ao usuário que o processo não existe e
+ * repete a busca, pagando de novo por uma resposta que não pode mudar. O motor
+ * publica a data-limite do índice em dois eixos — `updatedThrough` na busca de
+ * processo, `lastEditionDate` na leitura do diário — e este módulo é a leitura
+ * dos dois pelo mesmo nome.
+ */
+export type FreshnessAxis = "PROCESS" | "PUBLICATION";
+export type FreshnessState = 
+/** A fonte declarou até quando leu. */
+"KNOWN"
+/** A fonte não respondeu à sondagem, ou a resposta não traz o campo. */
+ | "INDETERMINATE";
+export interface Freshness {
+    state: FreshnessState;
+    axis: FreshnessAxis | null;
+    /** A data-limite do índice da fonte, quando declarada. */
+    readThrough: Date | null;
+    /** Quando a resposta montou essa data-limite. */
+    checkedAt: Date | null;
+    tribunalAlias: string | null;
+}
+/** O retrato completo do frescor de uma resposta. */
+export declare function freshnessOf(result: unknown): Freshness;
+/** A data-limite do índice da fonte, ou `null` quando ela não a declarou. */
+export declare function readThrough(result: unknown): Date | null;
+export interface NotYetIndexedOptions {
+    /**
+     * A data a partir da qual o alvo existiria — a distribuição do processo, o
+     * dia da publicação. Com ela, a resposta deixa de ser um palpite: a fonte
+     * lida só até antes dessa data não pode ter visto o alvo.
+     */
+    since?: Date | string;
+}
+/**
+ * Se o vazio desta resposta NÃO prova ausência.
+ *
+ * Verdadeiro quando a fonte não declarou até onde leu (o estado indeterminado
+ * — ausência de campo é estado, nunca erro) ou quando ela leu até antes de
+ * `since`. Falso quando há resultado, e falso quando a fonte declarou uma
+ * data-limite que cobre o que se perguntou: aí o vazio é resposta.
+ */
+export declare function isNotYetIndexed(result: unknown, options?: NotYetIndexedOptions): boolean;
+/** Uma frase em pt-BR sobre o alcance da fonte, pronta para a tela. */
+export declare function describeFreshness(result: unknown): string;

package/dist/freshness.js

@@ -0,0 +1,105 @@
+/**
+ * Até onde a fonte foi lida — o que qualifica um resultado vazio.
+ *
+ * Um `total: 0` sozinho não distingue "não existe" de "a fonte ainda não
+ * indexou". Quem confunde os dois diz ao usuário que o processo não existe e
+ * repete a busca, pagando de novo por uma resposta que não pode mudar. O motor
+ * publica a data-limite do índice em dois eixos — `updatedThrough` na busca de
+ * processo, `lastEditionDate` na leitura do diário — e este módulo é a leitura
+ * dos dois pelo mesmo nome.
+ */
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Aceita o envelope inteiro ou só o `data` — o consumidor tem os dois à mão. */
+function payloadOf(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    return asRecord(record.data) ?? record;
+}
+function toDate(value) {
+    if (typeof value !== "string" || !value)
+        return null;
+    // A data do diário vem como AAAA-MM-DD; lê-la sem fuso a jogaria para o dia
+    // anterior em qualquer máquina a oeste de Greenwich.
+    const iso = /^\d{4}-\d{2}-\d{2}$/u.test(value)
+        ? `${value}T00:00:00.000Z`
+        : value;
+    const parsed = new Date(iso);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+/** O retrato completo do frescor de uma resposta. */
+export function freshnessOf(result) {
+    const payload = payloadOf(result);
+    const sourceIndex = asRecord(payload?.sourceIndex);
+    if (!sourceIndex) {
+        return {
+            state: "INDETERMINATE",
+            axis: null,
+            readThrough: null,
+            checkedAt: null,
+            tribunalAlias: null,
+        };
+    }
+    const axis = "lastEditionDate" in sourceIndex ? "PUBLICATION" : "PROCESS";
+    const limite = toDate(axis === "PUBLICATION"
+        ? sourceIndex.lastEditionDate
+        : sourceIndex.updatedThrough);
+    return {
+        state: limite ? "KNOWN" : "INDETERMINATE",
+        axis,
+        readThrough: limite,
+        checkedAt: toDate(sourceIndex.checkedAt),
+        tribunalAlias: typeof sourceIndex.tribunalAlias === "string"
+            ? sourceIndex.tribunalAlias
+            : null,
+    };
+}
+/** A data-limite do índice da fonte, ou `null` quando ela não a declarou. */
+export function readThrough(result) {
+    return freshnessOf(result).readThrough;
+}
+function hasResults(payload) {
+    if (!payload)
+        return false;
+    if (Array.isArray(payload.items) && payload.items.length > 0)
+        return true;
+    return typeof payload.total === "number" && payload.total > 0;
+}
+/**
+ * Se o vazio desta resposta NÃO prova ausência.
+ *
+ * Verdadeiro quando a fonte não declarou até onde leu (o estado indeterminado
+ * — ausência de campo é estado, nunca erro) ou quando ela leu até antes de
+ * `since`. Falso quando há resultado, e falso quando a fonte declarou uma
+ * data-limite que cobre o que se perguntou: aí o vazio é resposta.
+ */
+export function isNotYetIndexed(result, options = {}) {
+    const payload = payloadOf(result);
+    if (hasResults(payload))
+        return false;
+    const { readThrough: limite } = freshnessOf(result);
+    if (!limite)
+        return true;
+    const since = typeof options.since === "string"
+        ? toDate(options.since)
+        : (options.since ?? null);
+    if (!since)
+        return false;
+    return limite.getTime() < since.getTime();
+}
+function ddmmaaaa(date) {
+    const dia = String(date.getUTCDate()).padStart(2, "0");
+    const mes = String(date.getUTCMonth() + 1).padStart(2, "0");
+    return `${dia}/${mes}/${date.getUTCFullYear()}`;
+}
+/** Uma frase em pt-BR sobre o alcance da fonte, pronta para a tela. */
+export function describeFreshness(result) {
+    const { readThrough: limite } = freshnessOf(result);
+    return limite
+        ? `fonte lida até ${ddmmaaaa(limite)}`
+        : "fonte sem data-limite conhecida";
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cliente de runtime e tipos do contrato do motor de dados jurídicos.
+ *
+ * **Servidor apenas.** A credencial é uma chave de CONTA: no browser ela está
+ * publicada. Um app com usuários finais fala com o próprio backend, e é o
+ * backend que fala com o motor, atribuindo cada chamada ao seu sub-tenant por
+ * `X-Office-Id`.
+ *
+ * Sem dependências de runtime: `fetch` global e `node:crypto`, Node >= 20.
+ */
+export type * from "../schema.js";
+export { createLexNodeClient } from "./client.js";
+export type { LexNodeClient, LexNodeClientOptions } from "./client.js";
+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 { paginate } from "./paginate.js";
+export type { PaginateOptions } from "./paginate.js";
+export { searchProcesses, waitForSearchJob } from "./search.js";
+export type { ProcessSearchOutcome, ProcessSearchResult, QueuedSearchJob, SearchJob, SearchJobState, WaitForSearchJobOptions, } from "./search.js";
+export { describeFreshness, freshnessOf, isNotYetIndexed, readThrough, } from "./freshness.js";
+export type { Freshness, FreshnessAxis, FreshnessState, NotYetIndexedOptions, } from "./freshness.js";
+export { isFirstAppearance, resubscribeOnFirstAppearance, unwatchProcess, watchProcess, } from "./watch.js";
+export type { FirstAppearanceEvent, ResubscribeSubscriber, UnwatchProcessInput, WatchProcessInput, WatchProcessResult, } from "./watch.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * Cliente de runtime e tipos do contrato do motor de dados jurídicos.
+ *
+ * **Servidor apenas.** A credencial é uma chave de CONTA: no browser ela está
+ * publicada. Um app com usuários finais fala com o próprio backend, e é o
+ * backend que fala com o motor, atribuindo cada chamada ao seu sub-tenant por
+ * `X-Office-Id`.
+ *
+ * Sem dependências de runtime: `fetch` global e `node:crypto`, Node >= 20.
+ */
+export { createLexNodeClient } from "./client.js";
+export { LEXNODE_ERROR_CODES, LexNodeError, isLexNodeError } from "./errors.js";
+export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, LEXNODE_WEBHOOK_HEADERS, WEBHOOK_EVENT_TYPES, WEBHOOK_TEST_EVENT_TYPE, isKnownWebhookEventType, isReceiverFault, isWebhookTest, parseWebhookEvent, verifyWebhookSignature, webhookRejectionStatus, } from "./webhooks.js";
+export { paginate } from "./paginate.js";
+export { searchProcesses, waitForSearchJob } from "./search.js";
+export { describeFreshness, freshnessOf, isNotYetIndexed, readThrough, } from "./freshness.js";
+export { isFirstAppearance, resubscribeOnFirstAppearance, unwatchProcess, watchProcess, } from "./watch.js";

package/dist/paginate.d.ts

@@ -0,0 +1,21 @@
+import type { paths } from "../schema.js";
+import type { LexNodeClient } from "./client.js";
+import type { Data, MethodOf, RequestArgs } from "./types.js";
+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.
+     */
+    maxPages?: number;
+}
+/**
+ * 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 declare function paginate<P extends keyof paths, M extends MethodOf<P>>(client: LexNodeClient, path: P, method: M, args: RequestArgs<P, M>, options?: PaginateOptions): AsyncGenerator<Data<P, M>, void, undefined>;

package/dist/paginate.js

@@ -0,0 +1,106 @@
+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)
+        ? value
+        : null;
+}
+function readCursor(bag) {
+    const cursor = bag?.nextCursor;
+    return typeof cursor === "string" && cursor ? cursor : null;
+}
+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);
+    if (cursor)
+        return { ...query, cursor };
+    const total = readNumber(payload, "total");
+    if (total === null)
+        return null;
+    const pageSize = readNumber(payload, "pageSize");
+    const atual = readNumber(payload, "page");
+    if (pageSize !== null && atual !== null) {
+        return atual * pageSize >= total
+            ? null
+            : { ...query, page: atual + 1, pageSize };
+    }
+    if (typeof query.offset === "number" || typeof query.limit === "number") {
+        const lidos = pageLength(data, payload);
+        const offset = typeof query.offset === "number" ? query.offset : 0;
+        const percorrido = offset + lidos;
+        return lidos === 0 || percorrido >= total
+            ? null
+            : { ...query, offset: percorrido };
+    }
+    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 = {
+        ...(args.params
+            ?.query ?? {}),
+    };
+    let visto = null;
+    for (let pagina = 1; pagina <= maxPages; pagina += 1) {
+        const { data, meta } = await client.request(path, method, {
+            ...args,
+            params: { ...args.params, query },
+        });
+        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;
+        }
+        visto = proxima.cursor;
+        query = proxima;
+    }
+    throw new LexNodeError({
+        code: "PAGINATION_LIMIT_REACHED",
+        message: `A paginação de ${String(path)} passou de ${maxPages} páginas; aumente maxPages ou recorte a consulta.`,
+        status: 400,
+        errorClass: "TERMINAL",
+        retryable: false,
+        details: { path: String(path), maxPages },
+    });
+}

package/dist/search.d.ts

@@ -0,0 +1,64 @@
+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. */
+export type ProcessSearchResult = Extract<SearchData, {
+    items: unknown;
+}>;
+/** O trabalho enfileirado, a ser acompanhado por `waitForSearchJob`. */
+export type QueuedSearchJob = Extract<SearchData, {
+    jobId: unknown;
+}>;
+export type ProcessSearchOutcome = {
+    kind: "sync";
+    result: ProcessSearchResult;
+    meta: SearchMeta;
+} | {
+    kind: "async";
+    job: QueuedSearchJob;
+    meta: SearchMeta;
+};
+/** O trabalho como a consulta de estado o devolve. */
+export type SearchJob = Data<"/v1/search-jobs/{jobId}", "get">;
+export type SearchJobState = SearchJob["status"];
+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.
+     */
+    budgetMs?: number;
+    /** Primeira espera entre consultas, em ms; dobra até `maxPollIntervalMs`. */
+    pollIntervalMs?: number;
+    maxPollIntervalMs?: number;
+    signal?: AbortSignal;
+    /** Chamado a cada leitura de estado, para a UI acompanhar. */
+    onState?: (state: SearchJobState, job: SearchJob) => void;
+    officeId?: string | null;
+}
+/**
+ * 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 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.
+ *
+ * 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 declare function waitForSearchJob(client: LexNodeClient, jobId: string, options?: WaitForSearchJobOptions): Promise<SearchJob>;
+export {};