feat(email-campaigns): add billing integration for campaign creation (#2685)

* feat(email-campaigns): add billing integration for campaign creation

- Add checkCampaignBilling function to validate credits before campaign
- Support partialCampaign parameter for retry flow
- Use chargedUnits for total_recipients instead of eligibleContacts.length
- Forward 402/266 responses for CreditsDialog handling
- Block campaign if billing enabled but fails (fail closed)

* docs(env): document ENABLE_BILLING configuration

- Add ENABLE_BILLING env variable for optional campaign billing
- Defaults to false for backward compatibility

* feat: add compliance middleware and billing integration

- Add compliance-middleware.ts for consent filtering
- Filters opt_out contacts from campaign requests
- Returns 266 with reason='consent' if consent limits campaign
- Use supabaseAdmin.functions.invoke for billing in try/catch
- Handle 402/266 responses from billing
- Add ComplianceDialog component for consent validation
- Update CampaignComposerDialog for unified error handling

* refactor: move all compliance and billing logic to middleware

- Compliance middleware now handles:
  - Consent filtering (opt_out contacts)
  - Billing check via supabaseAdmin.functions.invoke
  - Returns 266 with reason field for both consent/credits
  - Modifies request body with filtered emails
- Handler simplified: just uses filtered emails
- Frontend: add onResponse handler to show ComplianceDialog or CreditsDialog
- Add ComplianceDialog component to template

* feat: refactor campaign billing flow with proper middleware chain

- Split compliance into campaignCheck and campaignBill middleware
- Use /quota before creation, /charge after creation
- Fix table reference (persons -> refinedpersons)
- Add CreditsDialog integration for 402/266 responses
- Add plural i18n support in ComplianceDialog
- Keep dialog open for partial campaign flows
- Add await next() in controller chain
- Add unit tests for middleware

* chore: remove local plans from repo and add to gitignore

* refactor: add campaign billing middleware chain and CreditsDialog integration

* fix: resolve deepsource issues in test files and index.ts

* fix: add skipcq for unused getCurrentUtcDayStart function

* rename to ENABLE_CREDIT for consistency

Author: malek10xdev

.gitignore

@@ -20,3 +20,4 @@ backend/config/default.yml
 supabase/config.toml
 frontend-v4/*
 .worktrees/
+.opencode/plans/

frontend/src/components/campaigns/CampaignComposerDialog.vue

@@ -334,19 +334,35 @@
             :label="t('send_campaign')"
             :loading="isSubmitting"
             :disabled="isActionDisabled"
-            @click="submit"
+            @click="submit(false)"
           />
         </div>
       </div>
     </template>
   </Dialog>
+
+  <ComplianceDialog ref="complianceDialogRef" @confirm-partial="submit(true)" />
+
+  <component
+    :is="CreditsDialog"
+    ref="CreditsDialogCampaignRef"
+    engagement-type="contact"
+    action-type="campaign"
+    @secondary-action="submit(true)"
+  />
 </template>
 
 <script setup lang="ts">
 import type { Contact } from '@/types/contact';
 import { extractUnavailableSenderEmails } from '@/utils/senderOptions';
 import { updateMiningSourcesValidityFromUnavailable } from '@/utils/sources';
 import Editor from 'primevue/editor';
+import ComplianceDialog from './ComplianceDialog.vue';
+import {
+  CreditsDialog,
+  CreditsDialogCampaignRef,
+  openCreditsDialog,
+} from '@/utils/credits';
 
 const isVisible = defineModel<boolean>('visible', { required: true });
 
@@ -402,6 +418,9 @@ type SenderOptionItem = {
 const senderOptions = ref<SenderOptionItem[]>([]);
 const fallbackSenderEmail = ref('');
 const runtimeConfig = useRuntimeConfig();
+const complianceDialogRef = ref<InstanceType<typeof ComplianceDialog> | null>(
+  null,
+);
 
 const DEFAULT_PROJECT_URL = 'https://example.com/project';
 const DEFAULT_PROJECT_IMAGE_SRC =
@@ -623,7 +642,6 @@ const editorModules = computed(() => ({
 }));
 
 type AttributeTarget = 'subject' | 'body';
-
 const activeAttributeTarget = ref<AttributeTarget>('body');
 
 const attributeMenuItems = computed(() =>
@@ -1046,7 +1064,7 @@ async function sendPreview() {
   }
 }
 
-async function submit() {
+async function submit(partialCampaign = false) {
   if (!ensureValidForm()) {
     return;
   }
@@ -1056,6 +1074,9 @@ async function submit() {
   }
 
   isSubmitting.value = true;
+  let shouldCloseDialog = true;
+  let showErrorToast = true;
+
   try {
     const data = await $saasEdgeFunctions('email-campaigns/campaigns/create', {
       method: 'POST',
@@ -1073,42 +1094,89 @@ async function submit() {
         trackClick: form.trackClick,
         plainTextOnly: form.plainTextOnly,
         onlyValidContacts: form.onlyValidContacts,
+        partialCampaign,
+      },
+      onResponse: ({ response }) => {
+        if (response.status === 402) {
+          openCreditsDialog(
+            CreditsDialogCampaignRef,
+            true,
+            response._data.total,
+            response._data.available,
+            response._data.availableAlready,
+          );
+          shouldCloseDialog = false;
+          showErrorToast = false;
+          return;
+        }
+
+        if (response.status === 266 && response._data?.reason === 'credits') {
+          openCreditsDialog(
+            CreditsDialogCampaignRef,
+            false,
+            response._data.total,
+            response._data.available,
+            response._data.availableAlready,
+          );
+          shouldCloseDialog = false;
+          showErrorToast = false;
+          return;
+        }
+
+        if (response.status === 266 && response._data?.reason === 'consent') {
+          complianceDialogRef.value?.openModal(
+            response._data.total,
+            response._data.available,
+          );
+          shouldCloseDialog = false;
+          showErrorToast = false;
+          return;
+        }
+
+        if (response.status === 200) {
+          return;
+        }
+
+        throw new Error(response._data?.error || 'Campaign creation failed');
       },
     });
 
-    $toast.add({
-      group: 'has-links',
-      severity: 'success',
-      summary: t('campaign_started'),
-      detail: {
-        message: t('campaign_started_detail'),
-        button: {
-          text: t('see_campaigns'),
-          action: () => navigateTo('/campaigns'),
+    if (shouldCloseDialog) {
+      $toast.add({
+        severity: 'success',
+        summary: t('campaign_started'),
+        detail: {
+          message: t('campaign_started_detail'),
+          button: {
+            text: t('see_campaigns'),
+            action: () => navigateTo('/campaigns'),
+          },
         },
-      },
-      life: 6000,
-    });
+        life: 6000,
+      });
 
-    if (data?.campaignId) {
-      startCampaignCompletionWatcher(data.campaignId);
-    }
+      if (data?.campaignId) {
+        startCampaignCompletionWatcher(data.campaignId);
+      }
 
-    isVisible.value = false;
-  } catch (error: unknown) {
-    const parsedError = error as EdgeResponseError;
-    const code = parsedError?.data?.code;
-    if (code === 'SENDER_SMTP_FAILED' && fallbackSenderEmail.value) {
-      form.senderEmail =
-        parsedError?.data?.fallbackSenderEmail || fallbackSenderEmail.value;
+      isVisible.value = false;
     }
+  } catch (error: unknown) {
+    if (showErrorToast) {
+      const parsedError = error as EdgeResponseError;
+      const code = parsedError?.data?.code;
+      if (code === 'SENDER_SMTP_FAILED' && fallbackSenderEmail.value) {
+        form.senderEmail =
+          parsedError?.data?.fallbackSenderEmail || fallbackSenderEmail.value;
+      }
 
-    $toast.add({
-      severity: 'error',
-      summary: t('campaign_start_failed'),
-      detail: resolveErrorMessage(error, 'error_campaign_start_failed'),
-      life: 5000,
-    });
+      $toast.add({
+        severity: 'error',
+        summary: t('campaign_start_failed'),
+        detail: resolveErrorMessage(error, 'error_campaign_start_failed'),
+        life: 5000,
+      });
+    }
   } finally {
     isSubmitting.value = false;
   }

frontend/src/components/campaigns/ComplianceDialog.vue

@@ -0,0 +1,79 @@
+<template>
+  <Dialog v-model:visible="showModal" modal :header="t('consent_required')">
+    <p class="m-0">
+      {{ t('consent_message', { available, total: t('contact', total) }) }}
+    </p>
+    <template #footer>
+      <div class="flex justify-end gap-2">
+        <Button :label="t('privacy_policy')" link @click="openPrivacyPolicy" />
+        <Button :label="t('cancel')" severity="secondary" @click="closeModal" />
+        <Button
+          :label="
+            t('continue_with_available', { count: t('contact', available) })
+          "
+          severity="contrast"
+          @click="confirmPartial"
+        />
+      </div>
+    </template>
+  </Dialog>
+</template>
+
+<script setup lang="ts">
+const { t } = useI18n({
+  useScope: 'local',
+});
+
+const emit = defineEmits<{
+  'confirm-partial': [];
+}>();
+
+const showModal = ref(false);
+const total = ref(0);
+const available = ref(0);
+
+const openModal = (totalCount: number, availableCount: number) => {
+  total.value = totalCount;
+  available.value = availableCount;
+  showModal.value = true;
+};
+
+const closeModal = () => {
+  showModal.value = false;
+};
+
+const openPrivacyPolicy = () => {
+  window.open('/privacy-policy', '_blank');
+};
+
+const confirmPartial = () => {
+  emit('confirm-partial');
+  closeModal();
+};
+
+defineExpose({
+  openModal,
+  closeModal,
+});
+</script>
+
+<i18n lang="json">
+{
+  "en": {
+    "consent_required": "Consent Required",
+    "consent_message": "Only {available} of {total} have given consent to be contacted.",
+    "contact": "contact | contacts",
+    "privacy_policy": "Privacy Policy",
+    "cancel": "Cancel",
+    "continue_with_available": "Continue with {count}"
+  },
+  "fr": {
+    "consent_required": "Consentement Requis",
+    "consent_message": "Seulement {available} sur {total} ont donné leur consentement.",
+    "contact": "contact | contacts",
+    "privacy_policy": "Politique de Confidentialité",
+    "cancel": "Annuler",
+    "continue_with_available": "Continuer avec {count}"
+  }
+}
+</i18n>

frontend/src/utils/credits.ts

@@ -2,6 +2,7 @@ export const CreditsCounter = null;
 export const CreditsDialog = null;
 export const CreditsDialogEnrichRef = ref();
 export const CreditsDialogExportRef = ref();
+export const CreditsDialogCampaignRef = ref();
 // skipcq: JS-0356
 export const openCreditsDialog = (
   _ref: Ref<unknown>,

supabase/functions/.env.dev

@@ -17,4 +17,4 @@ SERVER_ENDPOINT =  http://localhost:8081    # ( REQUIRED ) URL of the Backend se
 GOOGLE_CLIENT_ID = your_azure_client_id   # ( REQUIRED ) Google client ID
 GOOGLE_SECRET = your_azure_client_id      # ( REQUIRED ) Google secret
 AZURE_CLIENT_ID = your_azure_client_id                  # ( REQUIRED ) Azure client ID
-AZURE_SECRET = your_azure_client_secret                 # ( REQUIRED ) Azure secret
+AZURE_SECRET = your_azure_client_secret                 # ( REQUIRED ) Azure secret

supabase/functions/email-campaigns/campaign-bill-middleware.ts

@@ -0,0 +1,76 @@
+import { Context, Next } from "hono";
+import { createSupabaseAdmin } from "../_shared/supabase.ts";
+import { createLogger } from "../_shared/logger.ts";
+
+const logger = createLogger("email-campaigns:bill");
+
+export async function campaignBillMiddleware(c: Context, next: Next) {
+  if (!c.req.path.endsWith("/campaigns/create")) {
+    return next();
+  }
+
+  const billingEnabled = Deno.env.get("ENABLE_CREDIT") === "true";
+
+  const campaignData = c.get("campaignCreate");
+  if (!campaignData) {
+    logger.error("No campaign data in context");
+    return c.json(
+      { error: "Campaign creation data missing", code: "INTERNAL_ERROR" },
+      500,
+    );
+  }
+
+  const { campaignId, createdCount, userId } = campaignData;
+
+  if (!billingEnabled) {
+    return c.json({
+      msg: "Campaign queued",
+      campaignId,
+      queuedCount: createdCount,
+    });
+  }
+
+  try {
+    const supabaseAdmin = createSupabaseAdmin();
+
+    const { data, error } = await supabaseAdmin.functions.invoke(
+      "billing/campaign/charge",
+      {
+        body: {
+          userId,
+          units: createdCount,
+          partialCampaign: false,
+        },
+      },
+    );
+
+    if (error) {
+      logger.error("Billing charge failed", {
+        error: error.message,
+        userId,
+        campaignId,
+        createdCount,
+      });
+    } else {
+      logger.info("Billing charge successful", {
+        userId,
+        campaignId,
+        createdCount,
+        chargedUnits: data?.payload?.chargedUnits,
+      });
+    }
+
+    return c.json({
+      msg: "Campaign queued",
+      campaignId,
+      queuedCount: createdCount,
+    });
+  } catch (error) {
+    logger.error("Billing charge exception", { error, userId, campaignId });
+    return c.json({
+      msg: "Campaign queued",
+      campaignId,
+      queuedCount: createdCount,
+    });
+  }
+}