@lexnode/legal-data-sdk 1.30.0 → 1.32.0

package/dist/webhooks.d.ts

@@ -1,10 +1,6 @@
 /**
- * Verificação e tipagem das entregas assinadas do motor.
- *
- * O motor assina cada entrega como `x-lexnode-signature: t=<unix>,v1=<hex>`,
- * onde o HMAC-SHA256 cobre `${t}.${corpoCru}` com o segredo do endpoint. A
- * conferência é sobre os BYTES CRUS recebidos: reserializar o JSON muda a
- * ordem das chaves e o digest deixa de bater.
+ * Os cabeçalhos de uma entrega de webhook: o tipo do evento, o instante, a
+ * assinatura e o número da tentativa.
  */
 export declare const LEXNODE_WEBHOOK_HEADERS: {
     readonly event: "x-lexnode-event";
@@ -12,14 +8,20 @@ export declare const LEXNODE_WEBHOOK_HEADERS: {
     readonly signature: "x-lexnode-signature";
     readonly deliveryAttempt: "x-lexnode-delivery-attempt";
 };
-/** Janela de replay do motor. */
+/**
+ * A tolerância padrão, em segundos, entre o instante da assinatura e o seu
+ * relógio. Entrega fora dela é recusada como `TIMESTAMP_OUT_OF_TOLERANCE`.
+ */
 export declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
 /**
- * Os BYTES como chegaram. Reserializar o JSON reordena as chaves e o digest
- * deixa de bater, então um corpo já parseado é recusado em vez de conferido.
+ * O corpo da entrega como chegou, em texto ou bytes. Um objeto já convertido
+ * de JSON é recusado como `RAW_BODY_REQUIRED`: a assinatura vale para os bytes
+ * originais.
  */
 export type WebhookRawBody = string | Uint8Array;
+/** Por que `verifyWebhookSignature` recusou a entrega. */
 export type WebhookRejection = "MISSING_SECRET" | "RAW_BODY_REQUIRED" | "MISSING_SIGNATURE" | "MALFORMED_SIGNATURE" | "TIMESTAMP_MISMATCH" | "TIMESTAMP_OUT_OF_TOLERANCE" | "SIGNATURE_MISMATCH";
+/** O resultado de `verifyWebhookSignature`. */
 export type WebhookVerification = {
     ok: true;
     timestamp: number;
@@ -27,14 +29,17 @@ export type WebhookVerification = {
     ok: false;
     reason: WebhookRejection;
 };
+/**
+ * Por que `parseWebhookEvent` recusou a entrega: a assinatura, o JSON ou o
+ * formato do evento.
+ */
 export type WebhookParseRejection = WebhookRejection | "INVALID_JSON" | "INVALID_ENVELOPE";
 /**
- * O desfecho de `parseWebhookEvent`.
- *
- * `known` é o discriminador que separa o catálogo conhecido do resto. Ele mora
- * no RESULTADO, e não no evento, por uma razão de tipo: um ramo `type: string`
- * dentro da própria união apagaria o estreitamento por `type` de todos os
- * outros — `payload` viraria `unknown` mesmo no caso reconhecido.
+ * O resultado de `parseWebhookEvent`. Com `ok: true`, `known` diz se o tipo do
+ * evento está no catálogo deste pacote: com `known: true`, `event.type`
+ * estreita o `payload`; com `known: false`, o evento é um
+ * `UnknownWebhookEvent`. Com `ok: false`, `reason` diz por que a entrega foi
+ * recusada.
  */
 export type WebhookParseResult = {
     ok: true;
@@ -48,42 +53,68 @@ export type WebhookParseResult = {
     ok: false;
     reason: WebhookParseRejection;
 };
-/** Cabeçalhos como um `Headers` do fetch ou como o objeto cru de um framework. */
+/**
+ * Os cabeçalhos da entrega, como `Headers` do `fetch` ou como o objeto de
+ * cabeçalhos de um framework.
+ */
 export type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
+/** As opções de `verifyWebhookSignature` e de `parseWebhookEvent`. */
 export interface VerifyWebhookOptions {
-    /** Janela de replay, em segundos. Padrão: 300, como o motor. */
+    /** A tolerância do instante da entrega, em segundos. Padrão: 300. */
     toleranceSeconds?: number;
-    /** Relógio, em SEGUNDOS da época Unix — o mesmo eixo do `t` do cabeçalho. */
+    /**
+     * O instante atual, em segundos da época Unix — a mesma unidade do `t` da
+     * assinatura. Útil em testes.
+     */
     now?: number;
 }
 /**
- * Confere a assinatura de uma entrega e diz POR QUE recusou.
+ * Confere a assinatura de uma entrega de webhook e diz por que recusou.
  *
- * O veredito é motivado de propósito: um `false` nu manda o receptor devolver
- * o mesmo erro para segredo trocado, relógio fora de hora e corpo adulterado —
- * três incidentes com conduta diferente.
+ * Recebe o corpo como chegou, os cabeçalhos e o segredo do endpoint. A
+ * assinatura, no cabeçalho `x-lexnode-signature: t=<unix>,v1=<hex>`, é um
+ * HMAC-SHA256 de `${t}.${corpo}` com o segredo. Devolve `{ ok: true,
+ * timestamp }` ou `{ ok: false, reason }`, sem lançar; responda à recusa com
+ * `webhookRejectionStatus(reason)`.
+ *
+ * Passe o corpo como chegou, nunca um JSON convertido e serializado de novo: a
+ * ordem das chaves muda e a assinatura deixa de conferir. O cabeçalho
+ * `x-lexnode-timestamp`, quando vem, precisa repetir o `t` da assinatura.
  */
 export declare function verifyWebhookSignature(rawBody: WebhookRawBody, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): WebhookVerification;
-/** O envelope comum a toda entrega. */
+/** Os campos comuns a toda entrega. */
 export interface WebhookEventEnvelope {
+    /**
+     * O id do evento. A mesma entrega pode chegar mais de uma vez: use o id para
+     * descartar a repetida.
+     */
     id: string;
+    /** Quando o evento ocorreu (ISO 8601). */
     occurredAt: string;
+    /** O projeto da conta a que o evento pertence, quando houver. */
     projectId: string | null;
+    /** O monitor que produziu o evento, quando houver. */
     monitorId: string | null;
 }
-/** Sinal compacto de suspensão de prazo — nível, termos e trecho. */
+/**
+ * O indício de suspensão de prazo no teor da publicação: o nível de
+ * confiança, os termos encontrados e o trecho.
+ */
 export interface SuspensionSignal {
     confidence: "HIGH" | "MEDIUM" | "LOW";
     keywords: string[];
     excerpt: string;
 }
-/** A data-limite do índice da fonte que qualifica um `total: 0`. */
+/**
+ * Até quando o índice da fonte processual foi lido no tribunal: a data com
+ * que um `total: 0` se distingue de um atraso.
+ */
 export interface ProcessSourceIndex {
     tribunalAlias: string;
     updatedThrough: string | null;
     checkedAt: string;
 }
-/** Quantos movimentos novos de um grau a captura anunciou. */
+/** Quantos movimentos novos de um grau chegaram na atualização. */
 export interface ProcessMovementInstanceCount {
     /** A sigla do grau (G1, G2, JE, TR…); nula quando a fonte não a declara. */
     degree: string | null;
@@ -92,23 +123,22 @@ export interface ProcessMovementInstanceCount {
     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`.
+ * O aviso de movimentação nova num processo assinado: um por assinatura e por
+ * atualização do processo, descrito pelo movimento novo mais recente, cuja
+ * chave é `latestMovementKey`.
  */
 export interface ProcessMovementCreatedPayload {
     canonicalProcessId: string;
     tribunalAlias: string;
     processNumber: string;
-    /** O ponteiro que o consumidor informou ao assinar o processo. */
+    /** A referência que você informou ao assinar o processo. */
     externalRef: string | null;
     newMovementCount: number;
     latestMovementKey: string;
     /**
-     * O que a movimentação mais recente É: o código da Tabela Processual
-     * Unificada e o nome do ato como a fonte o escreve. Nulos quando a fonte não
-     * os declara. É por eles que um aviso diz o que aconteceu sem reler a
-     * listagem de movimentações a cada evento.
+     * O código da movimentação mais recente na Tabela Processual Unificada e o
+     * nome do ato como a fonte o escreve; `null` quando a fonte não os declara.
+     * Com eles, o aviso diz o que aconteceu sem reler a lista de movimentações.
      */
     latestMovementCode?: number | null;
     latestMovementLabel?: string | null;
@@ -125,31 +155,32 @@ export interface ProcessMovementCreatedPayload {
      */
     instances?: ProcessMovementInstanceCount[];
     /**
-     * Presente quando o processo não é compartilhável: o aviso diz que ele andou
-     * e não diz o quê nem em que grau, porque ali o nome do ato é teor.
+     * Presente quando o processo não é compartilhável: o aviso diz que ele andou,
+     * sem dizer o quê nem em que grau, porque o nome do ato faz parte do 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`.
+ * turma recursal…). O histórico desse grau não sai movimento a movimento em
+ * `PROCESS_MOVEMENT_CREATED`: este aviso 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. */
+    /** A referência que você 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;
+    /** O órgão julgador do grau novo. */
     courtBody: string | null;
-    /** Quantos movimentos o grau trouxe na captura que o descobriu. */
+    /** Quantos movimentos o grau trouxe quando apareceu. */
     movementCount: number;
-    /** Quantos deles entraram no acervo sem aviso próprio. */
+    /** Quantos deles não saíram em aviso próprio. */
     historyMovementCount: number;
     /**
      * Quantos deles saíram também em `PROCESS_MOVEMENT_CREATED`: os datados
@@ -173,7 +204,7 @@ export interface ProcessInstanceDiscoveredWithheldPayload {
     externalRef: string | null;
     contentWithheld: true;
 }
-/** Um grau do número como a varredura da vigília de processo o deixou. */
+/** Um grau do processo como a última varredura do monitor o encontrou. */
 export interface MonitorSyncInstance {
     degree: string | null;
     /** O documento da fonte deste grau — o `sourceId` dele em `instances`. */
@@ -183,24 +214,25 @@ export interface MonitorSyncInstance {
     courtBody: string | null;
     sourceUpdatedAt: string | null;
     latestMovementAt: string | null;
-    /** Nulo quando os movimentos deste grau nunca foram capturados. */
+    /** `null` 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;
 }
+/** Uma publicação nova achada por um monitor de OAB, termo, parte ou CNPJ. */
 export interface PublicationCreatedPayload {
     monitorId: string;
     officeId: string | null;
     publicationKey: string;
     processNumber: string;
     formattedProcessNumber: string;
-    /** `null` quando o diário devolveu sigla que o catálogo do CNJ não cobre. */
+    /** `null` quando o diário devolveu sigla que o catálogo de tribunais não cobre. */
     tribunalAlias: string | null;
     tribunalCode: string | null;
     availableAt: string | null;
     sourceUrl: string | null;
     type: string;
-    /** Prévia do teor; `null` quando o gate reteve. */
+    /** Prévia do teor; `null` quando o controle de confidencialidade o reteve. */
     excerpt: string | null;
     suspensionSignal: SuspensionSignal | null;
     /** Presente só quando o teor foi retido no instante do envio. */
@@ -210,14 +242,23 @@ export interface PublicationCreatedPayload {
     /** Só na vigília por nome de parte. */
     partyName?: string;
     partyRole?: string | null;
-    /** Só na vigília por CNPJ: o literal vigiado — o documento pontuado
-     *  inteiro, ou a raiz `NN.NNN.NNN` quando `includeBranches`. */
+    /**
+     * Só na vigília por CNPJ: o que é vigiado — o CNPJ pontuado inteiro, ou a
+     * raiz `NN.NNN.NNN` com `includeBranches`.
+     */
     partyDocument?: string;
+    /** Só na vigília por CNPJ: se a vigília alcança matriz e filiais. */
     includeBranches?: boolean;
-    /** `document`: o CNPJ consta no teor — a empresa foi citada no ato, seja
-     *  ou não parte. */
+    /**
+     * `document`: o CNPJ consta no teor — a empresa foi citada no ato, sendo
+     * parte ou não.
+     */
     matchedBy?: "document";
 }
+/**
+ * O resultado de uma varredura do monitor. O monitor de processo emite um a
+ * cada varredura, com ou sem novidade (`changed`).
+ */
 export interface MonitorSyncSucceededPayload {
     monitorId: string;
     officeId: string | null;
@@ -249,16 +290,15 @@ export interface MonitorSyncSucceededPayload {
      * datas, e sem `instances`.
      */
     contentWithheld?: true;
-    /** O alvo que a fonte não indexava passou a existir nesta passada. */
+    /** O processo que a fonte ainda não mostrava apareceu nesta varredura. */
     firstAppearance?: true;
-    /** A vigília de aparição segue esperando o alvo entrar no índice. */
+    /** O monitor segue esperando o processo aparecer no índice da fonte. */
     awaitingAppearance?: true;
     indexUpdatedThrough?: string | null;
     expectedFrom?: string | null;
     /**
-     * Varredura de diário: os EXTREMOS do que a passada abriu de fato. `null`
-     * quando o ciclo não abriu fatia nenhuma — anunciar uma janela nesse caso
-     * seria dizer que leu o que não leu.
+     * Varredura de diário: a primeira e a última data que a varredura leu de
+     * fato; `null` quando ela não leu nenhuma.
      */
     availableFrom?: string | null;
     availableTo?: string | null;
@@ -266,17 +306,17 @@ export interface MonitorSyncSucceededPayload {
     pagesFetched?: number;
     publicationsSeen?: number;
     coveredThrough?: string;
-    /** Onde a próxima passada retoma: o dia e a página. `null` quando fechou. */
+    /** Onde a próxima varredura retoma, o dia e a página; `null` ao terminar. */
     resumesAt?: {
         day: string;
         page: number;
     } | null;
     pendingDays?: number;
     /**
-     * Fatias encerradas sem leitura completa, como chaves `AAAA-MM-DD#SIGLA`
-     * (sem a sigla no dia não dividido). `volumeCapped` é o dia grande demais,
-     * com cauda por ler; `refusedDays` é o que a fonte recusa em definitivo.
-     * Separá-los do dia lido por inteiro é a razão de os campos existirem.
+     * Os dias encerrados sem leitura completa, como `AAAA-MM-DD#SIGLA` (sem a
+     * sigla quando o dia não foi dividido por tribunal). `volumeCapped` traz os
+     * dias grandes demais, com parte por ler; `refusedDays`, os que a fonte
+     * recusa em definitivo.
      */
     volumeCapped?: string[];
     refusedDays?: string[];
@@ -286,16 +326,19 @@ export interface MonitorSyncSucceededPayload {
     includeBranches?: boolean;
     publicationsMatched?: number;
 }
+/** A falha de uma varredura do monitor. */
 export interface MonitorSyncFailedPayload {
     monitorId: string;
     officeId: string | null;
+    /** A descrição da falha. */
     error: string;
     code: string;
     class: "RETRYABLE" | "TERMINAL";
     retryable: boolean;
-    /** O que o ciclo alcançou antes da recusa, quando houve ciclo. */
+    /** O que a varredura alcançou antes da falha, quando chegou a ler algo. */
     coverage?: Record<string, unknown>;
 }
+/** O fim de uma busca enfileirada que concluiu. */
 export interface SearchJobSucceededPayload {
     jobId: string;
     status: "SUCCEEDED";
@@ -308,6 +351,7 @@ export interface SearchJobSucceededPayload {
     processNumbers: string[];
     pollUrl: string;
 }
+/** O fim de uma busca enfileirada que falhou. */
 export interface SearchJobFailedPayload {
     jobId: string;
     status: "FAILED";
@@ -324,11 +368,10 @@ 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.
+ * O fim de uma consulta em segundo plano (`POST /v1/processes/lookups`). O
+ * evento aponta a consulta e nunca traz o processo: leia-o em `pollUrl`, sem
+ * nova cobrança e pelo controle de confidencialidade de quem lê. A
+ * movimentação nova que a entrega trouxer chega em `PROCESS_MOVEMENT_CREATED`.
  */
 interface ProcessLookupCompletedBase {
     lookupId: string;
@@ -338,19 +381,26 @@ interface ProcessLookupCompletedBase {
     processNumber: string;
     officeId: string | null;
     traceId: string | null;
-    /** Idas à fonte, a leitura que abriu a consulta incluída. */
+    /**
+     * Quantas vezes a fonte foi consultada, contando a leitura que abriu a
+     * consulta.
+     */
     attempts: number;
     pollUrl: string;
 }
+/** O fim de uma consulta em segundo plano que entregou o processo. */
 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.
+     * Quem entregou: `SOURCE`, a fonte; `LAKE`, a cópia guardada que outra
+     * leitura atualizou; ou `DIRECT_READ`, uma leitura direta sua, que já cobrou
+     * — então esta não cobra.
      */
     satisfiedBy: "SOURCE" | "LAKE" | "DIRECT_READ";
+    /** Os créditos cobrados pela entrega. */
     creditsCharged: number;
 }
+/** O fim de uma consulta em segundo plano que terminou sem o processo. */
 export interface ProcessLookupFailedPayload extends ProcessLookupCompletedBase {
     status: "FAILED";
     satisfiedBy: null;
@@ -359,12 +409,13 @@ export interface ProcessLookupFailedPayload extends ProcessLookupCompletedBase {
     error: {
         class: "RETRYABLE" | "TERMINAL";
         code: string;
-        /** O texto público fixo do código. */
+        /** A mensagem fixa do código. */
         message: string;
         retryable: boolean;
         upstreamStatus?: number;
     };
 }
+/** Uma publicação nova que casou com a vigília de texto. */
 export interface PublicationTextAlertMatch {
     source: string;
     publicationKey: string;
@@ -374,6 +425,7 @@ export interface PublicationTextAlertMatch {
     /** Presente só quando o teor deste item foi retido no envio. */
     contentWithheld?: true;
 }
+/** As publicações novas que casaram com uma vigília de texto. */
 export interface PublicationTextAlertMatchedPayload {
     alertId: string;
     externalRef: string | null;
@@ -382,6 +434,10 @@ export interface PublicationTextAlertMatchedPayload {
     totalNew: number;
     matches: PublicationTextAlertMatch[];
 }
+/**
+ * O fim de uma colheita pedida em
+ * `POST /v1/publications/corpus/harvest-requests`.
+ */
 export interface PublicationHarvestCompletedPayload {
     sliceId: string;
     tribunalSigla: string;
@@ -389,6 +445,7 @@ export interface PublicationHarvestCompletedPayload {
     seedTerm: string | null;
     itemsIndexable: number;
 }
+/** O aviso de saldo de créditos baixo no período. */
 export interface QuotaLowPayload {
     usedCredits: number;
     limitCredits: number;
@@ -399,19 +456,21 @@ export interface QuotaLowPayload {
     periodStart: string;
     periodEnd: string;
 }
+/** O aviso de fim próximo do período do plano. */
 export interface PeriodEndingPayload {
     planCode: string;
     periodEnd: string;
     daysRemaining: number;
 }
+/** O aviso de pagamento da assinatura do plano em atraso. */
 export interface SubscriptionPastDuePayload {
     status: string;
     planCode: string;
     currentPeriodEnd: string | null;
 }
 /**
- * A entrega sintética do teste de conectividade do endpoint. O motor a manda a
- * pedido, com a mesma assinatura de um evento real.
+ * A entrega de teste do endpoint, enviada a pedido e assinada como um evento
+ * real.
  */
 export interface WebhookTestPayload {
     message: string;
@@ -420,51 +479,83 @@ type Typed<T extends string, P> = WebhookEventEnvelope & {
     type: T;
     payload: P;
 };
-/** Os tipos do catálogo e a entrega de teste, discriminados por `type`. */
+/**
+ * Os eventos do catálogo deste pacote 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.
- *
- * Tipo novo é coisa a ignorar, nunca exceção: o receptor precisa responder 2xx
- * para o motor não entrar na curva de reentrega por uma novidade inofensiva.
+ * Um evento de tipo que este pacote ainda não descreve. Responda 2xx e
+ * ignore-o: sem o 2xx, a entrega é repetida.
  */
 export type UnknownWebhookEvent = WebhookEventEnvelope & {
     type: string;
     payload: unknown;
 };
+/** Os tipos de `WebhookEvent`, inclusive a entrega de teste. */
 export type WebhookEventType = WebhookEvent["type"];
 /**
- * A entrega de teste, que o endpoint recebe sem assinar.
+ * O tipo da entrega de teste, `WEBHOOK_TEST`.
  *
- * Ela é o PRIMEIRO corpo que um receptor novo vê — o botão de testar
- * conectividade existe para ser apertado antes do primeiro evento real. Por
- * isso está na união (quem faz `switch (event.type)` precisa enxergá-la) e
- * fora do catálogo assinável (não se pede, não se recusa, chega a qualquer
- * endpoint).
+ * Ela chega a qualquer endpoint sem constar de `eventTypes` — o tipo nem
+ * entra nessa lista ao cadastrar um endpoint — e costuma ser o primeiro corpo
+ * que um receptor novo recebe: trate-a no seu `switch (event.type)`.
  */
 export declare const WEBHOOK_TEST_EVENT_TYPE: "WEBHOOK_TEST";
-/** Os tipos que se pode ASSINAR ao cadastrar um endpoint. */
+/** Os tipos de evento que um endpoint pode assinar em `eventTypes`. */
 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.
+ * Um tipo de evento que se pode assinar em `eventTypes`. A entrega de teste
+ * fica de fora: mandá-la nessa lista é recusado.
  */
 export type SubscribableWebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
-/** Se o tipo está no catálogo que este pacote descreve. */
+/** Diz se o tipo está no catálogo de eventos que este pacote descreve. */
 export declare function isKnownWebhookEventType(type: string): type is WebhookEventType;
-/** Se este evento é a entrega de teste, e não um fato do acervo. */
+/** Diz se o evento é a entrega de teste. */
 export declare function isWebhookTest(event: WebhookEvent): event is Extract<WebhookEvent, {
     type: "WEBHOOK_TEST";
 }>;
+/**
+ * O status HTTP com que o seu receptor responde a uma entrega recusada.
+ *
+ * 401 para a assinatura ausente, malformada, fora da tolerância ou que não
+ * confere; 400 para JSON ou formato de evento inválido; 503 para o segredo
+ * não configurado no receptor; 500 para o corpo já convertido de JSON. Os dois
+ * últimos são defeitos do receptor (`isReceiverFault`): corrigido o defeito,
+ * as entregas repetidas passam a ser aceitas.
+ *
+ * @example
+ * ```ts
+ * if (!resultado.ok) {
+ *   return reply.status(webhookRejectionStatus(resultado.reason)).send();
+ * }
+ * ```
+ */
 export declare function webhookRejectionStatus(reason: WebhookParseRejection): number;
-/** Se a recusa é de responsabilidade do receptor, e o remetente deve voltar. */
+/**
+ * Diz se a recusa vem do próprio receptor — segredo não configurado ou corpo
+ * já convertido de JSON — e não da entrega. Nesses casos o status é 5xx.
+ */
 export declare function isReceiverFault(reason: WebhookParseRejection): boolean;
 /**
- * Confere a assinatura e devolve o evento tipado.
+ * Confere a assinatura de uma entrega e devolve o evento tipado.
+ *
+ * Depois da assinatura, confere que o corpo é um evento: JSON com `id`,
+ * `type`, `occurredAt` e `payload`. Devolve `{ ok: true, known, event }` — com
+ * `known: false` para um tipo fora do catálogo deste pacote, que você deve
+ * aceitar com 2xx e ignorar — ou `{ ok: false, reason }`, sem lançar.
  *
- * A assinatura prova a ORIGEM; a conferência de forma que vem depois prova que
- * o corpo é um envelope de evento — sem ela, um corpo assinado mas malformado
- * viraria um `as` silencioso dentro do consumidor.
+ * @example
+ * ```ts
+ * const resultado = parseWebhookEvent(rawBody, request.headers, segredo);
+ * if (!resultado.ok) {
+ *   return reply.status(webhookRejectionStatus(resultado.reason)).send();
+ * }
+ * if (!resultado.known) return reply.status(200).send();
+ * if (resultado.event.type === "PUBLICATION_CREATED") {
+ *   resultado.event.payload.publicationKey;
+ * }
+ * ```
  */
 export declare function parseWebhookEvent(rawBody: WebhookRawBody, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): WebhookParseResult;
 export {};