@adatechnology/meta-whatsapp-contracts 0.2.0-rc.8 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { b as WhatsAppMessage, f as WhatsAppStatus } from './webhook.types-PxhpmpzC.js';
-export { W as WhatsAppInteractive, a as WhatsAppMedia, c as WhatsAppMessageEcho, d as WhatsAppMessageStatusValue, e as WhatsAppOrder, g as WhatsAppWebhookPayload, w as whatsAppInteractiveSchema, h as whatsAppMediaSchema, i as whatsAppMessageEchoSchema, j as whatsAppMessageSchema, k as whatsAppMessageStatusSchema, l as whatsAppOrderSchema, m as whatsAppStatusSchema, n as whatsAppWebhookPayloadSchema } from './webhook.types-PxhpmpzC.js';
+import { c as WhatsAppMessage, i as WhatsAppStatus, k as WhatsAppTemplateStatusUpdate, g as WhatsAppPhoneNumberQualityUpdate } from './webhook.types-DWaAhvNu.js';
+export { W as WHATSAPP_WEBHOOK_FIELDS, a as WhatsAppInteractive, b as WhatsAppMedia, d as WhatsAppMessageEcho, e as WhatsAppMessageStatusValue, f as WhatsAppOrder, h as WhatsAppQualityEvent, j as WhatsAppTemplateStatusEvent, l as WhatsAppWebhookChange, m as WhatsAppWebhookField, n as WhatsAppWebhookPayload, o as WhatsAppWebhookValue, w as whatsAppInteractiveSchema, p as whatsAppMediaSchema, q as whatsAppMessageEchoSchema, r as whatsAppMessageSchema, s as whatsAppMessageStatusSchema, t as whatsAppOrderSchema, u as whatsAppPhoneNumberQualityUpdateSchema, v as whatsAppQualityEventSchema, x as whatsAppStatusSchema, y as whatsAppTemplateStatusEventSchema, z as whatsAppTemplateStatusUpdateSchema, A as whatsAppWebhookChangeSchema, B as whatsAppWebhookPayloadSchema, C as whatsAppWebhookValueSchema } from './webhook.types-DWaAhvNu.js';
 import { z } from 'zod';
 
 type SessionState = string;
@@ -84,6 +84,7 @@ declare const crossFlowKey: (target: string) => string;
 type FlowNodeData = {
     id: string;
     type: FlowNodeType;
+    label?: string;
     contextKey?: string;
     questionType?: FlowQuestionType;
     question?: string;
@@ -338,98 +339,49 @@ declare const flowGraphNodesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
     }>]>>;
 }, z.ZodTypeAny, "passthrough">>>;
 
