@adatechnology/meta-whatsapp-module 0.2.0-rc.29 → 0.2.0-rc.30

package/dist/index.d.cts

@@ -1,10 +1,10 @@
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
 import * as _adatechnology_meta_whatsapp_contracts from '@adatechnology/meta-whatsapp-contracts';
-import { TranscriptionMode, SessionState, SessionMode, ConversationSummary, MessageDirection, MessageSender, MessageStatus, CacheInterface, FlowGraphData, FlowGraphSummary, LiveFlowPosition, WhatsAppSettings, RealtimeNotifierInterface, ChannelAdapterInterface, ObjectStorageInterface, FlowActionKind, FlowActionHandler, ConversationSession, MetaWhatsAppHooks, SubjectResolverInterface, CatalogPort } from '@adatechnology/meta-whatsapp-contracts';
+import { TranscriptionMode, SessionState, SessionMode, ConversationSummary, MessageDirection, MessageSender, MessageStatus, CacheInterface, FlowGraphData, FlowGraphSummary, LiveFlowPosition, WhatsAppSettings, RealtimeNotifierInterface, ChannelAdapterInterface, ObjectStorageInterface, FlowActionKind, FlowActionHandler, ConversationSession, WhatsAppMessage, WhatsAppStatus, MetaWhatsAppHooks, SubjectResolverInterface, CatalogPort } from '@adatechnology/meta-whatsapp-contracts';
 export { PREVIEW_MEDIA_ID_PREFIX, TranscriptionMode, resolvePreviewUploadId, toPreviewMediaId } from '@adatechnology/meta-whatsapp-contracts';
 import { WhatsAppMessageProvider } from '@adatechnology/meta-whatsapp-provider';
