@lexnode/legal-data-sdk 1.30.0 → 1.31.0

package/dist/types.d.ts

@@ -1,29 +1,15 @@
 import type { paths } from "../schema.js";
-/**
- * A ponte entre o documento OpenAPI gerado e as assinaturas do cliente.
- *
- * Tudo aqui deriva de `paths`: nenhuma forma de requisição ou de resposta é
- * redigitada. Quando o contrato ganha rota, campo ou código de resposta, o
- * cliente acompanha sem edição — e uma chamada que deixou de casar o contrato
- * falha no compilador do consumidor, não em produção.
- */
-/** O objeto vazio, escrito sem a sintaxe que a regra de tipo-vazio recusa. */
+/** Um objeto sem campos. */
 type Empty = {
     [K in never]: never;
 };
-/** Os métodos que a superfície `/v1` usa. */
+/** Os métodos HTTP das rotas `/v1`. */
 export type HttpMethod = "get" | "post" | "patch" | "delete";
-/**
- * Os métodos que uma rota de fato aceita.
- *
- * O gerador declara os métodos ausentes como `put?: never`, então filtrar por
- * `keyof` sozinho ofereceria `put` em toda rota; o que separa os dois é o tipo
- * do valor.
- */
+/** Os métodos HTTP que a rota `P` aceita no contrato. */
 export type MethodOf<P extends keyof paths> = {
     [M in Extract<keyof paths[P], HttpMethod>]: paths[P][M] extends undefined ? never : M;
 }[Extract<keyof paths[P], HttpMethod>];
-/** A operação de uma rota + método, já sem o `undefined` do método ausente. */
+/** A operação do contrato para a rota `P` e o método `M`. */
 export type Operation<P extends keyof paths, M extends MethodOf<P>> = M extends keyof paths[P] ? NonNullable<paths[P][M]> : never;
 type PathParamsOf<O> = O extends {
     parameters: {
@@ -42,17 +28,14 @@ type BodyOf<O> = O extends {
         };
     };
 } ? B : never;
-/** Os códigos de sucesso que a superfície usa. */
+/** Os códigos HTTP de sucesso das rotas `/v1`. */
 type SuccessStatus = 200 | 201 | 202;
 type JsonBody<R> = R extends {
     content: {
         "application/json": infer C;
     };
 } ? C : never;
