@lexnode/legal-data-sdk 1.28.0 → 1.30.0

package/README.md

@@ -495,6 +495,39 @@ em segundo plano em vez de virar erro:
 - 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.
 
+Para uma integração que precisa continuar mesmo quando a fonte demora, use
+`readProcessWithRecovery`. A aceitação da cópia antiga é explícita; a espera
+total é limitada. O fim da espera devolve `pending`, com a mesma consulta e
+a próxima leitura útil, sem cancelar nem abrir outra compra:
+
+```ts
+import { readProcessWithRecovery } from "@lexnode/legal-data-sdk";
+
+const leitura = await readProcessWithRecovery(lexnode, {
+  tribunalAlias: "api_publica_tjsp",
+  processNumber: numeroDoProcesso,
+  view: "PROCESS",
+  waitSeconds: 5,
+  staleOnFailure: true, // aceita cópia anterior à falha: confira sourceFetchedAt
+}, { completionBudgetMs: 30_000 });
+
+if (leitura.kind === "ready") {
+  usarProcesso(leitura.data, leitura.meta.sourceFetchedAt);
+} else if (leitura.kind === "pending") {
+  guardarConsulta(leitura.lookup.lookupId, leitura.nextReadAt);
+  // leitura.stale, quando presente, conserva a data da cópia.
+  // Continue pelo pollUrl ou pelo webhook PROCESS_LOOKUP_COMPLETED.
+} else {
+  registrarDesfecho(leitura.kind, leitura.lookup.error);
+  // failed, canceled ou expired; nenhum deles afirma que o processo não existe.
+}
+```
+
+Sem `completionBudgetMs`, o helper entrega o 200 ou o 202 imediatamente após
+a abertura. O orçamento adicional cobre somente o acompanhamento: cada chamada
+mantém seu próprio timeout. Abortar a espera local não cancela a consulta no motor.
+O custo, o gate de confidencialidade e a cobrança única são os do endpoint existente.
+
 `lookupProcess` diz, no tipo, qual dos dois desfechos aconteceu, e
 `waitForProcessLookup` espera a consulta terminar:
 

package/dist/index.d.ts

@@ -18,8 +18,8 @@ export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, LEXNODE_WEBHOOK_HEADERS, WEBHOOK_EVE
 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 { lookupProcess, waitForProcessLookup, readProcessWithRecovery, } from "./lookup.js";
+export type { ProcessLookup, ProcessLookupInput, ProcessLookupOutcome, ProcessLookupRead, ProcessLookupState, ProcessLookupView, ProcessRecoveryOutcome, 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,7 +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 { lookupProcess, waitForProcessLookup, readProcessWithRecovery, } 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

@@ -54,7 +54,7 @@ export interface WaitForProcessLookupOptions {
     budgetMs?: number;
     signal?: AbortSignal;
     /** Chamado a cada leitura da consulta, para a UI acompanhar. */
-    onState?: (state: ProcessLookupState, lookup: ProcessLookup) => void;
+    onState?: (state: ProcessLookupState, lookup: ProcessLookup, meta: Meta<"/v1/processes/lookups/{lookupId}", "get"> & MetaExtras) => void;
     officeId?: string | null;
 }
 /**
@@ -76,4 +76,31 @@ export interface WaitForProcessLookupOptions {
  * com `error`; ou `CANCELED`.
  */
 export declare function waitForProcessLookup(client: LexNodeClient, lookupId: string, options?: WaitForProcessLookupOptions): Promise<ProcessLookup>;
+type ProcessRecoveryMeta = CreateMeta | (Meta<"/v1/processes/lookups/{lookupId}", "get"> & MetaExtras);
+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;
+};
+/**
+ * Abre uma consulta recuperável e acompanha somente dentro do orçamento.
+ * A aceitação de cópia antiga é explícita. Ao esgotar a espera, devolve a
+ * consulta pendente, sem novo POST nem cancelamento do trabalho no motor.
+ */
+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

@@ -115,7 +115,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 +124,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 +156,69 @@ export async function waitForProcessLookup(client, lookupId, options = {}) {
         options.signal?.removeEventListener("abort", onCallerAbort);
     }
 }
+/**
+ * Abre uma consulta recuperável e acompanha somente dentro do orçamento.
+ * A aceitação de cópia antiga é explícita. Ao esgotar a espera, devolve a
+ * consulta pendente, sem novo POST nem cancelamento do trabalho no motor.
+ */
+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/package.json

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

package/schema.d.ts

