@lexnode/legal-data-sdk 1.0.0 → 1.18.0

package/README.md

@@ -1,25 +1,327 @@
 # @lexnode/legal-data-sdk
 
-Tipos TypeScript do contrato da API do **LexNode**, o motor de dados jurídicos
-do Brasil: processos e movimentações, publicações dos diários oficiais,
-jurisprudência, monitores e webhooks. O pacote traz **só tipos** — nenhum
-cliente HTTP embutido —, para que você escolha o transporte e o compilador
-confira o resto.
+Cliente TypeScript do **LexNode**, o motor de dados jurídicos do Brasil:
+processos e movimentações, publicações dos diários oficiais, jurisprudência,
+monitores e webhooks.
+
+O pacote traz **os tipos gerados do contrato OpenAPI** e um **cliente de
+runtime** construído sobre eles: transporte com os cabeçalhos certos, erros
+classificados, verificação de assinatura de webhook, espera de busca
+assíncrona, leitura do alcance da fonte e a composição de vigília com vários
+interessados.
+
+- **Sem dependências de runtime.** `fetch` global e `node:crypto`.
+- **Node >= 20**, ESM.
+
+> ⚠️ **Servidor apenas, e só por TLS.** A credencial é uma chave de **conta**:
+> no browser ela está publicada, e em `http://` ela é lida por quem estiver no
+> caminho — uma `baseUrl` sem https é recusada no construtor (host local é a
+> exceção, para desenvolvimento). 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 pelo cabeçalho `X-Office-Id`.
 
 ## Instalação
 
 ```sh
-npm install -D @lexnode/legal-data-sdk
+npm install @lexnode/legal-data-sdk
+```
+
+## O cliente
+
+```ts
+import { createLexNodeClient } from "@lexnode/legal-data-sdk";
+
+const lexnode = createLexNodeClient({
+  baseUrl: "https://api.lexnode.com.br",
+  apiKey: process.env.LEXNODE_API_KEY!,
+  // Sub-tenant padrão; cada chamada pode trocá-lo.
+  officeId: "escritorio-01",
+  timeoutMs: 30_000,
+  userAgent: "meu-app/1.0",
+});
+
+const { data, meta } = await lexnode.processes.get("00012345620268260100", {
+  tribunalAlias: "api_publica_tjsp",
+});
+
+console.log(data.formattedNumber, meta.credits, meta.rateLimit?.remaining);
+```
+
+Toda chamada manda `Authorization: Bearer`, `X-Request-Id`, `X-Trace-Id` e,
+quando há um, `X-Office-Id`; respeita o prazo do cliente **combinado** com o
+`signal` de quem chamou; e devolve `{ data, meta }` tipados pela rota. O `meta`
+é o do contrato mais `status` (o código HTTP) e `rateLimit` (os cabeçalhos
+`RateLimit-*` / `Retry-After`, lidos **inclusive no sucesso**).
+
+Em `rateLimit`, use `remaining` para desacelerar: `resetSeconds` repete o que o
+cabeçalho `RateLimit-Reset` trouxe, e o motor lhe dá dois sentidos — segundos
+até reabrir na recusa, comprimento da janela (60 s) no sucesso.
+
+O pacote **não valida a resposta em tempo de execução**: `data` e `meta` chegam
+tipados pelo contrato, e o que garante a correspondência é a versão fixada, não
+uma conferência a cada chamada. Quem precisa de barreira na borda — porque o
+dado alimenta um banco, por exemplo — valida o que consome.
+
+### Métodos nomeados e a chamada genérica
+
+Os métodos nomeados cobrem o uso diário:
+
+```ts
+await lexnode.tribunals.list();
+await lexnode.processes.movements(numero, { tribunalAlias });
+await lexnode.publications.list({ oabNumber: "123456", oabState: "SP" });
+await lexnode.monitors.create({ type: "OAB", oabNumber: "123456", oabState: "SP" });
+await lexnode.subscriptions.create({ tribunalAlias, processNumber, externalRef });
+await lexnode.searchJobs.get(jobId);
+await lexnode.events.list({ limit: 50 });
+await lexnode.webhooks.endpoints.list();
+await lexnode.usage.get();
+```
+
+Qualquer rota do contrato — inclusive uma que o pacote ainda não batizou — sai
+pela chamada genérica, tipada por `paths`:
+
+```ts
+const { data } = await lexnode.request("/v1/precedents", "get", {
+  params: { query: { query: "dano moral", limit: 20 } },
+});
+```
+
+### Páginas
+
+O motor pagina de três jeitos (cursor no `meta`, cursor no `data`, e
+página/tamanho ou deslocamento/teto). `paginate` percorre qualquer um deles, com
+teto explícito de páginas — cada página é uma chamada medida:
+
+```ts
+import { paginate } from "@lexnode/legal-data-sdk";
+
+for await (const page of paginate(lexnode, "/v1/monitors", "get", {})) {
+  for (const monitor of page) console.log(monitor.id);
+}
+```
+
+### Erros
+
+```ts
+import { LexNodeError } from "@lexnode/legal-data-sdk";
+
+try {
+  await lexnode.processes.search({ tribunalAlias, number });
+} catch (error) {
+  if (error instanceof LexNodeError) {
+    error.code;              // "RATE_LIMITED", "PROCESS_NOT_FOUND", …
+    error.class;             // "RETRYABLE" | "TERMINAL"
+    error.retryable;
+    error.status;
+    error.upstreamStatus;    // o status real da fonte, quando preservado
+    error.requestId;         // o que o suporte pede
+    error.fieldErrors;       // recusa de validação, por campo
+    error.retryAfterSeconds;
+    error.rateLimit;
+  }
+}
+```
+
+Prazo esgotado vira `CLIENT_TIMEOUT` (504, retentável); falha de rede vira
+`CLIENT_NETWORK_ERROR` (502, retentável); resposta fora do envelope vira
+`INVALID_RESPONSE` (502) com o corpo cru truncado na mensagem; o que o
+transporte recusa mandar — cabeçalho com quebra de linha, corpo que não
+serializa — vira `CLIENT_INVALID_REQUEST` (400, **não** retentável), porque
+repetir o que nunca saiu não cura.
+
+`LEXNODE_ERROR_CODES` traz o catálogo para o `switch`, e `LexNodeErrorCode`
+mantém o autocompletar sem fechar a porta a um código novo. Importa na leitura
+de processo: o motor responde 404 tanto para `PROCESS_NOT_FOUND` (o processo não
+existe na fonte) quanto para `MOVEMENTS_NOT_AVAILABLE` (existe, mas as
+movimentações não vêm) — quem trata os dois igual conta a história errada.
+
+### Retentativa (opcional, desligada por padrão)
+
+```ts
+const lexnode = createLexNodeClient({
+  baseUrl,
+  apiKey,
+  retry: { attempts: 3, baseDelayMs: 500 },
+});
+```
+
+Repete só o que é `RETRYABLE`, respeitando `Retry-After`. `GET` e `DELETE` são
+repetidos por definição do HTTP. Uma **escrita** só é repetida quando o contrato
+declara a repetição segura — hoje `POST /v1/publications/text-searches`, que usa
+o `requestId` que você fixar como chave de replay — ou quando você mesmo o
+declara na chamada:
+
+```ts
+await lexnode.webhooks.endpoints.create(corpo, { idempotent: true });
+```
+
+A afirmação é sua: sem ela, um `POST` repetido cria um **segundo** recurso — dois
+endpoints para a mesma URL entregam cada evento em dobro, e o segredo do
+primeiro fica órfão. Em toda outra rota o `requestId` é só rastreio.
+
+## Webhooks
+
+```ts
+import {
+  parseWebhookEvent,
+  webhookRejectionStatus,
+} from "@lexnode/legal-data-sdk";
+
+// O corpo CRU, nunca um JSON reserializado: o digest é sobre os bytes.
+const resultado = parseWebhookEvent(
+  rawBody,
+  request.headers,
+  process.env.LEXNODE_WEBHOOK_SIGNING_SECRET!,
+);
+
+// O status de cada recusa vem junto: um corpo que não se autentica é 401 e não
+// volta; segredo ausente é 503, porque a falha é SUA e o motor precisa insistir.
+if (!resultado.ok) {
+  return reply.status(webhookRejectionStatus(resultado.reason)).send();
+}
+// Tipo que o catálogo ainda não descreve: ignore e responda 2xx.
+if (!resultado.known) return reply.status(200).send();
+
+switch (resultado.event.type) {
+  case "PUBLICATION_CREATED":
+    resultado.event.payload.publicationKey;
+    resultado.event.payload.excerpt; // null quando o teor foi retido
+    break;
+  case "PROCESS_MOVEMENT_CREATED":
+    resultado.event.payload.externalRef;
+    break;
+  case "SEARCH_JOB_COMPLETED":
+    if (resultado.event.payload.status === "FAILED") {
+      resultado.event.payload.error.code;
+    }
+    break;
+  case "WEBHOOK_TEST":
+    // A entrega de teste do console. Chega a qualquer endpoint, não se assina
+    // e não se recusa — é ela que valida o receptor antes do primeiro evento.
+    break;
+  default:
+    break;
+}
 ```
 
