@adatechnology/meta-whatsapp-module 0.2.0-rc.2 → 0.2.0-rc.20

package/dist/index.cjs

@@ -8,11 +8,11 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc2) => {
+var __copyProps = (to, from, except, desc3) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
       if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc2 = __getOwnPropDesc(from, key)) || desc2.enumerable });
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc3 = __getOwnPropDesc(from, key)) || desc3.enumerable });
   }
   return to;
 };
@@ -22,20 +22,30 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CreateFlowGraphUseCase: () => CreateFlowGraphUseCase,
+  DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS: () => DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS,
+  DeleteConversationUseCase: () => DeleteConversationUseCase,
   DeleteFlowGraphUseCase: () => DeleteFlowGraphUseCase,
+  DocumentRepository: () => DocumentRepository,
   ExportConversationUseCase: () => ExportConversationUseCase,
+  FlowGraphCache: () => FlowGraphCache,
   FlowGraphRepository: () => FlowGraphRepository,
   FlowInterpreter: () => FlowInterpreter,
+  FlowMediaRepository: () => FlowMediaRepository,
   GetFlowGraphUseCase: () => GetFlowGraphUseCase,
   GetLiveFlowPositionsUseCase: () => GetLiveFlowPositionsUseCase,
   IngestInboundMediaUseCase: () => IngestInboundMediaUseCase,
   InvalidFlowGraphError: () => InvalidFlowGraphError,
+  ListCompanyDocumentsUseCase: () => ListCompanyDocumentsUseCase,
+  ListConversationDocumentsUseCase: () => ListConversationDocumentsUseCase,
   ListConversationsUseCase: () => ListConversationsUseCase,
   ListFlowGraphsUseCase: () => ListFlowGraphsUseCase,
   ListMessagesUseCase: () => ListMessagesUseCase,
   LogMessageUseCase: () => LogMessageUseCase,
+  META_WHATSAPP_MIGRATIONS_TABLE: () => META_WHATSAPP_MIGRATIONS_TABLE,
   MessageRepository: () => MessageRepository,
   OptimisticLockError: () => OptimisticLockError,
+  PREVIEW_MEDIA_ID_PREFIX: () => import_meta_whatsapp_contracts8.PREVIEW_MEDIA_ID_PREFIX,
+  PurgeExpiredDocumentsUseCase: () => PurgeExpiredDocumentsUseCase,
   ReceiveWebhookUseCase: () => ReceiveWebhookUseCase,
   ReleaseConversationUseCase: () => ReleaseConversationUseCase,
   SaveFlowGraphUseCase: () => SaveFlowGraphUseCase,