@@ -641,7 +641,7 @@ export interface paths {
         };
         /**
          * Consultar a cobertura do corpus indexado
-         * @description Cobertura agregada do corpus de jurisprudência indexado localmente: documentos indexáveis por fonte × tribunal × mês (a mesma agregação congelada no snapshot de cobertura de cada busca textual), combinada com o estado das fatias de colheita do diário oficial — grupo com fatia pendente reporta `PARTIAL` (o conjunto indexado ainda pode crescer), grupo totalmente colhido/indexado reporta `INDEXED`, e `NONE` significa nada indexado nem colheita solicitada. Inclui totais por fonte com as datas da publicação indexada mais antiga e mais recente, e a cobertura por matéria em `areas` — cada área do direito com estado, contagens e tribunais indexados, inclusive as matérias fora do acervo (`covered: false`), para que resultado vazio nunca se confunda com matéria não coberta. As fontes são reportadas separadamente — um corpus estruturado espelhado do tribunal e menções no diário oficial são ativos diferentes. Leitura local, zero créditos.
+         * @description Cobertura agregada do corpus de jurisprudência indexado localmente: documentos indexáveis por fonte × tribunal × mês (a mesma agregação que cada busca textual congela no snapshot de cobertura — lá marcado `UNAVAILABLE`, sem grupos, quando ela não coube no prazo da busca), combinada com o estado das fatias de colheita do diário oficial — grupo com fatia pendente reporta `PARTIAL` (o conjunto indexado ainda pode crescer), grupo totalmente colhido/indexado reporta `INDEXED`, e `NONE` significa nada indexado nem colheita solicitada. Inclui totais por fonte com as datas da publicação indexada mais antiga e mais recente, e a cobertura por matéria em `areas` — cada área do direito com estado, contagens e tribunais indexados, inclusive as matérias fora do acervo (`covered: false`), para que resultado vazio nunca se confunda com matéria não coberta. As fontes são reportadas separadamente — um corpus estruturado espelhado do tribunal e menções no diário oficial são ativos diferentes. Leitura local, zero créditos.
          *
          *     **Escopo exigido na chave de API:** `PUBLICATIONS_READ`
          */
@@ -11136,10 +11136,10 @@ export interface operations {
                             }[];
                             coverage: {
                                 /**
-                                 * @description NONE = nada indexado nem colheita registrada; PARTIAL = há fatia de colheita pendente (o indexado pode crescer); INDEXED = há documento pesquisável indexado e nenhuma colheita pendente.
+                                 * @description NONE = nada indexado nem colheita registrada; PARTIAL = há fatia de colheita pendente (o indexado pode crescer); INDEXED = há documento pesquisável indexado e nenhuma colheita pendente. UNAVAILABLE = a cobertura do recorte não coube no prazo da busca: `byTribunalMonth` vem vazio, o ranking vem inteiro e a busca custa o preço de sempre. O valor congelado não muda depois; a cobertura do mesmo recorte sai em GET /v1/publications/corpus/coverage, a 0 crédito, com os tribunais da busca num só `tribunalCodes`, separados por vírgula (`tribunalCodes=STJ,TJSP`), e a janela dela em `from` e `to`.
                                  * @enum {string}
                                  */
-                                overallState: "NONE" | "PARTIAL" | "INDEXED";
+                                overallState: "NONE" | "PARTIAL" | "INDEXED" | "UNAVAILABLE";
                                 byTribunalMonth: {
                                     source?: string;
                                     tribunalSigla: string;
@@ -11396,10 +11396,10 @@ export interface operations {
                             corpusWatermark: string | null;
                             coverage: {
                                 /**
-                                 * @description NONE = nada indexado nem colheita registrada; PARTIAL = há fatia de colheita pendente (o indexado pode crescer); INDEXED = há documento pesquisável indexado e nenhuma colheita pendente.
+                                 * @description NONE = nada indexado nem colheita registrada; PARTIAL = há fatia de colheita pendente (o indexado pode crescer); INDEXED = há documento pesquisável indexado e nenhuma colheita pendente. UNAVAILABLE = a cobertura do recorte não coube no prazo da busca: `byTribunalMonth` vem vazio, o ranking vem inteiro e a busca custa o preço de sempre. O valor congelado não muda depois; a cobertura do mesmo recorte sai em GET /v1/publications/corpus/coverage, a 0 crédito, com os tribunais da busca num só `tribunalCodes`, separados por vírgula (`tribunalCodes=STJ,TJSP`), e a janela dela em `from` e `to`.
                                  * @enum {string}
                                  */
-                                overallState: "NONE" | "PARTIAL" | "INDEXED";
+                                overallState: "NONE" | "PARTIAL" | "INDEXED" | "UNAVAILABLE";
                                 byTribunalMonth: {
                                     source?: string;
                                     tribunalSigla: string;
@@ -11723,6 +11723,7 @@ export interface operations {
     getPublicationCorpusCoverage: {
         parameters: {
             query?: {
+                /** @description Tribunais do recorte num só valor, separados por vírgula (`tribunalCodes=STJ,TJSP`), pela sigla ou pelo apelido da fonte. Sem ele, a cobertura é a de todos os tribunais do acervo. */
                 tribunalCodes?: string;
                 from?: string;
                 to?: string;