@adatechnology/meta-whatsapp-module 0.2.0-rc.9 → 0.2.0

package/dist/index.d.ts

@@ -1,8 +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 { SessionState, SessionMode, ConversationSummary, FlowGraphData, FlowGraphSummary, LiveFlowPosition, WhatsAppSettings, MessageDirection, MessageSender, MessageStatus, 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, SendChannelMediaParams } 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_CLAIM_TTL_SECONDS, WEBHOOK_NONCE_TTL_SECONDS } from '@adatechnology/meta-graph-core';
 
 type MetaWhatsAppDatabase = PgDatabase<PgQueryResultHKT, any, any>;
 type DrizzleMigrateFunction = (db: never, config: {
@@ -10,6 +12,72 @@ type DrizzleMigrateFunction = (db: never, config: {
     migrationsTable?: string;
 }) => Promise<void>;
 
+/**
+ * Vocabulário de transcrição de áudio do módulo.
+ *
+ * Fica em arquivo próprio porque o schema e os dois use-cases (ingestão automática e sob demanda)
+ * precisam dos mesmos tipos, e pendurá-los em qualquer um dos três faria os outros dois importarem
+ * de dentro de uma camada que não é a deles.
+ */
+
+declare const TRANSCRIPTION_STATUS: {
+    /** Falhou de forma retriável (cota, rede, 5xx) — vai sair quando alguém tentar de novo. */
+    readonly PENDING: "pending";
+    /** Processado. Texto vazio aqui é áudio em silêncio, e NÃO deve ser reprocessado. */
+    readonly DONE: "done";
+    /** Falha definitiva do engine (credencial, áudio corrompido, arquivo grande demais). */
+    readonly FAILED: "failed";
+    /** Nenhum engine da cadeia aceita o formato. Retentar não conserta codec. */
+    readonly UNSUPPORTED: "unsupported";
+};
+type TranscriptionStatus = (typeof TRANSCRIPTION_STATUS)[keyof typeof TRANSCRIPTION_STATUS];
+/**
+ * Quando transcrever.
+ *
+ * `auto` transcreve durante a ingestão da mídia, onde o buffer do áudio JÁ está em memória — não
+ * custa um segundo download do storage. `onDemand` só transcreve quando o atendente pede, o que
+ * troca latência na interface por não gastar cota com áudio que ninguém vai ler.
+ *
+ * O tipo vem do contrato (o painel escolhe, a API transporta, o módulo obedece) e `satisfies`
+ * garante em tempo de compilação que estes valores continuam sendo exatamente os de lá — sem isso,
+ * um modo novo no contrato passaria despercebido aqui.
+ */
+declare const TRANSCRIPTION_MODE: {
+    readonly AUTO: "auto";
+    readonly ON_DEMAND: "onDemand";
+};
+
+/**
+ * O contrato mínimo de `@adatechnology/audio-transcription-provider`, declarado aqui em vez de
+ * importado — mesma decisão do `MessageModerator` em `LogMessage.use-case.ts`.
+ *
+ * Assim o módulo não ganha dependência de pacote por um recurso opcional, e transcrição não fica
+ * amarrada a WhatsApp: o que atravessa esta fronteira é um buffer de áudio e um mime.
+ */
+type AudioTranscriber = {
+    readonly name: string;
+    transcribe: (input: {
+        buffer: Buffer;
+        mimeType: string;
+        languageHint?: string;
+    }) => Promise<{
+        text: string;
+        language?: string;
+        durationSeconds?: number;
+        engine: string;
+    }>;
+};
+/**
+ * Recorte do erro do provider que o módulo precisa ler para escolher entre `'pending'` e
+ * `'failed'`. Estrutural, não `instanceof`: o provider é opcional e pode nem estar instalado, e um
+ * `instanceof` contra classe ausente não compila.
+ */
+declare function isRetriableTranscriptionError(error: unknown): boolean;
+declare function isUnsupportedTranscriptionError(error: unknown): boolean;
+declare function transcriptionRetryAfterSeconds(error: unknown): number | undefined;
+/** Mime de áudio? Só áudio é transcrito — vídeo, imagem e documento passam sem tocar no engine. */
+declare function isAudioMimeType(mimeType: string | undefined | null): boolean;
+
 declare const metaWhatsAppSchema: drizzle_orm_pg_core.PgSchema<"meta_whatsapp">;
 declare const sessions: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "sessions";
@@ -560,6 +628,81 @@ declare const messages: drizzle_orm_pg_core.PgTableWithColumns<{
         }, {}, {
             $type: string[];
         }>;
+        transcriptionStatus: drizzle_orm_pg_core.PgColumn<{
+            name: "transcription_status";
+            tableName: "messages";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: TranscriptionStatus;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 16;
+            $type: TranscriptionStatus;
+        }>;
+        transcriptionText: drizzle_orm_pg_core.PgColumn<{
+            name: "transcription_text";
+            tableName: "messages";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        transcriptionLanguage: drizzle_orm_pg_core.PgColumn<{
+            name: "transcription_language";
+            tableName: "messages";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 32;
+        }>;
+        transcriptionEngine: drizzle_orm_pg_core.PgColumn<{
+            name: "transcription_engine";
+            tableName: "messages";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 32;
+        }>;
         createdAt: drizzle_orm_pg_core.PgColumn<{
             name: "created_at";
             tableName: "messages";
@@ -580,13 +723,25 @@ declare const messages: drizzle_orm_pg_core.PgTableWithColumns<{
     };
     dialect: "pg";
 }>;
-declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
-    name: "flow_graphs";
+/**
+ * Biblioteca de arquivos da conversa.
+ *
+ * Tabela própria, e não derivada de `messages.payload`: o painel precisa de `source` e `linkedAt`,
+ * que não existem no payload; busca por nome de arquivo quer índice, não varredura de jsonb; e
+ * `messageId` anulável é o que permite o atendente anexar documento à conversa sem que exista uma
+ * mensagem correspondente.
+ *
+ * `sessionId` em cascata apaga a LINHA junto com a conversa, mas não o binário no storage — quem
+ * apaga objeto é passo de aplicação (listar `uploadId` → apagar no storage → apagar a sessão).
+ * Confiar só na FK deixaria objeto órfão sendo cobrado para sempre.
+ */
+declare const documents: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "documents";
     schema: "meta_whatsapp";
     columns: {
         id: drizzle_orm_pg_core.PgColumn<{
             name: "id";
-            tableName: "flow_graphs";
+            tableName: "documents";
             dataType: "string";
             columnType: "PgUUID";
             data: string;
@@ -603,7 +758,7 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
         }, {}, {}>;
         companyId: drizzle_orm_pg_core.PgColumn<{
             name: "company_id";
-            tableName: "flow_graphs";
+            tableName: "documents";
             dataType: "string";
             columnType: "PgUUID";
             data: string;
@@ -618,11 +773,11 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        key: drizzle_orm_pg_core.PgColumn<{
-            name: "key";
-            tableName: "flow_graphs";
+        sessionId: drizzle_orm_pg_core.PgColumn<{
+            name: "session_id";
+            tableName: "documents";
             dataType: "string";
-            columnType: "PgVarchar";
+            columnType: "PgUUID";
             data: string;
             driverParam: string;
             notNull: true;
@@ -630,16 +785,31 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
+            enumValues: undefined;
             baseColumn: never;
             identity: undefined;
             generated: undefined;
-        }, {}, {
-            length: 64;
-        }>;
-        label: drizzle_orm_pg_core.PgColumn<{
-            name: "label";
-            tableName: "flow_graphs";
+        }, {}, {}>;
+        messageId: drizzle_orm_pg_core.PgColumn<{
+            name: "message_id";
+            tableName: "documents";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        uploadId: drizzle_orm_pg_core.PgColumn<{
+            name: "upload_id";
+            tableName: "documents";
             dataType: "string";
             columnType: "PgVarchar";
             data: string;
@@ -654,11 +824,11 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: 120;
+            length: 256;
         }>;
-        startNodeId: drizzle_orm_pg_core.PgColumn<{
-            name: "start_node_id";
-            tableName: "flow_graphs";
+        filename: drizzle_orm_pg_core.PgColumn<{
+            name: "filename";
+            tableName: "documents";
             dataType: "string";
             columnType: "PgVarchar";
             data: string;
@@ -673,36 +843,36 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: 64;
+            length: 512;
         }>;
-        nodes: drizzle_orm_pg_core.PgColumn<{
-            name: "nodes";
-            tableName: "flow_graphs";
-            dataType: "json";
-            columnType: "PgJsonb";
-            data: Record<string, unknown>;
-            driverParam: unknown;
+        mimeType: drizzle_orm_pg_core.PgColumn<{
+            name: "mime_type";
+            tableName: "documents";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: undefined;
+            enumValues: [string, ...string[]];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
         }, {}, {
-            $type: Record<string, unknown>;
+            length: 128;
         }>;
-        version: drizzle_orm_pg_core.PgColumn<{
-            name: "version";
-            tableName: "flow_graphs";
+        sizeBytes: drizzle_orm_pg_core.PgColumn<{
+            name: "size_bytes";
+            tableName: "documents";
             dataType: "number";
             columnType: "PgInteger";
             data: number;
             driverParam: string | number;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -711,31 +881,33 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        showInMenu: drizzle_orm_pg_core.PgColumn<{
-            name: "show_in_menu";
-            tableName: "flow_graphs";
-            dataType: "boolean";
-            columnType: "PgBoolean";
-            data: boolean;
-            driverParam: boolean;
-            notNull: true;
-            hasDefault: true;
+        sha256: drizzle_orm_pg_core.PgColumn<{
+            name: "sha256";
+            tableName: "documents";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: undefined;
+            enumValues: [string, ...string[]];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
-        }, {}, {}>;
-        menuOptionLabel: drizzle_orm_pg_core.PgColumn<{
-            name: "menu_option_label";
-            tableName: "flow_graphs";
+        }, {}, {
+            length: 64;
+        }>;
+        source: drizzle_orm_pg_core.PgColumn<{
+            name: "source";
+            tableName: "documents";
             dataType: "string";
             columnType: "PgVarchar";
             data: string;
             driverParam: string;
-            notNull: false;
+            notNull: true;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
@@ -745,11 +917,11 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: 64;
+            length: 12;
         }>;
-        createdAt: drizzle_orm_pg_core.PgColumn<{
-            name: "created_at";
-            tableName: "flow_graphs";
+        linkedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "linked_at";
+            tableName: "documents";
             dataType: "date";
             columnType: "PgTimestamp";
             data: Date;
@@ -764,16 +936,23 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        updatedAt: drizzle_orm_pg_core.PgColumn<{
-            name: "updated_at";
+    };
+    dialect: "pg";
+}>;
+declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "flow_graphs";
+    schema: "meta_whatsapp";
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
             tableName: "flow_graphs";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
             driverParam: string;
             notNull: true;
             hasDefault: true;
-            isPrimaryKey: false;
+            isPrimaryKey: true;
             isAutoincrement: false;
             hasRuntimeDefault: false;
             enumValues: undefined;
@@ -781,23 +960,16 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-    };
-    dialect: "pg";
-}>;
-declare const settings: drizzle_orm_pg_core.PgTableWithColumns<{
-    name: "settings";
-    schema: "meta_whatsapp";
-    columns: {
         companyId: drizzle_orm_pg_core.PgColumn<{
             name: "company_id";
-            tableName: "settings";
+            tableName: "flow_graphs";
             dataType: "string";
             columnType: "PgUUID";
             data: string;
             driverParam: string;
             notNull: true;
             hasDefault: false;
-            isPrimaryKey: true;
+            isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
             enumValues: undefined;
@@ -805,14 +977,14 @@ declare const settings: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        templateName: drizzle_orm_pg_core.PgColumn<{
-            name: "template_name";
-            tableName: "settings";
+        key: drizzle_orm_pg_core.PgColumn<{
+            name: "key";
+            tableName: "flow_graphs";
             dataType: "string";
             columnType: "PgVarchar";
             data: string;
             driverParam: string;
-            notNull: false;
+            notNull: true;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
@@ -822,17 +994,17 @@ declare const settings: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: 128;
+            length: 64;
         }>;
-        templateLanguage: drizzle_orm_pg_core.PgColumn<{
-            name: "template_language";
-            tableName: "settings";
+        label: drizzle_orm_pg_core.PgColumn<{
+            name: "label";
+            tableName: "flow_graphs";
             dataType: "string";
             columnType: "PgVarchar";
             data: string;
             driverParam: string;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -841,31 +1013,488 @@ declare const settings: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {
-            length: 16;
+            length: 120;
         }>;
-        templateVariables: drizzle_orm_pg_core.PgColumn<{
-            name: "template_variables";
-            tableName: "settings";
-            dataType: "json";
-            columnType: "PgJsonb";
-            data: string[];
-            driverParam: unknown;
+        startNodeId: drizzle_orm_pg_core.PgColumn<{
+            name: "start_node_id";
+            tableName: "flow_graphs";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
             notNull: true;
-            hasDefault: true;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: undefined;
+            enumValues: [string, ...string[]];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
         }, {}, {
-            $type: string[];
+            length: 64;
         }>;
-        welcomeMessage: drizzle_orm_pg_core.PgColumn<{
-            name: "welcome_message";
-            tableName: "settings";
-            dataType: "string";
+        nodes: drizzle_orm_pg_core.PgColumn<{
+            name: "nodes";
+            tableName: "flow_graphs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        version: drizzle_orm_pg_core.PgColumn<{
+            name: "version";
+            tableName: "flow_graphs";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        showInMenu: drizzle_orm_pg_core.PgColumn<{
+            name: "show_in_menu";
+            tableName: "flow_graphs";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        menuOptionLabel: drizzle_orm_pg_core.PgColumn<{
+            name: "menu_option_label";
+            tableName: "flow_graphs";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 64;
+        }>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "flow_graphs";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "flow_graphs";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/**
+ * Biblioteca de mídia do bot: arquivos que um nó `action` de `send_media` dispara ao chegar nele.
+ *
+ * Tabela separada de `documents` de propósito, e não por simetria: `documents` é o acervo DE UMA
+ * CONVERSA (tem `sessionId` obrigatório) e tem índice único em (companyId, uploadId), porque lá o
+ * mesmo binário chegando duas vezes é reentrega de job. Aqui é o oposto — o mesmo arquivo é
+ * enviado para todo cliente que passar pelo nó, então aquele único bloquearia o segundo envio.
+ *
+ * Sem FK para `flow_graphs.id`: o vínculo natural é (companyId, flowKey), que é justamente o
+ * índice único de lá. `nodeId` não tem como ser FK — nós vivem dentro do jsonb `nodes` — então
+ * apagar um nó no editor deixa a linha órfã; quem lista sempre parte de um nó existente, e a
+ * limpeza é passo de aplicação ao salvar o grafo.
+ */
+declare const flowMedia: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "flow_media";
+    schema: "meta_whatsapp";
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        companyId: drizzle_orm_pg_core.PgColumn<{
+            name: "company_id";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        flowKey: drizzle_orm_pg_core.PgColumn<{
+            name: "flow_key";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 64;
+        }>;
+        nodeId: drizzle_orm_pg_core.PgColumn<{
+            name: "node_id";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 64;
+        }>;
+        uploadId: drizzle_orm_pg_core.PgColumn<{
+            name: "upload_id";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 256;
+        }>;
+        filename: drizzle_orm_pg_core.PgColumn<{
+            name: "filename";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 512;
+        }>;
+        mimeType: drizzle_orm_pg_core.PgColumn<{
+            name: "mime_type";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 128;
+        }>;
+        sizeBytes: drizzle_orm_pg_core.PgColumn<{
+            name: "size_bytes";
+            tableName: "flow_media";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        caption: drizzle_orm_pg_core.PgColumn<{
+            name: "caption";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sortOrder: drizzle_orm_pg_core.PgColumn<{
+            name: "sort_order";
+            tableName: "flow_media";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        active: drizzle_orm_pg_core.PgColumn<{
+            name: "active";
+            tableName: "flow_media";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        metaMediaIds: drizzle_orm_pg_core.PgColumn<{
+            name: "meta_media_ids";
+            tableName: "flow_media";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, string>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, string>;
+        }>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "flow_media";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "flow_media";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+declare const settings: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "settings";
+    schema: "meta_whatsapp";
+    columns: {
+        companyId: drizzle_orm_pg_core.PgColumn<{
+            name: "company_id";
+            tableName: "settings";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        templateName: drizzle_orm_pg_core.PgColumn<{
+            name: "template_name";
+            tableName: "settings";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 128;
+        }>;
+        templateLanguage: drizzle_orm_pg_core.PgColumn<{
+            name: "template_language";
+            tableName: "settings";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 16;
+        }>;
+        templateVariables: drizzle_orm_pg_core.PgColumn<{
+            name: "template_variables";
+            tableName: "settings";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: string[];
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: string[];
+        }>;
+        welcomeMessage: drizzle_orm_pg_core.PgColumn<{
+            name: "welcome_message";
+            tableName: "settings";
+            dataType: "string";
             columnType: "PgText";
             data: string;
             driverParam: string;
@@ -896,6 +1525,43 @@ declare const settings: drizzle_orm_pg_core.PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        transcriptionEnabled: drizzle_orm_pg_core.PgColumn<{
+            name: "transcription_enabled";
+            tableName: "settings";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        transcriptionMode: drizzle_orm_pg_core.PgColumn<{
+            name: "transcription_mode";
+            tableName: "settings";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: TranscriptionMode;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 16;
+            $type: TranscriptionMode;
+        }>;
         createdAt: drizzle_orm_pg_core.PgColumn<{
             name: "created_at";
             tableName: "settings";
@@ -941,6 +1607,10 @@ type MessageRow = typeof messages.$inferSelect;
 type NewMessageRow = typeof messages.$inferInsert;
 type FlowGraphRow = typeof flowGraphs.$inferSelect;
 type NewFlowGraphRow = typeof flowGraphs.$inferInsert;
+type DocumentRow = typeof documents.$inferSelect;
+type NewDocumentRow = typeof documents.$inferInsert;
+type FlowMediaRow = typeof flowMedia.$inferSelect;
+type NewFlowMediaRow = typeof flowMedia.$inferInsert;
 
 interface ListConversationsFilters {
     page?: number;
@@ -953,13 +1623,23 @@ declare class SessionRepository {
     constructor(db: MetaWhatsAppDatabase);
     getContext(companyId: string, whatsappNumber: string): Promise<SessionRow | undefined>;
     getOrCreate(companyId: string, whatsappNumber: string, startState: SessionState): Promise<SessionRow>;
-    setState(companyId: string, whatsappNumber: string, state: SessionState, context?: Record<string, unknown>): Promise<void>;
+    setState<TSessionContext extends Record<string, unknown> = Record<string, unknown>>(companyId: string, whatsappNumber: string, state: SessionState, context?: TSessionContext): Promise<void>;
+    patchContext<TSessionContext extends Record<string, unknown> = Record<string, unknown>>(companyId: string, whatsappNumber: string, patch: Partial<TSessionContext>): Promise<void>;
+    readContext<TSessionContext extends Record<string, unknown> = Record<string, unknown>>(companyId: string, whatsappNumber: string): Promise<TSessionContext | undefined>;
     setFlowPosition(companyId: string, whatsappNumber: string, flowKey: string | null, currentNodeId: string | null): Promise<void>;
     touchInbound(companyId: string, whatsappNumber: string): Promise<void>;
     hoursSinceLastInbound(companyId: string, whatsappNumber: string): Promise<number | undefined>;
     setMode(companyId: string, whatsappNumber: string, mode: SessionMode, assignedUserId?: string | null): Promise<void>;
     takeover(companyId: string, whatsappNumber: string, agentUserId: string): Promise<void>;
     release(companyId: string, whatsappNumber: string): Promise<void>;
+    /**
+     * Apaga a sessão; a cascata das FKs leva mensagens e documentos.
+     *
+     * Não apaga o binário no storage — isso é passo de aplicação, e é por isso que este método é
+     * chamado por `DeleteConversationUseCase` e não diretamente pelo host. Chamar daqui sem apagar os
+     * objetos antes deixa mídia órfã sendo cobrada para sempre.
+     */
+    deleteByNumber(companyId: string, whatsappNumber: string): Promise<void>;
     requestHuman(companyId: string, whatsappNumber: string): Promise<void>;
     markRead(companyId: string, whatsappNumber: string): Promise<void>;
     markAllRead(companyId: string, userId: string): Promise<number>;
@@ -998,41 +1678,15 @@ declare class SessionRepository {
             readAt: Date | null;
             moderationFlagged: boolean | null;
             moderationTerms: string[] | null;
+            transcriptionStatus: TranscriptionStatus | null;
+            transcriptionText: string | null;
+            transcriptionLanguage: string | null;
+            transcriptionEngine: string | null;
             createdAt: Date;
         }[];
     } | null>;
 }
 
-declare class InvalidFlowGraphError extends Error {
-    readonly validationMessage: string;
-    constructor(key: string, validationMessage: string);
-}
-declare class OptimisticLockError extends Error {
-    constructor(key: string);
-}
-declare class FlowGraphRepository {
-    private readonly db;
-    constructor(db: MetaWhatsAppDatabase);
-    get(companyId: string, key: string): Promise<FlowGraphData | undefined>;
-    list(companyId: string): Promise<FlowGraphSummary[]>;
-    private assertValidNodes;
-    create(companyId: string, graph: Omit<FlowGraphData, 'version'> & {
-        showInMenu?: boolean;
-        menuOptionLabel?: string;
-    }): Promise<FlowGraphData>;
-    save(companyId: string, graph: FlowGraphData, expectedVersion: number): Promise<FlowGraphData>;
-    delete(companyId: string, key: string): Promise<void>;
-    getLiveFlowPositions(companyId: string): Promise<LiveFlowPosition[]>;
-}
-
-declare class SettingsRepository {
-    private readonly db;
-    constructor(db: MetaWhatsAppDatabase);
-    get(companyId: string): Promise<WhatsAppSettings>;
-    save(companyId: string, update: Partial<WhatsAppSettings>): Promise<WhatsAppSettings>;
-    resolveTemplateVariables(companyId: string, context: Record<string, unknown>): Promise<string[]>;
-}
-
 interface InsertMessageParams {
     companyId: string;
     sessionId: string;
@@ -1055,14 +1709,106 @@ interface ListMessagesParams$1 {
     limit?: number;
     before?: string;
 }
+interface SaveTranscriptionByWaMessageIdParams extends Omit<SaveTranscriptionParams, 'messageId'> {
+    /**
+     * Id da mensagem na Meta. É o único que quem processa o webhook conhece — o id do módulo só
+     * existe depois da gravação, e obrigar o host a descobri-lo faria cada um escrever a própria
+     * consulta por `wa_message_id`.
+     */
+    waMessageId: string;
+}
+interface SaveTranscriptionParams {
+    companyId: string;
+    messageId: string;
+    status: TranscriptionStatus;
+    /** Ausente em `pending`/`failed`/`unsupported`; vazio em `done` é silêncio já processado. */
+    text?: string | null;
+    language?: string | null;
+    engine?: string | null;
+}
 declare class MessageRepository {
     private readonly db;
     constructor(db: MetaWhatsAppDatabase);
     insertMessage(params: InsertMessageParams): Promise<MessageRow | undefined>;
     updateMessageStatus(companyId: string, waMessageId: string, status: MessageStatus): Promise<MessageRow | undefined>;
+    /**
+     * Grava a transcrição endereçando pelo id da Meta, para quem só tem esse.
+     *
+     * Serve ao caso em que a transcrição acontece no próprio webhook — o grafo precisa do texto para
+     * responder ao cliente, e jogar fora o que ele já pagou para transcrever significaria transcrever
+     * o mesmo áudio uma segunda vez só para o painel ver.
+     *
+     * Devolve `undefined` quando não achou a mensagem: entrega duplicada e mensagem apagada são
+     * corridas normais, não erro.
+     */
+    saveTranscriptionByWaMessageId(params: SaveTranscriptionByWaMessageIdParams): Promise<MessageRow | undefined>;
+    findById(companyId: string, messageId: string): Promise<MessageRow | undefined>;
+    /**
+     * Grava o resultado da transcrição. Devolve `undefined` quando a mensagem não existe (apagada
+     * entre o enfileiramento e a execução do job) — não é erro, é corrida normal.
+     *
+     * `text`/`language`/`engine` só são tocados quando informados: uma retentativa que volta a falhar
+     * atualiza o status sem apagar a transcrição parcial de uma tentativa anterior que tenha vindo de
+     * outro engine da cadeia.
+     */
+    saveTranscription(params: SaveTranscriptionParams): Promise<MessageRow | undefined>;
     listByConversation(params: ListMessagesParams$1): Promise<MessageRow[]>;
 }
 
+declare const DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS = 300;
+/**
+ * Cache de leitura dos grafos de fluxo, com invalidação na publicação.
+ *
+ * TTL **e** invalidação explícita, e não um dos dois: só TTL deixaria o cliente andando no grafo
+ * antigo até a chave expirar, logo depois de alguém corrigir o fluxo no editor; só invalidação
+ * deixaria cache envenenado para sempre se um `delete` se perdesse (Redis reiniciando, deploy no
+ * meio da escrita).
+ *
+ * Toda operação é tolerante a falha por decisão de projeto: cache é aceleração, não dependência.
+ * Redis fora do ar tem que degradar para leitura no banco — que é exatamente o comportamento de
+ * quem não configura cache nenhum — em vez de derrubar a conversa do cliente.
+ */
+declare class FlowGraphCache {
+    private readonly provider;
+    private readonly ttlSeconds;
+    constructor(provider: CacheInterface, ttlSeconds?: number);
+    private keyFor;
+    read(companyId: string, flowKey: string): Promise<FlowGraphData | undefined>;
+    write(companyId: string, graph: FlowGraphData): Promise<void>;
+    invalidate(companyId: string, flowKey: string): Promise<void>;
+}
+
+declare class InvalidFlowGraphError extends Error {
+    readonly validationMessage: string;
+    constructor(key: string, validationMessage: string);
+}
+declare class OptimisticLockError extends Error {
+    constructor(key: string);
+}
+declare class FlowGraphRepository {
+    private readonly db;
+    private readonly cache?;
+    constructor(db: MetaWhatsAppDatabase, cache?: FlowGraphCache | undefined);
+    get(companyId: string, key: string): Promise<FlowGraphData | undefined>;
+    list(companyId: string): Promise<FlowGraphSummary[]>;
+    private assertValidNodes;
+    create(companyId: string, graph: Omit<FlowGraphData, 'version'> & {
+        showInMenu?: boolean;
+        menuOptionLabel?: string;
+    }): Promise<FlowGraphData>;
+    save(companyId: string, graph: FlowGraphData, expectedVersion: number): Promise<FlowGraphData>;
+    delete(companyId: string, key: string): Promise<void>;
+    getLiveFlowPositions(companyId: string): Promise<LiveFlowPosition[]>;
+}
+
+declare class SettingsRepository {
+    private readonly db;
+    constructor(db: MetaWhatsAppDatabase);
+    get(companyId: string): Promise<WhatsAppSettings>;
+    save(companyId: string, update: Partial<WhatsAppSettings>): Promise<WhatsAppSettings>;
+    resolveTemplateVariables(companyId: string, context: Record<string, unknown>): Promise<string[]>;
+}
+
 type LogMessageParams = Omit<InsertMessageParams, 'sessionId'> & {
     startState: SessionState;
 };
@@ -1089,6 +1835,100 @@ declare class LogMessageUseCase {
     private moderationOf;
 }
 
+interface LinkDocumentParams {
+    companyId: string;
+    sessionId: string;
+    messageId?: string | null;
+    uploadId: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    sha256?: string | null;
+    source: string;
+}
+interface ListDocumentsParams {
+    companyId: string;
+    sessionId: string;
+    search?: string;
+    /**
+     * Origens aceitas, como lista explícita (`['agent', 'bot']`) e não como apelido de UI.
+     *
+     * Agrupamento tipo "Equipe" é vocabulário de tela e muda por produto; traduzir aqui obrigaria o
+     * módulo a conhecer o rótulo de cada host. Quem recebe o apelido na borda é a rota.
+     */
+    sources?: readonly string[];
+    sortDirection?: 'asc' | 'desc';
+    page?: number;
+    limit?: number;
+}
+interface ListCompanyDocumentsParams$1 {
+    companyId: string;
+    search?: string;
+    sources?: readonly string[];
+    sortDirection?: 'asc' | 'desc';
+    page?: number;
+    limit?: number;
+}
+interface CompanyDocumentRow {
+    id: string;
+    uploadId: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    source: string;
+    linkedAt: Date;
+    whatsappNumber: string;
+}
+interface ListCompanyDocumentsResult {
+    rows: CompanyDocumentRow[];
+    total: number;
+}
+interface ListDocumentsResult {
+    rows: DocumentRow[];
+    /** Total no servidor, ANTES do corte de página — é o que permite calcular a última página. */
+    total: number;
+}
+declare class DocumentRepository {
+    private readonly db;
+    constructor(db: MetaWhatsAppDatabase);
+    /**
+     * Idempotente por (companyId, uploadId), garantido pelo índice único e não por SELECT prévio: o
+     * job de ingestão é reentregue por retry e duas tentativas concorrentes passariam as duas por uma
+     * checagem, duplicando a linha no painel.
+     *
+     * Devolve `undefined` quando o documento já estava linkado.
+     */
+    link(params: LinkDocumentParams): Promise<DocumentRow | undefined>;
+    listByConversation(params: ListDocumentsParams): Promise<ListDocumentsResult>;
+    /**
+     * A biblioteca da EMPRESA inteira, não de uma conversa.
+     *
+     * A busca casa nome do arquivo OU telefone da conversa — ver `companyDocumentSearch`.
+     *
+     * Faz join com `sessions` para carregar de qual conversa cada arquivo veio — numa lista global,
+     * arquivo sem essa referência é inútil: o atendente vê "comprovante.pdf" e não sabe de quem.
+     *
+     * Ordena por `linkedAt` apoiada no índice `idx_documents_company_linked`, que já existia para a
+     * varredura de retenção.
+     */
+    listByCompany(params: ListCompanyDocumentsParams$1): Promise<ListCompanyDocumentsResult>;
+    /**
+     * Um documento pela key do objeto. Serve para recuperar o nome original na hora de assinar o
+     * download: a key é caminho no bucket e salvaria o arquivo com o id da Meta.
+     */
+    findByUploadId(companyId: string, uploadId: string): Promise<DocumentRow | undefined>;
+    /**
+     * Os objetos a apagar no storage antes de a linha sumir.
+     *
+     * Existe porque a cascata da FK apaga a linha e deixa o binário órfão: quem for apagar a conversa
+     * precisa desta lista primeiro, senão paga armazenamento para sempre por arquivo inalcançável.
+     */
+    listUploadIdsBySession(companyId: string, sessionId: string): Promise<string[]>;
+    /** Varredura de retenção por idade — o par é o mesmo cuidado com o objeto no storage. */
+    listExpired(companyId: string, olderThan: Date, limit?: number): Promise<DocumentRow[]>;
+    deleteById(companyId: string, id: string): Promise<void>;
+}
+
 type SendTextParams = {
     companyId: string;
     whatsappNumber: string;
@@ -1123,7 +1963,8 @@ declare class SendMessageUseCase {
     private readonly sessionRepository;
     private readonly logMessage;
     private readonly objectStorage?;
-    constructor(channel: ChannelAdapterInterface, sessionRepository: SessionRepository, logMessage: LogMessageUseCase, objectStorage?: ObjectStorageInterface | undefined);
+    private readonly documentRepository?;
+    constructor(channel: ChannelAdapterInterface, sessionRepository: SessionRepository, logMessage: LogMessageUseCase, objectStorage?: ObjectStorageInterface | undefined, documentRepository?: DocumentRepository | undefined);
     private assertWithinWindow;
     sendText(params: SendTextParams): Promise<MessageRow | undefined>;
     sendMedia(params: SendMediaParams): Promise<MessageRow | undefined>;
@@ -1176,6 +2017,143 @@ declare class ListMessagesUseCase {
     execute(params: ListMessagesParams): Promise<MessageRow[]>;
 }
 
+type ListConversationDocumentsParams = {
+    companyId: string;
+    whatsappNumber: string;
+    search?: string;
+    /** Origens explícitas. O apelido de UI ("Equipe") é traduzido na borda HTTP, não aqui. */
+    sources?: readonly string[];
+    sortDirection?: 'asc' | 'desc';
+    page?: number;
+    limit?: number;
+};
+/**
+ * O que o `ConversationDocumentsPanel` do conversations-ui consome. O shape é o do pacote de UI
+ * (`ConversationDocument`), com `linkedAt` já em ISO para não obrigar cada host a serializar.
+ */
+type ConversationDocumentView = {
+    /**
+     * O `uploadId` (key no storage), e NÃO o id da linha.
+     *
+     * É este valor que o consumidor devolve para pedir a URL assinada ou montar o zip, então expor o
+     * UUID da tabela aqui fazia o download apontar para um objeto inexistente — falha que só aparece
+     * no clique, porque a assinatura é gerada sem consultar o bucket.
+     */
+    id: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    source: string;
+    linkedAt: string;
+};
+/** Espelha o `ConversationDocumentPage` do conversations-ui: lista da página + total no servidor. */
+type ConversationDocumentsPage = {
+    documents: ConversationDocumentView[];
+    total: number;
+};
+declare class ListConversationDocumentsUseCase {
+    private readonly sessionRepository;
+    private readonly documentRepository;
+    constructor(sessionRepository: SessionRepository, documentRepository: DocumentRepository);
+    execute(params: ListConversationDocumentsParams): Promise<ConversationDocumentsPage>;
+}
+
+type ListCompanyDocumentsParams = {
+    companyId: string;
+    search?: string;
+    /** Origens explícitas. O apelido de UI ("Equipe") é traduzido na borda HTTP, não aqui. */
+    sources?: readonly string[];
+    sortDirection?: 'asc' | 'desc';
+    page?: number;
+    limit?: number;
+};
+/**
+ * Um arquivo na biblioteca da empresa. Igual ao da conversa, mais `conversationId` — sem saber de
+ * quem veio, uma lista global de anexos não responde nenhuma pergunta útil.
+ */
+type CompanyDocumentView = {
+    /** O `uploadId` (key no storage), pelo mesmo motivo do `ConversationDocumentView`. */
+    id: string;
+    conversationId: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    source: string;
+    linkedAt: string;
+};
+type CompanyDocumentsPage = {
+    documents: CompanyDocumentView[];
+    total: number;
+};
+/**
+ * Biblioteca de arquivos de todas as conversas da empresa.
+ *
+ * Existe separada de `ListConversationDocumentsUseCase` porque a pergunta é outra: aquela parte de
+ * uma conversa conhecida, esta varre a empresa e por isso precisa dizer de qual conversa cada
+ * arquivo veio. Reaproveitar a primeira exigiria um `sessionId` opcional que muda o significado do
+ * retorno — dois nomes claros custam menos que um parâmetro que dobra o comportamento.
+ */
+declare class ListCompanyDocumentsUseCase {
+    private readonly documentRepository;
+    constructor(documentRepository: DocumentRepository);
+    execute(params: ListCompanyDocumentsParams): Promise<CompanyDocumentsPage>;
+}
+
+type DeleteConversationParams = {
+    companyId: string;
+    whatsappNumber: string;
+};
+type DeleteConversationResult = {
+    /** Objetos efetivamente apagados no storage. */
+    deletedObjects: number;
+    /** Objetos que o storage recusou. A conversa NÃO é apagada quando isto é maior que zero. */
+    failedObjects: readonly string[];
+};
+/**
+ * Apaga a conversa e a mídia dela.
+ *
+ * A ordem é o ponto: **storage primeiro, banco depois**. A FK de `documents.session_id` é
+ * `on delete cascade`, então apagar a sessão primeiro derrubaria as linhas e levaria embora a única
+ * lista de `uploadId` existente — os binários ficariam órfãos, cobrados para sempre e inalcançáveis.
+ *
+ * Se algum objeto falhar, a conversa é preservada e o chamador recebe a lista. Apagar as linhas
+ * "mesmo assim" transformaria uma falha visível e reexecutável em lixo silencioso no storage.
+ */
+declare class DeleteConversationUseCase {
+    private readonly sessionRepository;
+    private readonly documentRepository;
+    private readonly objectStorage?;
+    constructor(sessionRepository: SessionRepository, documentRepository: DocumentRepository, objectStorage?: ObjectStorageInterface | undefined);
+    execute(params: DeleteConversationParams): Promise<DeleteConversationResult>;
+}
+
+type PurgeExpiredDocumentsParams = {
+    companyId: string;
+    /** Dias de retenção. O produto configura; o módulo não escolhe política de dado pessoal. */
+    retentionDays: number;
+    /** Teto por execução, para o job não segurar conexão nem storage por tempo indefinido. */
+    batchSize?: number;
+    /** Instante de referência — injetado para o teste não depender do relógio. */
+    now?: Date;
+};
+type PurgeExpiredDocumentsResult = {
+    purged: number;
+    failed: readonly string[];
+};
+/**
+ * Apaga documento vencido: objeto no storage primeiro, linha depois — a mesma ordem do
+ * `DeleteConversationUseCase`, e pelo mesmo motivo.
+ *
+ * A linha só cai quando o objeto caiu. Contar como purgado sem ter apagado o binário deixaria lixo
+ * pago no storage sem nenhum registro que o alcance depois: a linha era o único ponteiro.
+ */
+declare class PurgeExpiredDocumentsUseCase {
+    private readonly documentRepository;
+    private readonly objectStorage?;
+    constructor(documentRepository: DocumentRepository, objectStorage?: ObjectStorageInterface | undefined);
+    execute(params: PurgeExpiredDocumentsParams): Promise<PurgeExpiredDocumentsResult>;
+}
+
 type ExportConversationParams = {
     companyId: string;
     whatsappNumber: string;
@@ -1297,10 +2275,77 @@ declare class FlowInterpreter {
     }): Promise<FlowRunResult>;
 }
 
+type FlowMediaLocation = {
+    companyId: string;
+    flowKey: string;
+    nodeId: string;
+};
+type AttachFlowMediaParams = FlowMediaLocation & {
+    uploadId: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    caption?: string;
+    sortOrder?: number;
+};
+type UpdateFlowMediaParams = {
+    companyId: string;
+    id: string;
+    caption?: string | null;
+    sortOrder?: number;
+    active?: boolean;
+};
+declare class FlowMediaRepository {
+    private readonly db;
+    constructor(db: MetaWhatsAppDatabase);
+    private locationFilter;
+    listActive(location: FlowMediaLocation): Promise<FlowMediaRow[]>;
+    listAll(location: FlowMediaLocation): Promise<FlowMediaRow[]>;
+    /**
+     * Anexa um arquivo já existente no storage ao nó.
+     *
+     * `onConflictDoUpdate` em vez de deixar estourar: reanexar o mesmo arquivo é clique repetido no
+     * editor, e o esperado ali é atualizar a legenda/ordem — não um erro de índice único na cara de
+     * quem está montando o fluxo.
+     */
+    attach(params: AttachFlowMediaParams): Promise<FlowMediaRow>;
+    update(params: UpdateFlowMediaParams): Promise<FlowMediaRow | undefined>;
+    /**
+     * Desanexa do nó. Não toca no storage de propósito: o mesmo `uploadId` pode estar anexado a
+     * outro nó ou a outro fluxo, e apagar o binário aqui quebraria os demais. Quem apaga objeto é o
+     * host, que é dono da biblioteca de arquivos.
+     */
+    detach(params: {
+        companyId: string;
+        id: string;
+    }): Promise<void>;
+    detachRemovedNodes(params: {
+        companyId: string;
+        flowKey: string;
+        existingNodeIds: string[];
+    }): Promise<void>;
+}
+
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * O algoritmo mora em `meta-graph-core`, compartilhado com os outros objetos que a Meta assina.
+ * Aqui fica só a tradução para o vocabulário deste domínio: o erro lançado e o namespace do nonce.
+ */
+
 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 const WEBHOOK_NONCE_TTL_SECONDS = 300;
+
 declare function verifyWebhookChallenge(params: {
     mode: string | null;
     token: string | null;
@@ -1312,11 +2357,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;
@@ -1327,11 +2462,15 @@ type ReceiveWebhookResult = {
     duplicate: boolean;
     messagesProcessed: number;
     statusesProcessed: number;
+    ignoredForeignNumber: number;
+    accountEventsProcessed: number;
+    unhandledEvents: number;
 };
 declare class ReceiveWebhookUseCase {
     private readonly params;
     constructor(params: {
         appSecret: string;
+        phoneNumberId: string;
         nonceStore: NonceStoreInterface;
         sessionRepository: SessionRepository;
         messageRepository: MessageRepository;
@@ -1339,12 +2478,53 @@ 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 handleAccountEvent;
     private handleMessage;
     private handleStatus;
+    private dispatch;
 }
 
+/**
+ * Política efetiva de transcrição de uma empresa.
+ *
+ * A separação que este arquivo existe para manter: **ambiente decide se é POSSÍVEL, settings decide
+ * se é para FAZER.** A capacidade (engine, chave, storage que sabe reler) é injetada pelo host e é
+ * por deploy — chave de API não vai para tabela de configuração de tenant. Já "transcrever ou não" e
+ * "automático ou sob demanda" são decisão de operação de cada empresa, e pedir deploy para mudar
+ * isso é o que transforma um interruptor em ticket.
+ */
+type TranscriptionPolicy = {
+    readonly isEnabled: boolean;
+    readonly mode: TranscriptionMode;
+};
+type TranscriptionPolicyDefaults = {
+    /** O que vale quando o painel não decidiu. Tipicamente vem do ambiente do host. */
+    readonly isEnabled: boolean;
+    readonly mode: TranscriptionMode;
+};
+type ResolveTranscriptionPolicyDependencies = {
+    readonly settingsRepository: SettingsRepository;
+    readonly defaults: TranscriptionPolicyDefaults;
+};
+/**
+ * Resolve a política por empresa, com o padrão do host como base.
+ *
+ * Uma consulta a `settings` por áudio transcrito. Não é cacheado de propósito: é uma leitura por
+ * chave primária, acontece uma vez por nota de voz (não por mensagem), e cachear introduziria a
+ * pergunta "por quanto tempo o operador continua vendo o interruptor antigo depois de mexer nele" —
+ * custo real, para economizar um índice único.
+ */
+declare function createTranscriptionPolicyResolver(dependencies: ResolveTranscriptionPolicyDependencies): (companyId: string) => Promise<TranscriptionPolicy>;
+type TranscriptionPolicyResolver = ReturnType<typeof createTranscriptionPolicyResolver>;
+
 type IngestInboundMediaParams = {
     companyId: string;
     messageId: string;
@@ -1355,13 +2535,52 @@ type IngestInboundMediaParams = {
 type IngestInboundMediaResult = {
     uploadId: string;
     alreadyIngested: boolean;
+    /**
+     * Só presente quando a transcrição automática rodou nesta execução. Ausente é o normal: mídia que
+     * não é áudio, transcrição desligada, modo sob demanda, ou mídia já ingerida antes.
+     */
+    transcription?: {
+        status: TranscriptionStatus;
+    };
+};
+/**
+ * Transcrição durante a ingestão — o modo `auto`.
+ *
+ * Entra aqui, e não em use-case separado, por um motivo só: neste ponto o buffer do áudio ACABOU de
+ * ser baixado e está em memória. Transcrever fora daqui custaria um segundo download do storage por
+ * áudio, e o `TranscribeAudioUseCase` existe justamente para esse caso (sob demanda e retomada).
+ */
+type IngestTranscriptionOptions = {
+    transcriber: AudioTranscriber;
+    messageRepository: MessageRepository;
+    /**
+     * Política POR EMPRESA, resolvida a cada áudio. Não é um `mode` fixo porque o interruptor mora nas
+     * configurações da empresa: um valor capturado na construção do use-case congelaria a escolha até
+     * o próximo deploy, e o worker é um processo longo — o operador mexeria no painel e nada mudaria.
+     */
+    resolvePolicy: TranscriptionPolicyResolver;
+    languageHint?: string;
+    hooks?: Pick<MetaWhatsAppHooks, 'onTranscriptionDeferred'>;
 };
 declare class IngestInboundMediaUseCase {
     private readonly db;
     private readonly channel;
     private readonly objectStorage;
-    constructor(db: MetaWhatsAppDatabase, channel: ChannelAdapterInterface, objectStorage: ObjectStorageInterface);
+    private readonly documentRepository?;
+    private readonly transcription?;
+    constructor(db: MetaWhatsAppDatabase, channel: ChannelAdapterInterface, objectStorage: ObjectStorageInterface, documentRepository?: DocumentRepository | undefined, transcription?: IngestTranscriptionOptions | undefined);
     execute(params: IngestInboundMediaParams): Promise<IngestInboundMediaResult>;
+    /**
+     * Transcreve o áudio recém-baixado, quando o modo é `auto`.
+     *
+     * **Nunca propaga erro.** Neste ponto o binário já está no storage e já entrou na biblioteca da
+     * conversa: deixar uma falha de transcrição subir marcaria a ingestão inteira como falha, e o
+     * retry do host baixaria de novo da Meta um arquivo que está salvo — gastando banda para reproduzir
+     * um efeito que já aconteceu. O status fica gravado na mensagem e o `onTranscriptionDeferred`
+     * avisa quem sabe reenfileirar.
+     */
+    private transcribeIfAuto;
+    private recordTranscriptionFailure;
 }
 declare function extractMediaDescriptor(message: MessageRow): {
     sourceMediaId: string;
@@ -1369,6 +2588,105 @@ declare function extractMediaDescriptor(message: MessageRow): {
     filename?: string;
 } | undefined;
 
+/**
+ * Storage com leitura garantida. `getObject` é opcional no contrato, então quem monta este use-case
+ * precisa provar que o método existe — sem os bytes não há o que transcrever, e um use-case que
+ * sempre falha é pior do que a ausência ser visível no tipo.
+ */
+type ReadableObjectStorage = ObjectStorageInterface & {
+    getObject: NonNullable<ObjectStorageInterface['getObject']>;
+};
+type TranscribeAudioParams = {
+    companyId: string;
+    messageId: string;
+    /**
+     * Refaz mesmo com transcrição já salva. Serve ao "transcrever de novo" depois de trocar de engine
+     * — sem isto, um resultado ruim do engine antigo ficaria congelado para sempre.
+     */
+    force?: boolean;
+};
+type TranscribeAudioResult = {
+    status: TranscriptionStatus;
+    text: string | null;
+    language: string | null;
+    engine: string | null;
+    /** `true` quando devolveu o que já estava salvo, sem gastar cota. */
+    alreadyTranscribed: boolean;
+};
+type TranscribeAudioDependencies = {
+    messageRepository: MessageRepository;
+    objectStorage: ReadableObjectStorage;
+    transcriber: AudioTranscriber;
+    /**
+     * Política por empresa. Ausente, a transcrição sob demanda não consulta configuração nenhuma e
+     * atende sempre — que é o comportamento de quem controla o liga/desliga só por ambiente.
+     */
+    resolvePolicy?: TranscriptionPolicyResolver;
+    /** ISO 639-1 do produto. Informar corta a detecção do Whisper e evita pt-BR curto virar espanhol. */
+    languageHint?: string;
+    hooks?: Pick<MetaWhatsAppHooks, 'onTranscriptionDeferred'>;
+};
+/**
+ * Transcreve o áudio de UMA mensagem já persistida e ingerida.
+ *
+ * Serve aos dois modos: é o que o painel chama no botão "transcrever" (`onDemand`) e é o que o host
+ * chama ao retomar um `pending` reenfileirado. O modo `auto` não passa por aqui — ele transcreve
+ * dentro da ingestão, onde o buffer já está em memória e não custa um segundo download.
+ *
+ * Idempotente por `transcription_status`: chamar de novo num `'done'` devolve o que está salvo em
+ * vez de gastar cota transcrevendo o mesmo áudio.
+ */
+declare class TranscribeAudioUseCase {
+    private readonly dependencies;
+    constructor(dependencies: TranscribeAudioDependencies);
+    execute(params: TranscribeAudioParams): Promise<TranscribeAudioResult>;
+    private transcribeBuffer;
+    /**
+     * Carimba o motivo antes de propagar. O status é o que impede os dois desperdícios simétricos:
+     * reprocessar para sempre um codec impossível, e desistir de um áudio que só esbarrou na cota.
+     */
+    private persistFailure;
+}
+declare function resolveFailureStatus(error: unknown): TranscriptionStatus;
+
+/**
+ * Guarda um arquivo gravado no simulador e devolve o id que o webhook vai referenciar.
+ *
+ * Existe como use-case para o host só precisar da ROTA: receber o corpo, chamar isto, devolver o
+ * `mediaId`. A parte que erra — onde gravar, com que chave, como marcar o id para o adaptador
+ * reconhecer depois — fica aqui, num lugar só, e não em cada produto.
+ *
+ * O SDK para exatamente na porta do HTTP: registrar endpoint é do host, e um pacote que abrisse rota
+ * no servidor de quem o instala decidiria caminho, autenticação e versionamento no lugar dele.
+ */
+type StorePreviewMediaParams = {
+    companyId: string;
+    /** Bytes do arquivo. Quem converte de base64 é a rota — o use-case não conhece transporte. */
+    buffer: Buffer;
+    mimeType: string;
+    filename?: string;
+};
+type StorePreviewMediaResult = {
+    /** Já com o prefixo: é isto que o simulador manda no webhook. */
+    mediaId: string;
+    uploadId: string;
+};
+declare class StorePreviewMediaUseCase {
+    private readonly objectStorage;
+    /**
+     * Fonte do sufixo único da chave. Injetada porque o módulo não escolhe gerador de id — e porque
+     * um teste precisa de chave previsível.
+     */
+    private readonly generateKeySuffix;
+    constructor(objectStorage: ObjectStorageInterface, 
+    /**
+     * Fonte do sufixo único da chave. Injetada porque o módulo não escolhe gerador de id — e porque
+     * um teste precisa de chave previsível.
+     */
+    generateKeySuffix: () => string);
+    execute(params: StorePreviewMediaParams): Promise<StorePreviewMediaResult>;
+}
+
 interface MetaWhatsAppModuleConfig {
     phoneNumberId: string;
     accessToken: string;
@@ -1377,16 +2695,66 @@ interface MetaWhatsAppModuleConfig {
     wabaId?: string;
     apiVersion?: string;
     baseUrl?: string;
+    /**
+     * Catálogo do Meta Commerce que a vitrine no chat oferece. Sem ele — ou sem `providers.catalog`
+     * — a action `send_product_list` não é registrada: nó que o editor oferece e que em silêncio não
+     * faz nada é pior do que nó que não existe.
+     */
+    catalogId?: string;
 }
 interface MetaWhatsAppModuleFeatures {
     flowEngine?: boolean;
+    flowGraphCache?: boolean | {
+        ttlSeconds?: number;
+    };
+    /**
+     * Aceita mídia do simulador de conversa — o que faz o microfone aparecer no preview do cliente.
+     *
+     * **Desligado por omissão, e a decisão é consciente.** Ligado, o canal passa a aceitar id que não
+     * veio da Meta: `preview-upload:<chave>` faz o servidor ler aquele objeto do storage. Em ambiente
+     * de simulação isso é o recurso; em produção é leitura arbitrária do bucket por webhook forjado.
+     *
+     * Exige `providers.objectStorage` com `getObject` — sem os bytes não há o que devolver, e o flag é
+     * ignorado em vez de produzir um canal que falha na primeira nota de voz.
+     */
+    previewMedia?: boolean;
+}
+/**
+ * Transcrição de áudio. Ausente = desligada, e as colunas ficam nulas ("não avaliado").
+ *
+ * `mode` é a decisão de produto que este objeto existe para carregar: `auto` transcreve toda nota de
+ * voz recebida, na ingestão, onde o buffer já está em memória; `onDemand` só transcreve quando o
+ * atendente pede, gastando cota apenas com áudio que alguém vai ler de fato.
+ */
+interface MetaWhatsAppTranscriptionConfig {
+    transcriber: AudioTranscriber;
+    /**
+     * PADRÃO, não decisão final: vale para as empresas que não mexeram no interruptor do painel. As
+     * configurações por empresa (`settings.transcriptionMode`) têm precedência.
+     *
+     * Padrão `onDemand` — o modo que não gasta cota sem alguém pedir.
+     */
+    mode?: TranscriptionMode;
+    /**
+     * PADRÃO de ligado/desligado para empresas sem escolha registrada. `true` — injetar o transcritor
+     * já é a declaração de que o host quer o recurso; quem controla por empresa usa o painel.
+     */
+    isEnabledByDefault?: boolean;
+    /** ISO 639-1 do produto (ex.: `'pt'`). Corta a detecção de idioma do engine. */
+    languageHint?: string;
 }
 interface MetaWhatsAppModuleProviders {
     objectStorage?: ObjectStorageInterface;
+    cache?: CacheInterface;
     realtime?: RealtimeNotifierInterface;
     subjectResolver?: SubjectResolverInterface;
     catalog?: CatalogPort;
     moderator?: MessageModerator;
+    /**
+     * Converte nota de voz em texto. Exige `objectStorage` com `getObject` para o modo sob demanda —
+     * transcrever um áudio já salvo significa ler os bytes de volta.
+     */
+    transcription?: MetaWhatsAppTranscriptionConfig;
 }
 interface CreateMetaWhatsAppModuleParams {
     db: MetaWhatsAppDatabase;
@@ -1407,10 +2775,31 @@ declare function createMetaWhatsAppModule(params: CreateMetaWhatsAppModuleParams
         release: ReleaseConversationUseCase;
         list: ListConversationsUseCase;
         listMessages: ListMessagesUseCase;
+        listDocuments: ListConversationDocumentsUseCase;
+        listCompanyDocuments: ListCompanyDocumentsUseCase;
+        delete: DeleteConversationUseCase;
+        purgeExpiredDocuments: PurgeExpiredDocumentsUseCase;
         export: ExportConversationUseCase;
+        transcribeAudio: TranscribeAudioUseCase | undefined;
         repository: SessionRepository;
+        messageRepository: MessageRepository;
+        documentRepository: DocumentRepository;
     };
+    /**
+     * `undefined` = o host não injetou transcritor, e nenhuma configuração de empresa muda isso: a
+     * capacidade não existe. Presente, `resolvePolicy` responde o que vale para uma empresa —
+     * é o que a rota de configurações usa para dizer ao painel se desenha o interruptor.
+     */
+    transcription: {
+        defaultMode: TranscriptionMode;
+        resolvePolicy: (companyId: string) => Promise<TranscriptionPolicy>;
+    } | undefined;
     settings: SettingsRepository;
+    /**
+     * `undefined` quando o recurso não está ligado (ou falta storage legível). O host consulta a
+     * ausência para não registrar a rota de upload — e o preview, sem a rota, esconde o microfone.
+     */
+    previewMedia: StorePreviewMediaUseCase | undefined;
     webhook: {
         receive: ReceiveWebhookUseCase;
         verifyChallenge: (query: {
@@ -1429,26 +2818,49 @@ declare function createMetaWhatsAppModule(params: CreateMetaWhatsAppModuleParams
         delete: DeleteFlowGraphUseCase;
         livePositions: GetLiveFlowPositionsUseCase;
         repository: FlowGraphRepository;
+        mediaRepository: FlowMediaRepository;
     } | undefined;
     catalog: CatalogPort | undefined;
 };
 type MetaWhatsAppModule = ReturnType<typeof createMetaWhatsAppModule>;
 
+/**
+ * Leitura de mídia do simulador de conversa.
+ *
+ * **Atrás de flag de propósito, e não ligado por omissão.** Aceitar id que não veio da Meta é
+ * exatamente o que um webhook forjado exploraria: bastaria mandar `preview-upload:<chave>` para
+ * fazer o servidor ler um objeto arbitrário do storage e devolvê-lo. Num ambiente de simulação isso
+ * é o recurso; em produção é leitura arbitrária. Quem liga assume, e a decisão fica visível no
+ * lugar onde o módulo é montado.
+ */
+type PreviewMediaSupport = {
+    readonly isEnabled: boolean;
+    readonly objectStorage: ObjectStorageInterface & {
+        getObject: NonNullable<ObjectStorageInterface['getObject']>;
+    };
+    /** Mime a devolver, já que o storage guarda bytes e não o tipo. Padrão `audio/ogg`. */
+    readonly defaultMimeType?: string;
+};
 declare class WhatsAppChannelAdapter implements ChannelAdapterInterface {
     private readonly messages;
-    constructor(messages: WhatsAppMessageProvider);
+    /**
+     * Ausente, o adaptador se comporta como sempre: todo id vai para a Graph API. É o que garante
+     * que atualizar o pacote não abre nada em quem não pediu.
+     */
+    private readonly previewMedia?;
+    constructor(messages: WhatsAppMessageProvider, 
+    /**
+     * Ausente, o adaptador se comporta como sempre: todo id vai para a Graph API. É o que garante
+     * que atualizar o pacote não abre nada em quem não pediu.
+     */
+    previewMedia?: PreviewMediaSupport | undefined);
     private translateErrors;
     sendText(to: string, body: string): Promise<{
         externalMessageId: string | null;
     }>;
-    sendMedia(params: {
-        to: string;
-        buffer: Buffer;
-        mimeType: string;
-        filename: string;
-        caption?: string;
-    }): Promise<{
+    sendMedia(params: SendChannelMediaParams): Promise<{
         externalMessageId: string | null;
+        mediaId?: string | undefined;
     }>;
     sendTemplate(params: {
         to: string;
@@ -1469,6 +2881,34 @@ declare class WhatsAppChannelAdapter implements ChannelAdapterInterface {
     }): Promise<{
         externalMessageId: string | null;
     }>;
+    sendInteractiveButtons(params: {
+        to: string;
+        body: string;
+        buttons: {
+            id: string;
+            title: string;
+        }[];
+    }): Promise<{
+        externalMessageId: string | null;
+    }>;
+    sendProductList(params: {
+        to: string;
+        headerText: string;
+        body: string;
+        footerText?: string;
+        sections: {
+            title: string;
+            retailerIds: string[];
+        }[];
+    }): Promise<{
+        externalMessageId: string | null;
+    }>;
+    /**
+     * Busca o binário da mídia — da Meta, ou do storage quando o id é do simulador.
+     *
+     * O desvio acontece ANTES de qualquer chamada de rede: id do simulador não existe na Meta, e
+     * tentar buscá-lo lá renderia um 404 confuso em vez do áudio que o operador acabou de gravar.
+     */
     fetchMediaAsBase64(mediaId: string): Promise<{
         data: string;
         mimeType: string;
@@ -1512,4 +2952,132 @@ declare function redeemSseTicket(store: TicketStoreInterface, ticket: string): P
     whatsappNumber: string;
 } | null>;
 
-export { type CreateFlowGraphParams, CreateFlowGraphUseCase, type CreateMetaWhatsAppModuleParams, DeleteFlowGraphUseCase, type DrizzleMigrateFunction, type ExportConversationParams, type ExportConversationResult, ExportConversationUseCase, FlowGraphRepository, type FlowGraphRow, FlowInterpreter, type FlowRunResult, type FlowStepInput, type FlowStepResult, GetFlowGraphUseCase, GetLiveFlowPositionsUseCase, type IngestInboundMediaParams, type IngestInboundMediaResult, IngestInboundMediaUseCase, type InsertMessageParams, InvalidFlowGraphError, type ListConversationsFilters, type ListConversationsParams, ListConversationsUseCase, 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 NewFlowGraphRow, type NewMessageRow, type NewSessionRow, type NewSettingsRow, type NonceStoreInterface, OptimisticLockError, type RealtimeRelay, type ReceiveWebhookParams, type ReceiveWebhookResult, ReceiveWebhookUseCase, type ReleaseConversationParams, ReleaseConversationUseCase, type ListMessagesParams$1 as RepositoryListMessagesParams, type RunMetaWhatsAppMigrationsParams, type SaveFlowGraphParams, SaveFlowGraphUseCase, type SendMediaParams, SendMessageUseCase, type SendTemplateParams, type SendTextParams, SessionRepository, type SessionRow, SettingsRepository, type SettingsRow, SseHub, type SseListener, type TakeoverConversationParams, TakeoverConversationUseCase, type TicketStoreInterface, WEBHOOK_NONCE_TTL_SECONDS, WhatsAppChannelAdapter, claimWebhookDelivery, createMetaWhatsAppModule, extractMediaDescriptor, flowGraphs, issueSseTicket, messages, metaWhatsAppMigrationsFolder, metaWhatsAppSchema, redeemSseTicket, runMetaWhatsAppMigrations, sessions, settings, verifyWebhookChallenge, verifyWebhookSignature };
+/**
+ * Porta de escrita no transcript, e não a classe `LogMessageUseCase`.
+ *
+ * Exigir a classe amarraria a action a quem já guarda as mensagens nas tabelas do módulo — um host
+ * em migração, com o transcript ainda no schema dele, não conseguiria usar a única action built-in
+ * sem gravar o envio numa tabela que o painel dele não lê. O que a action precisa é só de um lugar
+ * para registrar o que saiu.
+ */
+/**
+ * Onde guardar o `mediaId` que a Meta devolveu para cada arquivo da biblioteca.
+ *
+ * Porta, e não tabela: o módulo não sabe se o host guarda isso numa coluna, no Redis ou em memória.
+ * O que ele precisa é reaproveitar o id em vez de ressubir o mesmo binário para cada cliente que
+ * passa pelo nó — a Meta aceita reusar por 30 dias.
+ */
+type FlowMediaIdStore = {
+    get(params: {
+        flowMediaId: string;
+        senderKey: string;
+    }): Promise<string | undefined>;
+    set(params: {
+        flowMediaId: string;
+        senderKey: string;
+        mediaId: string;
+    }): Promise<void>;
+    clear(params: {
+        flowMediaId: string;
+        senderKey: string;
+    }): Promise<void>;
+};
+/**
+ * O `senderKey` vem junto do store, e não solto, para não existir a forma inválida.
+ *
+ * O `mediaId` é escopado ao número remetente (`phone_number_id`) na Meta: cachear sem separar por
+ * número faz o id de um número ser mandado pelo outro, e o envio falha. Exigi-lo dentro do mesmo
+ * objeto torna "liguei o cache e esqueci o número" impossível de escrever.
+ */
+type FlowMediaIdCache = {
+    readonly store: FlowMediaIdStore;
+    readonly senderKey: string;
+};
+type FlowMediaTranscriptLogger = {
+    execute(params: LogMessageParams): Promise<unknown>;
+};
+type CreateSendMediaActionParams = {
+    flowMediaRepository: FlowMediaRepository;
+    objectStorage: ObjectStorageInterface & {
+        getObject: NonNullable<ObjectStorageInterface['getObject']>;
+    };
+    logMessage: FlowMediaTranscriptLogger;
+    /**
+     * Reaproveitamento do arquivo já subido. Capacidade por ausência: sem o cache, cada envio ressobe
+     * o binário — exatamente o comportamento anterior, sem flag para desligar.
+     */
+    mediaIdCache?: FlowMediaIdCache;
+    startState: SessionState;
+    onError?: (error: unknown, details: {
+        flowKey: string;
+        nodeId: string;
+        uploadId: string;
+    }) => void;
+};
+declare function createSendMediaAction(params: CreateSendMediaActionParams): FlowActionHandler;
+
+/** Tetos da Meta para `interactive.product_list`. Acima disso a mensagem inteira é recusada. */
+declare const PRODUCT_LIST_LIMIT: {
+    readonly ITEMS: 30;
+    readonly SECTIONS: 10;
+};
+type CreateSendProductListActionParams = {
+    catalog: CatalogPort;
+    catalogId: string;
+    logMessage: FlowMediaTranscriptLogger;
+    startState: SessionState;
+    /** Falha de UMA vitrine não pode travar a conversa; o host observa por aqui. */
+    onError?: (error: unknown, details: {
+        flowKey: string;
+        nodeId: string;
+    }) => void;
+};
+/**
+ * Action `send_product_list`: ao passar pelo nó, envia a vitrine do catálogo publicado na Meta.
+ *
+ * O nó guarda **critério**, não a lista de produtos. Congelar `retailerId` em `actionParams` faria
+ * o fluxo continuar oferecendo o item esgotado — ou o item excluído, que a Meta recusa junto com a
+ * mensagem inteira. O que o operador edita é o texto e o filtro; o estoque manda no resto.
+ *
+ * Só produto em estoque entra. Vitrine que mostra o que não tem produz a pior conversa possível:
+ * o cliente escolhe, responde, e recebe "acabou".
+ */
+declare function createSendProductListAction(params: CreateSendProductListActionParams): FlowActionHandler;
+
+/**
+ * Store padrão do cache de `mediaId`, na própria linha da biblioteca de mídia.
+ *
+ * A porta `FlowMediaIdStore` existe para o host poder escolher Redis ou memória. Esta é a
+ * implementação que o módulo já traz pronta, para o caso comum não exigir nada de quem instala: a
+ * tabela é do módulo, a coluna é do módulo, e sem isso todo host reescreveria o mesmo repositório.
+ *
+ * Um mapa por `phone_number_id` na mesma linha, e não uma tabela à parte: o id não existe sem o
+ * arquivo, morre com ele, e a linha é lida de qualquer forma no envio.
+ */
+declare class FlowMediaIdRepository implements FlowMediaIdStore {
+    private readonly db;
+    constructor(db: MetaWhatsAppDatabase);
+    get(params: {
+        flowMediaId: string;
+        senderKey: string;
+    }): Promise<string | undefined>;
+    /**
+     * Grava só a chave deste número.
+     *
+     * `jsonb_set` no banco, e não ler-alterar-escrever na aplicação: dois clientes passando pelo nó
+     * ao mesmo tempo com números diferentes leriam o mesmo mapa e o último gravaria por cima,
+     * apagando o id do outro. A escrita atômica não tem essa janela.
+     */
+    set(params: {
+        flowMediaId: string;
+        senderKey: string;
+        mediaId: string;
+    }): Promise<void>;
+    /** Remove só a chave deste número — o id do outro número continua válido. */
+    clear(params: {
+        flowMediaId: string;
+        senderKey: string;
+    }): Promise<void>;
+}
+
+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 FlowMediaIdCache, FlowMediaIdRepository, type FlowMediaIdStore, 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 };