CRM WhatsApp Grupo 3 completo + Marco A/B (Asaas) + admin SaaS + refactors polimórficos

Sessão 11+: fechamento do CRM de WhatsApp com dois providers (Evolution/Twilio), sistema de créditos com Asaas/PIX, polimorfismo de telefones/emails, e integração admin SaaS no /saas/addons existente. ═══════════════════════════════════════════════════════════════════════════ GRUPO 3 — WORKFLOW / CRM (completo) ═══════════════════════════════════════════════════════════════════════════ 3.1 Tags · migration conversation_tags + seed de 5 system tags · composable useConversationTags.js · popover + pills no drawer e nos cards do Kanban. 3.2 Atribuição de conversa a terapeuta · migration 20260421000012 com PK (tenant_id, thread_key), UPSERT, RLS que valida assignee como membro ativo do mesmo tenant · view conversation_threads expandida com assigned_to + assigned_at · composable useConversationAssignment.js · drawer com Select filtrável + botão "Assumir" · inbox com filtro aside (Todas/Minhas/Não atribuídas) e chip do responsável em cada card (destaca "Eu" em azul). 3.3 Notas internas · migration conversation_notes · composable + seção colapsável no drawer · apenas o criador pode editar/apagar (RLS). 3.5 Converter desconhecido em paciente · botão + dialog quick-cadastro · "Vincular existente" com Select filter de até 500 pacientes · cria telefone WhatsApp (vinculado) via upsertWhatsappForExisting. 3.6 Histórico de conversa no prontuário · nova aba "Conversas" em PatientProntuario.vue · PatientConversationsTab.vue com stats (total / recebidas / enviadas / primeira / última), SelectButton de filtro, timeline com bolhas por direção, mídia inline (imagem/áudio/vídeo/doc via signed URL), indicadores ✓ ✓✓ de delivery, botão "Abrir no CRM". ═══════════════════════════════════════════════════════════════════════════ MARCO A — UNIFICAÇÃO WHATSAPP (dois providers mutuamente exclusivos) ═══════════════════════════════════════════════════════════════════════════ - Página chooser ConfiguracoesWhatsappChooserPage.vue com 2 cards (Pessoal/ Oficial), deactivate via edge function deactivate-notification-channel - send-whatsapp-message refatorada com roteamento por provider; Twilio deduz 1 crédito antes do envio e refunda em falha - Paridade Twilio (novo): módulo compartilhado supabase/functions/_shared/ whatsapp-hooks.ts com lógica provider-agnóstica (opt-in, opt-out, auto- reply, schedule helpers em TZ São Paulo, makeTwilioCreditedSendFn que envolve envio em dedução atômica + rollback). Consumido por Evolution E Twilio inbound. Evolution refatorado (~290 linhas duplicadas removidas). - Bucket privado whatsapp-media · decrypt via Evolution getBase64From MediaMessage · upload com path tenant/yyyy/mm · signed URLs on-demand ═══════════════════════════════════════════════════════════════════════════ MARCO B — SISTEMA DE CRÉDITOS WHATSAPP + ASAAS ═══════════════════════════════════════════════════════════════════════════ Banco: - Migration 20260421000007_whatsapp_credits (4 tabelas: balance, transactions, packages, purchases) + RPCs add_whatsapp_credits e deduct_whatsapp_credits (atômicas com SELECT FOR UPDATE) - Migration 20260421000013_tenant_cpf_cnpj (coluna em tenants com CHECK de 11 ou 14 dígitos) Edge functions: - create-whatsapp-credit-charge · Asaas v3 (sandbox + prod) · PIX com QR code · getOrCreateAsaasCustomer patcha customer existente com CPF quando está faltando - asaas-webhook · recebe PAYMENT_RECEIVED/CONFIRMED e credita balance Frontend (tenant): - Página /configuracoes/creditos-whatsapp com saldo + loja + histórico - Dialog de confirmação com CPF/CNPJ (validação via isValidCPF/CNPJ de utils/validators, formatação on-blur, pré-fill de tenants.cpf_cnpj, persiste no primeiro uso) · fallback sandbox 24971563792 REMOVIDO - Composable useWhatsappCredits extrai erros amigáveis via error.context.json() Frontend (SaaS admin): - Em /saas/addons (reuso do pattern existente, não criou página paralela): - Aba 4 "Pacotes WhatsApp" — CRUD whatsapp_credit_packages com DataTable, toggle is_active inline, dialog de edição com validação - Aba 5 "Topup WhatsApp" — tenant Select com saldo ao vivo · RPC add_whatsapp_credits com p_admin_id = auth.uid() (auditoria) · histórico das últimas 20 transações topup/adjustment/refund ═══════════════════════════════════════════════════════════════════════════ GRUPO 2 — AUTOMAÇÃO ═══════════════════════════════════════════════════════════════════════════ 2.3 Auto-reply · conversation_autoreply_settings + conversation_autoreply_ log · 3 modos de schedule (agenda das regras semanais, business_hours custom, custom_window) · cooldown por thread · respeita opt-out · agora funciona em Evolution E Twilio (hooks compartilhados) 2.4 Lembretes de sessão · conversation_session_reminders_settings + _logs · edge send-session-reminders (cron) · janelas 24h e 2h antes · Twilio deduz crédito com rollback em falha ═══════════════════════════════════════════════════════════════════════════ GRUPO 5 — COMPLIANCE (LGPD Art. 18 §2) ═══════════════════════════════════════════════════════════════════════════ 5.2 Opt-out · conversation_optouts + conversation_optout_keywords (10 system seed + custom por tenant) · detecção por regex word-boundary e normalização (lowercase + strip acentos + pontuação) · ack automático (deduz crédito em Twilio) · opt-in via "voltar", "retornar", "reativar", "restart" · página /configuracoes/conversas-optouts com CRUD de keywords ═══════════════════════════════════════════════════════════════════════════ REFACTOR POLIMÓRFICO — TELEFONES + EMAILS ═══════════════════════════════════════════════════════════════════════════ - contact_types + contact_phones (entity_type + entity_id) — migration 20260421000008 · contact_email_types + contact_emails — 20260421000011 - Componentes ContactPhonesEditor.vue e ContactEmailsEditor.vue (add/edit/ remove com confirm, primary selector, WhatsApp linked badge) - Composables useContactPhones.js + useContactEmails.js com unsetOtherPrimaries() e validação - Trocado em PatientsCadastroPage.vue e MedicosPage.vue (removidos campos legados telefone/telefone_alternativo e email_principal/email_alternativo) - Migration retroativa v2 (20260421000010) detecta conversation_messages e cria/atualiza phone como WhatsApp vinculado ═══════════════════════════════════════════════════════════════════════════ POLIMENTO VISUAL + INFRA ═══════════════════════════════════════════════════════════════════════════ - Skeletons simplificados no dashboard do terapeuta - Animações fade-up com stagger via [--delay:Xms] (fix specificity sobre .dash-card box-shadow transition) - ConfirmDialog com group="conversation-drawer" (evita montagem duplicada) - Image preview PrimeVue com botão de download injetado via MutationObserver (fetch + blob para funcionar cross-origin) - Áudio/vídeo com preload="metadata" e controles de velocidade do browser - friendlySendError() mapeia códigos do edge pra mensagens pt-BR via error.context.json() - Teleport #cfg-page-actions para ações globais de Configurações - Brotli/Gzip + auto-import Vue/PrimeVue + bundle analyzer - AppLayout consolidado (removidas duplicatas por área) + RouterPassthrough - Removido console.trace debug que estava em watch de router e queries Supabase (degradava perf pra todos) - Realtime em conversation_messages via publication supabase_realtime - Notifier global flutuante com beep + toggle mute (4 camadas: badge + sino + popup + browser notification) ═══════════════════════════════════════════════════════════════════════════ MIGRATIONS NOVAS (13) ═══════════════════════════════════════════════════════════════════════════ 20260420000001_patient_intake_invite_info_rpc 20260420000002_audit_logs_lgpd 20260420000003_audit_logs_unified_view 20260420000004_lgpd_export_patient_rpc 20260420000005_conversation_messages 20260420000005_search_global_rpc 20260420000006_conv_messages_notifications 20260420000007_notif_channels_saas_admin_insert 20260420000008_conv_messages_realtime 20260420000009_conv_messages_delivery_status 20260421000001_whatsapp_media_bucket 20260421000002_conversation_notes 20260421000003_conversation_tags 20260421000004_conversation_autoreply 20260421000005_conversation_optouts 20260421000006_session_reminders 20260421000007_whatsapp_credits 20260421000008_contact_phones 20260421000009_retroactive_whatsapp_link 20260421000010_retroactive_whatsapp_link_v2 20260421000011_contact_emails 20260421000012_conversation_assignments 20260421000013_tenant_cpf_cnpj ═══════════════════════════════════════════════════════════════════════════ EDGE FUNCTIONS NOVAS / MODIFICADAS ═══════════════════════════════════════════════════════════════════════════ Novas: - _shared/whatsapp-hooks.ts (módulo compartilhado) - asaas-webhook - create-whatsapp-credit-charge - deactivate-notification-channel - evolution-webhook-provision - evolution-whatsapp-inbound - get-intake-invite-info - notification-webhook - send-session-reminders - send-whatsapp-message - submit-patient-intake - twilio-whatsapp-inbound ═══════════════════════════════════════════════════════════════════════════ FRONTEND — RESUMO ═══════════════════════════════════════════════════════════════════════════ Composables novos: useAddonExtrato, useAuditoria, useAutoReplySettings, useClinicKPIs, useContactEmails, useContactPhones, useConversationAssignment, useConversationNotes, useConversationOptouts, useConversationTags, useConversations, useLgpdExport, useSessionReminders, useWhatsappCredits Stores: conversationDrawerStore Componentes novos: ConversationDrawer, GlobalInboundNotifier, GlobalSearch, ContactEmailsEditor, ContactPhonesEditor Páginas novas: CRMConversasPage, PatientConversationsTab, AddonsExtratoPage, AuditoriaPage, NotificationsHistoryPage, ConfiguracoesWhatsappChooserPage, ConfiguracoesConversasAutoreplyPage, ConfiguracoesConversasOptoutsPage, ConfiguracoesConversasTagsPage, ConfiguracoesCreditosWhatsappPage, ConfiguracoesLembretesSessaoPage Utils novos: addonExtratoExport, auditoriaExport, excelExport, lgpdExportFormats Páginas existentes alteradas: ClinicDashboard, PatientsCadastroPage, PatientCadastroDialog, PatientsListPage, MedicosPage, PatientProntuario, ConfiguracoesWhatsappPage, SaasWhatsappPage, ConfiguracoesRecursosExtrasPage, ConfiguracoesPage, AgendaTerapeutaPage, AgendaClinicaPage, NotificationItem, NotificationDrawer, AppLayout, AppTopbar, useMenuBadges, patientsRepository, SaasAddonsPage (aba 4 + 5 WhatsApp) Routes: routes.clinic, routes.configs, routes.therapist atualizados Menus: clinic.menu, therapist.menu, saas.menu atualizados ═══════════════════════════════════════════════════════════════════════════ NOTAS - Após subir, rodar supabase functions serve --no-verify-jwt --env-file supabase/functions/.env pra carregar o módulo _shared - WHATSAPP_SETUP.md reescrito (~400 linhas) com setup completo dos 3 providers + troubleshooting + LGPD - HANDOFF.md atualizado com estado atual e próximos passos Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 07:05:24 -03:00
parent 037ba3721f
commit 2644e60bb6
191 changed files with 38629 additions and 3756 deletions
@@ -0,0 +1,371 @@
+/*
+|--------------------------------------------------------------------------
+| Agência PSI — Shared hooks: WhatsApp opt-out + auto-reply
+|--------------------------------------------------------------------------
+| Logica provider-agnostica compartilhada entre evolution-whatsapp-inbound
+| e twilio-whatsapp-inbound. Cada provider injeta seu proprio SendFn —
+| Evolution envia direto via API (sem deducao de credito), Twilio envolve
+| o envio em deducao atomica com rollback.
+|--------------------------------------------------------------------------
+*/
+
+import type { SupabaseClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+// Provider deve prover uma funcao de envio de texto puro
+export type SendFn = (phone: string, text: string) => Promise<{ ok: boolean; messageId?: string | null; error?: string }>
+
+export type ProviderLabel = 'evolution' | 'twilio'
+
+export function buildThreadKey(patientId: string | null, phone: string | null): string {
+    if (patientId) return patientId
+    return `anon:${phone ?? 'unknown'}`
+}
+
+export function normalizeForMatch(s: string | null | undefined): string {
+    return String(s ?? '')
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^\p{L}\p{N}\s]/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Opt-out (LGPD)
+// ═══════════════════════════════════════════════════════════════════════
+
+export async function detectOptoutKeyword(
+    supa: SupabaseClient,
+    tenantId: string,
+    body: string | null
+): Promise<string | null> {
+    if (!body) return null
+    const normalized = normalizeForMatch(body)
+    if (!normalized) return null
+
+    const { data } = await supa
+        .from('conversation_optout_keywords')
+        .select('keyword')
+        .or(`tenant_id.is.null,tenant_id.eq.${tenantId}`)
+        .eq('enabled', true)
+
+    if (!data || !data.length) return null
+
+    for (const row of data) {
+        const kw = normalizeForMatch(row.keyword)
+        if (!kw) continue
+        if (normalized === kw) return row.keyword
+        const pattern = new RegExp(`(^|\\s)${kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\s|$)`)
+        if (pattern.test(normalized)) return row.keyword
+    }
+    return null
+}
+
+export async function isOptedOut(supa: SupabaseClient, tenantId: string, phone: string): Promise<boolean> {
+    const { data } = await supa
+        .from('conversation_optouts')
+        .select('id')
+        .eq('tenant_id', tenantId)
+        .eq('phone', phone)
+        .is('opted_back_in_at', null)
+        .limit(1)
+        .maybeSingle()
+    return !!data
+}
+
+const OPT_IN_KEYWORDS = ['voltar', 'retornar', 'reativar', 'restart']
+export async function maybeOptIn(
+    supa: SupabaseClient,
+    tenantId: string,
+    phone: string,
+    body: string | null
+): Promise<boolean> {
+    if (!body) return false
+    const normalized = normalizeForMatch(body)
+    if (!normalized) return false
+    for (const kw of OPT_IN_KEYWORDS) {
+        if (normalized === kw || new RegExp(`(^|\\s)${kw}(\\s|$)`).test(normalized)) {
+            const { data } = await supa
+                .from('conversation_optouts')
+                .update({ opted_back_in_at: new Date().toISOString() })
+                .eq('tenant_id', tenantId)
+                .eq('phone', phone)
+                .is('opted_back_in_at', null)
+                .select('id')
+                .maybeSingle()
+            return !!data
+        }
+    }
+    return false
+}
+
+export async function registerOptout(
+    supa: SupabaseClient,
+    tenantId: string,
+    phone: string,
+    patientId: string | null,
+    originalMessage: string | null,
+    keywordMatched: string,
+    provider: ProviderLabel,
+    sendFn: SendFn
+): Promise<void> {
+    const { data: existing } = await supa
+        .from('conversation_optouts')
+        .select('id')
+        .eq('tenant_id', tenantId)
+        .eq('phone', phone)
+        .is('opted_back_in_at', null)
+        .maybeSingle()
+
+    if (existing) return
+
+    await supa.from('conversation_optouts').insert({
+        tenant_id: tenantId,
+        phone,
+        patient_id: patientId,
+        source: 'keyword',
+        keyword_matched: keywordMatched,
+        original_message: (originalMessage || '').slice(0, 500)
+    })
+
+    const ackText = 'OK! Não enviaremos mais mensagens automáticas. Você ainda pode falar com seu terapeuta diretamente quando quiser. Para voltar a receber, envie VOLTAR.'
+    try {
+        const res = await sendFn(phone, ackText)
+        if (res.ok) {
+            await supa.from('conversation_messages').insert({
+                tenant_id: tenantId,
+                patient_id: patientId,
+                channel: 'whatsapp',
+                direction: 'outbound',
+                from_number: null,
+                to_number: phone,
+                body: ackText,
+                provider,
+                provider_message_id: res.messageId ?? null,
+                provider_raw: { optout_ack: true },
+                kanban_status: 'resolved',
+                responded_at: new Date().toISOString()
+            })
+        } else {
+            console.error('[optout] ack send failed:', res.error)
+        }
+    } catch (err) {
+        console.error('[optout] ack send error:', err)
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Auto-reply (schedule-aware, cooldown, respeita opt-out)
+// ═══════════════════════════════════════════════════════════════════════
+
+export type ScheduleWindow = { dow: number; start: string; end: string }
+
+function hhmmToMinutes(s: string): number {
+    const m = String(s).match(/^(\d{1,2}):(\d{2})/)
+    if (!m) return -1
+    return parseInt(m[1], 10) * 60 + parseInt(m[2], 10)
+}
+
+function nowInSaoPaulo(): { dow: number; minutes: number } {
+    const now = new Date()
+    const fmt = new Intl.DateTimeFormat('en-US', {
+        timeZone: 'America/Sao_Paulo',
+        weekday: 'short',
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: false
+    })
+    const parts = fmt.formatToParts(now)
+    const weekday = parts.find((p) => p.type === 'weekday')?.value || 'Sun'
+    const hour = parseInt(parts.find((p) => p.type === 'hour')?.value || '0', 10)
+    const minute = parseInt(parts.find((p) => p.type === 'minute')?.value || '0', 10)
+    const dowMap: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 }
+    return { dow: dowMap[weekday] ?? 0, minutes: hour * 60 + minute }
+}
+
+function isWithinWindows(windows: ScheduleWindow[]): boolean {
+    if (!Array.isArray(windows) || !windows.length) return false
+    const { dow, minutes } = nowInSaoPaulo()
+    for (const w of windows) {
+        if (w.dow !== dow) continue
+        const start = hhmmToMinutes(w.start)
+        const end = hhmmToMinutes(w.end)
+        if (start < 0 || end < 0) continue
+        if (minutes >= start && minutes < end) return true
+    }
+    return false
+}
+
+async function windowsFromAgenda(supa: SupabaseClient, tenantId: string): Promise<ScheduleWindow[]> {
+    const { data, error } = await supa
+        .from('agenda_regras_semanais')
+        .select('dia_semana, hora_inicio, hora_fim, ativo')
+        .eq('tenant_id', tenantId)
+        .eq('ativo', true)
+    if (error || !data) return []
+    return data.map((r) => ({
+        dow: r.dia_semana,
+        start: String(r.hora_inicio).slice(0, 5),
+        end: String(r.hora_fim).slice(0, 5)
+    }))
+}
+
+export async function maybeSendAutoReply(
+    supa: SupabaseClient,
+    tenantId: string,
+    threadKey: string,
+    fromPhone: string | null,
+    provider: ProviderLabel,
+    sendFn: SendFn
+): Promise<{ sent: boolean; reason?: string }> {
+    if (!fromPhone) return { sent: false, reason: 'no_phone' }
+
+    if (await isOptedOut(supa, tenantId, fromPhone)) {
+        return { sent: false, reason: 'opted_out' }
+    }
+
+    const { data: settings } = await supa
+        .from('conversation_autoreply_settings')
+        .select('enabled, message, cooldown_minutes, schedule_mode, business_hours, custom_window')
+        .eq('tenant_id', tenantId)
+        .maybeSingle()
+
+    if (!settings || !settings.enabled) return { sent: false, reason: 'disabled' }
+
+    let withinHours = false
+    if (settings.schedule_mode === 'agenda') {
+        const windows = await windowsFromAgenda(supa, tenantId)
+        withinHours = isWithinWindows(windows)
+    } else if (settings.schedule_mode === 'business_hours') {
+        withinHours = isWithinWindows((settings.business_hours as ScheduleWindow[]) || [])
+    } else if (settings.schedule_mode === 'custom') {
+        withinHours = isWithinWindows((settings.custom_window as ScheduleWindow[]) || [])
+    }
+
+    if (withinHours) return { sent: false, reason: 'within_hours' }
+
+    if ((settings.cooldown_minutes ?? 0) > 0) {
+        const cutoff = new Date(Date.now() - settings.cooldown_minutes * 60 * 1000).toISOString()
+        const { data: recent } = await supa
+            .from('conversation_autoreply_log')
+            .select('sent_at')
+            .eq('tenant_id', tenantId)
+            .eq('thread_key', threadKey)
+            .gte('sent_at', cutoff)
+            .order('sent_at', { ascending: false })
+            .limit(1)
+            .maybeSingle()
+        if (recent) return { sent: false, reason: 'cooldown' }
+    }
+
+    const sendRes = await sendFn(fromPhone, settings.message)
+    if (!sendRes.ok) {
+        console.error('[auto-reply] send failed:', sendRes.error)
+        return { sent: false, reason: 'send_failed' }
+    }
+
+    await supa.from('conversation_messages').insert({
+        tenant_id: tenantId,
+        channel: 'whatsapp',
+        direction: 'outbound',
+        from_number: null,
+        to_number: fromPhone,
+        body: settings.message,
+        provider,
+        provider_message_id: sendRes.messageId ?? null,
+        provider_raw: { auto_reply: true },
+        kanban_status: 'awaiting_patient',
+        responded_at: new Date().toISOString()
+    })
+
+    await supa.from('conversation_autoreply_log').insert({
+        tenant_id: tenantId,
+        thread_key: threadKey
+    })
+
+    return { sent: true }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Twilio: send wrapper com deducao de credito + rollback
+// ═══════════════════════════════════════════════════════════════════════
+
+export type TwilioChannel = {
+    twilio_subaccount_sid: string
+    twilio_phone_number: string
+    credentials: { subaccount_auth_token?: string }
+}
+
+async function sendViaTwilioRaw(
+    channel: TwilioChannel,
+    toPhone: string,
+    text: string
+): Promise<{ ok: boolean; messageId?: string; error?: string }> {
+    const subSid = channel.twilio_subaccount_sid
+    const authToken = channel.credentials?.subaccount_auth_token
+    const fromNumber = channel.twilio_phone_number
+    if (!subSid || !authToken || !fromNumber) {
+        return { ok: false, error: 'Twilio credenciais incompletas' }
+    }
+    const endpoint = `https://api.twilio.com/2010-04-01/Accounts/${subSid}/Messages.json`
+    const basicAuth = btoa(`${subSid}:${authToken}`)
+    const toE164 = toPhone.startsWith('+') ? toPhone : `+${toPhone}`
+    const params = new URLSearchParams()
+    params.append('From', `whatsapp:${fromNumber}`)
+    params.append('To', `whatsapp:${toE164}`)
+    params.append('Body', text)
+
+    try {
+        const resp = await fetch(endpoint, {
+            method: 'POST',
+            headers: { Authorization: `Basic ${basicAuth}`, 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: params.toString()
+        })
+        const data = await resp.json().catch(() => null) as Record<string, unknown> | null
+        if (!resp.ok) {
+            return { ok: false, error: `Twilio ${resp.status}: ${(data?.message as string) || ''}` }
+        }
+        return { ok: true, messageId: String(data?.sid || '') }
+    } catch (e) {
+        return { ok: false, error: String(e) }
+    }
+}
+
+// Cria SendFn que:
+// 1) deduz 1 credito do tenant via RPC atomica
+// 2) envia via Twilio; se falhar, refunda o credito
+// 3) retorna resultado ao caller
+export function makeTwilioCreditedSendFn(
+    supa: SupabaseClient,
+    tenantId: string,
+    channel: TwilioChannel,
+    noteLabel: string
+): SendFn {
+    return async (phone: string, text: string) => {
+        const { error: dedErr } = await supa.rpc('deduct_whatsapp_credits', {
+            p_tenant_id: tenantId,
+            p_amount: 1,
+            p_conversation_message_id: null,
+            p_note: noteLabel
+        })
+        if (dedErr) {
+            const insufficient = String(dedErr.message || '').includes('insufficient_credits')
+            return { ok: false, error: insufficient ? 'insufficient_credits' : dedErr.message }
+        }
+
+        const sendRes = await sendViaTwilioRaw(channel, phone, text)
+        if (!sendRes.ok) {
+            await supa.rpc('add_whatsapp_credits', {
+                p_tenant_id: tenantId,
+                p_amount: 1,
+                p_kind: 'refund',
+                p_purchase_id: null,
+                p_admin_id: null,
+                p_note: `Refund ${noteLabel}: ${(sendRes.error || '').slice(0, 180)}`
+            })
+            return { ok: false, error: sendRes.error }
+        }
+        return { ok: true, messageId: sendRes.messageId ?? null }
+    }
+}