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

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { b as WhatsAppMessage, f as WhatsAppStatus } from './webhook.types-PxhpmpzC.cjs';
-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.cjs';
+import { c as WhatsAppMessage, i as WhatsAppStatus, k as WhatsAppTemplateStatusUpdate, g as WhatsAppPhoneNumberQualityUpdate } from './webhook.types-DWaAhvNu.cjs';
+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.cjs';
 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;
@@ -339,142 +340,48 @@ declare const flowGraphNodesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
 }, z.ZodTypeAny, "passthrough">>>;
 
 /**
- * Quando transcrever nota de voz.
+ * Tetos da Meta para escolha interativa.
  *
- * 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.
+ * 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.
  */
-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';
+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;
-    /**
-     * 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;
-}
-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;
+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;
@@ -495,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;
@@ -591,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;
@@ -687,4 +799,4 @@ declare function toPreviewMediaId(uploadId: string): string;
  */
 declare function resolvePreviewUploadId(mediaId: string): string | undefined;
 
-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 SessionMode, SessionNotFoundError, type SessionState, type SubjectResolverInterface, type TemplateConfig, TemplateNotConfiguredError, type TemplateVariablesMap, type TranscriptionDeferredDescriptor, TranscriptionDisabledError, type TranscriptionMode, WhatsAppMessage, type WhatsAppSettings, WhatsAppStatus, type WhatsAppTemplateSummary, WindowExpiredError, crossFlowKey, flowGraphNodesSchema, flowNodeDataSchema, flowNodeNextSchema, isCrossFlowTarget, resolvePreviewUploadId, toPreviewMediaId };
+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 };