-/**
- * O corpo de sucesso — UNIÃO quando a rota responde mais de um código, que é o
- * caso da busca de processos (200 síncrono, 202 enfileirado).
- */
+/** O corpo de sucesso; uma união quando a rota responde mais de um código. */
 type SuccessBody<O> = O extends {
     responses: infer R;
 } ? {
@@ -70,41 +53,47 @@ export type PathParams<P extends keyof paths, M extends MethodOf<P>> = PathParam
 export type Query<P extends keyof paths, M extends MethodOf<P>> = QueryParamsOf<Operation<P, M>>;
 /** O corpo JSON de uma rota, ou `never` quando ela não recebe corpo. */
 export type Body<P extends keyof paths, M extends MethodOf<P>> = BodyOf<Operation<P, M>>;
-/** O `data` do envelope de sucesso de uma rota. */
+/**
+ * O `data` da resposta de sucesso de uma rota. Na rota que responde mais de um
+ * código, como a busca de processos (200 com o resultado, 202 com a busca
+ * enfileirada), é a união dos dois.
+ */
 export type Data<P extends keyof paths, M extends MethodOf<P>> = DataOf<Operation<P, M>>;
-/** O `meta` do envelope de sucesso de uma rota, como o contrato o declara. */
+/** O `meta` da resposta de sucesso de uma rota, como o contrato o declara. */
 export type Meta<P extends keyof paths, M extends MethodOf<P>> = MetaOf<Operation<P, M>>;
-/** O que o motor anuncia sobre o teto por minuto, em TODA resposta. */
+/**
+ * Os cabeçalhos de limite de vazão de uma resposta. A API os envia em toda
+ * resposta autenticada, de sucesso ou de recusa.
+ */
 export interface RateLimitSnapshot {
-    /** Teto da janela, ou `null` quando o cabeçalho não veio. */
+    /** As chamadas permitidas por janela (`RateLimit-Limit`), ou `null`. */
     limit: number | null;
-    /** Quanto resta na janela, ou `null` quando o cabeçalho não veio. */
+    /**
+     * As chamadas que restam na janela (`RateLimit-Remaining`), ou `null`. Use-o
+     * para desacelerar antes de ser recusado.
+     */
     remaining: number | null;
     /**
-     * O que o cabeçalho `RateLimit-Reset` trouxe, ou `null`.
-     *
-     * Os dois sentidos são do motor, não do cliente: na RECUSA são os segundos
-     * até a janela reabrir; no SUCESSO é o COMPRIMENTO da janela (60 s), que é
-     * constante. Espaçar por este número depois de um sucesso perto do teto faz
-     * dormir a janela inteira — para desacelerar, olhe `remaining`.
+     * O valor de `RateLimit-Reset`, ou `null`. Na recusa, são os segundos até a
+     * janela reabrir; no sucesso, é a duração da janela (60 s), que não muda.
+     * Para desacelerar depois de um sucesso, use `remaining`.
      */
     resetSeconds: number | null;
     /**
-     * O `Retry-After` da recusa, quando houve; `null` em todo sucesso. A espera
-     * que a fonte pediu a uma leitura socorrida pelo acervo sai em
-     * `meta.lakeRescue.retryAfterSeconds`.
+     * O `Retry-After` da recusa, ou `null` em toda resposta de sucesso. Quando a
+     * leitura de um processo é respondida com a cópia guardada, a espera pedida
+     * pela fonte está em `meta.lakeRescue.retryAfterSeconds`.
      */
     retryAfterSeconds: number | null;
 }
-/**
- * O que o cliente acrescenta ao `meta` do contrato.
- *
- * `status` viaja aqui porque a busca de processos responde 200 ou 202 na MESMA
- * operação: sem o código, distinguir resultado pronto de trabalho enfileirado
- * exigiria farejar campos do corpo.
- */
+/** Os campos que este pacote acrescenta ao `meta` de toda resposta. */
 export interface MetaExtras {
+    /**
+     * O código HTTP da resposta. Distingue 200 de 202 nas rotas que respondem
+     * os dois, como a busca de processos.
+     */
     status: number;
+    /** Os cabeçalhos de limite de vazão, ou `null` quando nenhum veio. */
     rateLimit: RateLimitSnapshot | null;
 }
 /** O par `{ data, meta }` que toda chamada devolve, tipado pela rota. */
@@ -135,52 +124,72 @@ type BodySlot<O> = [BodyOf<O>] extends [never] ? {
 } : {
     body: BodyOf<O>;
 };
-/** Política de retentativa. Desligada por padrão — ver `createLexNodeClient`. */
+/**
+ * A política de retentativa, desligada por padrão.
+ *
+ * Repete só erros retentáveis. `GET` e `DELETE` são repetidos; uma escrita, só
+ * com `idempotent: true` na chamada ou, em
+ * `POST /v1/publications/text-searches`, com o `requestId` fixado por você. O
+ * tempo esgotado da fonte (`UPSTREAM_TIMEOUT`) na ficha, no retrato e em
+ * `processLookups.create` não é repetido. Entre as tentativas, espera o
+ * `Retry-After` da recusa ou, sem ele, `baseDelayMs` dobrando a cada
+ * tentativa, sempre até `maxDelayMs`. A recusa que pede uma espera maior que
+ * `maxDelayMs` não é repetida: ela é lançada, e `retryAfterSeconds` diz
+ * quando vale tentar de novo.
+ *
+ * @example
+ * ```ts
+ * const lexnode = createLexNodeClient({
+ *   baseUrl,
+ *   apiKey,
+ *   retry: { attempts: 3, baseDelayMs: 500 },
+ * });
+ * ```
+ */
 export interface RetryPolicy {
-    /** Total de tentativas, contando a primeira. `1` (ou menos) desliga. */
+    /** Total de tentativas, contando a primeira. `1` ou menos desliga. */
     attempts: number;
-    /** Espera da primeira retentativa, em ms; dobra a cada rodada. */
+    /** A espera antes da primeira repetição, em ms. Padrão: 500. */
     baseDelayMs?: number;
-    /** Teto da espera, em ms. */
+    /**
+     * A espera máxima entre tentativas, em ms. Padrão: 8 000. A recusa cujo
+     * `Retry-After` pede mais que isso é lançada sem repetição.
+     */
     maxDelayMs?: number;
 }
 /** O que toda chamada aceita, além dos parâmetros da própria rota. */
 export interface CallOptions {
     /**
-     * Sub-tenant desta chamada. Vence o do construtor; `null` OMITE o cabeçalho
-     * mesmo quando o construtor trouxe um — é o que a vigília precisa, porque o
-     * motor recorta monitor por escritório na listagem e na remoção.
+     * Escritório (sub-tenant) desta chamada, no cabeçalho `X-Office-Id`.
+     * Substitui o do construtor; `null` envia a chamada sem o cabeçalho, mesmo
+     * que o construtor tenha um.
      */
     officeId?: string | null;
-    /** Aborta a chamada. É COMBINADO com o prazo, nunca o substitui. */
+    /** Cancela a chamada. Vale junto com o prazo: o que vier primeiro encerra. */
     signal?: AbortSignal;
     /**
-     * Prazo desta chamada, em ms. Vence o do construtor e o que o cliente
-     * calcula para a ficha e o retrato de um processo a partir da espera.
+     * Prazo desta chamada, em ms. Substitui o do construtor e o calculado a
+     * partir de `waitSeconds` nas leituras de um processo.
      */
     timeoutMs?: number;
     /**
-     * `X-Request-Id`. Cunhado quando ausente.
-     *
-     * É rastreio em toda rota. Chave de replay em uma só —
-     * `POST /v1/publications/text-searches`, onde reenviar o mesmo valor devolve
-     * a busca já congelada sem cobrar de novo; é essa rota, e não a presença do
-     * id, que autoriza a retentativa de uma escrita.
+     * O `X-Request-Id` da chamada; criado quando ausente. Serve para o suporte
+     * encontrar a chamada. Em `POST /v1/publications/text-searches`, reenviar o
+     * mesmo valor devolve a busca já feita sem nova cobrança, e só ali ele
+     * libera a retentativa de uma escrita.
      */
     requestId?: string;
     /**
-     * Declara que repetir ESTA escrita é seguro, liberando a retentativa numa
-     * rota que o contrato não declara idempotente.
-     *
-     * A afirmação é de quem chama: sem ela, uma escrita repetida cria um segundo
-     * recurso — e o consumidor guarda o segundo sem nunca ver o primeiro.
+     * Declara que repetir esta escrita é seguro e libera a retentativa nela.
+     * Sem isso, a retentativa só repete as escritas que o contrato declara
+     * repetíveis: repetir uma criação cria um segundo recurso.
      */
     idempotent?: boolean;
-    /** `X-Trace-Id` da operação lógica. Cunhado quando ausente. */
+    /** O `X-Trace-Id` da operação; criado quando ausente. */
     traceId?: string;
-    /** Política de retentativa desta chamada. Vence a do construtor. */
+    /** Política de retentativa desta chamada. Substitui a do construtor. */
     retry?: RetryPolicy;
 }
-/** O argumento da chamada genérica: parâmetros, corpo e opções de transporte. */
+/** O argumento de `request`: parâmetros, corpo e opções da chamada. */
 export type RequestArgs<P extends keyof paths, M extends MethodOf<P>> = ParamsSlot<Operation<P, M>> & BodySlot<Operation<P, M>> & CallOptions;
 export {};

package/dist/watch.d.ts

@@ -1,67 +1,88 @@
 import type { LexNodeClient } from "./client.js";
 import type { CallOptions, Data } from "./types.js";
 import type { MonitorSyncSucceededPayload, WebhookEvent } from "./webhooks.js";
-/**
- * Vigiar um processo para N interessados.
- *
- * O motor separa duas primitivas que costumam ser confundidas:
- *
- * - o **sensor** (`Monitor`) é quem varre a fonte. Ele é único por alvo dentro
- *   da conta e do projeto, e tem teto: pedir um segundo para o mesmo processo
- *   responde 409;
- * - a **assinatura** (`ProcessSubscription`) é quem quer ser avisado. Ela é
- *   única por `externalRef`, não tem teto, e o aviso
- *   `PROCESS_MOVEMENT_CREATED` a ecoa de volta.
- *
- * Milhares de interessados no mesmo processo são, portanto, UM sensor e N
- * assinaturas. Este módulo é essa composição.
- */
+/** O processo a vigiar e o interessado que recebe os avisos. */
 export interface WatchProcessInput {
+    /** O número do processo. */
     processNumber: string;
+    /** O tribunal, pela sigla (por exemplo, `TJSP`). */
     tribunalAlias: string;
-    /** O sub-tenant do interessado. A ASSINATURA nasce com ele. */
+    /** O escritório (sub-tenant) do interessado; a assinatura é criada nele. */
     officeId?: string | null;
-    /** O ponteiro do consumidor, ecoado no evento de movimentação. */
+    /**
+     * A sua referência para o interessado, devolvida no evento
+     * `PROCESS_MOVEMENT_CREATED`.
+     */
     externalRef: string;
+    /** Um rótulo para o monitor. */
     label?: string;
-    /** AAAA-MM-DD da distribuição, para a vigília de aparição ter critério. */
+    /**
+     * A data de distribuição (AAAA-MM-DD) do processo que ainda não aparece na
+     * fonte, para o monitor saber até quando esperá-lo.
+     */
     distributedAt?: string;
 }
+/** O resultado de `watchProcess`. */
 export interface WatchProcessResult {
     /**
-     * O sensor do alvo, tenha ele nascido agora ou já existido — a recusa 409
-     * carrega o id do que está lá, em `details.monitorId`. Nulo só quando a
-     * recusa não o traz.
+     * O monitor do processo, criado agora ou já existente; `null` só quando a
+     * recusa de monitor repetido não informou o id.
      */
     monitorId: string | null;
+    /** Se o monitor já existia antes desta chamada. */
     monitorAlreadyExisted: boolean;
+    /** A assinatura criada para o interessado. */
     subscription: Data<"/v1/subscriptions", "post">;
 }
 /**
- * Garante o sensor e registra o interessado.
+ * Vigia um processo para um interessado: garante o monitor do processo e cria
+ * a assinatura do interessado.
+ *
+ * Cada processo tem um monitor por conta e projeto, que consulta a fonte, e
+ * cada interessado tem a própria assinatura, identificada pelo `externalRef`,
+ * que recebe os avisos. Chame esta função uma vez por interessado: a primeira
+ * chamada cria o monitor, e as seguintes reaproveitam o existente
+ * (`monitorAlreadyExisted: true`). O monitor é criado sem escritório, para
+ * ficar ao alcance das chamadas de todos os escritórios — um monitor criado
+ * num escritório não aparece para as chamadas de outro —, e a assinatura é
+ * criada no escritório de `officeId`.
  *
- * O sensor é criado **sem `X-Office-Id`**: o motor recorta monitor por
- * escritório na listagem e na remoção, e um sensor preso ao escritório do
- * primeiro interessado desapareceria para o segundo. A assinatura, sim, nasce
- * com o escritório de quem quer o aviso.
+ * Lança `LexNodeError` nas recusas da API, exceto a de monitor repetido. A
+ * chave de teste (`lapi_test_`) não cria monitores: a criação responde 403
+ * `SANDBOX_UPSTREAM_DISABLED`, e a vigília exige a chave de produção.
  *
- * A chave de teste (`lapi_test_`) não cria trabalho de fundo: o sensor responde
- * 403 `SANDBOX_UPSTREAM_DISABLED`. A composição só fecha com chave viva.
+ * @example
+ * ```ts
+ * const { monitorId, subscription } = await watchProcess(lexnode, {
+ *   processNumber: "00012345620268260100",
+ *   tribunalAlias: "TJSP",
+ *   officeId: "usuario-4711",
+ *   externalRef: "caso-42",
+ * });
+ * ```
  */
 export declare function watchProcess(client: LexNodeClient, input: WatchProcessInput, opts?: CallOptions): Promise<WatchProcessResult>;
+/** O interessado que deixa de vigiar o processo. */
 export interface UnwatchProcessInput {
+    /** A referência usada em `watchProcess`. */
     externalRef: string;
+    /** O escritório (sub-tenant) usado em `watchProcess`. */
     officeId?: string | null;
 }
 /**
- * Remove o interesse de UM assinante.
+ * Cancela a assinatura deste interessado no processo.
  *
- * O sensor fica de pé de propósito: quantos interessados restam é contagem do
- * consumidor, e o SDK não tem como adivinhá-la — desligar a varredura aqui
- * calaria o aviso de todo mundo que continua assinando o mesmo processo.
+ * O monitor do processo continua ativo, porque outros interessados podem
+ * depender dele. Quando o último interessado sair, remova o monitor com
+ * `client.monitors.delete(monitorId)`.
+ *
+ * Lança `LexNodeError` nas recusas da API.
  */
 export declare function unwatchProcess(client: LexNodeClient, input: UnwatchProcessInput, opts?: CallOptions): Promise<Data<"/v1/subscriptions", "delete">>;
-/** O evento de varredura em que um alvo antes ausente apareceu na fonte. */
+/**
+ * O evento `MONITOR_SYNC_SUCCEEDED` que anuncia a primeira aparição do
+ * processo na fonte (`firstAppearance: true`).
+ */
 export type FirstAppearanceEvent = Extract<WebhookEvent, {
     type: "MONITOR_SYNC_SUCCEEDED";
 }> & {
@@ -70,24 +91,38 @@ export type FirstAppearanceEvent = Extract<WebhookEvent, {
     };
 };
 /**
- * Se este evento anuncia a primeira aparição do alvo na fonte.
+ * Diz se o evento anuncia a primeira aparição do processo na fonte.
  *
- * Importa porque a assinatura criada ANTES de o processo entrar no acervo
- * nasce sem vínculo com a linha canônica, e o leque de
- * `PROCESS_MOVEMENT_CREATED` escolhe assinantes por esse vínculo: até a
- * primeira aparição, o assinante não recebe nada. Refazer o
- * `POST /v1/subscriptions` depois deste evento preenche o vínculo.
+ * Uma assinatura criada antes de o processo aparecer na fonte não recebe
+ * `PROCESS_MOVEMENT_CREATED` até ser refeita. Quando este evento chegar,
+ * refaça as assinaturas do processo com `resubscribeOnFirstAppearance`.
  */
 export declare function isFirstAppearance(event: WebhookEvent): event is FirstAppearanceEvent;
+/**
+ * Um interessado a assinar de novo: a referência e o escritório usados em
+ * `watchProcess`.
+ */
 export interface ResubscribeSubscriber {
+    /** A referência do interessado. */
     externalRef: string;
+    /** O escritório (sub-tenant) do interessado. */
     officeId?: string | null;
 }
 /**
- * Refaz as assinaturas de um alvo que acabou de aparecer na fonte.
+ * Refaz as assinaturas de um processo que acabou de aparecer na fonte.
+ *
+ * Passe o evento recebido e os interessados do processo, que o evento não
+ * traz. Devolve as assinaturas refeitas, ou uma lista vazia, sem chamar a API,
+ * quando o evento não é de primeira aparição ou não traz o tribunal e o número
+ * do processo. Lança `LexNodeError` nas recusas da API.
  *
- * Quem são os interessados é do consumidor — o evento não os carrega —, então
- * eles entram por parâmetro. Sem `tribunalAlias` no payload, nada é refeito: a
- * assinatura é por (fonte, tribunal, processo).
+ * @example
+ * ```ts
+ * if (isFirstAppearance(evento)) {
+ *   await resubscribeOnFirstAppearance(lexnode, evento, [
+ *     { externalRef: "caso-42", officeId: "usuario-4711" },
+ *   ]);
+ * }
+ * ```
  */
 export declare function resubscribeOnFirstAppearance(client: LexNodeClient, event: WebhookEvent, subscribers: ReadonlyArray<ResubscribeSubscriber>, opts?: CallOptions): Promise<Array<Data<"/v1/subscriptions", "post">>>;

package/dist/watch.js

@@ -1,17 +1,5 @@
 import { LexNodeError } from "./errors.js";
-/** A recusa de alvo já vigiado — que, para esta composição, é sucesso. */
 const MONITOR_ALREADY_EXISTS = "MONITOR_ALREADY_EXISTS";
-/**
- * Garante o sensor e registra o interessado.
- *
- * O sensor é criado **sem `X-Office-Id`**: o motor recorta monitor por
- * escritório na listagem e na remoção, e um sensor preso ao escritório do
- * primeiro interessado desapareceria para o segundo. A assinatura, sim, nasce
- * com o escritório de quem quer o aviso.
- *
- * A chave de teste (`lapi_test_`) não cria trabalho de fundo: o sensor responde
- * 403 `SANDBOX_UPSTREAM_DISABLED`. A composição só fecha com chave viva.
- */
 export async function watchProcess(client, input, opts = {}) {
     let monitorId = null;
     let monitorAlreadyExisted = false;
@@ -43,37 +31,14 @@ export async function watchProcess(client, input, opts = {}) {
     }, { ...opts, officeId: input.officeId });
     return { monitorId, monitorAlreadyExisted, subscription };
 }
