@adatechnology/meta-whatsapp-module 0.2.0-rc.16 → 0.2.0-rc.18

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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, CacheInterface, 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, MetaWhatsAppHooks, SubjectResolverInterface, CatalogPort } from '@adatechnology/meta-whatsapp-contracts';
+export { PREVIEW_MEDIA_ID_PREFIX, TranscriptionMode, resolvePreviewUploadId, toPreviewMediaId } from '@adatechnology/meta-whatsapp-contracts';
 import { WhatsAppMessageProvider } from '@adatechnology/meta-whatsapp-provider';
 
 type MetaWhatsAppDatabase = PgDatabase<PgQueryResultHKT, any, any>;
@@ -10,6 +11,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 +627,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";
@@ -1363,6 +1505,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";
@@ -1479,11 +1658,83 @@ 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>;
 }
 
+interface InsertMessageParams {
+    companyId: string;
+    sessionId: string;
+    whatsappNumber: string;
+    direction: MessageDirection;
+    sender: MessageSender;
+    agentUserId?: string | null;
+    type: string;
+    content?: string | null;
+    payload?: Record<string, unknown> | null;
+    waMessageId?: string | null;
+    status?: MessageStatus | null;
+    /** `undefined` deixa a coluna nula: não avaliado, distinto de avaliado e limpo. */
+    moderationFlagged?: boolean | null;
+    moderationTerms?: string[] | null;
+}
+interface ListMessagesParams$1 {
+    companyId: string;
+    sessionId: string;
+    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.
@@ -1538,36 +1789,6 @@ declare class SettingsRepository {
     resolveTemplateVariables(companyId: string, context: Record<string, unknown>): Promise<string[]>;
 }
 
-interface InsertMessageParams {
-    companyId: string;
-    sessionId: string;
-    whatsappNumber: string;
-    direction: MessageDirection;
-    sender: MessageSender;
-    agentUserId?: string | null;
-    type: string;
-    content?: string | null;
-    payload?: Record<string, unknown> | null;
-    waMessageId?: string | null;
-    status?: MessageStatus | null;
-    /** `undefined` deixa a coluna nula: não avaliado, distinto de avaliado e limpo. */
-    moderationFlagged?: boolean | null;
-    moderationTerms?: string[] | null;
-}
-interface ListMessagesParams$1 {
-    companyId: string;
-    sessionId: string;
-    limit?: number;
-    before?: string;
-}
-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>;
-    listByConversation(params: ListMessagesParams$1): Promise<MessageRow[]>;
-}
-
 type LogMessageParams = Omit<InsertMessageParams, 'sessionId'> & {
     startState: SessionState;
 };
@@ -2133,6 +2354,39 @@ declare class ReceiveWebhookUseCase {
     private handleStatus;
 }
 
+/**
+ * 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;
@@ -2143,14 +2397,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;
     private readonly documentRepository?;
-    constructor(db: MetaWhatsAppDatabase, channel: ChannelAdapterInterface, objectStorage: ObjectStorageInterface, documentRepository?: DocumentRepository | undefined);
+    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;
@@ -2158,6 +2450,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;
@@ -2172,6 +2563,41 @@ interface MetaWhatsAppModuleFeatures {
     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;
@@ -2180,6 +2606,11 @@ interface MetaWhatsAppModuleProviders {
     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;
@@ -2205,10 +2636,26 @@ declare function createMetaWhatsAppModule(params: CreateMetaWhatsAppModuleParams
         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: {
@@ -2233,9 +2680,36 @@ declare function createMetaWhatsAppModule(params: CreateMetaWhatsAppModuleParams
 };
 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;
@@ -2268,6 +2742,12 @@ declare class WhatsAppChannelAdapter implements ChannelAdapterInterface {
     }): 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;
@@ -2349,4 +2829,4 @@ type CreateSendMediaActionParams = {
  */
 declare function createSendMediaAction(params: CreateSendMediaActionParams): FlowActionHandler;
 
