@lexnode/legal-data-sdk 1.26.0 → 1.28.0

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

@@ -83,6 +83,19 @@ export interface ProcessSourceIndex {
     updatedThrough: string | null;
     checkedAt: string;
 }
+/** Quantos movimentos novos de um grau a captura anunciou. */
+export interface ProcessMovementInstanceCount {
+    /** A sigla do grau (G1, G2, JE, TR…); nula quando a fonte não a declara. */
+    degree: string | null;
+    newMovementCount: number;
+    /** A chave do movimento novo mais recente deste grau. */
+    latestMovementKey: string;
+}
+/**
+ * Um aviso por assinante e por captura do processo, descrito pelo movimento
+ * novo mais recente: o topo do payload é dele, e a chave dele é
+ * `latestMovementKey`.
+ */
 export interface ProcessMovementCreatedPayload {
     canonicalProcessId: string;
     tribunalAlias: string;
@@ -99,12 +112,82 @@ export interface ProcessMovementCreatedPayload {
      */
     latestMovementCode?: number | null;
     latestMovementLabel?: string | null;
+    /**
+     * O grau do movimento mais recente e o documento da fonte que o trouxe — o
+     * `sourceId` da instância na leitura do processo. Ausentes quando o processo
+     * não é compartilhável.
+     */
+    degree?: string | null;
+    instanceSourceId?: string | null;
+    /**
+     * Quantos movimentos novos vieram de cada grau nesta captura, o grau do mais
+     * recente primeiro. Ausente quando o processo não é compartilhável.
+     */
+    instances?: ProcessMovementInstanceCount[];
     /**
      * Presente quando o processo não é compartilhável: o aviso diz que ele andou
-     * e não diz o quê, porque ali o nome do ato é teor.
+     * e não diz o quê nem em que grau, porque ali o nome do ato é teor.
      */
     contentWithheld?: true;
 }
+/**
+ * Outro grau de um processo assinado apareceu na fonte (1º grau, 2º grau,
+ * turma recursal…). O histórico dele entrou no acervo sem virar
+ * `PROCESS_MOVEMENT_CREATED` movimento a movimento: este aviso é o que diz que
+ * ele chegou, e os movimentos estão no retrato do processo, em `instances`.
+ */
+export interface ProcessInstanceDiscoveredPayload {
+    canonicalProcessId: string;
+    tribunalAlias: string;
+    processNumber: string;
+    /** O ponteiro que o consumidor informou ao assinar o processo. */
+    externalRef: string | null;
+    /** A sigla do grau novo; nula quando a fonte não a declara. */
+    degree: string | null;
+    /** O documento da fonte deste grau — o `sourceId` dele em `instances`. */
+    instanceSourceId: string;
+    courtBody: string | null;
+    /** Quantos movimentos o grau trouxe na captura que o descobriu. */
+    movementCount: number;
+    /** Quantos deles entraram no acervo sem aviso próprio. */
+    historyMovementCount: number;
+    /**
+     * Quantos deles saíram também em `PROCESS_MOVEMENT_CREATED`: os datados
+     * depois da primeira captura do número.
+     */
+    announcedMovementCount: number;
+    /** O movimento mais recente do grau novo. */
+    latestMovementAt: string | null;
+    latestMovementCode: number | null;
+    latestMovementLabel: string | null;
+    contentWithheld?: never;
+}
+/**
+ * O mesmo aviso sobre processo não compartilhável: diz que o número ganhou um
+ * grau e não diz qual, nem o órgão, nem quantos movimentos.
+ */
+export interface ProcessInstanceDiscoveredWithheldPayload {
+    canonicalProcessId: string;
+    tribunalAlias: string;
+    processNumber: string;
+    externalRef: string | null;
+    contentWithheld: true;
+}
+/** Um grau do número como a varredura da vigília de processo o deixou. */
+export interface MonitorSyncInstance {
+    degree: string | null;
+    /** O documento da fonte deste grau — o `sourceId` dele em `instances`. */
+    instanceSourceId: string;
+    /** A instância que o topo da leitura do processo serve. */
+    primary: boolean;
+    courtBody: string | null;
+    sourceUpdatedAt: string | null;
+    latestMovementAt: string | null;
+    /** Nulo quando os movimentos deste grau nunca foram capturados. */
+    movementCount: number | null;
+    /** Desde quando a resposta completa da fonte vem sem este documento. */
+    absentSince: string | null;
+}
 export interface PublicationCreatedPayload {
     monitorId: string;
     officeId: string | null;
@@ -151,6 +234,21 @@ export interface MonitorSyncSucceededPayload {
     snapshotHash?: string;
     sourceUpdatedAt?: string | null;
     latestMovementAt?: string | null;
+    /**
+     * Vigília de processo: os graus do número e os que esta passada reconheceu
+     * como novos. Só quando o controle de confidencialidade deixa o dono do
+     * monitor ler o número inteiro.
+     */
+    instances?: MonitorSyncInstance[];
+    instancesDiscovered?: MonitorSyncInstance[];
+    /**
+     * Vigília de processo cujo número corre em segredo num grau que o dono do
+     * monitor não buscou: a passada sai sem o hash e sem as datas da fonte, e
+     * `changed` fica `false`. O dono que buscou o grau em segredo, numa conta
+     * que não aceita a proveniência, recebe a passada com `changed`, o hash e as
+     * datas, e sem `instances`.
+     */
+    contentWithheld?: true;
     /** O alvo que a fonte não indexava passou a existir nesta passada. */
     firstAppearance?: true;
     /** A vigília de aparição segue esperando o alvo entrar no índice. */
@@ -225,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;
@@ -280,8 +420,8 @@ type Typed<T extends string, P> = WebhookEventEnvelope & {
     type: T;
     payload: P;
 };
-/** Os dez tipos do catálogo, discriminados por `type`. */
-export type WebhookEvent = Typed<"PROCESS_MOVEMENT_CREATED", ProcessMovementCreatedPayload> | 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>;
+/** 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<"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.
  *
@@ -304,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", "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

@@ -117,12 +117,14 @@ export const WEBHOOK_TEST_EVENT_TYPE = "WEBHOOK_TEST";
 /** Os tipos que se pode ASSINAR ao cadastrar um endpoint. */
 export const WEBHOOK_EVENT_TYPES = [
     "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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexnode/legal-data-sdk",
-  "version": "1.26.0",
+  "version": "1.28.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",