-/**
- * Remove o interesse de UM assinante.
- *
- * O sensor fica de pé de propósito: quantos interessados restam é contagem do
- * consumidor, e o SDK não tem como adivinhá-la — desligar a varredura aqui
- * calaria o aviso de todo mundo que continua assinando o mesmo processo.
- */
 export async function unwatchProcess(client, input, opts = {}) {
     const { data } = await client.subscriptions.delete({ reason: "CASE_LINK", externalRef: input.externalRef }, { ...opts, officeId: input.officeId });
     return data;
 }
-/**
- * Se este evento anuncia a primeira aparição do alvo na fonte.
- *
- * Importa porque a assinatura criada ANTES de o processo entrar no acervo
- * nasce sem vínculo com a linha canônica, e o leque de
- * `PROCESS_MOVEMENT_CREATED` escolhe assinantes por esse vínculo: até a
- * primeira aparição, o assinante não recebe nada. Refazer o
- * `POST /v1/subscriptions` depois deste evento preenche o vínculo.
- */
 export function isFirstAppearance(event) {
     return (event.type === "MONITOR_SYNC_SUCCEEDED" &&
         event.payload.firstAppearance === true);
 }
-/**
- * Refaz as assinaturas de um alvo que acabou de aparecer na fonte.
- *
- * Quem são os interessados é do consumidor — o evento não os carrega —, então
- * eles entram por parâmetro. Sem `tribunalAlias` no payload, nada é refeito: a
- * assinatura é por (fonte, tribunal, processo).
- */
 export async function resubscribeOnFirstAppearance(client, event, subscribers, opts = {}) {
     if (!isFirstAppearance(event))
         return [];