Phase7: Void/Refund logic

2026-05-25 21:54:51 +02:00
parent 9cd9879a18
commit e15a668f8e
19 changed files with 2679 additions and 41 deletions
--- a/src/lib/email.ts
+++ b/src/lib/email.ts
@@ -1158,3 +1158,156 @@ export async function sendInvoiceReminderEmail(params: {
    );
  }
 }
+
+// ---------------------------------------------------------------------------
+// Credit note emails — Phase 7
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a credit-note notification to the customer's billing email.
+ *
+ * Covers both kinds (void and refund). The subject and body adapt
+ * based on `kind` — voids ("we've cancelled invoice X, no payment
+ * needed") read very differently from refunds ("we've refunded CHF
+ * X, expect to see it on your card statement within 5-10 days").
+ *
+ * Link-only — the PDF is not attached. The customer downloads it
+ * from /api/credit-notes/<number>/pdf when they click through, which
+ * also gives them a permanent in-portal record next to their
+ * invoices. Same approach as invoice emails.
+ *
+ * Best-effort: failures are logged and swallowed. A mail-server
+ * hiccup must never roll back a credit-note issuance.
+ */
+export async function sendCreditNoteEmail(params: {
+  to: string;
+  contactName: string;
+  companyName: string;
+  creditNoteNumber: string;
+  invoiceNumber: string;
+  amountChf: number;
+  currency: string;
+  kind: "void" | "refund";
+  reason: string | null;
+  locale: "de" | "en" | "fr" | "it";
+}): Promise<void> {
+  const L = params.locale;
+  const totalFmt = `${params.currency} ${params.amountChf.toFixed(2)}`;
+  const link = `https://app.pieced.ch/billing/cn/${encodeURIComponent(
+    params.creditNoteNumber
+  )}`;
+
+  // Subject lines diverge between void and refund — different
+  // mental models for the recipient. Void: "your charge is
+  // cancelled". Refund: "your money is on the way back".
+  const subjectsByLocale: Record<typeof L, { void: string; refund: string }> = {
+    en: {
+      void: `Invoice ${params.invoiceNumber} cancelled — credit note ${params.creditNoteNumber}`,
+      refund: `Refund of ${totalFmt} for invoice ${params.invoiceNumber} — credit note ${params.creditNoteNumber}`,
+    },
+    de: {
+      void: `Rechnung ${params.invoiceNumber} storniert — Gutschrift ${params.creditNoteNumber}`,
+      refund: `Rückerstattung ${totalFmt} für Rechnung ${params.invoiceNumber} — Gutschrift ${params.creditNoteNumber}`,
+    },
+    fr: {
+      void: `Facture ${params.invoiceNumber} annulée — note de crédit ${params.creditNoteNumber}`,
+      refund: `Remboursement ${totalFmt} pour la facture ${params.invoiceNumber} — note de crédit ${params.creditNoteNumber}`,
+    },
+    it: {
+      void: `Fattura ${params.invoiceNumber} annullata — nota di credito ${params.creditNoteNumber}`,
+      refund: `Rimborso ${totalFmt} per fattura ${params.invoiceNumber} — nota di credito ${params.creditNoteNumber}`,
+    },
+  };
+
+  const greetingsByLocale: Record<typeof L, string> = {
+    en: `Hello ${params.contactName},`,
+    de: `Sehr geehrte/r ${params.contactName},`,
+    fr: `Bonjour ${params.contactName},`,
+    it: `Gentile ${params.contactName},`,
+  };
+
+  // Intro: distinct phrasing per kind in each locale.
+  const introsByLocale: Record<typeof L, { void: string; refund: string }> = {
+    en: {
+      void: `We've cancelled invoice ${params.invoiceNumber}. The invoice is no longer payable, and a credit note has been issued for your records.`,
+      refund: `We've refunded ${totalFmt} for invoice ${params.invoiceNumber}. The refund will appear on the original payment method within 5–10 business days, depending on your bank.`,
+    },
+    de: {
+      void: `Wir haben Rechnung ${params.invoiceNumber} storniert. Die Rechnung ist nicht mehr zahlbar; eine Gutschrift wurde für Ihre Unterlagen ausgestellt.`,
+      refund: `Wir haben ${totalFmt} für Rechnung ${params.invoiceNumber} zurückerstattet. Der Betrag wird je nach Bank innerhalb von 5–10 Geschäftstagen auf dem ursprünglichen Zahlungsweg gutgeschrieben.`,
+    },
+    fr: {
+      void: `Nous avons annulé la facture ${params.invoiceNumber}. La facture n'est plus exigible ; une note de crédit a été émise pour vos archives.`,
+      refund: `Nous avons remboursé ${totalFmt} pour la facture ${params.invoiceNumber}. Le montant apparaîtra sur le moyen de paiement initial sous 5 à 10 jours ouvrés, selon votre banque.`,
+    },
+    it: {
+      void: `Abbiamo annullato la fattura ${params.invoiceNumber}. La fattura non è più dovuta; è stata emessa una nota di credito per la sua documentazione.`,
+      refund: `Abbiamo rimborsato ${totalFmt} per la fattura ${params.invoiceNumber}. L'importo apparirà sul metodo di pagamento originale entro 5–10 giorni lavorativi, a seconda della banca.`,
+    },
+  };
+
+  const labels: Record<typeof L, Record<string, string>> = {
+    en: { creditNote: "Credit note", invoice: "Invoice", amount: "Amount", reason: "Reason", cta: "View credit note & download PDF", signoff: "Best regards", brand: "PieCed IT" },
+    de: { creditNote: "Gutschrift", invoice: "Rechnung", amount: "Betrag", reason: "Begründung", cta: "Gutschrift ansehen & PDF herunterladen", signoff: "Mit freundlichen Grüssen", brand: "PieCed IT" },
+    fr: { creditNote: "Note de crédit", invoice: "Facture", amount: "Montant", reason: "Motif", cta: "Voir la note de crédit & télécharger le PDF", signoff: "Cordialement", brand: "PieCed IT" },
+    it: { creditNote: "Nota di credito", invoice: "Fattura", amount: "Importo", reason: "Motivo", cta: "Visualizza nota di credito & scarica PDF", signoff: "Cordiali saluti", brand: "PieCed IT" },
+  };
+  const l = labels[L];
+
+  const subject = subjectsByLocale[L][params.kind];
+  const intro = introsByLocale[L][params.kind];
+  const safeName = escapeHtml(params.contactName);
+  const safeNumberCN = escapeHtml(params.creditNoteNumber);
+  const safeNumberINV = escapeHtml(params.invoiceNumber);
+  const safeReason = params.reason ? escapeHtml(params.reason) : null;
+
+  // Red accent (#DC2626) for the credit-note emails, mirroring the
+  // PDF accent so the document family reads visually consistent.
+  // The invoice email uses emerald; the credit note uses red.
+  const ACCENT = "#DC2626";
+
+  try {
+    await getTransporter().sendMail({
+      from: getFrom(),
+      to: params.to,
+      subject,
+      text: [
+        greetingsByLocale[L],
+        "",
+        intro,
+        "",
+        `${l.creditNote}:  ${params.creditNoteNumber}`,
+        `${l.invoice}:    ${params.invoiceNumber}`,
+        `${l.amount}:     ${totalFmt}`,
+        ...(params.reason ? [`${l.reason}:    ${params.reason}`] : []),
+        "",
+        `${l.cta}:`,
+        link,
+        "",
+        `${l.signoff},`,
+        l.brand,
+      ].join("\n"),
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, sans-serif; max-width: 560px; padding: 24px; background: #1a1a1a; color: #e5e5e5;">
+          <h2 style="margin: 0 0 16px; color: ${ACCENT};">${escapeHtml(intro)}</h2>
+          <p>${safeName === "" ? "" : escapeHtml(greetingsByLocale[L])}</p>
+          <table style="width:100%; border-collapse:collapse; margin:16px 0; font-size:14px;">
+            <tr><td style="color:#888; padding:6px 0; width:140px;">${l.creditNote}</td><td><strong>${safeNumberCN}</strong></td></tr>
+            <tr><td style="color:#888; padding:6px 0;">${l.invoice}</td><td>${safeNumberINV}</td></tr>
+            <tr><td style="color:#888; padding:6px 0;">${l.amount}</td><td style="color:${ACCENT}; font-weight:600;">${escapeHtml(totalFmt)}</td></tr>
+            ${safeReason ? `<tr><td style="color:#888; padding:6px 0; vertical-align:top;">${l.reason}</td><td style="color:#bbb;">${safeReason}</td></tr>` : ""}
+          </table>
+          <p>
+            <a href="${link}" style="display:inline-block; padding:10px 24px; background:${ACCENT}; color:#fff; text-decoration:none; border-radius:8px; font-weight:500;">
+              ${l.cta}
+            </a>
+          </p>
+          <hr style="border:none; border-top:1px solid #333; margin:24px 0;" />
+          <p style="color:#666; font-size:12px;">${l.brand}</p>
+        </div>
+      `,
+    });
+  } catch (err) {
+    console.error("Failed to send credit note email:", err);
+  }
+}