-export { type AttachFlowMediaParams, type CompanyDocumentView, type CompanyDocumentsPage, type ConversationDocumentView, type ConversationDocumentsPage, type CreateFlowGraphParams, CreateFlowGraphUseCase, type CreateMetaWhatsAppModuleParams, type CreateSendMediaActionParams, DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS, type DeleteConversationParams, type DeleteConversationResult, DeleteConversationUseCase, DeleteFlowGraphUseCase, DocumentRepository, type DocumentRow, type DrizzleMigrateFunction, type ExportConversationParams, type ExportConversationResult, ExportConversationUseCase, FlowGraphCache, FlowGraphRepository, type FlowGraphRow, FlowInterpreter, type FlowMediaLocation, FlowMediaRepository, type FlowMediaRow, type FlowMediaTranscriptLogger, type FlowRunResult, type FlowStepInput, type FlowStepResult, GetFlowGraphUseCase, GetLiveFlowPositionsUseCase, type IngestInboundMediaParams, type IngestInboundMediaResult, IngestInboundMediaUseCase, type 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 NewDocumentRow, type NewFlowGraphRow, type NewFlowMediaRow, type NewMessageRow, type NewSessionRow, type NewSettingsRow, type NonceStoreInterface, OptimisticLockError, type PurgeExpiredDocumentsParams, type PurgeExpiredDocumentsResult, PurgeExpiredDocumentsUseCase, 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, type UpdateFlowMediaParams, WEBHOOK_NONCE_TTL_SECONDS, WhatsAppChannelAdapter, claimWebhookDelivery, createMetaWhatsAppModule, createSendMediaAction, documents, extractMediaDescriptor, flowGraphs, flowMedia, issueSseTicket, messages, metaWhatsAppMigrationsFolder, metaWhatsAppSchema, redeemSseTicket, runMetaWhatsAppMigrations, sessions, settings, verifyWebhookChallenge, verifyWebhookSignature };
+export { type AttachFlowMediaParams, type AudioTranscriber, type CompanyDocumentView, type CompanyDocumentsPage, type ConversationDocumentView, type ConversationDocumentsPage, type CreateFlowGraphParams, CreateFlowGraphUseCase, type CreateMetaWhatsAppModuleParams, type CreateSendMediaActionParams, DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS, type DeleteConversationParams, type DeleteConversationResult, DeleteConversationUseCase, DeleteFlowGraphUseCase, DocumentRepository, type DocumentRow, type DrizzleMigrateFunction, type ExportConversationParams, type ExportConversationResult, ExportConversationUseCase, FlowGraphCache, FlowGraphRepository, type FlowGraphRow, FlowInterpreter, type FlowMediaLocation, FlowMediaRepository, type FlowMediaRow, type FlowMediaTranscriptLogger, type FlowRunResult, type FlowStepInput, type FlowStepResult, GetFlowGraphUseCase, GetLiveFlowPositionsUseCase, type IngestInboundMediaParams, type IngestInboundMediaResult, IngestInboundMediaUseCase, type IngestTranscriptionOptions, type InsertMessageParams, InvalidFlowGraphError, type LinkDocumentParams, type ListCompanyDocumentsParams, ListCompanyDocumentsUseCase, type ListConversationDocumentsParams, ListConversationDocumentsUseCase, type ListConversationsFilters, type ListConversationsParams, ListConversationsUseCase, type ListDocumentsParams, type ListDocumentsResult, ListFlowGraphsUseCase, type ListMessagesParams, ListMessagesUseCase, type LogMessageParams, LogMessageUseCase, META_WHATSAPP_MIGRATIONS_TABLE, type MessageModerator, MessageRepository, type MessageRow, type MetaWhatsAppDatabase, type MetaWhatsAppModule, type MetaWhatsAppModuleConfig, type MetaWhatsAppModuleFeatures, type MetaWhatsAppModuleProviders, type MetaWhatsAppTranscriptionConfig, type NewDocumentRow, type NewFlowGraphRow, type NewFlowMediaRow, type NewMessageRow, type NewSessionRow, type NewSettingsRow, type NonceStoreInterface, OptimisticLockError, type PreviewMediaSupport, type PurgeExpiredDocumentsParams, type PurgeExpiredDocumentsResult, PurgeExpiredDocumentsUseCase, type RealtimeRelay, type ReceiveWebhookParams, type ReceiveWebhookResult, ReceiveWebhookUseCase, type ReleaseConversationParams, ReleaseConversationUseCase, type ListMessagesParams$1 as RepositoryListMessagesParams, type ResolveTranscriptionPolicyDependencies, type RunMetaWhatsAppMigrationsParams, type SaveFlowGraphParams, SaveFlowGraphUseCase, type SaveTranscriptionByWaMessageIdParams, type SaveTranscriptionParams, type SendMediaParams, SendMessageUseCase, type SendTemplateParams, type SendTextParams, SessionRepository, type SessionRow, SettingsRepository, type SettingsRow, SseHub, type SseListener, type StorePreviewMediaParams, type StorePreviewMediaResult, StorePreviewMediaUseCase, TRANSCRIPTION_MODE, TRANSCRIPTION_STATUS, type TakeoverConversationParams, TakeoverConversationUseCase, type TicketStoreInterface, type TranscribeAudioDependencies, type TranscribeAudioParams, type TranscribeAudioResult, TranscribeAudioUseCase, type TranscriptionPolicy, type TranscriptionPolicyDefaults, type TranscriptionPolicyResolver, type TranscriptionStatus, type UpdateFlowMediaParams, WEBHOOK_NONCE_TTL_SECONDS, WhatsAppChannelAdapter, claimWebhookDelivery, createMetaWhatsAppModule, createSendMediaAction, createTranscriptionPolicyResolver, documents, extractMediaDescriptor, flowGraphs, flowMedia, isAudioMimeType, isRetriableTranscriptionError, isUnsupportedTranscriptionError, issueSseTicket, messages, metaWhatsAppMigrationsFolder, metaWhatsAppSchema, redeemSseTicket, resolveFailureStatus, runMetaWhatsAppMigrations, sessions, settings, transcriptionRetryAfterSeconds, verifyWebhookChallenge, verifyWebhookSignature };