-## Uso
+O envelope precisa ser endereçável: entrega sem `id` ou sem `occurredAt` é
+recusada como `INVALID_ENVELOPE`. O `id` é a chave de idempotência de todo
+receptor — aceitá-lo vazio faria a primeira entrega ocupar a única vaga de
+deduplicação e todas as seguintes parecerem repetição dela.
 
-Os tipos são gerados do documento OpenAPI publicado pela API e expõem as
-interfaces `paths` e `operations`. Combine-os com o cliente de sua preferência
-(por exemplo, `openapi-fetch`):
+`WEBHOOK_EVENT_TYPES` é o catálogo **assinável** (o que entra em `eventTypes`
+ao cadastrar um endpoint) e não inclui `WEBHOOK_TEST`, que chega sem ser
+pedido — use `isWebhookTest(event)` para separá-lo.
+
+`verifyWebhookSignature(rawBody, headers, secret)` faz só a conferência e
+devolve o motivo da recusa (`MISSING_SIGNATURE`, `MALFORMED_SIGNATURE`,
+`TIMESTAMP_MISMATCH`, `TIMESTAMP_OUT_OF_TOLERANCE`, `SIGNATURE_MISMATCH`,
+`RAW_BODY_REQUIRED`), em vez de um `false` que faria vários incidentes
+diferentes virarem a mesma resposta.
+
+O corpo entra como `string` ou `Buffer` — os bytes como chegaram. Passar o JSON
+já parseado é recusado como `RAW_BODY_REQUIRED`, e não confundido com
+adulteração: reserializar reordena as chaves e o digest deixa de bater.
+
+A janela de replay e o digest saem do `t` que viaja **dentro** da assinatura; o
+cabeçalho `x-lexnode-timestamp` é redundante e só é conferido quando vem. Um
+receptor escrito à mão que o exigia continua correto — o SDK apenas não faz da
+ausência dele um motivo de recusa, porque ela não prova nada.
+
+## Busca síncrona ou assíncrona
+
+`POST /v1/processes/search` responde **200** com o resultado pronto ou **202**
+com um trabalho enfileirado. O SDK diz qual foi, no tipo:
 
 ```ts
-import type { paths, operations } from "@lexnode/legal-data-sdk";
+import { searchProcesses, waitForSearchJob } from "@lexnode/legal-data-sdk";
+
+const desfecho = await searchProcesses(lexnode, { tribunalAlias, number });
+
+if (desfecho.kind === "sync") {
+  desfecho.result.items;
+} else {
+  // O orçamento é explícito: num ambiente serverless, esperar sem teto gasta
+  // a requisição inteira. Quem integrou por webhook nem espera — recebe o
+  // SEARCH_JOB_COMPLETED.
+  const job = await waitForSearchJob(lexnode, desfecho.job.jobId, {
+    budgetMs: 20_000,
+  });
+  job.status; // "SUCCEEDED" | "FAILED" | "CANCELED"
+}
+```
+
+## Frescor: o `total: 0` qualificado
+
+Um resultado vazio não distingue sozinho "não existe" de "a fonte ainda não
+indexou". O motor publica a data-limite do índice; o SDK a lê nos dois eixos
+(processo e diário):
+
+```ts
+import {
+  describeFreshness,
+  isNotYetIndexed,
+  readThrough,
+} from "@lexnode/legal-data-sdk";
+
+const busca = await lexnode.processes.search({ tribunalAlias, number });
+
+if (isNotYetIndexed(busca, { since: "2026-09-15" })) {
+  // Não diga "não existe": diga até quando a fonte foi lida.
+  mostrar(describeFreshness(busca)); // "fonte lida até 10/09/2026"
+}
+
+readThrough(busca); // Date | null — null é ESTADO indeterminado, não erro
+```
+
+## Vigília com vários interessados
+
+O motor separa duas primitivas: o **sensor** (`Monitor`), único por alvo na
+conta e com teto, e a **assinatura** (`ProcessSubscription`), única por
+`externalRef`, sem teto e ecoada no aviso. N interessados no mesmo processo são
+um sensor e N assinaturas.
+
+```ts
+import { unwatchProcess, watchProcess } from "@lexnode/legal-data-sdk";
+
+const { monitorId, monitorAlreadyExisted, subscription } = await watchProcess(
+  lexnode,
+  {
+    processNumber: "00012345620268260100",
+    tribunalAlias: "api_publica_tjsp",
+    officeId: "usuario-4711",
+    externalRef: "caso-42",
+  },
+);
+
+// Um interessado desiste; o sensor continua varrendo para os demais.
+await unwatchProcess(lexnode, {
+  externalRef: "caso-42",
+  officeId: "usuario-4711",
+});
+```
+
+**Limitação conhecida:** uma assinatura criada **antes** de o processo entrar no
+acervo não recebe `PROCESS_MOVEMENT_CREATED` até a primeira aparição do alvo na
+fonte. O contorno é refazer a assinatura quando chegar o
+`MONITOR_SYNC_SUCCEEDED` com `firstAppearance: true`:
+
+```ts
+import { resubscribeOnFirstAppearance } from "@lexnode/legal-data-sdk";
+
+await resubscribeOnFirstAppearance(lexnode, evento, [
+  { externalRef: "caso-42", officeId: "usuario-4711" },
+]);
+```
+
+## Só os tipos
+
+O uso antigo continua valendo — o pacote exporta `paths` e `operations` como
+sempre:
+
+```ts
+import type { operations, paths } from "@lexnode/legal-data-sdk";
 
 // Uma operação inteira, pela rota e pelo método:
 type SearchProcesses = paths["/v1/processes/search"]["post"];
@@ -29,6 +331,24 @@ type Tribunals =
   operations["listTribunals"]["responses"][200]["content"]["application/json"]["data"];
 ```
 
