@lexnode/legal-data-sdk 1.0.0 → 1.18.0

package/dist/search.js

@@ -0,0 +1,75 @@
+import { LexNodeError } from "./errors.js";
+/** Estados em que o trabalho não avança mais. */
+const TERMINAL_STATES = new Set(["SUCCEEDED", "FAILED", "CANCELED"]);
+const DEFAULT_BUDGET_MS = 45_000;
+const DEFAULT_POLL_INTERVAL_MS = 1_500;
+const DEFAULT_MAX_POLL_INTERVAL_MS = 8_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 });
+    });
+}
+/**
+ * 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 async function searchProcesses(client, body, opts = {}) {
+    const { data, meta } = await client.processes.search(body, opts);
+    if (meta.status === 202) {
+        return { kind: "async", job: data, meta };
+    }
+    return { kind: "sync", result: data, meta };
+}
+/**
+ * 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 async function waitForSearchJob(client, jobId, options = {}) {
+    const budgetMs = options.budgetMs ?? DEFAULT_BUDGET_MS;
+    const maxIntervalMs = options.maxPollIntervalMs ?? DEFAULT_MAX_POLL_INTERVAL_MS;
+    let intervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const deadline = Date.now() + budgetMs;
+    for (;;) {
+        const { data } = await client.searchJobs.get(jobId, {
+            signal: options.signal,
+            officeId: options.officeId,
+        });
+        options.onState?.(data.status, data);
+        if (TERMINAL_STATES.has(data.status))
+            return data;
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            throw new LexNodeError({
+                code: "SEARCH_JOB_BUDGET_EXCEEDED",
+                message: `O trabalho ${jobId} não concluiu em ${budgetMs} ms; ele segue na fila.`,
+                status: 504,
+                errorClass: "RETRYABLE",
+                retryable: true,
+                details: { jobId, status: data.status, budgetMs },
+            });
+        }
+        await wait(Math.min(intervalMs, remainingMs), options.signal);
+        intervalMs = Math.min(intervalMs * 2, maxIntervalMs);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,179 @@
+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. */
+type Empty = {
+    [K in never]: never;
+};
+/** Os métodos que a superfície `/v1` usa. */
+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.
+ */
+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. */
+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: {
+        path: infer T;
+    };
+} ? T : never;
+type QueryParamsOf<O> = O extends {
+    parameters: {
+        query?: infer T;
+    };
+} ? NonNullable<T> : never;
+type BodyOf<O> = O extends {
+    requestBody: {
+        content: {
+            "application/json": infer B;
+        };
+    };
+} ? B : never;
+/** Os códigos de sucesso que a superfície usa. */
+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).
+ */
+type SuccessBody<O> = O extends {
+    responses: infer R;
+} ? {
+    [S in Extract<SuccessStatus, keyof R>]: JsonBody<R[S]>;
+}[Extract<SuccessStatus, keyof R>] : never;
+type DataOf<O> = SuccessBody<O> extends {
+    data: infer D;
+} ? D : never;
+type MetaOf<O> = SuccessBody<O> extends {
+    meta: infer M;
+} ? M : Record<string, unknown>;
+/** Os parâmetros de caminho de uma rota, ou `never` quando ela não tem. */
+export type PathParams<P extends keyof paths, M extends MethodOf<P>> = PathParamsOf<Operation<P, M>>;
+/** Os parâmetros de consulta de uma rota, ou `never` quando ela não tem. */
+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. */
+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. */
+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. */
+export interface RateLimitSnapshot {
+    /** Teto da janela, ou `null` quando o cabeçalho não veio. */
+    limit: number | null;
+    /** Quanto resta na janela, ou `null` quando o cabeçalho não veio. */
+    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`.
+     */
+    resetSeconds: number | null;
+    /** O `Retry-After` da recusa, quando houve. */
+    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.
+ */
+export interface MetaExtras {
+    status: number;
+    rateLimit: RateLimitSnapshot | null;
+}
+/** O par `{ data, meta }` que toda chamada devolve, tipado pela rota. */
+export interface LexNodeResult<P extends keyof paths, M extends MethodOf<P>> {
+    data: Data<P, M>;
+    meta: Meta<P, M> & MetaExtras;
+}
+type PathSlot<O> = [PathParamsOf<O>] extends [never] ? Empty : {
+    path: PathParamsOf<O>;
+};
+type QuerySlot<O> = [QueryParamsOf<O>] extends [never] ? Empty : Empty extends QueryParamsOf<O> ? {
+    query?: QueryParamsOf<O>;
+} : {
+    query: QueryParamsOf<O>;
+};
+type ParamsBag<O> = PathSlot<O> & QuerySlot<O>;
+/** `params` é obrigatório só quando a rota tem algum parâmetro obrigatório. */
+type ParamsSlot<O> = Empty extends ParamsBag<O> ? {
+    params?: ParamsBag<O>;
+} : {
+    params: ParamsBag<O>;
+};
+/** `body` é obrigatório só quando a rota exige corpo. */
+type BodySlot<O> = [BodyOf<O>] extends [never] ? {
+    body?: never;
+} : Empty extends BodyOf<O> ? {
+    body?: BodyOf<O>;
+} : {
+    body: BodyOf<O>;
+};
+/** Política de retentativa. Desligada por padrão — ver `createLexNodeClient`. */
+export interface RetryPolicy {
+    /** Total de tentativas, contando a primeira. `1` (ou menos) desliga. */
+    attempts: number;
+    /** Espera da primeira retentativa, em ms; dobra a cada rodada. */
+    baseDelayMs?: number;
+    /** Teto da espera, em ms. */
+    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.
+     */
+    officeId?: string | null;
+    /** Aborta a chamada. É COMBINADO com o prazo, nunca o substitui. */
+    signal?: AbortSignal;
+    /** Prazo desta chamada, em ms. Vence o do construtor. */
+    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.
+     */
+    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.
+     */
+    idempotent?: boolean;
+    /** `X-Trace-Id` da operação lógica. Cunhado quando ausente. */
+    traceId?: string;
+    /** Política de retentativa desta chamada. Vence a do construtor. */
+    retry?: RetryPolicy;
+}
+/** O argumento da chamada genérica: parâmetros, corpo e opções de transporte. */
+export type RequestArgs<P extends keyof paths, M extends MethodOf<P>> = ParamsSlot<Operation<P, M>> & BodySlot<Operation<P, M>> & CallOptions;
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/watch.d.ts

@@ -0,0 +1,93 @@
+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.
+ */
+export interface WatchProcessInput {
+    processNumber: string;
+    tribunalAlias: string;
+    /** O sub-tenant do interessado. A ASSINATURA nasce com ele. */
+    officeId?: string | null;
+    /** O ponteiro do consumidor, ecoado no evento de movimentação. */
+    externalRef: string;
+    label?: string;
+    /** AAAA-MM-DD da distribuição, para a vigília de aparição ter critério. */
+    distributedAt?: string;
+}
+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.
+     */
+    monitorId: string | null;
+    monitorAlreadyExisted: boolean;
+    subscription: Data<"/v1/subscriptions", "post">;
+}
+/**
+ * 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 declare function watchProcess(client: LexNodeClient, input: WatchProcessInput, opts?: CallOptions): Promise<WatchProcessResult>;
+export interface UnwatchProcessInput {
+    externalRef: string;
+    officeId?: string | null;
+}
+/**
+ * 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 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. */
+export type FirstAppearanceEvent = Extract<WebhookEvent, {
+    type: "MONITOR_SYNC_SUCCEEDED";
+}> & {
+    payload: MonitorSyncSucceededPayload & {
+        firstAppearance: true;
+    };
+};
+/**
+ * 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 declare function isFirstAppearance(event: WebhookEvent): event is FirstAppearanceEvent;
+export interface ResubscribeSubscriber {
+    externalRef: string;
+    officeId?: string | null;
+}
+/**
+ * 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 declare function resubscribeOnFirstAppearance(client: LexNodeClient, event: WebhookEvent, subscribers: ReadonlyArray<ResubscribeSubscriber>, opts?: CallOptions): Promise<Array<Data<"/v1/subscriptions", "post">>>;

package/dist/watch.js

@@ -0,0 +1,95 @@
+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;
+    try {
+        const { data } = await client.monitors.create({
+            type: "PROCESS",
+            tribunalAlias: input.tribunalAlias,
+            processNumber: input.processNumber,
+            ...(input.label ? { label: input.label } : {}),
+            ...(input.distributedAt ? { distributedAt: input.distributedAt } : {}),
+        }, { ...opts, officeId: null });
+        monitorId = data.id;
+    }
+    catch (error) {
+        if (!(error instanceof LexNodeError) ||
+            error.code !== MONITOR_ALREADY_EXISTS) {
+            throw error;
+        }
+        monitorAlreadyExisted = true;
+        const conhecido = error.details?.monitorId;
+        monitorId = typeof conhecido === "string" ? conhecido : null;
+    }
+    const { data: subscription } = await client.subscriptions.create({
+        source: "CNJ_DATAJUD",
+        tribunalAlias: input.tribunalAlias,
+        processNumber: input.processNumber,
+        reason: "CASE_LINK",
+        externalRef: input.externalRef,
+    }, { ...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 [];
+    const { processNumber, tribunalAlias } = event.payload;
+    if (!processNumber || !tribunalAlias)
+        return [];
+    const refeitas = [];
+    for (const subscriber of subscribers) {
+        const { data } = await client.subscriptions.create({
+            source: "CNJ_DATAJUD",
+            tribunalAlias,
+            processNumber,
+            reason: "CASE_LINK",
+            externalRef: subscriber.externalRef,
+        }, { ...opts, officeId: subscriber.officeId });
+        refeitas.push(data);
+    }
+    return refeitas;
+}