organify-email 1.0.0

package/src/brevo-client.ts

@@ -0,0 +1,242 @@
+// ─────────────────────────────────────────────
+// Brevo Email Client — Transactional API
+// ─────────────────────────────────────────────
+// Shared email service using Brevo API for all
+// Organify microservices.
+//
+// Limits:
+//   - 300 emails/day (Brevo free tier)
+//   - ~30 estimated for beta
+//   - Built-in daily counter + priority system
+//
+// Usage:
+//   const client = new BrevoEmailClient({ apiKey, senderName, senderEmail });
+//   await client.send({ to, subject, template: 'report-ready', params });
+// ─────────────────────────────────────────────
+
+import { emailTemplates, type EmailTemplateName } from './templates';
+
+// ─── Types ──────────────────────────────────
+
+export interface BrevoEmailConfig {
+  apiKey: string;
+  senderName?: string;
+  senderEmail?: string;
+  /** Daily send limit (default: 300) */
+  dailyLimit?: number;
+  /** Enable sending (set false for dev/test to just log) */
+  enabled?: boolean;
+}
+
+export interface EmailRecipient {
+  email: string;
+  name?: string;
+}
+
+export interface SendEmailOptions {
+  to: EmailRecipient | EmailRecipient[];
+  subject: string;
+  /** Use a named template with dynamic params */
+  template?: EmailTemplateName;
+  /** Template parameters (dynamic variables) */
+  params?: Record<string, string | number | boolean>;
+  /** Raw HTML content (overrides template) */
+  htmlContent?: string;
+  /** Plain text fallback */
+  textContent?: string;
+  /** Priority: 'critical' always sends, 'normal' respects rate limits, 'low' may be skipped */
+  priority?: 'critical' | 'normal' | 'low';
+  /** Tags for tracking */
+  tags?: string[];
+  /** CC recipients */
+  cc?: EmailRecipient[];
+  /** BCC recipients */
+  bcc?: EmailRecipient[];
+  /** Reply-to address */
+  replyTo?: EmailRecipient;
+}
+
+export interface SendResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+  skipped?: boolean;
+  reason?: string;
+}
+
+export interface DailyStats {
+  sent: number;
+  limit: number;
+  remaining: number;
+  date: string;
+  byPriority: { critical: number; normal: number; low: number };
+}
+
+// ─── Client ─────────────────────────────────
+
+export class BrevoEmailClient {
+  private readonly apiKey: string;
+  private readonly senderName: string;
+  private readonly senderEmail: string;
+  private readonly dailyLimit: number;
+  private readonly enabled: boolean;
+
+  // Daily counter (in-memory, resets on restart)
+  private dailySent = 0;
+  private dailyDate = '';
+  private dailyByPriority = { critical: 0, normal: 0, low: 0 };
+
+  private static readonly API_URL = 'https://api.brevo.com/v3/smtp/email';
+
+  constructor(config: BrevoEmailConfig) {
+    this.apiKey = config.apiKey;
+    this.senderName = config.senderName || 'Organify Team';
+    this.senderEmail = config.senderEmail || 'noreply@organify.studio';
+    this.dailyLimit = config.dailyLimit || 300;
+    this.enabled = config.enabled !== false;
+  }
+
+  // ─── Main Send ────────────────────────────
+
+  async send(options: SendEmailOptions): Promise<SendResult> {
+    const priority = options.priority || 'normal';
+
+    // Reset counter if new day
+    this.checkDayReset();
+
+    // Rate limit check (critical bypasses)
+    if (priority !== 'critical') {
+      if (this.dailySent >= this.dailyLimit) {
+        return {
+          success: false,
+          skipped: true,
+          reason: `Daily limit reached (${this.dailyLimit}/day). Email queued for tomorrow.`,
+        };
+      }
+
+      // Reserve 10% for critical emails
+      const criticalReserve = Math.floor(this.dailyLimit * 0.1);
+      if (priority === 'low' && this.dailySent >= this.dailyLimit - criticalReserve) {
+        return {
+          success: false,
+          skipped: true,
+          reason: `Low-priority email skipped (remaining quota reserved for critical/normal).`,
+        };
+      }
+    }
+
+    // Build HTML content
+    let htmlContent = options.htmlContent;
+    if (!htmlContent && options.template) {
+      const templateFn = emailTemplates[options.template];
+      if (templateFn) {
+        htmlContent = templateFn(options.params || {});
+      }
+    }
+
+    if (!htmlContent && !options.textContent) {
+      return { success: false, error: 'No content provided (template, htmlContent, or textContent required)' };
+    }
+
+    // Disabled mode (dev/test)
+    if (!this.enabled) {
+      const recipients = Array.isArray(options.to) ? options.to : [options.to];
+      console.log(`[BrevoEmail] DRY RUN → ${recipients.map((r) => r.email).join(', ')} | Subject: ${options.subject}`);
+      this.incrementCounter(priority);
+      return { success: true, messageId: `dry-run-${Date.now()}`, skipped: false };
+    }
+
+    // Build Brevo payload
+    const recipients = Array.isArray(options.to) ? options.to : [options.to];
+    const payload: Record<string, any> = {
+      sender: { name: this.senderName, email: this.senderEmail },
+      to: recipients.map((r) => ({ email: r.email, name: r.name })),
+      subject: options.subject,
+    };
+
+    if (htmlContent) payload.htmlContent = htmlContent;
+    else if (options.textContent) payload.textContent = options.textContent;
+
+    if (options.params) payload.params = options.params;
+    if (options.tags) payload.tags = options.tags;
+    if (options.cc) payload.cc = options.cc;
+    if (options.bcc) payload.bcc = options.bcc;
+    if (options.replyTo) payload.replyTo = options.replyTo;
+
+    try {
+      const response = await fetch(BrevoEmailClient.API_URL, {
+        method: 'POST',
+        headers: {
+          'accept': 'application/json',
+          'api-key': this.apiKey,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify(payload),
+      });
+
+      if (!response.ok) {
+        const body = await response.text();
+        console.error(`[BrevoEmail] API error ${response.status}: ${body}`);
+        return { success: false, error: `Brevo API error: ${response.status} — ${body}` };
+      }
+
+      const data = await response.json() as { messageId?: string };
+      this.incrementCounter(priority);
+
+      return { success: true, messageId: data.messageId };
+    } catch (err: any) {
+      console.error(`[BrevoEmail] Network error: ${err.message}`);
+      return { success: false, error: `Network error: ${err.message}` };
+    }
+  }
+
+  // ─── Batch Send (same template, multiple recipients) ──
+
+  async sendBatch(
+    recipients: EmailRecipient[],
+    options: Omit<SendEmailOptions, 'to'>,
+  ): Promise<SendResult[]> {
+    // Brevo supports multiple "to" in a single request
+    // But for individual params, send separately
+    if (options.params) {
+      // Each recipient gets their own email
+      const results: SendResult[] = [];
+      for (const recipient of recipients) {
+        results.push(await this.send({ ...options, to: recipient }));
+      }
+      return results;
+    }
+
+    // Single request with multiple recipients
+    return [await this.send({ ...options, to: recipients })];
+  }
+
+  // ─── Stats ────────────────────────────────
+
+  getStats(): DailyStats {
+    this.checkDayReset();
+    return {
+      sent: this.dailySent,
+      limit: this.dailyLimit,
+      remaining: Math.max(0, this.dailyLimit - this.dailySent),
+      date: this.dailyDate,
+      byPriority: { ...this.dailyByPriority },
+    };
+  }
+
+  // ─── Internal ─────────────────────────────
+
+  private checkDayReset() {
+    const today = new Date().toISOString().slice(0, 10);
+    if (this.dailyDate !== today) {
+      this.dailySent = 0;
+      this.dailyDate = today;
+      this.dailyByPriority = { critical: 0, normal: 0, low: 0 };
+    }
+  }
+
+  private incrementCounter(priority: 'critical' | 'normal' | 'low') {
+    this.dailySent++;
+    this.dailyByPriority[priority]++;
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// ─────────────────────────────────────────────
+// organify-email — Public API
+// ─────────────────────────────────────────────
+
+export {
+  BrevoEmailClient,
+  type BrevoEmailConfig,
+  type EmailRecipient,
+  type SendEmailOptions,
+  type SendResult,
+  type DailyStats,
+} from './brevo-client';
+
+export {
+  emailTemplates,
+  type EmailTemplateName,
+} from './templates';