-interface WhatsAppSettings {
-    templateName: string;
-    templateLanguage: string;
-    templateVariables: string[];
-    welcomeMessage: string;
-    farewellMessage: string;
-}
-interface TemplateVariablesMap {
-    [index: number]: string;
-}
-interface TemplateConfig {
-    name: string;
-    category: 'UTILITY' | 'MARKETING';
-    language: string;
-    headerType: 'NONE' | 'TEXT';
-    headerText?: string;
-    bodyText: string;
-    footerText?: string;
-}
-interface WhatsAppTemplateSummary {
-    id: string;
-    name: string;
-    shortId: string;
-    displayName: string;
-    status: string;
-    category: string;
-    language: string;
-    bodyText: string | null;
-    variableCount: number;
-}
-interface CreateTemplateResult {
-    ok: boolean;
-    message: string;
-    status?: string;
-}
-
-type MessageHookOutcome = {
-    outcome: 'handled';
-} | {
-    outcome: 'continue';
+/**
+ * Tetos da Meta para escolha interativa.
+ *
+ * Ficam no contrato porque quem escreve o texto da opção precisa deles antes de publicar: passar do
+ * limite não degrada nada, a Graph API recusa a mensagem inteira e o cliente vê silêncio. Botão é
+ * mais curto que linha de lista, e o emoji conta como caractere.
+ */
+declare const WHATSAPP_CHOICE_LIMIT: {
+    readonly BUTTONS: 3;
+    readonly BUTTON_TITLE_LENGTH: 20;
+    readonly LIST_ROWS: 10;
+    readonly LIST_ROW_TITLE_LENGTH: 24;
 };
-interface MetaWhatsAppHooks {
-    onMessageReceived?: (message: WhatsAppMessage, session: ConversationSession) => Promise<MessageHookOutcome>;
-    onStatusUpdate?: (status: WhatsAppStatus, session: ConversationSession | null) => Promise<void>;
-    onSessionExpired?: (session: ConversationSession) => Promise<void>;
-    onHumanRequested?: (session: ConversationSession) => Promise<void>;
-    /**
-     * Mídia recebida do cliente, já persistida como mensagem e pronta para ser copiada da Meta para
-     * o storage do host — normalmente enfileirando um job.
-     *
-     * Hook próprio, e não parte do `onMessageReceived`, porque aquele pertence ao fluxo do bot: ele
-     * nem é chamado quando a conversa está em atendimento humano, que é exatamente quando o cliente
-     * manda documento para o atendente. Ligar ingestão lá perderia esses arquivos em silêncio.
-     *
-     * A URL de download da Meta expira, então quem implementa deve tratar como trabalho urgente.
-     */
-    onMediaReceived?: (media: InboundMediaDescriptor) => Promise<void>;
-    /**
-     * Falha ao enviar UM arquivo da biblioteca num nó `send_media`.
-     *
-     * O erro é entregue aqui em vez de propagado porque um PDF que não subiu não pode travar a
-     * conversa num nó automático — o cliente ficaria parado sem nenhuma mensagem. O módulo segue
-     * para o próximo arquivo e para o próximo nó; observar e alertar é do host.
-     */
-    onFlowMediaError?: (error: unknown, details: {
-        flowKey: string;
-        nodeId: string;
-        uploadId: string;
-    }) => void;
-}
-type InboundMediaDescriptor = {
-    readonly companyId: string;
-    readonly messageId: string;
-    readonly whatsappNumber: string;
-    /** ID da mídia na Meta — a origem do download, que expira. */
-    readonly sourceMediaId: string;
-    readonly mimeType: string;
-    readonly filename?: string;
+type SendChannelMediaCommon = {
+    to: string;
+    mimeType: string;
+    filename: string;
+    caption?: string;
 };
-
+/**
+ * Ou o binário, ou um `mediaId` já conhecido — nunca nenhum dos dois.
+ *
+ * União em vez de dois campos opcionais: com ambos opcionais, "esqueci de passar os dois" compila e
+ * só quebra na chamada à Meta, em produção.
+ */
+type SendChannelMediaParams = (SendChannelMediaCommon & {
+    buffer: Buffer;
+    mediaId?: string | undefined;
+}) | (SendChannelMediaCommon & {
+    buffer?: undefined;
+    mediaId: string;
+});
 interface ChannelAdapterInterface {
     sendText(to: string, body: string): Promise<{
         externalMessageId: string | null;
     }>;
-    sendMedia(params: {
-        to: string;
-        buffer: Buffer;
-        mimeType: string;
-        filename: string;
-        caption?: string;
-    }): Promise<{
+    /**
+     * Envia arquivo. Com `mediaId` conhecido, o binário não sobe de novo — a Meta aceita reusar o id
+     * por 30 dias, e o `mediaId` devolvido é o que permite guardá-lo para os próximos destinatários.
+     */
+    sendMedia(params: SendChannelMediaParams): Promise<{
         externalMessageId: string | null;
+        mediaId?: string | undefined;
     }>;
     sendTemplate(params: {
         to: string;
@@ -450,6 +402,43 @@ interface ChannelAdapterInterface {
     }): Promise<{
         externalMessageId: string | null;
     }>;
+    /**
+     * Botão de resposta rápida — opcional porque a lista sempre serve de alternativa.
+     *
+     * Exigi-lo na porta quebraria todo dublê de teste e todo canal já escrito, para uma capacidade
+     * que nem todo canal tem: quem não implementa continua caindo na lista, que é o que o WhatsApp
+     * fazia antes. A Meta limita a 3 botões, e o provider recusa o quarto.
+     */
+    sendInteractiveButtons?(params: {
+        to: string;
+        body: string;
+        buttons: {
+            id: string;
+            title: string;
+        }[];
+    }): Promise<{
+        externalMessageId: string | null;
+    }>;
+    /**
+     * Vitrine de produtos — opcional pelo mesmo motivo do botão: canal que não sabe enviar produto
+     * continua funcionando, e a ausência do método é o que desliga o recurso, sem flag `hasCatalog`.
+     *
+     * A Meta limita a 30 itens por mensagem, distribuídos em até 10 seções; o provider recusa acima
+     * disso. Quem monta a lista corta antes — mandar tudo e ver a Graph API recusar a mensagem
+     * inteira deixa o cliente no silêncio.
+     */
+    sendProductList?(params: {
+        to: string;
+        headerText: string;
+        body: string;
+        footerText?: string;
+        sections: {
+            title: string;
+            retailerIds: string[];
+        }[];
+    }): Promise<{
+        externalMessageId: string | null;
+    }>;
     fetchMediaAsBase64(mediaId: string): Promise<{
         data: string;
         mimeType: string;
@@ -546,6 +535,174 @@ interface FlowActionRegistry {
     registerFlowAction(kind: FlowActionKind, handler: FlowActionHandler): void;
 }
 
+/**
+ * Quando transcrever nota de voz.
+ *
+ * Vive no contrato, e não só no módulo, porque atravessa três fronteiras: o painel escolhe, a API
+ * transporta e o módulo obedece. Duas definições concorrentes divergiriam no primeiro valor novo.
+ */
+type TranscriptionMode = 'auto' | 'onDemand';
+interface WhatsAppSettings {
+    templateName: string;
+    templateLanguage: string;
+    templateVariables: string[];
+    welcomeMessage: string;
+    farewellMessage: string;
+    /**
+     * Transcrição de áudio ligada para ESTA empresa.
+     *
+     * Tri-state de propósito: `null` significa "não decidido pelo painel", e aí vale o padrão que o
+     * host injetou (tipicamente ambiente). Se fosse `boolean` com padrão `false`, atualizar o módulo
+     * desligaria a transcrição de quem já a tinha ligada por variável de ambiente — regressão
+     * silenciosa num recurso que estava funcionando.
+     *
+     * Ligar aqui não cria capacidade: sem engine e chave injetados no host, não há o que transcrever.
+     * Ambiente decide se É POSSÍVEL; isto decide se é para FAZER.
+     */
+    transcriptionEnabled: boolean | null;
+    /** `null` = herda o modo injetado pelo host. */
+    transcriptionMode: TranscriptionMode | null;
+}
+interface TemplateVariablesMap {
+    [index: number]: string;
+}
+interface TemplateConfig {
+    name: string;
+    category: 'UTILITY' | 'MARKETING';
+    language: string;
+    headerType: 'NONE' | 'TEXT';
+    headerText?: string;
+    bodyText: string;
+    footerText?: string;
+}
+interface WhatsAppTemplateSummary {
+    id: string;
+    name: string;
+    shortId: string;
+    displayName: string;
+    status: string;
+    category: string;
+    language: string;
+    bodyText: string | null;
+    variableCount: number;
+}
+interface CreateTemplateResult {
+    ok: boolean;
+    message: string;
+    status?: string;
+}
+
+type MessageHookOutcome = {
+    outcome: 'handled';
+} | {
+    outcome: 'continue';
+};
+interface MetaWhatsAppHooks {
+    onMessageReceived?: (message: WhatsAppMessage, session: ConversationSession) => Promise<MessageHookOutcome>;
+    onStatusUpdate?: (status: WhatsAppStatus, session: ConversationSession | null) => Promise<void>;
+    onSessionExpired?: (session: ConversationSession) => Promise<void>;
+    onHumanRequested?: (session: ConversationSession) => Promise<void>;
+    /**
+     * Mídia recebida do cliente, já persistida como mensagem e pronta para ser copiada da Meta para
+     * o storage do host — normalmente enfileirando um job.
+     *
+     * Hook próprio, e não parte do `onMessageReceived`, porque aquele pertence ao fluxo do bot: ele
+     * nem é chamado quando a conversa está em atendimento humano, que é exatamente quando o cliente
+     * manda documento para o atendente. Ligar ingestão lá perderia esses arquivos em silêncio.
+     *
+     * A URL de download da Meta expira, então quem implementa deve tratar como trabalho urgente.
+     */
+    onMediaReceived?: (media: InboundMediaDescriptor) => Promise<void>;
+    /**
+     * Falha ao enviar UM arquivo da biblioteca num nó `send_media`.
+     *
+     * O erro é entregue aqui em vez de propagado porque um PDF que não subiu não pode travar a
+     * conversa num nó automático — o cliente ficaria parado sem nenhuma mensagem. O módulo segue
+     * para o próximo arquivo e para o próximo nó; observar e alertar é do host.
+     */
+    onFlowMediaError?: (error: unknown, details: {
+        flowKey: string;
+        nodeId: string;
+        uploadId: string;
+    }) => void;
+    /**
+     * Falha ao enviar a vitrine de produtos num nó `send_product_list`.
+     *
+     * Hook próprio, e não o de mídia: aqui não há `uploadId` — o que falhou foi a montagem da
+     * vitrine a partir do catálogo, e o host precisa saber qual nó ficou mudo.
+     */
+    onFlowProductListError?: (error: unknown, details: {
+        flowKey: string;
+        nodeId: string;
+    }) => void;
+    /**
+     * Transcrição de áudio falhou de forma **retriável** (cota estourada, rede, 5xx) — o áudio segue
+     * transcritível e alguém precisa tentar de novo.
+     *
+     * É hook, e não exceção propagada, porque a mídia JÁ foi copiada para o storage quando isto
+     * acontece: deixar o erro subir marcaria a ingestão inteira como falha e o job reprocessaria o
+     * download de um binário que está salvo. E é hook, e não retentativa interna, porque o módulo não
+     * tem fila — quem sabe reenfileirar com atraso é o host, que já tem uma.
+     *
+     * Sem implementar, o áudio fica com `transcription_status = 'pending'` e nada o retoma: a
+     * transcrição não se perde nem mente, mas só sai se pedirem sob demanda.
+     */
+    onTranscriptionDeferred?: (details: TranscriptionDeferredDescriptor) => Promise<void> | void;
+    /**
+     * A Meta mudou o status de um template (aprovado, rejeitado, pausado).
+     *
+     * É um evento de conta, não de conversa: não tem `session` nem número de cliente, e chega mesmo
+     * quando nenhuma conversa está acontecendo. Sem implementar, a única forma de descobrir que um
+     * template foi rejeitado é alguém abrir o painel da Meta e reparar.
+     */
+    onTemplateStatusUpdate?: (update: WhatsAppTemplateStatusUpdate) => Promise<void> | void;
+    /**
+     * Qualidade ou limite de envio do número mudou (`FLAGGED` = qualidade caiu e o número corre risco
+     * de restrição; `DOWNGRADE` = teto de envio reduzido).
+     *
+     * Vale tratar como alerta operacional: quando vira restrição de fato, as mensagens já estão
+     * falhando, e o histórico de qualidade que explicaria a queda tem retenção curta no painel.
+     */
+    onPhoneNumberQualityUpdate?: (update: WhatsAppPhoneNumberQualityUpdate) => Promise<void> | void;
+    /**
+     * Chegou um `field` que este módulo não sabe tratar — ou um que sabe, mas com corpo fora do
+     * schema (versão nova da Cloud API, campo assinado sem handler).
+     *
+     * Existe para que o webhook nunca seja um buraco negro: descartar em silêncio é indistinguível de
+     * webhook que parou de chegar, e foi assim que os eventos de template ficaram invisíveis até
+     * alguém procurar. Observar aqui é do host; o módulo não decide que é erro.
+     */
+    onUnhandledWebhookEvent?: (details: UnhandledWebhookEventDescriptor) => Promise<void> | void;
+}
+type UnhandledWebhookEventDescriptor = {
+    /** O `changes[].field` como a Meta mandou; `undefined` quando o payload nem trouxe o campo. */
+    readonly field: string | undefined;
+    /** Por que não foi tratado: sem handler para o field, ou corpo que não bate com o schema dele. */
+    readonly reason: 'unknown-field' | 'invalid-shape';
+    /** O `value` cru, para diagnóstico. Nunca logar inteiro: pode conter dado de cliente. */
+    readonly value: unknown;
+};
+type TranscriptionDeferredDescriptor = {
+    readonly companyId: string;
+    readonly messageId: string;
+    readonly whatsappNumber: string;
+    /** Onde o áudio já está salvo — quem retomar lê daqui, não da Meta (cuja URL expira). */
+    readonly uploadId: string;
+    /** Do `Retry-After` do engine, quando informado. É o intervalo mínimo a respeitar. */
+    readonly retryAfterSeconds?: number;
+    readonly reason: 'rate-limited' | 'transient-failure';
+    readonly error: unknown;
+};
+type InboundMediaDescriptor = {
+    readonly companyId: string;
+    readonly messageId: string;
+    readonly whatsappNumber: string;
+    /** ID da mídia na Meta — a origem do download, que expira. */
+    readonly sourceMediaId: string;
+    readonly mimeType: string;
+    readonly filename?: string;
+};
+
 declare class MetaWhatsAppError extends Error {
     readonly statusCode: number;
     readonly code: string;
@@ -559,6 +716,9 @@ declare const META_WHATSAPP_ERROR_CODES: {
     readonly CONFIG_MISSING: "META_WHATSAPP_CONFIG_MISSING";
     readonly TEMPLATE_NOT_CONFIGURED: "META_WHATSAPP_TEMPLATE_NOT_CONFIGURED";
     readonly SESSION_NOT_FOUND: "META_WHATSAPP_SESSION_NOT_FOUND";
+    readonly AUDIO_NOT_INGESTED: "META_WHATSAPP_AUDIO_NOT_INGESTED";
+    readonly MESSAGE_NOT_AUDIO: "META_WHATSAPP_MESSAGE_NOT_AUDIO";
+    readonly TRANSCRIPTION_DISABLED: "META_WHATSAPP_TRANSCRIPTION_DISABLED";
 };
 declare class WindowExpiredError extends MetaWhatsAppError {
     readonly hoursSinceLastMessage?: number | undefined;
@@ -579,5 +739,64 @@ declare class TemplateNotConfiguredError extends MetaWhatsAppError {
 declare class SessionNotFoundError extends MetaWhatsAppError {
     constructor(whatsappNumber: string);
 }
+/**
+ * Pediram transcrição de um áudio que ainda não foi copiado da Meta para o storage.
+ *
+ * 409 e não 404: a mensagem existe e o áudio vai chegar — a ingestão é assíncrona e o atendente
+ * simplesmente clicou antes de ela terminar. É o único erro de transcrição em que "tente de novo em
+ * alguns segundos" é a orientação correta para a interface.
+ */
+declare class AudioNotIngestedError extends MetaWhatsAppError {
+    constructor(messageId: string);
+}
+/**
+ * Transcrição está desligada para esta empresa.
+ *
+ * Guarda de última linha, não o caminho normal: o painel lê as configurações e nem desenha o botão
+ * quando está desligado. Existe para o caso de a tela estar com dado velho, ou de alguém chamar a
+ * rota direto — e é `409` (estado atual conflita com a operação), não `403`: ninguém está sem
+ * permissão, o recurso está desligado por escolha e liga a qualquer momento.
+ */
+declare class TranscriptionDisabledError extends MetaWhatsAppError {
+    constructor();
+}
+/** Pediram transcrição de mensagem que não é áudio. Nunca melhora com retentativa. */
+declare class MessageNotAudioError extends MetaWhatsAppError {
+    constructor(messageId: string, type: string);
+}
+
+/**
+ * Mídia que veio do simulador de conversa, não da Meta.
+ *
+ * Vive no `contracts` porque é literalmente um contrato entre as duas pontas: o front gera o id, o
+ * backend o resolve. Nasceu duplicado num produto (duas constantes iguais, cada uma com um
+ * comentário pedindo "precisa bater com a outra") e por isso o segundo produto não herdou nada —
+ * este pacote é o único lugar em que os dois lados já se encontram.
+ *
+ * O simulador manda **webhook**, e webhook da Meta carrega referência de mídia (um id), nunca o
+ * binário. Então o arquivo gravado no navegador precisa existir em algum lugar que o servidor
+ * alcance, e o id precisa dizer onde — é essa a convenção deste arquivo.
+ *
+ * Existe no pacote, e não em cada host, porque a convenção tem DOIS lados que precisam concordar
+ * (quem gera o id no front, quem o resolve no backend). Onde ela ficou no host, o resultado foi
+ * exatamente o previsível: duas constantes iguais em pacotes diferentes, cada uma com um comentário
+ * pedindo "precisa bater com a outra" — e o segundo produto não herdou nada e ficou sem o recurso.
+ */
+/**
+ * Prefixo que marca o id como local.
+ *
+ * Dois-pontos no fim de propósito: id da Meta é alfanumérico com `_` e `-`, então o separador torna
+ * a colisão impossível em vez de improvável.
+ */
+declare const PREVIEW_MEDIA_ID_PREFIX = "preview-upload:";
+/** Monta o id que o simulador manda no webhook. */
+declare function toPreviewMediaId(uploadId: string): string;
+/**
+ * `uploadId` embutido no id, ou `undefined` quando a mídia veio mesmo da Meta.
+ *
+ * Devolver `undefined` para id sem prefixo é o que mantém o caminho normal intacto: o adaptador só
+ * desvia para o storage quando o prefixo está lá.
+ */
+declare function resolvePreviewUploadId(mediaId: string): string | undefined;
 
-export { CROSS_FLOW_PREFIX, type CacheInterface, type CatalogPort, type CatalogProduct, type ChannelAdapterInterface, ConfigMissingError, type ConversationMessage, type ConversationSession, type ConversationSummary, type CreateTemplateResult, DuplicateWebhookDeliveryError, FLOW_ACTION_KIND, type FlowActionHandler, type FlowActionKind, type FlowActionRegistry, type FlowActionResult, type FlowConditionOperator, type FlowGraphData, type FlowGraphSummary, type FlowNodeData, type FlowNodeNext, type FlowNodeType, type FlowQuestionType, type InboundMediaDescriptor, InvalidWebhookSignatureError, type ListConversationsParams, type ListMessagesParams, type LiveFlowPosition, META_WHATSAPP_ERROR_CODES, type MessageDirection, type MessageHookOutcome, type MessageSender, type MessageStatus, MetaWhatsAppError, type MetaWhatsAppHooks, type ObjectStorageInterface, type RealtimeNotifierInterface, type SessionMode, SessionNotFoundError, type SessionState, type SubjectResolverInterface, type TemplateConfig, TemplateNotConfiguredError, type TemplateVariablesMap, WhatsAppMessage, type WhatsAppSettings, WhatsAppStatus, type WhatsAppTemplateSummary, WindowExpiredError, crossFlowKey, flowGraphNodesSchema, flowNodeDataSchema, flowNodeNextSchema, isCrossFlowTarget };
+export { AudioNotIngestedError, CROSS_FLOW_PREFIX, type CacheInterface, type CatalogPort, type CatalogProduct, type ChannelAdapterInterface, ConfigMissingError, type ConversationMessage, type ConversationSession, type ConversationSummary, type CreateTemplateResult, DuplicateWebhookDeliveryError, FLOW_ACTION_KIND, type FlowActionHandler, type FlowActionKind, type FlowActionRegistry, type FlowActionResult, type FlowConditionOperator, type FlowGraphData, type FlowGraphSummary, type FlowNodeData, type FlowNodeNext, type FlowNodeType, type FlowQuestionType, type InboundMediaDescriptor, InvalidWebhookSignatureError, type ListConversationsParams, type ListMessagesParams, type LiveFlowPosition, META_WHATSAPP_ERROR_CODES, type MessageDirection, type MessageHookOutcome, MessageNotAudioError, type MessageSender, type MessageStatus, MetaWhatsAppError, type MetaWhatsAppHooks, type ObjectStorageInterface, PREVIEW_MEDIA_ID_PREFIX, type RealtimeNotifierInterface, type SendChannelMediaParams, type SessionMode, SessionNotFoundError, type SessionState, type SubjectResolverInterface, type TemplateConfig, TemplateNotConfiguredError, type TemplateVariablesMap, type TranscriptionDeferredDescriptor, TranscriptionDisabledError, type TranscriptionMode, type UnhandledWebhookEventDescriptor, WHATSAPP_CHOICE_LIMIT, WhatsAppMessage, WhatsAppPhoneNumberQualityUpdate, type WhatsAppSettings, WhatsAppStatus, WhatsAppTemplateStatusUpdate, type WhatsAppTemplateSummary, WindowExpiredError, crossFlowKey, flowGraphNodesSchema, flowNodeDataSchema, flowNodeNextSchema, isCrossFlowTarget, resolvePreviewUploadId, toPreviewMediaId };

package/dist/index.js

@@ -75,22 +75,70 @@ var whatsAppStatusSchema = z.object({
   timestamp: z.string(),
   recipient_id: z.string().optional()
 });
+var WHATSAPP_WEBHOOK_FIELDS = {
+  MESSAGES: "messages",
+  MESSAGE_ECHOES: "message_echoes",
+  TEMPLATE_STATUS_UPDATE: "message_template_status_update",
+  PHONE_NUMBER_QUALITY_UPDATE: "phone_number_quality_update"
+};
+var whatsAppTemplateStatusEventSchema = z.enum([
+  "APPROVED",
+  "REJECTED",
+  "PENDING",
+  "PAUSED",
+  "PENDING_DELETION",
+  "DISABLED",
+  "FLAGGED"
+]);
+var whatsAppTemplateStatusUpdateSchema = z.object({
+  event: whatsAppTemplateStatusEventSchema,
+  // A Meta manda o id do template como número em alguns eventos e como string em outros; o resto
+  // do sistema trata id como string, então normalizamos na fronteira em vez de espalhar `String()`.
+  message_template_id: z.union([
+    z.string(),
+    z.number()
+  ]).transform((value) => String(value)),
+  message_template_name: z.string(),
+  message_template_language: z.string(),
+  // Só vem em REJECTED/PAUSED/DISABLED, e a Meta às vezes manda `null` em vez de omitir.
+  reason: z.string().nullish(),
+  disable_date: z.string().optional()
+});
+var whatsAppQualityEventSchema = z.enum([
+  "FLAGGED",
+  "UNFLAGGED",
+  "ONBOARDING",
+  "UPGRADE",
+  "DOWNGRADE"
+]);
+var whatsAppPhoneNumberQualityUpdateSchema = z.object({
+  display_phone_number: z.string(),
+  event: whatsAppQualityEventSchema,
+  // Tier de envio (`TIER_1K`, `TIER_10K`, …). Ausente em evento que não mexe no limite.
+  current_limit: z.string().optional(),
+  old_limit: z.string().optional()
+});
+var whatsAppWebhookValueSchema = z.object({
+  messaging_product: z.string().optional(),
+  messages: z.array(whatsAppMessageSchema).optional(),
+  message_echoes: z.array(whatsAppMessageEchoSchema).optional(),
+  statuses: z.array(whatsAppStatusSchema).optional(),
+  metadata: z.object({
+    display_phone_number: z.string(),
+    phone_number_id: z.string()
+  }).optional()
+}).passthrough();
+var whatsAppWebhookChangeSchema = z.object({
+  // Qual assinatura disparou. Opcional porque payload antigo de fixture não tem, e porque a
+  // ausência precisa degradar para "trata como mensagem", que é o comportamento histórico.
+  field: z.string().optional(),
+  value: whatsAppWebhookValueSchema
+});
 var whatsAppWebhookPayloadSchema = z.object({
   object: z.string(),
   entry: z.array(z.object({
     id: z.string(),
-    changes: z.array(z.object({
-      value: z.object({
-        messaging_product: z.string(),
-        messages: z.array(whatsAppMessageSchema).optional(),
-        message_echoes: z.array(whatsAppMessageEchoSchema).optional(),
-        statuses: z.array(whatsAppStatusSchema).optional(),
-        metadata: z.object({
-          display_phone_number: z.string(),
-          phone_number_id: z.string()
-        }).optional()
-      })
-    }))
+    changes: z.array(whatsAppWebhookChangeSchema)
   }))
 });
 
@@ -158,6 +206,14 @@ var flowNodeDataSchema = z2.object({
 }).passthrough();
 var flowGraphNodesSchema = z2.record(z2.string(), flowNodeDataSchema);
 
+// src/providers.ts
+var WHATSAPP_CHOICE_LIMIT = {
+  BUTTONS: 3,
+  BUTTON_TITLE_LENGTH: 20,
+  LIST_ROWS: 10,
+  LIST_ROW_TITLE_LENGTH: 24
+};
+
 // src/errors.ts
 var MetaWhatsAppError = class extends Error {
   static {
@@ -177,7 +233,10 @@ var META_WHATSAPP_ERROR_CODES = {
   DUPLICATE_DELIVERY: "META_WHATSAPP_DUPLICATE_DELIVERY",
   CONFIG_MISSING: "META_WHATSAPP_CONFIG_MISSING",
   TEMPLATE_NOT_CONFIGURED: "META_WHATSAPP_TEMPLATE_NOT_CONFIGURED",
-  SESSION_NOT_FOUND: "META_WHATSAPP_SESSION_NOT_FOUND"
+  SESSION_NOT_FOUND: "META_WHATSAPP_SESSION_NOT_FOUND",
+  AUDIO_NOT_INGESTED: "META_WHATSAPP_AUDIO_NOT_INGESTED",
+  MESSAGE_NOT_AUDIO: "META_WHATSAPP_MESSAGE_NOT_AUDIO",
+  TRANSCRIPTION_DISABLED: "META_WHATSAPP_TRANSCRIPTION_DISABLED"
 };
 var WindowExpiredError = class extends MetaWhatsAppError {
   static {
@@ -236,29 +295,84 @@ var SessionNotFoundError = class extends MetaWhatsAppError {
     });
   }
 };
+var AudioNotIngestedError = class extends MetaWhatsAppError {
+  static {
+    __name(this, "AudioNotIngestedError");
+  }
+  constructor(messageId) {
+    super("\xC1udio ainda est\xE1 sendo copiado \u2014 tente novamente em alguns segundos.", 409, META_WHATSAPP_ERROR_CODES.AUDIO_NOT_INGESTED, {
+      messageId
+    });
+  }
+};
+var TranscriptionDisabledError = class extends MetaWhatsAppError {
+  static {
+    __name(this, "TranscriptionDisabledError");
+  }
+  constructor() {
+    super("Transcri\xE7\xE3o de \xE1udio est\xE1 desligada para esta empresa.", 409, META_WHATSAPP_ERROR_CODES.TRANSCRIPTION_DISABLED);
+  }
+};
+var MessageNotAudioError = class extends MetaWhatsAppError {
+  static {
+    __name(this, "MessageNotAudioError");
+  }
+  constructor(messageId, type) {
+    super(`Mensagem ${messageId} \xE9 do tipo "${type}" \u2014 s\xF3 \xE1udio \xE9 transcrito.`, 422, META_WHATSAPP_ERROR_CODES.MESSAGE_NOT_AUDIO, {
+      messageId,
+      type
+    });
+  }
+};
+
+// src/previewMedia.types.ts
+var PREVIEW_MEDIA_ID_PREFIX = "preview-upload:";
+function toPreviewMediaId(uploadId) {
+  return `${PREVIEW_MEDIA_ID_PREFIX}${uploadId}`;
+}
+__name(toPreviewMediaId, "toPreviewMediaId");
+function resolvePreviewUploadId(mediaId) {
+  if (!mediaId.startsWith(PREVIEW_MEDIA_ID_PREFIX)) return void 0;
+  return mediaId.slice(PREVIEW_MEDIA_ID_PREFIX.length) || void 0;
+}
+__name(resolvePreviewUploadId, "resolvePreviewUploadId");
 export {
+  AudioNotIngestedError,
   CROSS_FLOW_PREFIX,
   ConfigMissingError,
   DuplicateWebhookDeliveryError,
   FLOW_ACTION_KIND,
   InvalidWebhookSignatureError,
   META_WHATSAPP_ERROR_CODES,
+  MessageNotAudioError,
   MetaWhatsAppError,
+  PREVIEW_MEDIA_ID_PREFIX,
   SessionNotFoundError,
   TemplateNotConfiguredError,
+  TranscriptionDisabledError,
+  WHATSAPP_CHOICE_LIMIT,
+  WHATSAPP_WEBHOOK_FIELDS,
   WindowExpiredError,
   crossFlowKey,
   flowGraphNodesSchema,
   flowNodeDataSchema,
   flowNodeNextSchema,
   isCrossFlowTarget,
+  resolvePreviewUploadId,
+  toPreviewMediaId,
   whatsAppInteractiveSchema,
   whatsAppMediaSchema,
   whatsAppMessageEchoSchema,
   whatsAppMessageSchema,
   whatsAppMessageStatusSchema,
   whatsAppOrderSchema,
+  whatsAppPhoneNumberQualityUpdateSchema,
+  whatsAppQualityEventSchema,
   whatsAppStatusSchema,
-  whatsAppWebhookPayloadSchema
+  whatsAppTemplateStatusEventSchema,
+  whatsAppTemplateStatusUpdateSchema,
+  whatsAppWebhookChangeSchema,
+  whatsAppWebhookPayloadSchema,
+  whatsAppWebhookValueSchema
 };
 //# sourceMappingURL=index.js.map