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

package/dist/index.cjs

@@ -44,6 +44,7 @@ __export(index_exports, {
   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,
@@ -52,24 +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
 });
@@ -77,7 +90,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/createMetaWhatsAppModule.ts
 var import_meta_whatsapp_provider = require("@adatechnology/meta-whatsapp-provider");
-var import_meta_whatsapp_contracts11 = require("@adatechnology/meta-whatsapp-contracts");
+var import_meta_whatsapp_contracts13 = require("@adatechnology/meta-whatsapp-contracts");
 
 // src/repositories/SessionRepository.ts
 var import_drizzle_orm2 = require("drizzle-orm");
@@ -180,6 +193,27 @@ var messages = metaWhatsAppSchema.table("messages", {
   // 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()
@@ -194,7 +228,11 @@ var messages = metaWhatsAppSchema.table("messages", {
   (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}`)
+  (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(),
@@ -317,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(),
@@ -580,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),
@@ -764,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");
@@ -773,7 +876,9 @@ var EMPTY_SETTINGS = {
   templateLanguage: "pt_BR",
   templateVariables: [],
   welcomeMessage: "",
-  farewellMessage: ""
+  farewellMessage: "",
+  transcriptionEnabled: null,
+  transcriptionMode: null
 };
 var SettingsRepository = class {
   static {
@@ -802,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: {
@@ -811,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();
@@ -1799,20 +1911,27 @@ var FlowMediaRepository = class {
 
 // src/channel/WhatsAppChannelAdapter.ts
 var import_meta_graph_core = require("@adatechnology/meta-graph-core");
+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_contracts8.WindowExpiredError();
+      if (error instanceof import_meta_graph_core.WhatsAppWindowExpiredError) throw new import_meta_whatsapp_contracts9.WindowExpiredError();
       throw error;
     }
   }
@@ -1850,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_contracts10 = 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_contracts9 = 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();
@@ -1870,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_contracts9.InvalidWebhookSignatureError();
+    throw new import_meta_whatsapp_contracts10.InvalidWebhookSignatureError();
   }
   if (!safeEqualStrings(params.token, params.expectedToken)) {
-    throw new import_meta_whatsapp_contracts9.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_contracts9.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_contracts9.InvalidWebhookSignatureError();
+  if (!safeEqualStrings(received, expected)) throw new import_meta_whatsapp_contracts10.InvalidWebhookSignatureError();
 }
 __name(verifyWebhookSignature, "verifyWebhookSignature");
 async function claimWebhookDelivery(params) {
@@ -1894,6 +2027,160 @@ __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");
@@ -1902,11 +2189,13 @@ var IngestInboundMediaUseCase = class {
   channel;
   objectStorage;
   documentRepository;
-  constructor(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);
@@ -1952,9 +2241,84 @@ var IngestInboundMediaUseCase = class {
       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
+      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
     };
   }
 };
@@ -2057,7 +2421,7 @@ var ReceiveWebhookUseCase = class {
       statusesProcessed: 0
     };
     const rawText = typeof input.rawBody === "string" ? input.rawBody : input.rawBody.toString("utf8");
-    const payload = import_meta_whatsapp_contracts10.whatsAppWebhookPayloadSchema.parse(JSON.parse(rawText));
+    const payload = import_meta_whatsapp_contracts12.whatsAppWebhookPayloadSchema.parse(JSON.parse(rawText));
     let messagesProcessed = 0;
     let statusesProcessed = 0;
     for (const entry of payload.entry) {
@@ -2124,6 +2488,51 @@ var ReceiveWebhookUseCase = 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, "StorePreviewMediaUseCase");
+  }
+  objectStorage;
+  generateKeySuffix;
+  constructor(objectStorage, generateKeySuffix) {
+    this.objectStorage = objectStorage;
+    this.generateKeySuffix = generateKeySuffix;
+  }
+  async execute(params) {
+    const key = `meta-whatsapp/${params.companyId}/preview/${this.generateKeySuffix()}`;
+    const { uploadId } = await this.objectStorage.upload({
+      buffer: params.buffer,
+      mimeType: params.mimeType,
+      key
+    });
+    return {
+      mediaId: (0, import_meta_whatsapp_contracts8.toPreviewMediaId)(uploadId),
+      uploadId
+    };
+  }
+};
+
 // src/createMetaWhatsAppModule.ts
 function createMetaWhatsAppModule(params) {
   const { db, config, nonceStore, providers = {}, hooks } = params;
@@ -2136,7 +2545,11 @@ 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);
@@ -2159,7 +2572,7 @@ function createMetaWhatsAppModule(params) {
   });
   const flowInterpreter = flowEngineEnabled ? new FlowInterpreter() : void 0;
   if (flowInterpreter && providers.objectStorage?.getObject) {
-    flowInterpreter.registerFlowAction(import_meta_whatsapp_contracts11.FLOW_ACTION_KIND.SEND_MEDIA, createSendMediaAction({
+    flowInterpreter.registerFlowAction(import_meta_whatsapp_contracts13.FLOW_ACTION_KIND.SEND_MEDIA, createSendMediaAction({
       flowMediaRepository,
       objectStorage: providers.objectStorage,
       logMessage,
@@ -2167,7 +2580,39 @@ function createMetaWhatsAppModule(params) {
       onError: hooks?.onFlowMediaError
     }));
   }
-  const ingestInboundMedia = providers.objectStorage ? new IngestInboundMediaUseCase(db, channel, providers.objectStorage, documentRepository) : void 0;
+  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,
@@ -2188,10 +2633,28 @@ function createMetaWhatsAppModule(params) {
       delete: new DeleteConversationUseCase(sessionRepository, documentRepository, providers.objectStorage),
       purgeExpiredDocuments: new PurgeExpiredDocumentsUseCase(documentRepository, providers.objectStorage),
       export: new ExportConversationUseCase(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.
@@ -2336,6 +2799,7 @@ __name(redeemSseTicket, "redeemSseTicket");
   META_WHATSAPP_MIGRATIONS_TABLE,
   MessageRepository,
   OptimisticLockError,
+  PREVIEW_MEDIA_ID_PREFIX,
   PurgeExpiredDocumentsUseCase,
   ReceiveWebhookUseCase,
   ReleaseConversationUseCase,
@@ -2344,24 +2808,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
 });