+E os atalhos derivados deles, que o cliente usa internamente:
+
+```ts
+import type { Body, Data, Query } from "@lexnode/legal-data-sdk";
+
+type CorpoDaBusca = Body<"/v1/processes/search", "post">;
+type ConsultaDeProcesso = Query<"/v1/processes/{processNumber}", "get">;
+type Tribunais = Data<"/v1/tribunals", "get">;
+```
+
+## A chave de teste
+
+A chave `lapi_test_` lê o acervo já formado, mas **não consulta a fonte viva nem
+cria trabalho de fundo**: monitor, vigília, colheita e busca assíncrona
+respondem 403 `SANDBOX_UPSTREAM_DISABLED`. Na prática, `watchProcess` e o ramo
+`async` de `searchProcesses` só fecham com chave viva — vale saber antes de
+achar que a integração está errada.
+
 ## Referências
 
 - Documentação: <https://www.lexnode.com.br/docs>

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+import type { paths } from "../schema.js";
+import type { Body, CallOptions, LexNodeResult, MethodOf, Query, RequestArgs, RetryPolicy } from "./types.js";
+export interface LexNodeClientOptions {
+    /** Base da API, por exemplo `https://api.lexnode.com.br`. */
+    baseUrl: string;
+    /**
+     * Chave de CONTA (`Authorization: Bearer`). É credencial de servidor: ver o
+     * aviso de `createLexNodeClient`.
+     */
+    apiKey: string;
+    /** Sub-tenant padrão (`X-Office-Id`). Cada chamada pode trocá-lo ou omiti-lo. */
+    officeId?: string;
+    /** Prazo de cada chamada, em ms. Padrão: 30 s. */
+    timeoutMs?: number;
+    /** Transporte alternativo — o `fetch` global é o padrão. */
+    fetch?: typeof globalThis.fetch;
+    /** Identifica a sua integração no `User-Agent`. */
+    userAgent?: string;
+    /** Política de retentativa padrão. Ausente = desligada. */
+    retry?: RetryPolicy;
+}
+/**
+ * O cliente de runtime do motor de dados jurídicos.
+ *
+ * **Servidor apenas, e só por TLS.** A credencial é de CONTA: uma chave no
+ * browser é uma chave publicada, e uma chave em `http://` é uma chave lida por
+ * quem estiver no caminho — `baseUrl` sem https é recusada aqui, exceto em
+ * host local. 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`.
+ */
+export declare function createLexNodeClient(options: LexNodeClientOptions): {
+    request: <P extends keyof paths, M extends MethodOf<P>>(path: P, method: M, args: RequestArgs<P, M>) => Promise<LexNodeResult<P, M>>;
+    tribunals: {
+        list: (query?: Query<"/v1/tribunals", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/tribunals", "get">>;
+    };
+    processes: {
+        search: (body: Body<"/v1/processes/search", "post">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/search", "post">>;
+        get: (processNumber: string, query: Query<"/v1/processes/{processNumber}", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/{processNumber}", "get">>;
+        movements: (processNumber: string, query: Query<"/v1/processes/{processNumber}/movements", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/{processNumber}/movements", "get">>;
+        snapshot: (processNumber: string, query: Query<"/v1/processes/{processNumber}/snapshot", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/{processNumber}/snapshot", "get">>;
+        related: (processNumber: string, query: Query<"/v1/processes/{processNumber}/related", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/{processNumber}/related", "get">>;
+        snapshotBatch: (body: Body<"/v1/processes/snapshot-batch", "post">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/processes/snapshot-batch", "post">>;
+    };
+    publications: {
+        list: (query?: Query<"/v1/publications", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/publications", "get">>;
+        read: (publicationKey: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/publications/{publicationKey}", "get">>;
+        textSearch: (body: Body<"/v1/publications/text-searches", "post">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/publications/text-searches", "post">>;
+        textAlerts: {
+            create: (body: Body<"/v1/publications/text-alerts", "post">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/publications/text-alerts", "post">>;
+            list: (query?: Query<"/v1/publications/text-alerts", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/publications/text-alerts", "get">>;
+            delete: (alertId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/publications/text-alerts/{alertId}", "delete">>;
+        };
+    };
+    monitors: {
+        create: (body: Body<"/v1/monitors", "post">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/monitors", "post">>;
+        list: (query?: Query<"/v1/monitors", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/monitors", "get">>;
+        get: (monitorId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/monitors/{monitorId}", "get">>;
+        update: (monitorId: string, body: Body<"/v1/monitors/{monitorId}", "patch">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/monitors/{monitorId}", "patch">>;
+        delete: (monitorId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/monitors/{monitorId}", "delete">>;
+        sync: (monitorId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/monitors/{monitorId}/sync", "post">>;
+    };
+    subscriptions: {
+        create: (body: Body<"/v1/subscriptions", "post">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/subscriptions", "post">>;
+        list: (query?: Query<"/v1/subscriptions", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/subscriptions", "get">>;
+        delete: (body: Body<"/v1/subscriptions", "delete">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/subscriptions", "delete">>;
+    };
+    searchJobs: {
+        get: (jobId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/search-jobs/{jobId}", "get">>;
+        list: (query?: Query<"/v1/search-jobs", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/search-jobs", "get">>;
+        cancel: (jobId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/search-jobs/{jobId}/cancel", "post">>;
+    };
+    events: {
+        list: (query?: Query<"/v1/events", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/events", "get">>;
+        get: (eventId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/events/{eventId}", "get">>;
+    };
+    usage: {
+        get: (query?: Query<"/v1/usage", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/usage", "get">>;
+    };
+    webhooks: {
+        endpoints: {
+            list: (query?: Query<"/v1/webhooks/endpoints", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/webhooks/endpoints", "get">>;
+            create: (body: Body<"/v1/webhooks/endpoints", "post">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/webhooks/endpoints", "post">>;
+            update: (endpointId: string, body: Body<"/v1/webhooks/endpoints/{endpointId}", "patch">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/webhooks/endpoints/{endpointId}", "patch">>;
+            delete: (endpointId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/webhooks/endpoints/{endpointId}", "delete">>;
+            test: (endpointId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/webhooks/endpoints/{endpointId}/test", "post">>;
+            rotateSecret: (endpointId: string, opts?: CallOptions) => Promise<LexNodeResult<"/v1/webhooks/endpoints/{endpointId}/rotate-secret", "post">>;
+        };
+        deliveries: (query?: Query<"/v1/webhooks/deliveries", "get">, opts?: CallOptions) => Promise<LexNodeResult<"/v1/webhooks/deliveries", "get">>;
+        health: (opts?: CallOptions) => Promise<LexNodeResult<"/v1/webhooks/health", "get">>;
+    };
+};
+export type LexNodeClient = ReturnType<typeof createLexNodeClient>;