-export { WEBHOOK_NONCE_TTL_SECONDS } from '@adatechnology/meta-graph-core';
+export { WEBHOOK_CLAIM_TTL_SECONDS, WEBHOOK_NONCE_TTL_SECONDS } from '@adatechnology/meta-graph-core';
 
 type MetaWhatsAppDatabase = PgDatabase<PgQueryResultHKT, any, any>;
 type DrizzleMigrateFunction = (db: never, config: {
@@ -2316,6 +2316,15 @@ declare class FlowMediaRepository {
 
 interface NonceStoreInterface {
     setIfAbsent(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Estende a chave já reivindicada para a janela cheia. Um SET simples, sem NX.
+     *
+     * Opcional só por compatibilidade com hosts que ainda não o implementam: sem ele o claim curto
+     * expira, e a Meta pode reentregar uma entrega já processada — trabalho repetido, que a dedupe
+     * por `waMessageId` ainda segura antes de virar efeito visível ao cliente. Implementar é o
+     * caminho correto.
+     */
+    confirm?(key: string, ttlSeconds: number): Promise<void>;
 }
 
 declare function verifyWebhookChallenge(params: {
@@ -2329,11 +2338,101 @@ declare function verifyWebhookSignature(params: {
     signatureHeader: string | null | undefined;
     appSecret: string;
 }): void;
+/**
+ * Reivindica a entrega por pouco tempo. O par obrigatório é `confirmWebhookDelivery` ao fim do
+ * processamento — ver `WEBHOOK_CLAIM_TTL_SECONDS` para o porquê dos dois tempos.
+ */
 declare function claimWebhookDelivery(params: {
     nonceStore: NonceStoreInterface;
     signatureHeader: string;
     ttlSeconds?: number;
 }): Promise<boolean>;
+/** Só depois da entrega processada por inteiro: é isto que fecha a janela anti-replay. */
+declare function confirmWebhookDelivery(params: {
+    nonceStore: NonceStoreInterface;
+    signatureHeader: string;
+    ttlSeconds?: number;
+}): Promise<void>;
+
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * Separa a entrega do webhook em duas metades: o que precisa acontecer antes de responder à Meta
+ * (persistir a mensagem, que é escrita local e rápida) e o que pode esperar alguns milissegundos
+ * (os hooks do host, que costumam falar com rede — motor de fluxo, IA, integrações).
+ *
+ * A segunda metade rodava dentro da requisição do webhook. Um deploy no meio de uma conversa
+ * matava a chamada em voo, e o cliente ficava sem resposta sem que nada registrasse a perda. Com
+ * uma fila no host, derrubar o processo vira atraso: o job espera e é retomado.
+ */
+
+type InboundMediaDescriptor = {
+    sourceMediaId: string;
+    mimeType: string;
+    filename?: string;
+};
+type InboundMessageEffectsJob = {
+    kind: 'message';
+    companyId: string;
+    message: WhatsAppMessage;
+    savedMessageId: string;
+    media?: InboundMediaDescriptor;
+    receivedAt: number;
+};
+type InboundStatusEffectsJob = {
+    kind: 'status';
+    companyId: string;
+    status: WhatsAppStatus;
+    whatsappNumber: string;
+    receivedAt: number;
+};
+type InboundDispatchJob = InboundMessageEffectsJob | InboundStatusEffectsJob;
+/**
+ * Porta de fila. O módulo não escolhe a tecnologia — BullMQ, SQS, o que o host já tiver — mas
+ * exige dela duas garantias, e sem as duas o padrão não entrega o que promete:
+ *
+ * 1. **Durabilidade**: o job sobrevive à morte do processo que o enfileirou. Uma fila em memória
+ *    reintroduz exatamente a perda que este desenho existe para evitar.
+ * 2. **Retentativa com backoff**: o destino dos hooks (n8n, IA, API de terceiro) também cai em
+ *    deploy. Sem retry, o job falha uma vez e a conversa morre do mesmo jeito.
+ *
+ * `jobId` é estável e derivado da mensagem: reentrega da Meta e re-enfileiramento produzem o mesmo
+ * id, e a fila descarta o segundo em vez de rodar o efeito duas vezes.
+ */
+interface InboundDispatchQueueInterface {
+    enqueue(job: InboundDispatchJob, options: {
+        jobId: string;
+    }): Promise<void>;
+}
+declare function buildInboundJobId(job: InboundDispatchJob): string;
+declare function toSessionContract(row: SessionRow): ConversationSession;
+/**
+ * Os efeitos de host de uma entrega já persistida. Vive fora do `ReceiveWebhookUseCase` porque
+ * roda nos dois lados: inline, quando o host não configurou fila, e dentro do worker, quando
+ * configurou. Um só corpo de regra para os dois caminhos — duas cópias divergiriam.
+ */
+declare class InboundEffectsDispatcher {
+    private readonly params;
+    constructor(params: {
+        sessionRepository: SessionRepository;
+        hooks?: MetaWhatsAppHooks;
+        realtime?: RealtimeNotifierInterface;
+    });
+    run(job: InboundDispatchJob): Promise<void>;
+    runMessageEffects(job: InboundMessageEffectsJob): Promise<void>;
+    runStatusEffects(job: InboundStatusEffectsJob): Promise<void>;
+}
+/**
+ * Ponto de entrada do worker do host: recebe o job que a fila devolveu e roda os efeitos.
+ *
+ * Deixe a exceção propagar. É ela que faz a fila contar a tentativa e reagendar com backoff;
+ * capturar aqui para logar transforma falha recuperável em mensagem perdida em silêncio.
+ */
+declare class ProcessInboundDispatchUseCase {
+    private readonly dispatcher;
+    constructor(dispatcher: InboundEffectsDispatcher);
+    execute(job: InboundDispatchJob): Promise<void>;
+}
 
 type ReceiveWebhookParams = {
     companyId: string;
@@ -2358,10 +2457,17 @@ declare class ReceiveWebhookUseCase {
         startState: SessionState;
         hooks?: MetaWhatsAppHooks;
         realtime?: RealtimeNotifierInterface;
+        /**
+         * Sem fila o módulo se comporta como sempre: os hooks rodam dentro da requisição do webhook.
+         * Configurá-la é o que faz a conversa sobreviver a um deploy no meio do atendimento.
+         */
+        inboundQueue?: InboundDispatchQueueInterface;
     });
+    private readonly dispatcher;
     execute(input: ReceiveWebhookParams): Promise<ReceiveWebhookResult>;
     private handleMessage;
     private handleStatus;
+    private dispatch;
 }
 
 /**
@@ -2895,4 +3001,4 @@ type CreateSendProductListActionParams = {
  */
 declare function createSendProductListAction(params: CreateSendProductListActionParams): FlowActionHandler;
 
-export { type AttachFlowMediaParams, type AudioTranscriber, type CompanyDocumentView, type CompanyDocumentsPage, type ConversationDocumentView, type ConversationDocumentsPage, type CreateFlowGraphParams, CreateFlowGraphUseCase, type CreateMetaWhatsAppModuleParams, type CreateSendMediaActionParams, type CreateSendProductListActionParams, DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS, type DeleteConversationParams, type DeleteConversationResult, DeleteConversationUseCase, DeleteFlowGraphUseCase, DocumentRepository, type DocumentRow, type DrizzleMigrateFunction, type ExportConversationParams, type ExportConversationResult, ExportConversationUseCase, FlowGraphCache, FlowGraphRepository, type FlowGraphRow, FlowInterpreter, type FlowMediaLocation, FlowMediaRepository, type FlowMediaRow, type FlowMediaTranscriptLogger, type FlowRunResult, type FlowStepInput, type FlowStepResult, GetFlowGraphUseCase, GetLiveFlowPositionsUseCase, type IngestInboundMediaParams, type IngestInboundMediaResult, IngestInboundMediaUseCase, type IngestTranscriptionOptions, type InsertMessageParams, InvalidFlowGraphError, type LinkDocumentParams, type ListCompanyDocumentsParams, ListCompanyDocumentsUseCase, type ListConversationDocumentsParams, ListConversationDocumentsUseCase, type ListConversationsFilters, type ListConversationsParams, ListConversationsUseCase, type ListDocumentsParams, type ListDocumentsResult, ListFlowGraphsUseCase, type ListMessagesParams, ListMessagesUseCase, type LogMessageParams, LogMessageUseCase, META_WHATSAPP_MIGRATIONS_TABLE, type MessageModerator, MessageRepository, type MessageRow, type MetaWhatsAppDatabase, type MetaWhatsAppModule, type MetaWhatsAppModuleConfig, type MetaWhatsAppModuleFeatures, type MetaWhatsAppModuleProviders, type MetaWhatsAppTranscriptionConfig, type NewDocumentRow, type NewFlowGraphRow, type NewFlowMediaRow, type NewMessageRow, type NewSessionRow, type NewSettingsRow, type NonceStoreInterface, OptimisticLockError, PRODUCT_LIST_LIMIT, type PreviewMediaSupport, type PurgeExpiredDocumentsParams, type PurgeExpiredDocumentsResult, PurgeExpiredDocumentsUseCase, type RealtimeRelay, type ReceiveWebhookParams, type ReceiveWebhookResult, ReceiveWebhookUseCase, type ReleaseConversationParams, ReleaseConversationUseCase, type ListMessagesParams$1 as RepositoryListMessagesParams, type ResolveTranscriptionPolicyDependencies, type RunMetaWhatsAppMigrationsParams, type SaveFlowGraphParams, SaveFlowGraphUseCase, type SaveTranscriptionByWaMessageIdParams, type SaveTranscriptionParams, type SendMediaParams, SendMessageUseCase, type SendTemplateParams, type SendTextParams, SessionRepository, type SessionRow, SettingsRepository, type SettingsRow, SseHub, type SseListener, type StorePreviewMediaParams, type StorePreviewMediaResult, StorePreviewMediaUseCase, TRANSCRIPTION_MODE, TRANSCRIPTION_STATUS, type TakeoverConversationParams, TakeoverConversationUseCase, type TicketStoreInterface, type TranscribeAudioDependencies, type TranscribeAudioParams, type TranscribeAudioResult, TranscribeAudioUseCase, type TranscriptionPolicy, type TranscriptionPolicyDefaults, type TranscriptionPolicyResolver, type TranscriptionStatus, type UpdateFlowMediaParams, WhatsAppChannelAdapter, claimWebhookDelivery, createMetaWhatsAppModule, createSendMediaAction, createSendProductListAction, createTranscriptionPolicyResolver, documents, extractMediaDescriptor, flowGraphs, flowMedia, isAudioMimeType, isRetriableTranscriptionError, isUnsupportedTranscriptionError, issueSseTicket, messages, metaWhatsAppMigrationsFolder, metaWhatsAppSchema, redeemSseTicket, resolveFailureStatus, runMetaWhatsAppMigrations, sessions, settings, transcriptionRetryAfterSeconds, verifyWebhookChallenge, verifyWebhookSignature };
+export { type AttachFlowMediaParams, type AudioTranscriber, type CompanyDocumentView, type CompanyDocumentsPage, type ConversationDocumentView, type ConversationDocumentsPage, type CreateFlowGraphParams, CreateFlowGraphUseCase, type CreateMetaWhatsAppModuleParams, type CreateSendMediaActionParams, type CreateSendProductListActionParams, DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS, type DeleteConversationParams, type DeleteConversationResult, DeleteConversationUseCase, DeleteFlowGraphUseCase, DocumentRepository, type DocumentRow, type DrizzleMigrateFunction, type ExportConversationParams, type ExportConversationResult, ExportConversationUseCase, FlowGraphCache, FlowGraphRepository, type FlowGraphRow, FlowInterpreter, type FlowMediaLocation, FlowMediaRepository, type FlowMediaRow, type FlowMediaTranscriptLogger, type FlowRunResult, type FlowStepInput, type FlowStepResult, GetFlowGraphUseCase, GetLiveFlowPositionsUseCase, type InboundDispatchJob, type InboundDispatchQueueInterface, InboundEffectsDispatcher, type InboundMediaDescriptor, type InboundMessageEffectsJob, type InboundStatusEffectsJob, type IngestInboundMediaParams, type IngestInboundMediaResult, IngestInboundMediaUseCase, type IngestTranscriptionOptions, type InsertMessageParams, InvalidFlowGraphError, type LinkDocumentParams, type ListCompanyDocumentsParams, ListCompanyDocumentsUseCase, type ListConversationDocumentsParams, ListConversationDocumentsUseCase, type ListConversationsFilters, type ListConversationsParams, ListConversationsUseCase, type ListDocumentsParams, type ListDocumentsResult, ListFlowGraphsUseCase, type ListMessagesParams, ListMessagesUseCase, type LogMessageParams, LogMessageUseCase, META_WHATSAPP_MIGRATIONS_TABLE, type MessageModerator, MessageRepository, type MessageRow, type MetaWhatsAppDatabase, type MetaWhatsAppModule, type MetaWhatsAppModuleConfig, type MetaWhatsAppModuleFeatures, type MetaWhatsAppModuleProviders, type MetaWhatsAppTranscriptionConfig, type NewDocumentRow, type NewFlowGraphRow, type NewFlowMediaRow, type NewMessageRow, type NewSessionRow, type NewSettingsRow, type NonceStoreInterface, OptimisticLockError, PRODUCT_LIST_LIMIT, type PreviewMediaSupport, ProcessInboundDispatchUseCase, type PurgeExpiredDocumentsParams, type PurgeExpiredDocumentsResult, PurgeExpiredDocumentsUseCase, type RealtimeRelay, type ReceiveWebhookParams, type ReceiveWebhookResult, ReceiveWebhookUseCase, type ReleaseConversationParams, ReleaseConversationUseCase, type ListMessagesParams$1 as RepositoryListMessagesParams, type ResolveTranscriptionPolicyDependencies, type RunMetaWhatsAppMigrationsParams, type SaveFlowGraphParams, SaveFlowGraphUseCase, type SaveTranscriptionByWaMessageIdParams, type SaveTranscriptionParams, type SendMediaParams, SendMessageUseCase, type SendTemplateParams, type SendTextParams, SessionRepository, type SessionRow, SettingsRepository, type SettingsRow, SseHub, type SseListener, type StorePreviewMediaParams, type StorePreviewMediaResult, StorePreviewMediaUseCase, TRANSCRIPTION_MODE, TRANSCRIPTION_STATUS, type TakeoverConversationParams, TakeoverConversationUseCase, type TicketStoreInterface, type TranscribeAudioDependencies, type TranscribeAudioParams, type TranscribeAudioResult, TranscribeAudioUseCase, type TranscriptionPolicy, type TranscriptionPolicyDefaults, type TranscriptionPolicyResolver, type TranscriptionStatus, type UpdateFlowMediaParams, WhatsAppChannelAdapter, buildInboundJobId, claimWebhookDelivery, confirmWebhookDelivery, createMetaWhatsAppModule, createSendMediaAction, createSendProductListAction, createTranscriptionPolicyResolver, documents, extractMediaDescriptor, flowGraphs, flowMedia, isAudioMimeType, isRetriableTranscriptionError, isUnsupportedTranscriptionError, issueSseTicket, messages, metaWhatsAppMigrationsFolder, metaWhatsAppSchema, redeemSseTicket, resolveFailureStatus, runMetaWhatsAppMigrations, sessions, settings, toSessionContract, transcriptionRetryAfterSeconds, verifyWebhookChallenge, verifyWebhookSignature };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
 import * as _adatechnology_meta_whatsapp_contracts from '@adatechnology/meta-whatsapp-contracts';
-import { TranscriptionMode, SessionState, SessionMode, ConversationSummary, MessageDirection, MessageSender, MessageStatus, CacheInterface, FlowGraphData, FlowGraphSummary, LiveFlowPosition, WhatsAppSettings, RealtimeNotifierInterface, ChannelAdapterInterface, ObjectStorageInterface, FlowActionKind, FlowActionHandler, ConversationSession, MetaWhatsAppHooks, SubjectResolverInterface, CatalogPort } from '@adatechnology/meta-whatsapp-contracts';
+import { TranscriptionMode, SessionState, SessionMode, ConversationSummary, MessageDirection, MessageSender, MessageStatus, CacheInterface, FlowGraphData, FlowGraphSummary, LiveFlowPosition, WhatsAppSettings, RealtimeNotifierInterface, ChannelAdapterInterface, ObjectStorageInterface, FlowActionKind, FlowActionHandler, ConversationSession, WhatsAppMessage, WhatsAppStatus, MetaWhatsAppHooks, SubjectResolverInterface, CatalogPort } from '@adatechnology/meta-whatsapp-contracts';
 export { PREVIEW_MEDIA_ID_PREFIX, TranscriptionMode, resolvePreviewUploadId, toPreviewMediaId } from '@adatechnology/meta-whatsapp-contracts';
 import { WhatsAppMessageProvider } from '@adatechnology/meta-whatsapp-provider';
-export { WEBHOOK_NONCE_TTL_SECONDS } from '@adatechnology/meta-graph-core';
+export { WEBHOOK_CLAIM_TTL_SECONDS, WEBHOOK_NONCE_TTL_SECONDS } from '@adatechnology/meta-graph-core';
 
 type MetaWhatsAppDatabase = PgDatabase<PgQueryResultHKT, any, any>;
 type DrizzleMigrateFunction = (db: never, config: {
@@ -2316,6 +2316,15 @@ declare class FlowMediaRepository {
 
 interface NonceStoreInterface {
     setIfAbsent(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Estende a chave já reivindicada para a janela cheia. Um SET simples, sem NX.
+     *
+     * Opcional só por compatibilidade com hosts que ainda não o implementam: sem ele o claim curto
+     * expira, e a Meta pode reentregar uma entrega já processada — trabalho repetido, que a dedupe
+     * por `waMessageId` ainda segura antes de virar efeito visível ao cliente. Implementar é o
+     * caminho correto.
+     */
+    confirm?(key: string, ttlSeconds: number): Promise<void>;
 }
 
 declare function verifyWebhookChallenge(params: {
@@ -2329,11 +2338,101 @@ declare function verifyWebhookSignature(params: {
     signatureHeader: string | null | undefined;
     appSecret: string;
 }): void;
+/**
+ * Reivindica a entrega por pouco tempo. O par obrigatório é `confirmWebhookDelivery` ao fim do
+ * processamento — ver `WEBHOOK_CLAIM_TTL_SECONDS` para o porquê dos dois tempos.
+ */
 declare function claimWebhookDelivery(params: {
     nonceStore: NonceStoreInterface;
     signatureHeader: string;
     ttlSeconds?: number;
 }): Promise<boolean>;
+/** Só depois da entrega processada por inteiro: é isto que fecha a janela anti-replay. */
+declare function confirmWebhookDelivery(params: {
+    nonceStore: NonceStoreInterface;
+    signatureHeader: string;
+    ttlSeconds?: number;
+}): Promise<void>;
+
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * Separa a entrega do webhook em duas metades: o que precisa acontecer antes de responder à Meta
+ * (persistir a mensagem, que é escrita local e rápida) e o que pode esperar alguns milissegundos
+ * (os hooks do host, que costumam falar com rede — motor de fluxo, IA, integrações).
+ *
+ * A segunda metade rodava dentro da requisição do webhook. Um deploy no meio de uma conversa
+ * matava a chamada em voo, e o cliente ficava sem resposta sem que nada registrasse a perda. Com
+ * uma fila no host, derrubar o processo vira atraso: o job espera e é retomado.
+ */
+
+type InboundMediaDescriptor = {
+    sourceMediaId: string;
+    mimeType: string;
+    filename?: string;
+};
+type InboundMessageEffectsJob = {
+    kind: 'message';
+    companyId: string;
+    message: WhatsAppMessage;
+    savedMessageId: string;
+    media?: InboundMediaDescriptor;
+    receivedAt: number;
+};
+type InboundStatusEffectsJob = {
+    kind: 'status';
+    companyId: string;
+    status: WhatsAppStatus;
+    whatsappNumber: string;
+    receivedAt: number;
+};
+type InboundDispatchJob = InboundMessageEffectsJob | InboundStatusEffectsJob;
+/**
+ * Porta de fila. O módulo não escolhe a tecnologia — BullMQ, SQS, o que o host já tiver — mas
+ * exige dela duas garantias, e sem as duas o padrão não entrega o que promete:
+ *
+ * 1. **Durabilidade**: o job sobrevive à morte do processo que o enfileirou. Uma fila em memória
+ *    reintroduz exatamente a perda que este desenho existe para evitar.
+ * 2. **Retentativa com backoff**: o destino dos hooks (n8n, IA, API de terceiro) também cai em
+ *    deploy. Sem retry, o job falha uma vez e a conversa morre do mesmo jeito.
+ *
+ * `jobId` é estável e derivado da mensagem: reentrega da Meta e re-enfileiramento produzem o mesmo
+ * id, e a fila descarta o segundo em vez de rodar o efeito duas vezes.
+ */
+interface InboundDispatchQueueInterface {
+    enqueue(job: InboundDispatchJob, options: {
+        jobId: string;
+    }): Promise<void>;
+}
+declare function buildInboundJobId(job: InboundDispatchJob): string;
+declare function toSessionContract(row: SessionRow): ConversationSession;
+/**
+ * Os efeitos de host de uma entrega já persistida. Vive fora do `ReceiveWebhookUseCase` porque
+ * roda nos dois lados: inline, quando o host não configurou fila, e dentro do worker, quando
+ * configurou. Um só corpo de regra para os dois caminhos — duas cópias divergiriam.
+ */
+declare class InboundEffectsDispatcher {
+    private readonly params;
+    constructor(params: {
+        sessionRepository: SessionRepository;
+        hooks?: MetaWhatsAppHooks;
+        realtime?: RealtimeNotifierInterface;
+    });
+    run(job: InboundDispatchJob): Promise<void>;
+    runMessageEffects(job: InboundMessageEffectsJob): Promise<void>;
+    runStatusEffects(job: InboundStatusEffectsJob): Promise<void>;
+}
+/**
+ * Ponto de entrada do worker do host: recebe o job que a fila devolveu e roda os efeitos.
+ *
+ * Deixe a exceção propagar. É ela que faz a fila contar a tentativa e reagendar com backoff;
+ * capturar aqui para logar transforma falha recuperável em mensagem perdida em silêncio.
+ */
+declare class ProcessInboundDispatchUseCase {
+    private readonly dispatcher;
+    constructor(dispatcher: InboundEffectsDispatcher);
+    execute(job: InboundDispatchJob): Promise<void>;
+}
 
 type ReceiveWebhookParams = {
     companyId: string;
@@ -2358,10 +2457,17 @@ declare class ReceiveWebhookUseCase {
         startState: SessionState;
         hooks?: MetaWhatsAppHooks;
         realtime?: RealtimeNotifierInterface;
+        /**
+         * Sem fila o módulo se comporta como sempre: os hooks rodam dentro da requisição do webhook.
+         * Configurá-la é o que faz a conversa sobreviver a um deploy no meio do atendimento.
+         */
+        inboundQueue?: InboundDispatchQueueInterface;
     });
+    private readonly dispatcher;
     execute(input: ReceiveWebhookParams): Promise<ReceiveWebhookResult>;
     private handleMessage;
     private handleStatus;
+    private dispatch;
 }
 
 /**
@@ -2895,4 +3001,4 @@ type CreateSendProductListActionParams = {
  */
 declare function createSendProductListAction(params: CreateSendProductListActionParams): FlowActionHandler;
 
-export { type AttachFlowMediaParams, type AudioTranscriber, type CompanyDocumentView, type CompanyDocumentsPage, type ConversationDocumentView, type ConversationDocumentsPage, type CreateFlowGraphParams, CreateFlowGraphUseCase, type CreateMetaWhatsAppModuleParams, type CreateSendMediaActionParams, type CreateSendProductListActionParams, DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS, type DeleteConversationParams, type DeleteConversationResult, DeleteConversationUseCase, DeleteFlowGraphUseCase, DocumentRepository, type DocumentRow, type DrizzleMigrateFunction, type ExportConversationParams, type ExportConversationResult, ExportConversationUseCase, FlowGraphCache, FlowGraphRepository, type FlowGraphRow, FlowInterpreter, type FlowMediaLocation, FlowMediaRepository, type FlowMediaRow, type FlowMediaTranscriptLogger, type FlowRunResult, type FlowStepInput, type FlowStepResult, GetFlowGraphUseCase, GetLiveFlowPositionsUseCase, type IngestInboundMediaParams, type IngestInboundMediaResult, IngestInboundMediaUseCase, type IngestTranscriptionOptions, type InsertMessageParams, InvalidFlowGraphError, type LinkDocumentParams, type ListCompanyDocumentsParams, ListCompanyDocumentsUseCase, type ListConversationDocumentsParams, ListConversationDocumentsUseCase, type ListConversationsFilters, type ListConversationsParams, ListConversationsUseCase, type ListDocumentsParams, type ListDocumentsResult, ListFlowGraphsUseCase, type ListMessagesParams, ListMessagesUseCase, type LogMessageParams, LogMessageUseCase, META_WHATSAPP_MIGRATIONS_TABLE, type MessageModerator, MessageRepository, type MessageRow, type MetaWhatsAppDatabase, type MetaWhatsAppModule, type MetaWhatsAppModuleConfig, type MetaWhatsAppModuleFeatures, type MetaWhatsAppModuleProviders, type MetaWhatsAppTranscriptionConfig, type NewDocumentRow, type NewFlowGraphRow, type NewFlowMediaRow, type NewMessageRow, type NewSessionRow, type NewSettingsRow, type NonceStoreInterface, OptimisticLockError, PRODUCT_LIST_LIMIT, type PreviewMediaSupport, type PurgeExpiredDocumentsParams, type PurgeExpiredDocumentsResult, PurgeExpiredDocumentsUseCase, type RealtimeRelay, type ReceiveWebhookParams, type ReceiveWebhookResult, ReceiveWebhookUseCase, type ReleaseConversationParams, ReleaseConversationUseCase, type ListMessagesParams$1 as RepositoryListMessagesParams, type ResolveTranscriptionPolicyDependencies, type RunMetaWhatsAppMigrationsParams, type SaveFlowGraphParams, SaveFlowGraphUseCase, type SaveTranscriptionByWaMessageIdParams, type SaveTranscriptionParams, type SendMediaParams, SendMessageUseCase, type SendTemplateParams, type SendTextParams, SessionRepository, type SessionRow, SettingsRepository, type SettingsRow, SseHub, type SseListener, type StorePreviewMediaParams, type StorePreviewMediaResult, StorePreviewMediaUseCase, TRANSCRIPTION_MODE, TRANSCRIPTION_STATUS, type TakeoverConversationParams, TakeoverConversationUseCase, type TicketStoreInterface, type TranscribeAudioDependencies, type TranscribeAudioParams, type TranscribeAudioResult, TranscribeAudioUseCase, type TranscriptionPolicy, type TranscriptionPolicyDefaults, type TranscriptionPolicyResolver, type TranscriptionStatus, type UpdateFlowMediaParams, WhatsAppChannelAdapter, claimWebhookDelivery, createMetaWhatsAppModule, createSendMediaAction, createSendProductListAction, createTranscriptionPolicyResolver, documents, extractMediaDescriptor, flowGraphs, flowMedia, isAudioMimeType, isRetriableTranscriptionError, isUnsupportedTranscriptionError, issueSseTicket, messages, metaWhatsAppMigrationsFolder, metaWhatsAppSchema, redeemSseTicket, resolveFailureStatus, runMetaWhatsAppMigrations, sessions, settings, transcriptionRetryAfterSeconds, verifyWebhookChallenge, verifyWebhookSignature };
+export { type AttachFlowMediaParams, type AudioTranscriber, type CompanyDocumentView, type CompanyDocumentsPage, type ConversationDocumentView, type ConversationDocumentsPage, type CreateFlowGraphParams, CreateFlowGraphUseCase, type CreateMetaWhatsAppModuleParams, type CreateSendMediaActionParams, type CreateSendProductListActionParams, DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS, type DeleteConversationParams, type DeleteConversationResult, DeleteConversationUseCase, DeleteFlowGraphUseCase, DocumentRepository, type DocumentRow, type DrizzleMigrateFunction, type ExportConversationParams, type ExportConversationResult, ExportConversationUseCase, FlowGraphCache, FlowGraphRepository, type FlowGraphRow, FlowInterpreter, type FlowMediaLocation, FlowMediaRepository, type FlowMediaRow, type FlowMediaTranscriptLogger, type FlowRunResult, type FlowStepInput, type FlowStepResult, GetFlowGraphUseCase, GetLiveFlowPositionsUseCase, type InboundDispatchJob, type InboundDispatchQueueInterface, InboundEffectsDispatcher, type InboundMediaDescriptor, type InboundMessageEffectsJob, type InboundStatusEffectsJob, type IngestInboundMediaParams, type IngestInboundMediaResult, IngestInboundMediaUseCase, type IngestTranscriptionOptions, type InsertMessageParams, InvalidFlowGraphError, type LinkDocumentParams, type ListCompanyDocumentsParams, ListCompanyDocumentsUseCase, type ListConversationDocumentsParams, ListConversationDocumentsUseCase, type ListConversationsFilters, type ListConversationsParams, ListConversationsUseCase, type ListDocumentsParams, type ListDocumentsResult, ListFlowGraphsUseCase, type ListMessagesParams, ListMessagesUseCase, type LogMessageParams, LogMessageUseCase, META_WHATSAPP_MIGRATIONS_TABLE, type MessageModerator, MessageRepository, type MessageRow, type MetaWhatsAppDatabase, type MetaWhatsAppModule, type MetaWhatsAppModuleConfig, type MetaWhatsAppModuleFeatures, type MetaWhatsAppModuleProviders, type MetaWhatsAppTranscriptionConfig, type NewDocumentRow, type NewFlowGraphRow, type NewFlowMediaRow, type NewMessageRow, type NewSessionRow, type NewSettingsRow, type NonceStoreInterface, OptimisticLockError, PRODUCT_LIST_LIMIT, type PreviewMediaSupport, ProcessInboundDispatchUseCase, type PurgeExpiredDocumentsParams, type PurgeExpiredDocumentsResult, PurgeExpiredDocumentsUseCase, type RealtimeRelay, type ReceiveWebhookParams, type ReceiveWebhookResult, ReceiveWebhookUseCase, type ReleaseConversationParams, ReleaseConversationUseCase, type ListMessagesParams$1 as RepositoryListMessagesParams, type ResolveTranscriptionPolicyDependencies, type RunMetaWhatsAppMigrationsParams, type SaveFlowGraphParams, SaveFlowGraphUseCase, type SaveTranscriptionByWaMessageIdParams, type SaveTranscriptionParams, type SendMediaParams, SendMessageUseCase, type SendTemplateParams, type SendTextParams, SessionRepository, type SessionRow, SettingsRepository, type SettingsRow, SseHub, type SseListener, type StorePreviewMediaParams, type StorePreviewMediaResult, StorePreviewMediaUseCase, TRANSCRIPTION_MODE, TRANSCRIPTION_STATUS, type TakeoverConversationParams, TakeoverConversationUseCase, type TicketStoreInterface, type TranscribeAudioDependencies, type TranscribeAudioParams, type TranscribeAudioResult, TranscribeAudioUseCase, type TranscriptionPolicy, type TranscriptionPolicyDefaults, type TranscriptionPolicyResolver, type TranscriptionStatus, type UpdateFlowMediaParams, WhatsAppChannelAdapter, buildInboundJobId, claimWebhookDelivery, confirmWebhookDelivery, createMetaWhatsAppModule, createSendMediaAction, createSendProductListAction, createTranscriptionPolicyResolver, documents, extractMediaDescriptor, flowGraphs, flowMedia, isAudioMimeType, isRetriableTranscriptionError, isUnsupportedTranscriptionError, issueSseTicket, messages, metaWhatsAppMigrationsFolder, metaWhatsAppSchema, redeemSseTicket, resolveFailureStatus, runMetaWhatsAppMigrations, sessions, settings, toSessionContract, transcriptionRetryAfterSeconds, verifyWebhookChallenge, verifyWebhookSignature };

package/dist/index.js

@@ -2005,7 +2005,7 @@ var WhatsAppChannelAdapter = class {
 import { whatsAppWebhookPayloadSchema } from "@adatechnology/meta-whatsapp-contracts";
 
 // src/channel/webhookSecurity.ts
-import { WEBHOOK_NONCE_TTL_SECONDS, buildWebhookDeliveryKey, isValidWebhookChallenge, isValidWebhookSignature } from "@adatechnology/meta-graph-core";
+import { WEBHOOK_CLAIM_TTL_SECONDS, WEBHOOK_NONCE_TTL_SECONDS, buildWebhookDeliveryKey, isValidWebhookChallenge, isValidWebhookSignature } from "@adatechnology/meta-graph-core";
 import { InvalidWebhookSignatureError } from "@adatechnology/meta-whatsapp-contracts";
 var WEBHOOK_NONCE_NAMESPACE = "meta-whatsapp";
 function verifyWebhookChallenge(params) {
@@ -2017,14 +2017,21 @@ function verifyWebhookSignature(params) {
   if (!isValidWebhookSignature(params)) throw new InvalidWebhookSignatureError();
 }
 __name(verifyWebhookSignature, "verifyWebhookSignature");
-async function claimWebhookDelivery(params) {
-  const key = buildWebhookDeliveryKey({
+function deliveryKey(signatureHeader) {
+  return buildWebhookDeliveryKey({
     namespace: WEBHOOK_NONCE_NAMESPACE,
-    signatureHeader: params.signatureHeader
+    signatureHeader
   });
-  return params.nonceStore.setIfAbsent(key, params.ttlSeconds ?? WEBHOOK_NONCE_TTL_SECONDS);
+}
+__name(deliveryKey, "deliveryKey");
+async function claimWebhookDelivery(params) {
+  return params.nonceStore.setIfAbsent(deliveryKey(params.signatureHeader), params.ttlSeconds ?? WEBHOOK_CLAIM_TTL_SECONDS);
 }
 __name(claimWebhookDelivery, "claimWebhookDelivery");
+async function confirmWebhookDelivery(params) {
+  await params.nonceStore.confirm?.(deliveryKey(params.signatureHeader), params.ttlSeconds ?? WEBHOOK_NONCE_TTL_SECONDS);
+}
+__name(confirmWebhookDelivery, "confirmWebhookDelivery");
 
 // src/channel/IngestInboundMedia.use-case.ts
 import { eq as eq7, and as and6 } from "drizzle-orm";
@@ -2345,7 +2352,11 @@ function extractMediaDescriptor(message) {
 }
 __name(extractMediaDescriptor, "extractMediaDescriptor");
 
-// src/channel/ReceiveWebhook.use-case.ts
+// src/channel/inboundDispatch.ts
+function buildInboundJobId(job) {
+  return job.kind === "message" ? `wa-inbound-message:${job.message.id}` : `wa-inbound-status:${job.status.id}:${job.status.status}`;
+}
+__name(buildInboundJobId, "buildInboundJobId");
 function toSessionContract(row) {
   return {
     id: row.id,
@@ -2366,6 +2377,65 @@ function toSessionContract(row) {
   };
 }
 __name(toSessionContract, "toSessionContract");
+function extractAnswer(message) {
+  const interactive = message.interactive;
+  if (interactive?.button_reply) return interactive.button_reply.id;
+  if (interactive?.list_reply) return interactive.list_reply.id;
+  return message.text?.body;
+}
+__name(extractAnswer, "extractAnswer");
+var InboundEffectsDispatcher = class {
+  static {
+    __name(this, "InboundEffectsDispatcher");
+  }
+  params;
+  constructor(params) {
+    this.params = params;
+  }
+  async run(job) {
+    if (job.kind === "message") return this.runMessageEffects(job);
+    return this.runStatusEffects(job);
+  }
+  async runMessageEffects(job) {
+    const { companyId, message, savedMessageId, media } = job;
+    if (media) {
+      await this.params.hooks?.onMediaReceived?.({
+        companyId,
+        messageId: savedMessageId,
+        whatsappNumber: message.from,
+        sourceMediaId: media.sourceMediaId,
+        mimeType: media.mimeType,
+        ...media.filename ? {
+          filename: media.filename
+        } : {}
+      });
+    }
+    const sessionRow = await this.params.sessionRepository.getContext(companyId, message.from);
+    if (!sessionRow) return;
+    if (sessionRow.mode === "human") return;
+    const outcome = await this.params.hooks?.onMessageReceived?.(message, toSessionContract(sessionRow));
+    if (outcome?.outcome === "handled") return;
+    void extractAnswer(message);
+  }
+  async runStatusEffects(job) {
+    const sessionRow = await this.params.sessionRepository.getContext(job.companyId, job.whatsappNumber);
+    await this.params.hooks?.onStatusUpdate?.(job.status, sessionRow ? toSessionContract(sessionRow) : null);
+  }
+};
+var ProcessInboundDispatchUseCase = class {
+  static {
+    __name(this, "ProcessInboundDispatchUseCase");
+  }
+  dispatcher;
+  constructor(dispatcher) {
+    this.dispatcher = dispatcher;
+  }
+  async execute(job) {
+    await this.dispatcher.run(job);
+  }
+};
+
+// src/channel/ReceiveWebhook.use-case.ts
 function extractContent(message) {
   if (message.text?.body) return message.text.body;
   const interactive = message.interactive;
@@ -2378,13 +2448,6 @@ function extractContent(message) {
   return message.image?.caption ?? message.document?.caption ?? null;
 }
 __name(extractContent, "extractContent");
-function extractAnswer(message) {
-  const interactive = message.interactive;
-  if (interactive?.button_reply) return interactive.button_reply.id;
-  if (interactive?.list_reply) return interactive.list_reply.id;
-  return message.text?.body;
-}
-__name(extractAnswer, "extractAnswer");
 function extractPayload(message) {
   const payload = {};
   if (message.interactive) payload["interactive"] = message.interactive;
@@ -2405,7 +2468,17 @@ var ReceiveWebhookUseCase = class {
   params;
   constructor(params) {
     this.params = params;
+    this.dispatcher = new InboundEffectsDispatcher({
+      sessionRepository: params.sessionRepository,
+      ...params.hooks ? {
+        hooks: params.hooks
+      } : {},
+      ...params.realtime ? {
+        realtime: params.realtime
+      } : {}
+    });
   }
+  dispatcher;
   async execute(input) {
     verifyWebhookSignature({
       rawBody: input.rawBody,
@@ -2444,6 +2517,10 @@ var ReceiveWebhookUseCase = class {
         }
       }
     }
+    await confirmWebhookDelivery({
+      nonceStore: this.params.nonceStore,
+      signatureHeader: input.signatureHeader
+    });
     return {
       duplicate: false,
       messagesProcessed,
@@ -2466,24 +2543,16 @@ var ReceiveWebhookUseCase = class {
     });
     if (!saved) return;
     const media = extractMediaDescriptor(saved);
-    if (media) {
-      await this.params.hooks?.onMediaReceived?.({
-        companyId,
-        messageId: saved.id,
-        whatsappNumber: message.from,
-        sourceMediaId: media.sourceMediaId,
-        mimeType: media.mimeType,
-        ...media.filename ? {
-          filename: media.filename
-        } : {}
-      });
-    }
-    const sessionRow = await this.params.sessionRepository.getContext(companyId, message.from);
-    if (!sessionRow) return;
-    if (sessionRow.mode === "human") return;
-    const outcome = await this.params.hooks?.onMessageReceived?.(message, toSessionContract(sessionRow));
-    if (outcome?.outcome === "handled") return;
-    void extractAnswer(message);
+    await this.dispatch({
+      kind: "message",
+      companyId,
+      message,
+      savedMessageId: saved.id,
+      ...media ? {
+        media
+      } : {},
+      receivedAt: Date.now()
+    });
   }
   async handleStatus(companyId, status) {
     const updated = await this.params.messageRepository.updateMessageStatus(companyId, status.id, status.status);
@@ -2492,8 +2561,24 @@ var ReceiveWebhookUseCase = class {
       waMessageId: status.id,
       status: status.status
     });
-    const sessionRow = await this.params.sessionRepository.getContext(companyId, updated.whatsappNumber);
-    await this.params.hooks?.onStatusUpdate?.(status, sessionRow ? toSessionContract(sessionRow) : null);
+    await this.dispatch({
+      kind: "status",
+      companyId,
+      status,
+      whatsappNumber: updated.whatsappNumber,
+      receivedAt: Date.now()
+    });
+  }
+  // Com fila configurada, os efeitos saem da requisição do webhook; sem ela, rodam aqui mesmo e o
+  // comportamento é o de sempre. É o mesmo `InboundEffectsDispatcher` nos dois caminhos.
+  async dispatch(job) {
+    if (this.params.inboundQueue) {
+      await this.params.inboundQueue.enqueue(job, {
+        jobId: buildInboundJobId(job)
+      });
+      return;
+    }
+    await this.dispatcher.run(job);
   }
 };
 
@@ -2806,6 +2891,7 @@ export {
   FlowMediaRepository,
   GetFlowGraphUseCase,
   GetLiveFlowPositionsUseCase,
+  InboundEffectsDispatcher,
   IngestInboundMediaUseCase,
   InvalidFlowGraphError,
   ListCompanyDocumentsUseCase,
@@ -2819,6 +2905,7 @@ export {
   OptimisticLockError,
   PREVIEW_MEDIA_ID_PREFIX,
   PRODUCT_LIST_LIMIT,
+  ProcessInboundDispatchUseCase,
   PurgeExpiredDocumentsUseCase,
   ReceiveWebhookUseCase,
   ReleaseConversationUseCase,
@@ -2832,9 +2919,12 @@ export {
   TRANSCRIPTION_STATUS,
   TakeoverConversationUseCase,
   TranscribeAudioUseCase,
+  WEBHOOK_CLAIM_TTL_SECONDS,
   WEBHOOK_NONCE_TTL_SECONDS,
   WhatsAppChannelAdapter,
+  buildInboundJobId,
   claimWebhookDelivery,
+  confirmWebhookDelivery,
   createMetaWhatsAppModule,
   createSendMediaAction,
   createSendProductListAction,
@@ -2857,6 +2947,7 @@ export {
   sessions,
   settings,
   toPreviewMediaId,
+  toSessionContract,
   transcriptionRetryAfterSeconds,
   verifyWebhookChallenge,
   verifyWebhookSignature