@@ -43,20 +53,36 @@ __export(index_exports, {
   SessionRepository: () => SessionRepository,
   SettingsRepository: () => SettingsRepository,
   SseHub: () => SseHub,
+  StorePreviewMediaUseCase: () => StorePreviewMediaUseCase,
+  TRANSCRIPTION_MODE: () => TRANSCRIPTION_MODE,
+  TRANSCRIPTION_STATUS: () => TRANSCRIPTION_STATUS,
   TakeoverConversationUseCase: () => TakeoverConversationUseCase,
+  TranscribeAudioUseCase: () => TranscribeAudioUseCase,
   WEBHOOK_NONCE_TTL_SECONDS: () => WEBHOOK_NONCE_TTL_SECONDS,
   WhatsAppChannelAdapter: () => WhatsAppChannelAdapter,
   claimWebhookDelivery: () => claimWebhookDelivery,
   createMetaWhatsAppModule: () => createMetaWhatsAppModule,
+  createSendMediaAction: () => createSendMediaAction,
+  createTranscriptionPolicyResolver: () => createTranscriptionPolicyResolver,
+  documents: () => documents,
   extractMediaDescriptor: () => extractMediaDescriptor,
   flowGraphs: () => flowGraphs,
+  flowMedia: () => flowMedia,
+  isAudioMimeType: () => isAudioMimeType,
+  isRetriableTranscriptionError: () => isRetriableTranscriptionError,
+  isUnsupportedTranscriptionError: () => isUnsupportedTranscriptionError,
   issueSseTicket: () => issueSseTicket,
   messages: () => messages,
+  metaWhatsAppMigrationsFolder: () => metaWhatsAppMigrationsFolder,
   metaWhatsAppSchema: () => metaWhatsAppSchema,
   redeemSseTicket: () => redeemSseTicket,
+  resolveFailureStatus: () => resolveFailureStatus,
+  resolvePreviewUploadId: () => import_meta_whatsapp_contracts8.resolvePreviewUploadId,
   runMetaWhatsAppMigrations: () => runMetaWhatsAppMigrations,
   sessions: () => sessions,
   settings: () => settings,
+  toPreviewMediaId: () => import_meta_whatsapp_contracts8.toPreviewMediaId,
+  transcriptionRetryAfterSeconds: () => transcriptionRetryAfterSeconds,
   verifyWebhookChallenge: () => verifyWebhookChallenge,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
@@ -64,6 +90,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/createMetaWhatsAppModule.ts
 var import_meta_whatsapp_provider = require("@adatechnology/meta-whatsapp-provider");
+var import_meta_whatsapp_contracts13 = require("@adatechnology/meta-whatsapp-contracts");
 
 // src/repositories/SessionRepository.ts
 var import_drizzle_orm2 = require("drizzle-orm");
@@ -139,9 +166,14 @@ var messages = metaWhatsAppSchema.table("messages", {
     length: 12
   }).notNull(),
   agentUserId: (0, import_pg_core.uuid)("agent_user_id"),
-  type: (0, import_pg_core.varchar)("type", {
-    length: 16
-  }).notNull().default("text"),
+  // 32, não 16: os tipos da própria Meta são curtos ('text', 'interactive'), mas o host rotula
+  type: (
+    // a saída com o subtipo que enviou ('interactive_buttons' já tem 19). Apertar aqui só
+    // transfere para o consumidor a escolha entre truncar o rótulo e estourar o insert.
+    (0, import_pg_core.varchar)("type", {
+      length: 32
+    }).notNull().default("text")
+  ),
   content: (0, import_pg_core.text)("content"),
   // T5.4 — nunca base64 aqui; mídia vive no ObjectStorageInterface do host, referenciada por
   // uploadId dentro deste jsonb.
@@ -155,6 +187,33 @@ var messages = metaWhatsAppSchema.table("messages", {
   readAt: (0, import_pg_core.timestamp)("read_at", {
     withTimezone: true
   }),
+  // Moderação de conteúdo. `null` significa NÃO AVALIADO (moderação desligada, ou mensagem
+  // anterior ao recurso) — diferente de `false`, que é avaliado e limpo. Colunas em vez de chave
+  // dentro de `payload` porque "listar o que foi sinalizado" é consulta de operação, e índice
+  // parcial sobre boolean resolve isso sem cavar jsonb.
+  moderationFlagged: (0, import_pg_core.boolean)("moderation_flagged"),
+  moderationTerms: (0, import_pg_core.jsonb)("moderation_terms").$type(),
+  /**
+   * Transcrição de áudio. `null` em `transcription_status` significa NÃO AVALIADO — áudio nunca
+   * pedido (modo sob demanda), transcrição desligada, mensagem anterior ao recurso, ou mensagem
+   * que não é áudio. Diferente de `'done'` com texto vazio, que é áudio em silêncio já processado
+   * e que NÃO deve ser reprocessado.
+   *
+   * Colunas em vez de chave em `payload` pelo mesmo motivo da moderação: "quais áudios ficaram
+   * pendentes" e "quais falharam" são consultas de operação, e índice parcial resolve sem cavar
+   * jsonb. Buscar texto de áudio também deixa de exigir varredura de payload.
+   */
+  transcriptionStatus: (0, import_pg_core.varchar)("transcription_status", {
+    length: 16
+  }).$type(),
+  transcriptionText: (0, import_pg_core.text)("transcription_text"),
+  transcriptionLanguage: (0, import_pg_core.varchar)("transcription_language", {
+    length: 32
+  }),
+  /** Qual engine produziu. Com uma cadeia de engines, é o que responde "por que esta saiu ruim". */
+  transcriptionEngine: (0, import_pg_core.varchar)("transcription_engine", {
+    length: 32
+  }),
   createdAt: (0, import_pg_core.timestamp)("created_at", {
     withTimezone: true
   }).notNull().defaultNow()
@@ -166,7 +225,54 @@ var messages = metaWhatsAppSchema.table("messages", {
   // paralelo, então as duas passariam pela checagem e inseririam duplicado. Parcial porque
   // mensagens outbound ainda sem waMessageId (envio em curso) são legitimamente NULL, e NULLs
   // não podem competir entre si por unicidade.
-  (0, import_pg_core.uniqueIndex)("idx_messages_company_wa_message_id").on(table.companyId, table.waMessageId).where(import_drizzle_orm.sql`${table.waMessageId} is not null`)
+  (0, import_pg_core.uniqueIndex)("idx_messages_company_wa_message_id").on(table.companyId, table.waMessageId).where(import_drizzle_orm.sql`${table.waMessageId} is not null`),
+  // Parcial: só as sinalizadas entram, então o índice fica do tamanho do problema e não do
+  // tamanho do transcript.
+  (0, import_pg_core.index)("idx_messages_moderation_flagged").on(table.companyId, table.createdAt).where(import_drizzle_orm.sql`${table.moderationFlagged}`),
+  // Alimenta a varredura de retomada: "quais áudios ficaram pendentes de transcrição". Parcial
+  // porque pendente é estado transitório e raro — o índice fica do tamanho da fila atrasada, não
+  // do transcript inteiro.
+  (0, import_pg_core.index)("idx_messages_transcription_pending").on(table.companyId, table.createdAt).where(import_drizzle_orm.sql`${table.transcriptionStatus} = 'pending'`)
+]);
+var documents = metaWhatsAppSchema.table("documents", {
+  id: (0, import_pg_core.uuid)("id").primaryKey().defaultRandom(),
+  companyId: (0, import_pg_core.uuid)("company_id").notNull(),
+  sessionId: (0, import_pg_core.uuid)("session_id").notNull().references(() => sessions.id, {
+    onDelete: "cascade"
+  }),
+  // Anulável e `set null`: apagar a mensagem não deve apagar o arquivo da biblioteca, e arquivo
+  // do atendente nasce sem mensagem.
+  messageId: (0, import_pg_core.uuid)("message_id").references(() => messages.id, {
+    onDelete: "set null"
+  }),
+  uploadId: (0, import_pg_core.varchar)("upload_id", {
+    length: 256
+  }).notNull(),
+  filename: (0, import_pg_core.varchar)("filename", {
+    length: 512
+  }).notNull(),
+  mimeType: (0, import_pg_core.varchar)("mime_type", {
+    length: 128
+  }).notNull(),
+  sizeBytes: (0, import_pg_core.integer)("size_bytes").notNull(),
+  // Do provider de storage, que é endereçado por conteúdo — serve para reconciliar storage
+  // contra tabela e para detectar o mesmo binário chegando duas vezes.
+  sha256: (0, import_pg_core.varchar)("sha256", {
+    length: 64
+  }),
+  source: (0, import_pg_core.varchar)("source", {
+    length: 12
+  }).notNull(),
+  linkedAt: (0, import_pg_core.timestamp)("linked_at", {
+    withTimezone: true
+  }).notNull().defaultNow()
+}, (table) => [
+  (0, import_pg_core.index)("idx_documents_session_linked").on(table.sessionId, table.linkedAt),
+  // Para varredura de retenção por idade sem passar por sessão.
+  (0, import_pg_core.index)("idx_documents_company_linked").on(table.companyId, table.linkedAt),
+  // O mesmo objeto não pode ser linkado duas vezes na mesma empresa: o job de ingestão é
+  // reentregue por retry, e sem isto a reentrega criaria linha duplicada no painel.
+  (0, import_pg_core.uniqueIndex)("idx_documents_company_upload").on(table.companyId, table.uploadId)
 ]);
 var flowGraphs = metaWhatsAppSchema.table("flow_graphs", {
   id: (0, import_pg_core.uuid)("id").primaryKey().defaultRandom(),
@@ -197,6 +303,46 @@ var flowGraphs = metaWhatsAppSchema.table("flow_graphs", {
 }, (table) => [
   (0, import_pg_core.uniqueIndex)("idx_flow_graphs_company_key").on(table.companyId, table.key)
 ]);
+var flowMedia = metaWhatsAppSchema.table("flow_media", {
+  id: (0, import_pg_core.uuid)("id").primaryKey().defaultRandom(),
+  companyId: (0, import_pg_core.uuid)("company_id").notNull(),
+  flowKey: (0, import_pg_core.varchar)("flow_key", {
+    length: 64
+  }).notNull(),
+  nodeId: (0, import_pg_core.varchar)("node_id", {
+    length: 64
+  }).notNull(),
+  uploadId: (0, import_pg_core.varchar)("upload_id", {
+    length: 256
+  }).notNull(),
+  filename: (0, import_pg_core.varchar)("filename", {
+    length: 512
+  }).notNull(),
+  mimeType: (0, import_pg_core.varchar)("mime_type", {
+    length: 128
+  }).notNull(),
+  sizeBytes: (0, import_pg_core.integer)("size_bytes").notNull(),
+  // Legenda da mídia no WhatsApp. Por arquivo, não por nó: um nó que manda tabela de preços e
+  // um folder precisa de textos diferentes para cada um.
+  caption: (0, import_pg_core.text)("caption"),
+  // Ordem de envio dentro do nó — o cliente recebe as mensagens em sequência, e "tabela antes
+  // do folder" é decisão de quem edita, não do banco.
+  sortOrder: (0, import_pg_core.integer)("sort_order").notNull().default(0),
+  // Desligar sem desanexar: trocar o material da campanha é o caso comum, e apagar a linha
+  // perderia a ordem e a legenda já ajustadas.
+  active: (0, import_pg_core.boolean)("active").notNull().default(true),
+  createdAt: (0, import_pg_core.timestamp)("created_at", {
+    withTimezone: true
+  }).notNull().defaultNow(),
+  updatedAt: (0, import_pg_core.timestamp)("updated_at", {
+    withTimezone: true
+  }).notNull().defaultNow()
+}, (table) => [
+  (0, import_pg_core.index)("idx_flow_media_node").on(table.companyId, table.flowKey, table.nodeId, table.sortOrder),
+  // O mesmo arquivo anexado duas vezes ao MESMO nó é erro de clique no editor, e o cliente
+  // receberia o documento repetido.
+  (0, import_pg_core.uniqueIndex)("idx_flow_media_node_upload").on(table.companyId, table.flowKey, table.nodeId, table.uploadId)
+]);
 var settings = metaWhatsAppSchema.table("settings", {
   companyId: (0, import_pg_core.uuid)("company_id").primaryKey(),
   templateName: (0, import_pg_core.varchar)("template_name", {
@@ -209,6 +355,15 @@ var settings = metaWhatsAppSchema.table("settings", {
   templateVariables: (0, import_pg_core.jsonb)("template_variables").$type().notNull().default([]),
   welcomeMessage: (0, import_pg_core.text)("welcome_message"),
   farewellMessage: (0, import_pg_core.text)("farewell_message"),
+  /**
+  * Política de transcrição desta empresa. Nulo é significativo: "o painel não decidiu", e aí vale
+  * o padrão que o host injetou. Sem a distinção, atualizar o módulo desligaria a transcrição de
+  * quem já a tinha ligada por ambiente.
+  */
+  transcriptionEnabled: (0, import_pg_core.boolean)("transcription_enabled"),
+  transcriptionMode: (0, import_pg_core.varchar)("transcription_mode", {
+    length: 16
+  }).$type(),
   createdAt: (0, import_pg_core.timestamp)("created_at", {
     withTimezone: true
   }).notNull().defaultNow(),
@@ -219,6 +374,31 @@ var settings = metaWhatsAppSchema.table("settings", {
 
 // src/repositories/SessionRepository.ts
 var DEFAULT_LIMIT = 20;
+var conversationSummaryProjection = {
+  lastContent: import_drizzle_orm2.sql`(
+    select m.content from ${messages} m
+    where m.company_id = ${sessions}.company_id and m.session_id = ${sessions}.id
+    order by m.created_at desc limit 1
+  )`,
+  lastDirection: import_drizzle_orm2.sql`(
+    select m.direction from ${messages} m
+    where m.company_id = ${sessions}.company_id and m.session_id = ${sessions}.id
+    order by m.created_at desc limit 1
+  )`,
+  // Entradas do cliente depois da última leitura do atendente. Sessão nunca lida conta
+  // tudo — é o comportamento esperado de uma conversa que ninguém abriu ainda.
+  unread: import_drizzle_orm2.sql`(
+    select count(*)::int from ${messages} m
+    where m.company_id = ${sessions}.company_id
+      and m.session_id = ${sessions}.id
+      and m.direction = 'inbound'
+      and (${sessions}.last_agent_read_at is null or m.created_at > ${sessions}.last_agent_read_at)
+  )`
+};
+function sessionContextPatch(patch) {
+  return import_drizzle_orm2.sql`${sessions.context} || ${JSON.stringify(patch)}::jsonb`;
+}
+__name(sessionContextPatch, "sessionContextPatch");
 var SessionRepository = class {
   static {
     __name(this, "SessionRepository");
@@ -249,6 +429,9 @@ var SessionRepository = class {
     }).returning();
     return created;
   }
+  // O `context` jsonb é o ponto de extensão oficial para estado de sessão por produto: o módulo
+  // não conhece a forma, o consumidor a declara em TSessionContext. Este setter SUBSTITUI o
+  // objeto inteiro — para acumular respostas ao longo da conversa use patchContext.
   async setState(companyId, whatsappNumber, state, context) {
     await this.db.update(sessions).set({
       currentState: state,
@@ -259,6 +442,25 @@ var SessionRepository = class {
       updatedAt: import_drizzle_orm2.sql`now()`
     }).where((0, import_drizzle_orm2.and)((0, import_drizzle_orm2.eq)(sessions.companyId, companyId), (0, import_drizzle_orm2.eq)(sessions.whatsappNumber, whatsappNumber)));
   }
+  // Mescla parcial do context, feita no banco (`||`) e não por read-modify-write no host: duas
+  // mensagens do mesmo cliente processadas em paralelo sobrescreveriam uma à outra, e o campo
+  // acumula justamente as respostas coletadas ao longo da conversa. Chave presente no patch
+  // vence a existente; as demais permanecem.
+  async patchContext(companyId, whatsappNumber, patch) {
+    await this.db.update(sessions).set({
+      context: sessionContextPatch(patch),
+      lastActivity: import_drizzle_orm2.sql`now()`,
+      updatedAt: import_drizzle_orm2.sql`now()`
+    }).where((0, import_drizzle_orm2.and)((0, import_drizzle_orm2.eq)(sessions.companyId, companyId), (0, import_drizzle_orm2.eq)(sessions.whatsappNumber, whatsappNumber)));
+  }
+  // Leitura tipada do estado de sessão do produto. Devolve undefined quando a sessão não existe —
+  // distinto de existir com context vazio, que devolve o objeto vazio.
+  async readContext(companyId, whatsappNumber) {
+    const [row] = await this.db.select({
+      context: sessions.context
+    }).from(sessions).where((0, import_drizzle_orm2.and)((0, import_drizzle_orm2.eq)(sessions.companyId, companyId), (0, import_drizzle_orm2.eq)(sessions.whatsappNumber, whatsappNumber))).limit(1);
+    return row?.context;
+  }
   // Posição no grafo de fluxo — chamado pelo host a cada transição do FlowInterpreter.
   // Passar null em ambos desliga o rastreio (ex.: conversa saiu do motor de fluxo).
   async setFlowPosition(companyId, whatsappNumber, flowKey, currentNodeId) {
@@ -301,6 +503,16 @@ var SessionRepository = class {
   async release(companyId, whatsappNumber) {
     await this.setMode(companyId, whatsappNumber, "bot", null);
   }
+  /**
+  * 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.
+  */
+  async deleteByNumber(companyId, whatsappNumber) {
+    await this.db.delete(sessions).where((0, import_drizzle_orm2.and)((0, import_drizzle_orm2.eq)(sessions.companyId, companyId), (0, import_drizzle_orm2.eq)(sessions.whatsappNumber, whatsappNumber)));
+  }
   async requestHuman(companyId, whatsappNumber) {
     await this.db.update(sessions).set({
       humanRequestedAt: import_drizzle_orm2.sql`now()`,
@@ -334,17 +546,28 @@ var SessionRepository = class {
       currentState: sessions.currentState,
       lastActivity: sessions.lastActivity,
       lastInboundAt: sessions.lastInboundAt,
-      humanRequestedAt: sessions.humanRequestedAt
+      humanRequestedAt: sessions.humanRequestedAt,
+      // Prévia e contagem saem de subquery correlacionada em vez de N+1 na volta: uma inbox
+      // lista dezenas de conversas por página, e uma query por linha é o gargalo clássico
+      // dessa tela. Ambos os campos são dados do próprio módulo — deixá-los para o host
+      // obrigaria todo consumidor a reescrever o mesmo join contra tabelas que não são dele.
+      ...conversationSummaryProjection
     }).from(sessions).where((0, import_drizzle_orm2.and)(...conditions)).orderBy((0, import_drizzle_orm2.desc)(sessions.lastActivity)).limit(limit).offset(offset);
     return rows.map((row) => ({
       id: row.id,
       whatsappNumber: row.whatsappNumber,
+      ...row.lastContent !== null ? {
+        lastContent: row.lastContent
+      } : {},
+      ...row.lastDirection !== null ? {
+        lastDirection: row.lastDirection
+      } : {},
       lastAt: row.lastActivity.toISOString(),
       lastInboundAt: row.lastInboundAt?.toISOString() ?? null,
       mode: row.mode,
       assignedUserId: row.assignedUserId,
       waitingHuman: row.humanRequestedAt !== null,
-      unread: 0,
+      unread: Number(row.unread),
       currentState: row.currentState
     }));
   }
@@ -388,7 +611,9 @@ var MessageRepository = class {
       content: params.content ?? null,
       payload: params.payload ?? null,
       waMessageId: params.waMessageId ?? null,
-      status: params.status ?? null
+      status: params.status ?? null,
+      moderationFlagged: params.moderationFlagged ?? null,
+      moderationTerms: params.moderationTerms ?? null
     };
     const [created] = await this.db.insert(messages).values(values).onConflictDoNothing().returning();
     return created;
@@ -402,6 +627,58 @@ var MessageRepository = class {
     }).where((0, import_drizzle_orm3.and)((0, import_drizzle_orm3.eq)(messages.companyId, companyId), (0, import_drizzle_orm3.eq)(messages.waMessageId, waMessageId))).returning();
     return updated;
   }
+  /**
+  * 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.
+  */
+  async saveTranscriptionByWaMessageId(params) {
+    const [updated] = await this.db.update(messages).set({
+      transcriptionStatus: params.status,
+      ...params.text !== void 0 ? {
+        transcriptionText: params.text
+      } : {},
+      ...params.language !== void 0 ? {
+        transcriptionLanguage: params.language
+      } : {},
+      ...params.engine !== void 0 ? {
+        transcriptionEngine: params.engine
+      } : {}
+    }).where((0, import_drizzle_orm3.and)((0, import_drizzle_orm3.eq)(messages.companyId, params.companyId), (0, import_drizzle_orm3.eq)(messages.waMessageId, params.waMessageId))).returning();
+    return updated;
+  }
+  async findById(companyId, messageId) {
+    const [found] = await this.db.select().from(messages).where((0, import_drizzle_orm3.and)((0, import_drizzle_orm3.eq)(messages.companyId, companyId), (0, import_drizzle_orm3.eq)(messages.id, messageId))).limit(1);
+    return found;
+  }
+  /**
+  * 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.
+  */
+  async saveTranscription(params) {
+    const [updated] = await this.db.update(messages).set({
+      transcriptionStatus: params.status,
+      ...params.text !== void 0 ? {
+        transcriptionText: params.text
+      } : {},
+      ...params.language !== void 0 ? {
+        transcriptionLanguage: params.language
+      } : {},
+      ...params.engine !== void 0 ? {
+        transcriptionEngine: params.engine
+      } : {}
+    }).where((0, import_drizzle_orm3.and)((0, import_drizzle_orm3.eq)(messages.companyId, params.companyId), (0, import_drizzle_orm3.eq)(messages.id, params.messageId))).returning();
+    return updated;
+  }
   async listByConversation(params) {
     const conditions = [
       (0, import_drizzle_orm3.eq)(messages.companyId, params.companyId),
@@ -451,12 +728,21 @@ var FlowGraphRepository = class {
     __name(this, "FlowGraphRepository");
   }
   db;
-  constructor(db) {
+  cache;
+  // Cache opcional: sem ele o repositório se comporta exatamente como antes, lendo sempre do
+  // banco. É o host que decide se quer cachear e com qual provedor (ver CacheInterface).
+  constructor(db, cache) {
     this.db = db;
+    this.cache = cache;
   }
   async get(companyId, key) {
+    const cached = await this.cache?.read(companyId, key);
+    if (cached) return cached;
     const [row] = await this.db.select().from(flowGraphs).where((0, import_drizzle_orm4.and)((0, import_drizzle_orm4.eq)(flowGraphs.companyId, companyId), (0, import_drizzle_orm4.eq)(flowGraphs.key, key))).limit(1);
-    return row ? toContractGraph(row) : void 0;
+    if (!row) return void 0;
+    const graph = toContractGraph(row);
+    await this.cache?.write(companyId, graph);
+    return graph;
   }
   async list(companyId) {
     const rows = await this.db.select().from(flowGraphs).where((0, import_drizzle_orm4.eq)(flowGraphs.companyId, companyId));
@@ -486,7 +772,9 @@ var FlowGraphRepository = class {
       showInMenu: graph.showInMenu ?? false,
       menuOptionLabel: graph.menuOptionLabel
     }).returning();
-    return toContractGraph(created);
+    const createdGraph = toContractGraph(created);
+    await this.cache?.invalidate(companyId, createdGraph.key);
+    return createdGraph;
   }
   // Lock otimista: a escrita só aplica se `expectedVersion` ainda bater com o que está salvo —
   // senão, alguém mais salvou entretanto e o editor precisa recarregar (ver comentário no schema).
@@ -500,10 +788,12 @@ var FlowGraphRepository = class {
       updatedAt: /* @__PURE__ */ new Date()
     }).where((0, import_drizzle_orm4.and)((0, import_drizzle_orm4.eq)(flowGraphs.companyId, companyId), (0, import_drizzle_orm4.eq)(flowGraphs.key, graph.key), (0, import_drizzle_orm4.eq)(flowGraphs.version, expectedVersion))).returning();
     if (rows.length === 0) throw new OptimisticLockError(graph.key);
+    await this.cache?.invalidate(companyId, graph.key);
     return toContractGraph(rows[0]);
   }
   async delete(companyId, key) {
     await this.db.delete(flowGraphs).where((0, import_drizzle_orm4.and)((0, import_drizzle_orm4.eq)(flowGraphs.companyId, companyId), (0, import_drizzle_orm4.eq)(flowGraphs.key, key)));
+    await this.cache?.invalidate(companyId, key);
   }
   // T4.2 — GetLiveFlowPositions: agrega sessões ativas por (flowKey, currentNodeId), lendo as
   // colunas dedicadas gravadas por SessionRepository.setFlowPosition. Agrega no banco (GROUP BY,
@@ -523,6 +813,48 @@ var FlowGraphRepository = class {
   }
 };
 
+// src/repositories/FlowGraphCache.ts
+var KEY_PREFIX = "meta-whatsapp:flow-graph";
+var DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS = 300;
+var FlowGraphCache = class {
+  static {
+    __name(this, "FlowGraphCache");
+  }
+  provider;
+  ttlSeconds;
+  constructor(provider, ttlSeconds = DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS) {
+    this.provider = provider;
+    this.ttlSeconds = ttlSeconds;
+  }
+  // companyId na chave, e não só a flowKey: a chave do fluxo é escolhida por quem edita e se
+  // repete entre empresas — 'consorcio' existe em todas — então uma chave sem tenant serviria o
+  // grafo de uma empresa para a conversa de outra.
+  keyFor(companyId, flowKey) {
+    return `${KEY_PREFIX}:${companyId}:${flowKey}`;
+  }
+  async read(companyId, flowKey) {
+    try {
+      const cached = await this.provider.get(this.keyFor(companyId, flowKey));
+      if (!cached) return void 0;
+      return JSON.parse(cached);
+    } catch {
+      return void 0;
+    }
+  }
+  async write(companyId, graph) {
+    try {
+      await this.provider.set(this.keyFor(companyId, graph.key), JSON.stringify(graph), this.ttlSeconds);
+    } catch {
+    }
+  }
+  async invalidate(companyId, flowKey) {
+    try {
+      await this.provider.delete(this.keyFor(companyId, flowKey));
+    } catch {
+    }
+  }
+};
+
 // src/repositories/SettingsRepository.ts
 var import_drizzle_orm5 = require("drizzle-orm");
 function toContractSettings(row) {
@@ -531,7 +863,11 @@ function toContractSettings(row) {
     templateLanguage: row.templateLanguage,
     templateVariables: row.templateVariables,
     welcomeMessage: row.welcomeMessage ?? "",
-    farewellMessage: row.farewellMessage ?? ""
+    farewellMessage: row.farewellMessage ?? "",
+    // `?? null` e não `?? false`: nulo é "o painel não decidiu", e é o que faz valer o padrão do
+    // host. Colapsar para `false` desligaria quem ligou por ambiente.
+    transcriptionEnabled: row.transcriptionEnabled ?? null,
+    transcriptionMode: row.transcriptionMode ?? null
   };
 }
 __name(toContractSettings, "toContractSettings");
@@ -540,7 +876,9 @@ var EMPTY_SETTINGS = {
   templateLanguage: "pt_BR",
   templateVariables: [],
   welcomeMessage: "",
-  farewellMessage: ""
+  farewellMessage: "",
+  transcriptionEnabled: null,
+  transcriptionMode: null
 };
 var SettingsRepository = class {
   static {
@@ -569,7 +907,12 @@ var SettingsRepository = class {
       templateLanguage: merged.templateLanguage,
       templateVariables: merged.templateVariables,
       welcomeMessage: merged.welcomeMessage || null,
-      farewellMessage: merged.farewellMessage || null
+      farewellMessage: merged.farewellMessage || null,
+      // Sem `|| null`: `false` aqui é decisão explícita do painel ("desligado para esta empresa"),
+      // e colapsá-lo para nulo faria a empresa voltar a herdar o padrão do host — exatamente o
+      // oposto do que o operador acabou de pedir.
+      transcriptionEnabled: merged.transcriptionEnabled,
+      transcriptionMode: merged.transcriptionMode
     }).onConflictDoUpdate({
       target: settings.companyId,
       set: {
@@ -578,6 +921,8 @@ var SettingsRepository = class {
         templateVariables: merged.templateVariables,
         welcomeMessage: merged.welcomeMessage || null,
         farewellMessage: merged.farewellMessage || null,
+        transcriptionEnabled: merged.transcriptionEnabled,
+        transcriptionMode: merged.transcriptionMode,
         updatedAt: /* @__PURE__ */ new Date()
       }
     }).returning();
@@ -604,16 +949,19 @@ var LogMessageUseCase = class {
   sessionRepository;
   messageRepository;
   realtime;
-  constructor(sessionRepository, messageRepository, realtime) {
+  moderator;
+  constructor(sessionRepository, messageRepository, realtime, moderator) {
     this.sessionRepository = sessionRepository;
     this.messageRepository = messageRepository;
     this.realtime = realtime;
+    this.moderator = moderator;
   }
   async execute(params) {
     const session = await this.sessionRepository.getOrCreate(params.companyId, params.whatsappNumber, params.startState);
     const saved = await this.messageRepository.insertMessage({
       ...params,
-      sessionId: session.id
+      sessionId: session.id,
+      ...this.moderationOf(params)
     });
     if (!saved) return void 0;
     if (params.direction === "inbound") {
@@ -626,6 +974,20 @@ var LogMessageUseCase = class {
     this.realtime?.emit("global", "data-changed", {});
     return saved;
   }
+  // Só o que o cliente escreveu: marcar o que o próprio atendente ou o bot enviou não sinaliza
+  // abuso, apenas sujaria o transcript com etiqueta na resposta de quem atende.
+  moderationOf(params) {
+    if (!this.moderator || params.direction !== "inbound") return {};
+    const text2 = params.content?.trim();
+    if (!text2) return {};
+    const verdict = this.moderator.inspect(text2);
+    return {
+      moderationFlagged: verdict.isOffensive,
+      moderationTerms: verdict.isOffensive ? [
+        ...verdict.matchedTerms
+      ] : null
+    };
+  }
 };
 
 // src/use-cases/SendMessage.use-case.ts
@@ -639,11 +1001,13 @@ var SendMessageUseCase = class {
   sessionRepository;
   logMessage;
   objectStorage;
-  constructor(channel, sessionRepository, logMessage, objectStorage) {
+  documentRepository;
+  constructor(channel, sessionRepository, logMessage, objectStorage, documentRepository) {
     this.channel = channel;
     this.sessionRepository = sessionRepository;
     this.logMessage = logMessage;
     this.objectStorage = objectStorage;
+    this.documentRepository = documentRepository;
   }
   async assertWithinWindow(companyId, whatsappNumber) {
     const hours = await this.sessionRepository.hoursSinceLastInbound(companyId, whatsappNumber);
@@ -680,7 +1044,7 @@ var SendMessageUseCase = class {
       mimeType: params.mimeType,
       key: `meta-whatsapp/${params.companyId}/${Date.now()}-${params.filename}`
     })).uploadId : void 0;
-    return this.logMessage.execute({
+    const saved = await this.logMessage.execute({
       companyId: params.companyId,
       whatsappNumber: params.whatsappNumber,
       direction: "outbound",
@@ -699,6 +1063,19 @@ var SendMessageUseCase = class {
       status: "sent",
       startState: params.startState
     });
+    if (saved && uploadId) {
+      await this.documentRepository?.link({
+        companyId: params.companyId,
+        sessionId: saved.sessionId,
+        messageId: saved.id,
+        uploadId,
+        filename: params.filename,
+        mimeType: params.mimeType,
+        sizeBytes: params.buffer.length,
+        source: params.sender
+      });
+    }
+    return saved;
   }
   // Template é o único envio que ignora a janela — é justamente o mecanismo que a Meta oferece
   // para reabri-la.
@@ -816,8 +1193,330 @@ var ListMessagesUseCase = class {
   }
 };
 
-// src/use-cases/ExportConversation.use-case.ts
+// src/use-cases/ListConversationDocuments.use-case.ts
 var import_meta_whatsapp_contracts4 = require("@adatechnology/meta-whatsapp-contracts");
+var ListConversationDocumentsUseCase = class {
+  static {
+    __name(this, "ListConversationDocumentsUseCase");
+  }
+  sessionRepository;
+  documentRepository;
+  constructor(sessionRepository, documentRepository) {
+    this.sessionRepository = sessionRepository;
+    this.documentRepository = documentRepository;
+  }
+  async execute(params) {
+    const session = await this.sessionRepository.getContext(params.companyId, params.whatsappNumber);
+    if (!session) throw new import_meta_whatsapp_contracts4.SessionNotFoundError(params.whatsappNumber);
+    const { rows, total } = await this.documentRepository.listByConversation({
+      companyId: params.companyId,
+      sessionId: session.id,
+      ...params.search ? {
+        search: params.search
+      } : {},
+      ...params.sources && params.sources.length > 0 ? {
+        sources: params.sources
+      } : {},
+      ...params.sortDirection ? {
+        sortDirection: params.sortDirection
+      } : {},
+      ...params.page ? {
+        page: params.page
+      } : {},
+      ...params.limit ? {
+        limit: params.limit
+      } : {}
+    });
+    return {
+      documents: rows.map((row) => ({
+        id: row.uploadId,
+        filename: row.filename,
+        mimeType: row.mimeType,
+        sizeBytes: row.sizeBytes,
+        source: row.source,
+        linkedAt: row.linkedAt.toISOString()
+      })),
+      total
+    };
+  }
+};
+
+// src/use-cases/ListCompanyDocuments.use-case.ts
+var ListCompanyDocumentsUseCase = class {
+  static {
+    __name(this, "ListCompanyDocumentsUseCase");
+  }
+  documentRepository;
+  constructor(documentRepository) {
+    this.documentRepository = documentRepository;
+  }
+  async execute(params) {
+    const { rows, total } = await this.documentRepository.listByCompany({
+      companyId: params.companyId,
+      ...params.search ? {
+        search: params.search
+      } : {},
+      ...params.sources && params.sources.length > 0 ? {
+        sources: params.sources
+      } : {},
+      ...params.sortDirection ? {
+        sortDirection: params.sortDirection
+      } : {},
+      ...params.page ? {
+        page: params.page
+      } : {},
+      ...params.limit ? {
+        limit: params.limit
+      } : {}
+    });
+    return {
+      documents: rows.map((row) => ({
+        id: row.uploadId,
+        conversationId: row.whatsappNumber,
+        filename: row.filename,
+        mimeType: row.mimeType,
+        sizeBytes: row.sizeBytes,
+        source: row.source,
+        linkedAt: row.linkedAt.toISOString()
+      })),
+      total
+    };
+  }
+};
+
+// src/use-cases/DeleteConversation.use-case.ts
+var import_meta_whatsapp_contracts5 = require("@adatechnology/meta-whatsapp-contracts");
+var DeleteConversationUseCase = class {
+  static {
+    __name(this, "DeleteConversationUseCase");
+  }
+  sessionRepository;
+  documentRepository;
+  objectStorage;
+  constructor(sessionRepository, documentRepository, objectStorage) {
+    this.sessionRepository = sessionRepository;
+    this.documentRepository = documentRepository;
+    this.objectStorage = objectStorage;
+  }
+  async execute(params) {
+    const session = await this.sessionRepository.getContext(params.companyId, params.whatsappNumber);
+    if (!session) throw new import_meta_whatsapp_contracts5.SessionNotFoundError(params.whatsappNumber);
+    const uploadIds = await this.documentRepository.listUploadIdsBySession(params.companyId, session.id);
+    if (uploadIds.length > 0 && !this.objectStorage?.delete) {
+      throw new Error("storage_delete_unsupported: a conversa tem arquivos e o storage injetado n\xE3o implementa delete");
+    }
+    const failedObjects = [];
+    let deletedObjects = 0;
+    for (const uploadId of uploadIds) {
+      try {
+        await this.objectStorage?.delete?.(uploadId);
+        deletedObjects++;
+      } catch {
+        failedObjects.push(uploadId);
+      }
+    }
+    if (failedObjects.length > 0) return {
+      deletedObjects,
+      failedObjects
+    };
+    await this.sessionRepository.deleteByNumber(params.companyId, params.whatsappNumber);
+    return {
+      deletedObjects,
+      failedObjects: []
+    };
+  }
+};
+
+// src/use-cases/PurgeExpiredDocuments.use-case.ts
+var DEFAULT_BATCH_SIZE = 50;
+var HOURS_IN_DAY = 24;
+var MILLISECONDS_IN_HOUR = 60 * 60 * 1e3;
+var PurgeExpiredDocumentsUseCase = class {
+  static {
+    __name(this, "PurgeExpiredDocumentsUseCase");
+  }
+  documentRepository;
+  objectStorage;
+  constructor(documentRepository, objectStorage) {
+    this.documentRepository = documentRepository;
+    this.objectStorage = objectStorage;
+  }
+  async execute(params) {
+    if (!this.objectStorage?.delete) {
+      throw new Error("storage_delete_unsupported: reten\xE7\xE3o exige um storage que implemente delete");
+    }
+    const reference = params.now ?? /* @__PURE__ */ new Date();
+    const olderThan = new Date(reference.getTime() - params.retentionDays * HOURS_IN_DAY * MILLISECONDS_IN_HOUR);
+    const expired = await this.documentRepository.listExpired(params.companyId, olderThan, params.batchSize ?? DEFAULT_BATCH_SIZE);
+    const failed = [];
+    let purged = 0;
+    for (const document of expired) {
+      try {
+        await this.objectStorage.delete(document.uploadId);
+      } catch {
+        failed.push(document.uploadId);
+        continue;
+      }
+      await this.documentRepository.deleteById(params.companyId, document.id);
+      purged++;
+    }
+    return {
+      purged,
+      failed
+    };
+  }
+};
+
+// src/repositories/DocumentRepository.ts
+var import_drizzle_orm6 = require("drizzle-orm");
+var DEFAULT_LIMIT3 = 50;
+function companyDocumentSearch(search) {
+  const term = search?.trim();
+  if (!term) return void 0;
+  const digits = term.replace(/\D/g, "");
+  const byFilename = (0, import_drizzle_orm6.ilike)(documents.filename, `%${term}%`);
+  if (!digits) return byFilename;
+  return (0, import_drizzle_orm6.or)(byFilename, (0, import_drizzle_orm6.ilike)(sessions.whatsappNumber, `%${digits}%`));
+}
+__name(companyDocumentSearch, "companyDocumentSearch");
+var DocumentRepository = class {
+  static {
+    __name(this, "DocumentRepository");
+  }
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  /**
+  * 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.
+  */
+  async link(params) {
+    const values = {
+      companyId: params.companyId,
+      sessionId: params.sessionId,
+      messageId: params.messageId ?? null,
+      uploadId: params.uploadId,
+      filename: params.filename,
+      mimeType: params.mimeType,
+      sizeBytes: params.sizeBytes,
+      sha256: params.sha256 ?? null,
+      source: params.source
+    };
+    const [created] = await this.db.insert(documents).values(values).onConflictDoNothing().returning();
+    return created;
+  }
+  async listByConversation(params) {
+    const filters = [
+      (0, import_drizzle_orm6.eq)(documents.companyId, params.companyId),
+      (0, import_drizzle_orm6.eq)(documents.sessionId, params.sessionId)
+    ];
+    if (params.search) filters.push((0, import_drizzle_orm6.ilike)(documents.filename, `%${params.search}%`));
+    if (params.sources && params.sources.length > 0) {
+      filters.push((0, import_drizzle_orm6.inArray)(documents.source, [
+        ...params.sources
+      ]));
+    }
+    const where = (0, import_drizzle_orm6.and)(...filters);
+    const limit = params.limit ?? DEFAULT_LIMIT3;
+    const page = params.page && params.page > 0 ? params.page : 1;
+    const orderBy = params.sortDirection === "asc" ? (0, import_drizzle_orm6.asc)(documents.linkedAt) : (0, import_drizzle_orm6.desc)(documents.linkedAt);
+    const [rows, counted] = await Promise.all([
+      this.db.select().from(documents).where(where).orderBy(orderBy).limit(limit).offset((page - 1) * limit),
+      this.db.select({
+        value: (0, import_drizzle_orm6.count)()
+      }).from(documents).where(where)
+    ]);
+    return {
+      rows,
+      total: counted[0]?.value ?? 0
+    };
+  }
+  /**
+  * 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.
+  */
+  async listByCompany(params) {
+    const filters = [
+      (0, import_drizzle_orm6.eq)(documents.companyId, params.companyId)
+    ];
+    const search = companyDocumentSearch(params.search);
+    if (search) filters.push(search);
+    if (params.sources && params.sources.length > 0) {
+      filters.push((0, import_drizzle_orm6.inArray)(documents.source, [
+        ...params.sources
+      ]));
+    }
+    const where = (0, import_drizzle_orm6.and)(...filters);
+    const limit = params.limit ?? DEFAULT_LIMIT3;
+    const page = params.page && params.page > 0 ? params.page : 1;
+    const orderBy = params.sortDirection === "asc" ? (0, import_drizzle_orm6.asc)(documents.linkedAt) : (0, import_drizzle_orm6.desc)(documents.linkedAt);
+    const [rows, counted] = await Promise.all([
+      this.db.select({
+        id: documents.id,
+        uploadId: documents.uploadId,
+        filename: documents.filename,
+        mimeType: documents.mimeType,
+        sizeBytes: documents.sizeBytes,
+        source: documents.source,
+        linkedAt: documents.linkedAt,
+        // Só o número: o NOME do cliente é dado do produto (tabela própria dele), não do
+        // módulo. Quem quiser exibir "Marina Alves" enriquece na borda.
+        whatsappNumber: sessions.whatsappNumber
+      }).from(documents).innerJoin(sessions, (0, import_drizzle_orm6.eq)(documents.sessionId, sessions.id)).where(where).orderBy(orderBy).limit(limit).offset((page - 1) * limit),
+      // O mesmo join da listagem, e não só `from(documents)`: a busca pode citar
+      // `sessions.whatsapp_number`, e uma contagem sem a tabela na cláusula não compila — pior,
+      // se compilasse, o total divergiria das linhas e a paginação prometeria páginas vazias.
+      this.db.select({
+        value: (0, import_drizzle_orm6.count)()
+      }).from(documents).innerJoin(sessions, (0, import_drizzle_orm6.eq)(documents.sessionId, sessions.id)).where(where)
+    ]);
+    return {
+      rows,
+      total: counted[0]?.value ?? 0
+    };
+  }
+  /**
+  * 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.
+  */
+  async findByUploadId(companyId, uploadId) {
+    const [row] = await this.db.select().from(documents).where((0, import_drizzle_orm6.and)((0, import_drizzle_orm6.eq)(documents.companyId, companyId), (0, import_drizzle_orm6.eq)(documents.uploadId, uploadId))).limit(1);
+    return row;
+  }
+  /**
+  * 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.
+  */
+  async listUploadIdsBySession(companyId, sessionId) {
+    const rows = await this.db.select({
+      uploadId: documents.uploadId
+    }).from(documents).where((0, import_drizzle_orm6.and)((0, import_drizzle_orm6.eq)(documents.companyId, companyId), (0, import_drizzle_orm6.eq)(documents.sessionId, sessionId)));
+    return rows.map((row) => row.uploadId);
+  }
+  /** Varredura de retenção por idade — o par é o mesmo cuidado com o objeto no storage. */
+  async listExpired(companyId, olderThan, limit = DEFAULT_LIMIT3) {
+    return this.db.select().from(documents).where((0, import_drizzle_orm6.and)((0, import_drizzle_orm6.eq)(documents.companyId, companyId), (0, import_drizzle_orm6.lt)(documents.linkedAt, olderThan))).orderBy(documents.linkedAt).limit(limit);
+  }
+  async deleteById(companyId, id) {
+    await this.db.delete(documents).where((0, import_drizzle_orm6.and)((0, import_drizzle_orm6.eq)(documents.companyId, companyId), (0, import_drizzle_orm6.eq)(documents.id, id)));
+  }
+};
+
+// src/use-cases/ExportConversation.use-case.ts
+var import_meta_whatsapp_contracts6 = require("@adatechnology/meta-whatsapp-contracts");
 var ExportConversationUseCase = class {
   static {
     __name(this, "ExportConversationUseCase");
@@ -828,7 +1527,7 @@ var ExportConversationUseCase = class {
   }
   async execute(params) {
     const result = await this.sessionRepository.exportConversation(params.companyId, params.whatsappNumber);
-    if (!result) throw new import_meta_whatsapp_contracts4.SessionNotFoundError(params.whatsappNumber);
+    if (!result) throw new import_meta_whatsapp_contracts6.SessionNotFoundError(params.whatsappNumber);
     return result;
   }
 };
@@ -908,7 +1607,7 @@ var GetLiveFlowPositionsUseCase = class {
 };
 
 // src/flows/FlowInterpreter.ts
-var import_meta_whatsapp_contracts5 = require("@adatechnology/meta-whatsapp-contracts");
+var import_meta_whatsapp_contracts7 = require("@adatechnology/meta-whatsapp-contracts");
 var DEFAULT_MAX_STEPS = 50;
 function evaluateCondition(node, context) {
   if (!node.conditionContextKey || !node.conditionOperator || !node.conditionValue) return false;
@@ -1009,9 +1708,9 @@ var FlowInterpreter = class {
       kind: "terminal",
       context: input.context
     };
-    if ((0, import_meta_whatsapp_contracts5.isCrossFlowTarget)(nextNodeId)) return {
+    if ((0, import_meta_whatsapp_contracts7.isCrossFlowTarget)(nextNodeId)) return {
       kind: "cross-flow",
-      flowKey: (0, import_meta_whatsapp_contracts5.crossFlowKey)(nextNodeId),
+      flowKey: (0, import_meta_whatsapp_contracts7.crossFlowKey)(nextNodeId),
       context: input.context
     };
     if (!input.graph.nodes[nextNodeId]) return {
@@ -1065,22 +1764,174 @@ var FlowInterpreter = class {
   }
 };
 
+// src/flows/createSendMediaAction.ts
+function mediaTypeFor2(mimeType) {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("video/")) return "video";
+  return "document";
+}
+__name(mediaTypeFor2, "mediaTypeFor");
+function createSendMediaAction(params) {
+  return async ({ node, session, channel }) => {
+    if (!session.flowKey) return;
+    const location = {
+      companyId: session.companyId,
+      flowKey: session.flowKey,
+      nodeId: node.id
+    };
+    const attachments = await params.flowMediaRepository.listActive(location);
+    for (const attachment of attachments) {
+      try {
+        const buffer = await params.objectStorage.getObject(attachment.uploadId);
+        const { externalMessageId } = await channel.sendMedia({
+          to: session.whatsappNumber,
+          buffer,
+          mimeType: attachment.mimeType,
+          filename: attachment.filename,
+          caption: attachment.caption ?? void 0
+        });
+        await params.logMessage.execute({
+          companyId: session.companyId,
+          whatsappNumber: session.whatsappNumber,
+          direction: "outbound",
+          sender: "bot",
+          agentUserId: null,
+          type: mediaTypeFor2(attachment.mimeType),
+          content: attachment.caption ?? attachment.filename,
+          payload: {
+            filename: attachment.filename,
+            mimeType: attachment.mimeType,
+            uploadId: attachment.uploadId,
+            flowMediaId: attachment.id
+          },
+          waMessageId: externalMessageId,
+          status: "sent",
+          startState: params.startState
+        });
+      } catch (error) {
+        params.onError?.(error, {
+          flowKey: location.flowKey,
+          nodeId: node.id,
+          uploadId: attachment.uploadId
+        });
+      }
+    }
+  };
+}
+__name(createSendMediaAction, "createSendMediaAction");
+
+// src/repositories/FlowMediaRepository.ts
+var import_drizzle_orm7 = require("drizzle-orm");
+var FlowMediaRepository = class {
+  static {
+    __name(this, "FlowMediaRepository");
+  }
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  locationFilter(location) {
+    return (0, import_drizzle_orm7.and)((0, import_drizzle_orm7.eq)(flowMedia.companyId, location.companyId), (0, import_drizzle_orm7.eq)(flowMedia.flowKey, location.flowKey), (0, import_drizzle_orm7.eq)(flowMedia.nodeId, location.nodeId));
+  }
+  // O que o nó realmente envia, na ordem de envio. `active` filtrado aqui e não no chamador:
+  // é a razão de a coluna existir, e um chamador que esquecesse do filtro mandaria ao cliente
+  // justamente o material que alguém desligou.
+  async listActive(location) {
+    return this.db.select().from(flowMedia).where((0, import_drizzle_orm7.and)(this.locationFilter(location), (0, import_drizzle_orm7.eq)(flowMedia.active, true))).orderBy((0, import_drizzle_orm7.asc)(flowMedia.sortOrder), (0, import_drizzle_orm7.asc)(flowMedia.createdAt));
+  }
+  // Inclui os desligados — é a visão do editor, onde desligar precisa continuar visível para
+  // poder ser religado.
+  async listAll(location) {
+    return this.db.select().from(flowMedia).where(this.locationFilter(location)).orderBy((0, import_drizzle_orm7.asc)(flowMedia.sortOrder), (0, import_drizzle_orm7.asc)(flowMedia.createdAt));
+  }
+  /**
+  * 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.
+  */
+  async attach(params) {
+    const [row] = await this.db.insert(flowMedia).values({
+      companyId: params.companyId,
+      flowKey: params.flowKey,
+      nodeId: params.nodeId,
+      uploadId: params.uploadId,
+      filename: params.filename,
+      mimeType: params.mimeType,
+      sizeBytes: params.sizeBytes,
+      caption: params.caption ?? null,
+      sortOrder: params.sortOrder ?? 0
+    }).onConflictDoUpdate({
+      target: [
+        flowMedia.companyId,
+        flowMedia.flowKey,
+        flowMedia.nodeId,
+        flowMedia.uploadId
+      ],
+      set: {
+        caption: params.caption ?? null,
+        sortOrder: params.sortOrder ?? 0,
+        active: true,
+        updatedAt: import_drizzle_orm7.sql`now()`
+      }
+    }).returning();
+    return row;
+  }
+  async update(params) {
+    const [row] = await this.db.update(flowMedia).set({
+      ...params.caption !== void 0 ? {
+        caption: params.caption
+      } : {},
+      ...params.sortOrder !== void 0 ? {
+        sortOrder: params.sortOrder
+      } : {},
+      ...params.active !== void 0 ? {
+        active: params.active
+      } : {},
+      updatedAt: import_drizzle_orm7.sql`now()`
+    }).where((0, import_drizzle_orm7.and)((0, import_drizzle_orm7.eq)(flowMedia.companyId, params.companyId), (0, import_drizzle_orm7.eq)(flowMedia.id, params.id))).returning();
+    return row;
+  }
+  /**
+  * 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.
+  */
+  async detach(params) {
+    await this.db.delete(flowMedia).where((0, import_drizzle_orm7.and)((0, import_drizzle_orm7.eq)(flowMedia.companyId, params.companyId), (0, import_drizzle_orm7.eq)(flowMedia.id, params.id)));
+  }
+  // Chamado ao salvar o grafo: nós apagados no editor deixam linhas que nada mais alcança.
+  async detachRemovedNodes(params) {
+    const condition = params.existingNodeIds.length === 0 ? void 0 : import_drizzle_orm7.sql`${flowMedia.nodeId} NOT IN ${params.existingNodeIds}`;
+    await this.db.delete(flowMedia).where((0, import_drizzle_orm7.and)((0, import_drizzle_orm7.eq)(flowMedia.companyId, params.companyId), (0, import_drizzle_orm7.eq)(flowMedia.flowKey, params.flowKey), condition));
+  }
+};
+
 // src/channel/WhatsAppChannelAdapter.ts
 var import_meta_graph_core = require("@adatechnology/meta-graph-core");
-var import_meta_whatsapp_contracts6 = require("@adatechnology/meta-whatsapp-contracts");
+var import_meta_whatsapp_contracts9 = require("@adatechnology/meta-whatsapp-contracts");
+
+// src/channel/previewMedia.ts
+var import_meta_whatsapp_contracts8 = require("@adatechnology/meta-whatsapp-contracts");
+
+// src/channel/WhatsAppChannelAdapter.ts
 var WhatsAppChannelAdapter = class {
   static {
     __name(this, "WhatsAppChannelAdapter");
   }
   messages;
-  constructor(messages2) {
+  previewMedia;
+  constructor(messages2, previewMedia) {
     this.messages = messages2;
+    this.previewMedia = previewMedia;
   }
   async translateErrors(operation) {
     try {
       return await operation();
     } catch (error) {
-      if (error instanceof import_meta_graph_core.WhatsAppWindowExpiredError) throw new import_meta_whatsapp_contracts6.WindowExpiredError();
+      if (error instanceof import_meta_graph_core.WhatsAppWindowExpiredError) throw new import_meta_whatsapp_contracts9.WindowExpiredError();
       throw error;
     }
   }
@@ -1118,17 +1969,31 @@ var WhatsAppChannelAdapter = class {
       externalMessageId: result.waMessageId
     };
   }
+  /**
+  * 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.
+  */
   async fetchMediaAsBase64(mediaId) {
+    const uploadId = this.previewMedia?.isEnabled ? (0, import_meta_whatsapp_contracts8.resolvePreviewUploadId)(mediaId) : void 0;
+    if (uploadId) {
+      const buffer = await this.previewMedia.objectStorage.getObject(uploadId);
+      return {
+        data: buffer.toString("base64"),
+        mimeType: this.previewMedia.defaultMimeType ?? "audio/ogg"
+      };
+    }
     return this.translateErrors(() => this.messages.fetchMediaAsBase64(mediaId));
   }
 };
 
 // src/channel/ReceiveWebhook.use-case.ts
-var import_meta_whatsapp_contracts8 = require("@adatechnology/meta-whatsapp-contracts");
+var import_meta_whatsapp_contracts12 = require("@adatechnology/meta-whatsapp-contracts");
 
 // src/channel/webhookSecurity.ts
 var import_node_crypto = require("crypto");
-var import_meta_whatsapp_contracts7 = require("@adatechnology/meta-whatsapp-contracts");
+var import_meta_whatsapp_contracts10 = require("@adatechnology/meta-whatsapp-contracts");
 var WEBHOOK_NONCE_TTL_SECONDS = 300;
 function safeEqualStrings(left, right) {
   const leftDigest = (0, import_node_crypto.createHmac)("sha256", "constant-time-compare").update(left).digest();
@@ -1138,20 +2003,20 @@ function safeEqualStrings(left, right) {
 __name(safeEqualStrings, "safeEqualStrings");
 function verifyWebhookChallenge(params) {
   if (params.mode !== "subscribe" || !params.token || !params.challenge) {
-    throw new import_meta_whatsapp_contracts7.InvalidWebhookSignatureError();
+    throw new import_meta_whatsapp_contracts10.InvalidWebhookSignatureError();
   }
   if (!safeEqualStrings(params.token, params.expectedToken)) {
-    throw new import_meta_whatsapp_contracts7.InvalidWebhookSignatureError();
+    throw new import_meta_whatsapp_contracts10.InvalidWebhookSignatureError();
   }
   return params.challenge;
 }
 __name(verifyWebhookChallenge, "verifyWebhookChallenge");
 function verifyWebhookSignature(params) {
   const { rawBody, signatureHeader, appSecret } = params;
-  if (!signatureHeader?.startsWith("sha256=")) throw new import_meta_whatsapp_contracts7.InvalidWebhookSignatureError();
+  if (!signatureHeader?.startsWith("sha256=")) throw new import_meta_whatsapp_contracts10.InvalidWebhookSignatureError();
   const expected = (0, import_node_crypto.createHmac)("sha256", appSecret).update(rawBody).digest("hex");
   const received = signatureHeader.slice("sha256=".length);
-  if (!safeEqualStrings(received, expected)) throw new import_meta_whatsapp_contracts7.InvalidWebhookSignatureError();
+  if (!safeEqualStrings(received, expected)) throw new import_meta_whatsapp_contracts10.InvalidWebhookSignatureError();
 }
 __name(verifyWebhookSignature, "verifyWebhookSignature");
 async function claimWebhookDelivery(params) {
@@ -1160,6 +2025,325 @@ async function claimWebhookDelivery(params) {
 }
 __name(claimWebhookDelivery, "claimWebhookDelivery");
 
+// src/channel/IngestInboundMedia.use-case.ts
+var import_drizzle_orm8 = require("drizzle-orm");
+
+// src/use-cases/TranscribeAudio.use-case.ts
+var import_meta_whatsapp_contracts11 = require("@adatechnology/meta-whatsapp-contracts");
+
+// src/transcription.types.ts
+var TRANSCRIPTION_STATUS = {
+  /** Falhou de forma retriável (cota, rede, 5xx) — vai sair quando alguém tentar de novo. */
+  PENDING: "pending",
+  /** Processado. Texto vazio aqui é áudio em silêncio, e NÃO deve ser reprocessado. */
+  DONE: "done",
+  /** Falha definitiva do engine (credencial, áudio corrompido, arquivo grande demais). */
+  FAILED: "failed",
+  /** Nenhum engine da cadeia aceita o formato. Retentar não conserta codec. */
+  UNSUPPORTED: "unsupported"
+};
+var TRANSCRIPTION_MODE = {
+  AUTO: "auto",
+  ON_DEMAND: "onDemand"
+};
+function isRetriableTranscriptionError(error) {
+  if (typeof error !== "object" || error === null) return true;
+  const isRetriable = error.isRetriable;
+  return typeof isRetriable === "boolean" ? isRetriable : true;
+}
+__name(isRetriableTranscriptionError, "isRetriableTranscriptionError");
+function isUnsupportedTranscriptionError(error) {
+  return typeof error === "object" && error !== null && error.name === "TranscriptionUnsupportedError";
+}
+__name(isUnsupportedTranscriptionError, "isUnsupportedTranscriptionError");
+function transcriptionRetryAfterSeconds(error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const retryAfter = error.retryAfterSeconds;
+  return typeof retryAfter === "number" ? retryAfter : void 0;
+}
+__name(transcriptionRetryAfterSeconds, "transcriptionRetryAfterSeconds");
+function isAudioMimeType(mimeType) {
+  return typeof mimeType === "string" && mimeType.trim().toLowerCase().startsWith("audio/");
+}
+__name(isAudioMimeType, "isAudioMimeType");
+
+// src/use-cases/TranscribeAudio.use-case.ts
+var TranscribeAudioUseCase = class {
+  static {
+    __name(this, "TranscribeAudioUseCase");
+  }
+  dependencies;
+  constructor(dependencies) {
+    this.dependencies = dependencies;
+  }
+  async execute(params) {
+    const message = await this.dependencies.messageRepository.findById(params.companyId, params.messageId);
+    if (!message) throw new Error(`Mensagem ${params.messageId} n\xE3o encontrada para transcri\xE7\xE3o`);
+    if (message.transcriptionStatus === TRANSCRIPTION_STATUS.DONE && !params.force) {
+      return {
+        status: TRANSCRIPTION_STATUS.DONE,
+        text: message.transcriptionText,
+        language: message.transcriptionLanguage,
+        engine: message.transcriptionEngine,
+        alreadyTranscribed: true
+      };
+    }
+    if (this.dependencies.resolvePolicy) {
+      const policy = await this.dependencies.resolvePolicy(params.companyId);
+      if (!policy.isEnabled) throw new import_meta_whatsapp_contracts11.TranscriptionDisabledError();
+    }
+    const audio = extractAudioReference(message);
+    const buffer = await this.dependencies.objectStorage.getObject(audio.uploadId);
+    return this.transcribeBuffer({
+      ...params,
+      buffer,
+      mimeType: audio.mimeType,
+      uploadId: audio.uploadId,
+      message
+    });
+  }
+  async transcribeBuffer(context) {
+    try {
+      const result = await this.dependencies.transcriber.transcribe({
+        buffer: context.buffer,
+        mimeType: context.mimeType,
+        ...this.dependencies.languageHint ? {
+          languageHint: this.dependencies.languageHint
+        } : {}
+      });
+      await this.dependencies.messageRepository.saveTranscription({
+        companyId: context.companyId,
+        messageId: context.messageId,
+        status: TRANSCRIPTION_STATUS.DONE,
+        text: result.text,
+        language: result.language ?? null,
+        engine: result.engine
+      });
+      return {
+        status: TRANSCRIPTION_STATUS.DONE,
+        text: result.text,
+        language: result.language ?? null,
+        engine: result.engine,
+        alreadyTranscribed: false
+      };
+    } catch (error) {
+      await this.persistFailure(context, error);
+      throw error;
+    }
+  }
+  /**
+  * 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.
+  */
+  async persistFailure(context, error) {
+    const status = resolveFailureStatus(error);
+    await this.dependencies.messageRepository.saveTranscription({
+      companyId: context.companyId,
+      messageId: context.messageId,
+      status
+    });
+    if (status !== TRANSCRIPTION_STATUS.PENDING) return;
+    const retryAfterSeconds = transcriptionRetryAfterSeconds(error);
+    await this.dependencies.hooks?.onTranscriptionDeferred?.({
+      companyId: context.companyId,
+      messageId: context.messageId,
+      whatsappNumber: context.message.whatsappNumber,
+      uploadId: context.uploadId,
+      ...retryAfterSeconds !== void 0 ? {
+        retryAfterSeconds
+      } : {},
+      reason: retryAfterSeconds !== void 0 ? "rate-limited" : "transient-failure",
+      error
+    });
+  }
+};
+function resolveFailureStatus(error) {
+  if (isUnsupportedTranscriptionError(error)) return TRANSCRIPTION_STATUS.UNSUPPORTED;
+  return isRetriableTranscriptionError(error) ? TRANSCRIPTION_STATUS.PENDING : TRANSCRIPTION_STATUS.FAILED;
+}
+__name(resolveFailureStatus, "resolveFailureStatus");
+function extractAudioReference(message) {
+  const payload = message.payload ?? {};
+  const audio = payload["audio"];
+  const mimeType = typeof payload["mimeType"] === "string" ? payload["mimeType"] : audio?.mime_type;
+  if (!isAudioMimeType(mimeType) && !audio) {
+    throw new import_meta_whatsapp_contracts11.MessageNotAudioError(message.id, message.type);
+  }
+  const uploadId = payload["uploadId"];
+  if (typeof uploadId !== "string" || uploadId.length === 0) {
+    throw new import_meta_whatsapp_contracts11.AudioNotIngestedError(message.id);
+  }
+  return {
+    uploadId,
+    mimeType: mimeType ?? "audio/ogg"
+  };
+}
+__name(extractAudioReference, "extractAudioReference");
+
+// src/channel/IngestInboundMedia.use-case.ts
+var IngestInboundMediaUseCase = class {
+  static {
+    __name(this, "IngestInboundMediaUseCase");
+  }
+  db;
+  channel;
+  objectStorage;
+  documentRepository;
+  transcription;
+  constructor(db, channel, objectStorage, documentRepository, transcription) {
+    this.db = db;
+    this.channel = channel;
+    this.objectStorage = objectStorage;
+    this.documentRepository = documentRepository;
+    this.transcription = transcription;
+  }
+  async execute(params) {
+    const [message] = await this.db.select().from(messages).where((0, import_drizzle_orm8.and)((0, import_drizzle_orm8.eq)(messages.companyId, params.companyId), (0, import_drizzle_orm8.eq)(messages.id, params.messageId))).limit(1);
+    if (!message) throw new Error(`Mensagem ${params.messageId} n\xE3o encontrada para ingest\xE3o de m\xEDdia`);
+    const payload = message.payload ?? {};
+    if (payload["uploadId"] && payload["sourceMediaId"] === params.sourceMediaId) {
+      return {
+        uploadId: String(payload["uploadId"]),
+        alreadyIngested: true
+      };
+    }
+    const { data, mimeType } = await this.channel.fetchMediaAsBase64(params.sourceMediaId);
+    const buffer = Buffer.from(data, "base64");
+    const { uploadId } = await this.objectStorage.upload({
+      buffer,
+      mimeType: mimeType || params.mimeType,
+      key: `meta-whatsapp/${params.companyId}/inbound/${params.sourceMediaId}`
+    });
+    const updatedPayload = {
+      ...payload,
+      uploadId,
+      sourceMediaId: params.sourceMediaId,
+      mimeType: mimeType || params.mimeType,
+      // O tamanho já está na mão (é o buffer que acabou de ser copiado) e a bolha de documento o
+      // exibe ao lado do tipo. Sem gravar aqui, a UI mostraria "PDF" sem o "· 180 KB", e buscá-lo
+      // depois custaria uma consulta à tabela de documentos por mensagem renderizada.
+      sizeBytes: buffer.length,
+      ...params.filename ? {
+        filename: params.filename
+      } : {}
+    };
+    await this.db.update(messages).set({
+      payload: updatedPayload
+    }).where((0, import_drizzle_orm8.and)((0, import_drizzle_orm8.eq)(messages.companyId, params.companyId), (0, import_drizzle_orm8.eq)(messages.id, params.messageId)));
+    await this.documentRepository?.link({
+      companyId: params.companyId,
+      sessionId: message.sessionId,
+      messageId: message.id,
+      uploadId,
+      // Áudio e sticker chegam sem nome; sem um rótulo o painel mostraria linha vazia.
+      filename: params.filename ?? `${params.sourceMediaId}`,
+      mimeType: mimeType || params.mimeType,
+      sizeBytes: buffer.length,
+      source: message.sender
+    });
+    const transcription = await this.transcribeIfAuto({
+      companyId: params.companyId,
+      message,
+      uploadId,
+      buffer,
+      mimeType: mimeType || params.mimeType
+    });
+    return {
+      uploadId,
+      alreadyIngested: false,
+      ...transcription ? {
+        transcription
+      } : {}
+    };
+  }
+  /**
+  * 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.
+  */
+  async transcribeIfAuto(context) {
+    const transcription = this.transcription;
+    if (!transcription) return void 0;
+    if (!isAudioMimeType(context.mimeType)) return void 0;
+    const policy = await transcription.resolvePolicy(context.companyId);
+    if (!policy.isEnabled || policy.mode !== TRANSCRIPTION_MODE.AUTO) return void 0;
+    const current = await transcription.messageRepository.findById(context.companyId, context.message.id);
+    if (current?.transcriptionStatus === TRANSCRIPTION_STATUS.DONE) return void 0;
+    try {
+      const result = await transcription.transcriber.transcribe({
+        buffer: context.buffer,
+        mimeType: context.mimeType,
+        ...transcription.languageHint ? {
+          languageHint: transcription.languageHint
+        } : {}
+      });
+      await transcription.messageRepository.saveTranscription({
+        companyId: context.companyId,
+        messageId: context.message.id,
+        status: TRANSCRIPTION_STATUS.DONE,
+        text: result.text,
+        language: result.language ?? null,
+        engine: result.engine
+      });
+      return {
+        status: TRANSCRIPTION_STATUS.DONE
+      };
+    } catch (error) {
+      return this.recordTranscriptionFailure(context, error);
+    }
+  }
+  async recordTranscriptionFailure(context, error) {
+    const status = resolveFailureStatus(error);
+    await this.transcription?.messageRepository.saveTranscription({
+      companyId: context.companyId,
+      messageId: context.message.id,
+      status
+    });
+    if (status === TRANSCRIPTION_STATUS.PENDING) {
+      const retryAfterSeconds = transcriptionRetryAfterSeconds(error);
+      await this.transcription?.hooks?.onTranscriptionDeferred?.({
+        companyId: context.companyId,
+        messageId: context.message.id,
+        whatsappNumber: context.message.whatsappNumber,
+        uploadId: context.uploadId,
+        ...retryAfterSeconds !== void 0 ? {
+          retryAfterSeconds
+        } : {},
+        reason: retryAfterSeconds !== void 0 ? "rate-limited" : "transient-failure",
+        error
+      });
+    }
+    return {
+      status
+    };
+  }
+};
+function extractMediaDescriptor(message) {
+  const payload = message.payload ?? {};
+  for (const key of [
+    "image",
+    "audio",
+    "video",
+    "document",
+    "sticker"
+  ]) {
+    const media = payload[key];
+    if (media?.id) {
+      return {
+        sourceMediaId: media.id,
+        mimeType: media.mime_type ?? "application/octet-stream",
+        filename: media.filename
+      };
+    }
+  }
+  return void 0;
+}
+__name(extractMediaDescriptor, "extractMediaDescriptor");
+
 // src/channel/ReceiveWebhook.use-case.ts
 function toSessionContract(row) {
   return {
@@ -1167,6 +2351,8 @@ function toSessionContract(row) {
     companyId: row.companyId,
     whatsappNumber: row.whatsappNumber,
     currentState: row.currentState,
+    flowKey: row.flowKey,
+    currentNodeId: row.currentNodeId,
     context: row.context,
     mode: row.mode,
     assignedUserId: row.assignedUserId,
@@ -1232,14 +2418,21 @@ var ReceiveWebhookUseCase = class {
     if (!claimed) return {
       duplicate: true,
       messagesProcessed: 0,
-      statusesProcessed: 0
+      statusesProcessed: 0,
+      ignoredForeignNumber: 0
     };
     const rawText = typeof input.rawBody === "string" ? input.rawBody : input.rawBody.toString("utf8");
-    const payload = import_meta_whatsapp_contracts8.whatsAppWebhookPayloadSchema.parse(JSON.parse(rawText));
+    const payload = import_meta_whatsapp_contracts12.whatsAppWebhookPayloadSchema.parse(JSON.parse(rawText));
     let messagesProcessed = 0;
     let statusesProcessed = 0;
+    let ignoredForeignNumber = 0;
     for (const entry of payload.entry) {
       for (const change of entry.changes) {
+        const targetNumber = change.value.metadata?.phone_number_id;
+        if (targetNumber && targetNumber !== this.params.phoneNumberId) {
+          ignoredForeignNumber++;
+          continue;
+        }
         for (const message of change.value.messages ?? []) {
           await this.handleMessage(input.companyId, message);
           messagesProcessed++;
@@ -1253,7 +2446,8 @@ var ReceiveWebhookUseCase = class {
     return {
       duplicate: false,
       messagesProcessed,
-      statusesProcessed
+      statusesProcessed,
+      ignoredForeignNumber
     };
   }
   async handleMessage(companyId, message) {
@@ -1270,6 +2464,19 @@ var ReceiveWebhookUseCase = class {
       startState: this.params.startState
     });
     if (!saved) return;
+    const media = extractMediaDescriptor(saved);
+    if (media) {
+      await this.params.hooks?.onMediaReceived?.({
+        companyId,
+        messageId: saved.id,
+        whatsappNumber: message.from,
+        sourceMediaId: media.sourceMediaId,
+        mimeType: media.mimeType,
+        ...media.filename ? {
+          filename: media.filename
+        } : {}
+      });
+    }
     const sessionRow = await this.params.sessionRepository.getContext(companyId, message.from);
     if (!sessionRow) return;
     if (sessionRow.mode === "human") return;
@@ -1289,76 +2496,50 @@ var ReceiveWebhookUseCase = class {
   }
 };
 
-// src/channel/IngestInboundMedia.use-case.ts
-var import_drizzle_orm6 = require("drizzle-orm");
-var IngestInboundMediaUseCase = class {
+// src/use-cases/resolveTranscriptionPolicy.ts
+function createTranscriptionPolicyResolver(dependencies) {
+  return /* @__PURE__ */ __name(async function resolveTranscriptionPolicy(companyId) {
+    const settings2 = await dependencies.settingsRepository.get(companyId);
+    return {
+      // `??` e não `||`: `false` gravado é decisão explícita de desligar, e `||` a trocaria pelo
+      // padrão do host — desligar no painel não faria nada num deploy com transcrição ligada.
+      isEnabled: settings2.transcriptionEnabled ?? dependencies.defaults.isEnabled,
+      mode: normalizeMode(settings2.transcriptionMode) ?? dependencies.defaults.mode
+    };
+  }, "resolveTranscriptionPolicy");
+}
+__name(createTranscriptionPolicyResolver, "createTranscriptionPolicyResolver");
+function normalizeMode(value) {
+  if (value === TRANSCRIPTION_MODE.AUTO) return TRANSCRIPTION_MODE.AUTO;
+  if (value === TRANSCRIPTION_MODE.ON_DEMAND) return TRANSCRIPTION_MODE.ON_DEMAND;
+  return void 0;
+}
+__name(normalizeMode, "normalizeMode");
+
+// src/use-cases/StorePreviewMedia.use-case.ts
+var StorePreviewMediaUseCase = class {
   static {
-    __name(this, "IngestInboundMediaUseCase");
+    __name(this, "StorePreviewMediaUseCase");
   }
-  db;
-  channel;
   objectStorage;
-  constructor(db, channel, objectStorage) {
-    this.db = db;
-    this.channel = channel;
+  generateKeySuffix;
+  constructor(objectStorage, generateKeySuffix) {
     this.objectStorage = objectStorage;
+    this.generateKeySuffix = generateKeySuffix;
   }
   async execute(params) {
-    const [message] = await this.db.select().from(messages).where((0, import_drizzle_orm6.and)((0, import_drizzle_orm6.eq)(messages.companyId, params.companyId), (0, import_drizzle_orm6.eq)(messages.id, params.messageId))).limit(1);
-    if (!message) throw new Error(`Mensagem ${params.messageId} n\xE3o encontrada para ingest\xE3o de m\xEDdia`);
-    const payload = message.payload ?? {};
-    if (payload["uploadId"] && payload["sourceMediaId"] === params.sourceMediaId) {
-      return {
-        uploadId: String(payload["uploadId"]),
-        alreadyIngested: true
-      };
-    }
-    const { data, mimeType } = await this.channel.fetchMediaAsBase64(params.sourceMediaId);
-    const buffer = Buffer.from(data, "base64");
+    const key = `meta-whatsapp/${params.companyId}/preview/${this.generateKeySuffix()}`;
     const { uploadId } = await this.objectStorage.upload({
-      buffer,
-      mimeType: mimeType || params.mimeType,
-      key: `meta-whatsapp/${params.companyId}/inbound/${params.sourceMediaId}`
+      buffer: params.buffer,
+      mimeType: params.mimeType,
+      key
     });
-    const updatedPayload = {
-      ...payload,
-      uploadId,
-      sourceMediaId: params.sourceMediaId,
-      mimeType: mimeType || params.mimeType,
-      ...params.filename ? {
-        filename: params.filename
-      } : {}
-    };
-    await this.db.update(messages).set({
-      payload: updatedPayload
-    }).where((0, import_drizzle_orm6.and)((0, import_drizzle_orm6.eq)(messages.companyId, params.companyId), (0, import_drizzle_orm6.eq)(messages.id, params.messageId)));
     return {
-      uploadId,
-      alreadyIngested: false
+      mediaId: (0, import_meta_whatsapp_contracts8.toPreviewMediaId)(uploadId),
+      uploadId
     };
   }
 };
-function extractMediaDescriptor(message) {
-  const payload = message.payload ?? {};
-  for (const key of [
-    "image",
-    "audio",
-    "video",
-    "document",
-    "sticker"
-  ]) {
-    const media = payload[key];
-    if (media?.id) {
-      return {
-        sourceMediaId: media.id,
-        mimeType: media.mime_type ?? "application/octet-stream",
-        filename: media.filename
-      };
-    }
-  }
-  return void 0;
-}
-__name(extractMediaDescriptor, "extractMediaDescriptor");
 
 // src/createMetaWhatsAppModule.ts
 function createMetaWhatsAppModule(params) {
@@ -1372,15 +2553,24 @@ function createMetaWhatsAppModule(params) {
     apiVersion: config.apiVersion,
     baseUrl: config.baseUrl
   });
-  const channel = new WhatsAppChannelAdapter(messageProvider);
+  const previewMediaSupport = params.features?.previewMedia && providers.objectStorage?.getObject ? {
+    isEnabled: true,
+    objectStorage: providers.objectStorage
+  } : void 0;
+  const channel = new WhatsAppChannelAdapter(messageProvider, previewMediaSupport);
   const sessionRepository = new SessionRepository(db);
   const messageRepository = new MessageRepository(db);
   const settingsRepository = new SettingsRepository(db);
-  const flowGraphRepository = new FlowGraphRepository(db);
-  const logMessage = new LogMessageUseCase(sessionRepository, messageRepository, providers.realtime);
-  const sendMessage = new SendMessageUseCase(channel, sessionRepository, logMessage, providers.objectStorage);
+  const flowGraphCacheFeature = params.features?.flowGraphCache ?? false;
+  const flowGraphCache = flowGraphCacheFeature && providers.cache ? new FlowGraphCache(providers.cache, typeof flowGraphCacheFeature === "object" ? flowGraphCacheFeature.ttlSeconds ?? DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS : DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS) : void 0;
+  const flowGraphRepository = new FlowGraphRepository(db, flowGraphCache);
+  const documentRepository = new DocumentRepository(db);
+  const flowMediaRepository = new FlowMediaRepository(db);
+  const logMessage = new LogMessageUseCase(sessionRepository, messageRepository, providers.realtime, providers.moderator);
+  const sendMessage = new SendMessageUseCase(channel, sessionRepository, logMessage, providers.objectStorage, documentRepository);
   const receiveWebhook = new ReceiveWebhookUseCase({
     appSecret: config.appSecret,
+    phoneNumberId: config.phoneNumberId,
     nonceStore,
     sessionRepository,
     messageRepository,
@@ -1390,7 +2580,49 @@ function createMetaWhatsAppModule(params) {
     realtime: providers.realtime
   });
   const flowInterpreter = flowEngineEnabled ? new FlowInterpreter() : void 0;
-  const ingestInboundMedia = providers.objectStorage ? new IngestInboundMediaUseCase(db, channel, providers.objectStorage) : void 0;
+  if (flowInterpreter && providers.objectStorage?.getObject) {
+    flowInterpreter.registerFlowAction(import_meta_whatsapp_contracts13.FLOW_ACTION_KIND.SEND_MEDIA, createSendMediaAction({
+      flowMediaRepository,
+      objectStorage: providers.objectStorage,
+      logMessage,
+      startState,
+      onError: hooks?.onFlowMediaError
+    }));
+  }
+  const transcriptionMode = providers.transcription?.mode ?? TRANSCRIPTION_MODE.ON_DEMAND;
+  const resolveTranscriptionPolicy = providers.transcription ? createTranscriptionPolicyResolver({
+    settingsRepository,
+    defaults: {
+      isEnabled: providers.transcription.isEnabledByDefault ?? true,
+      mode: transcriptionMode
+    }
+  }) : void 0;
+  const ingestInboundMedia = providers.objectStorage ? new IngestInboundMediaUseCase(db, channel, providers.objectStorage, documentRepository, providers.transcription && resolveTranscriptionPolicy ? {
+    transcriber: providers.transcription.transcriber,
+    resolvePolicy: resolveTranscriptionPolicy,
+    messageRepository,
+    ...providers.transcription.languageHint ? {
+      languageHint: providers.transcription.languageHint
+    } : {},
+    ...hooks ? {
+      hooks
+    } : {}
+  } : void 0) : void 0;
+  const transcribeAudio = providers.transcription && providers.objectStorage?.getObject ? new TranscribeAudioUseCase({
+    messageRepository,
+    objectStorage: providers.objectStorage,
+    transcriber: providers.transcription.transcriber,
+    ...resolveTranscriptionPolicy ? {
+      resolvePolicy: resolveTranscriptionPolicy
+    } : {},
+    ...providers.transcription.languageHint ? {
+      languageHint: providers.transcription.languageHint
+    } : {},
+    ...hooks ? {
+      hooks
+    } : {}
+  }) : void 0;
+  const listDocuments = new ListConversationDocumentsUseCase(sessionRepository, documentRepository);
   return {
     channel,
     // undefined quando providers.objectStorage não foi injetado.
@@ -1402,10 +2634,36 @@ function createMetaWhatsAppModule(params) {
       release: new ReleaseConversationUseCase(sessionRepository, providers.realtime),
       list: new ListConversationsUseCase(sessionRepository),
       listMessages: new ListMessagesUseCase(sessionRepository, messageRepository),
+      listDocuments,
+      // Biblioteca da empresa inteira, para uma tela de Documentos fora da conversa.
+      listCompanyDocuments: new ListCompanyDocumentsUseCase(documentRepository),
+      // Apaga a mídia no storage antes das linhas — a cascata da FK sozinha deixaria os binários
+      // órfãos, já que a lista de uploadId vive justamente nas linhas que ela derruba.
+      delete: new DeleteConversationUseCase(sessionRepository, documentRepository, providers.objectStorage),
+      purgeExpiredDocuments: new PurgeExpiredDocumentsUseCase(documentRepository, providers.objectStorage),
       export: new ExportConversationUseCase(sessionRepository),
-      repository: sessionRepository
+      // undefined quando transcrição não foi injetada, ou quando o storage não sabe ler de volta.
+      // O painel consulta a ausência para decidir se desenha o botão "transcrever".
+      transcribeAudio,
+      repository: sessionRepository,
+      messageRepository,
+      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: providers.transcription && resolveTranscriptionPolicy ? {
+      defaultMode: transcriptionMode,
+      resolvePolicy: resolveTranscriptionPolicy
+    } : void 0,
     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: previewMediaSupport ? new StorePreviewMediaUseCase(providers.objectStorage, () => `${Date.now()}-${Math.random().toString(36).slice(2)}`) : void 0,
     webhook: {
       receive: receiveWebhook,
       // GET de verificação da Meta — o host liga na sua rota e devolve o retorno como texto puro.
@@ -1424,7 +2682,11 @@ function createMetaWhatsAppModule(params) {
       save: new SaveFlowGraphUseCase(flowGraphRepository),
       delete: new DeleteFlowGraphUseCase(flowGraphRepository),
       livePositions: new GetLiveFlowPositionsUseCase(flowGraphRepository),
-      repository: flowGraphRepository
+      repository: flowGraphRepository,
+      // Biblioteca de mídia dos nós `send_media` — o host liga nas rotas do editor
+      // (anexar/reordenar/desligar). Existe mesmo sem storage injetado: gerenciar anexos é
+      // consultar a tabela, e só o ENVIO precisa dos bytes.
+      mediaRepository: flowMediaRepository
     } : void 0,
     catalog: providers.catalog
   };
@@ -1433,11 +2695,15 @@ __name(createMetaWhatsAppModule, "createMetaWhatsAppModule");
 
 // src/runMigrations.ts
 var import_node_path = require("path");
-var import_migrator = require("drizzle-orm/bun-sql/migrator");
-async function runMetaWhatsAppMigrations(db) {
-  await (0, import_migrator.migrate)(db, {
-    migrationsFolder: (0, import_node_path.join)(__dirname, "migrations"),
-    migrationsTable: "meta_whatsapp_migrations"
+var META_WHATSAPP_MIGRATIONS_TABLE = "meta_whatsapp_migrations";
+function metaWhatsAppMigrationsFolder() {
+  return (0, import_node_path.join)(__dirname, "migrations");
+}
+__name(metaWhatsAppMigrationsFolder, "metaWhatsAppMigrationsFolder");
+async function runMetaWhatsAppMigrations(params) {
+  await params.migrate(params.db, {
+    migrationsFolder: metaWhatsAppMigrationsFolder(),
+    migrationsTable: META_WHATSAPP_MIGRATIONS_TABLE
   });
 }
 __name(runMetaWhatsAppMigrations, "runMetaWhatsAppMigrations");
@@ -1520,20 +2786,30 @@ __name(redeemSseTicket, "redeemSseTicket");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CreateFlowGraphUseCase,
+  DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS,
+  DeleteConversationUseCase,
   DeleteFlowGraphUseCase,
+  DocumentRepository,
   ExportConversationUseCase,
+  FlowGraphCache,
   FlowGraphRepository,
   FlowInterpreter,
+  FlowMediaRepository,
   GetFlowGraphUseCase,
   GetLiveFlowPositionsUseCase,
   IngestInboundMediaUseCase,
   InvalidFlowGraphError,
+  ListCompanyDocumentsUseCase,
+  ListConversationDocumentsUseCase,
   ListConversationsUseCase,
   ListFlowGraphsUseCase,
   ListMessagesUseCase,
   LogMessageUseCase,
+  META_WHATSAPP_MIGRATIONS_TABLE,
   MessageRepository,
   OptimisticLockError,
+  PREVIEW_MEDIA_ID_PREFIX,
+  PurgeExpiredDocumentsUseCase,
   ReceiveWebhookUseCase,
   ReleaseConversationUseCase,
   SaveFlowGraphUseCase,
@@ -1541,20 +2817,36 @@ __name(redeemSseTicket, "redeemSseTicket");
   SessionRepository,
   SettingsRepository,
   SseHub,
+  StorePreviewMediaUseCase,
+  TRANSCRIPTION_MODE,
+  TRANSCRIPTION_STATUS,
   TakeoverConversationUseCase,
+  TranscribeAudioUseCase,
   WEBHOOK_NONCE_TTL_SECONDS,
   WhatsAppChannelAdapter,
   claimWebhookDelivery,
   createMetaWhatsAppModule,
+  createSendMediaAction,
+  createTranscriptionPolicyResolver,
+  documents,
   extractMediaDescriptor,
   flowGraphs,
+  flowMedia,
+  isAudioMimeType,
+  isRetriableTranscriptionError,
+  isUnsupportedTranscriptionError,
   issueSseTicket,
   messages,
+  metaWhatsAppMigrationsFolder,
   metaWhatsAppSchema,
   redeemSseTicket,
+  resolveFailureStatus,
+  resolvePreviewUploadId,
   runMetaWhatsAppMigrations,
   sessions,
   settings,
+  toPreviewMediaId,
+  transcriptionRetryAfterSeconds,
   verifyWebhookChallenge,
   verifyWebhookSignature
 });