@flink-app/email-plugin 1.0.0 → 2.0.0-alpha.100

package/src/ses-types.ts

@@ -0,0 +1,93 @@
+/**
+ * Parameters for sending a templated email via SES
+ */
+export interface SesTemplatedEmailParams {
+  /** Sender address (overrides defaultFrom) */
+  from?: string;
+  /** Recipient addresses */
+  to: string[];
+  /** CC addresses */
+  cc?: string[];
+  /** BCC addresses */
+  bcc?: string[];
+  /** Reply-to addresses */
+  replyTo?: string[];
+  /** SES template name */
+  template: string;
+  /** Template data as key-value pairs (will be JSON.stringify'd for SES) */
+  templateData: Record<string, unknown>;
+  /** SES configuration set (overrides client default) */
+  configurationSet?: string;
+  /** SES tags for event filtering */
+  tags?: Record<string, string>;
+}
+
+/**
+ * Parameters for sending bulk emails via SES template
+ */
+export interface SesBulkEmailParams {
+  /** Sender address (overrides defaultFrom) */
+  from?: string;
+  /** SES template name */
+  template: string;
+  /** Default template data applied to all destinations */
+  defaultTemplateData?: Record<string, unknown>;
+  /** Individual recipients with optional per-recipient template overrides */
+  destinations: SesBulkDestination[];
+  /** SES configuration set (overrides client default) */
+  configurationSet?: string;
+  /** Reply-to addresses */
+  replyTo?: string[];
+  /** SES tags for event filtering */
+  tags?: Record<string, string>;
+}
+
+export interface SesBulkDestination {
+  to: string[];
+  cc?: string[];
+  bcc?: string[];
+  /** Per-destination template data (merged with defaultTemplateData) */
+  templateData?: Record<string, unknown>;
+}
+
+/**
+ * Result from a single send operation
+ */
+export interface SesResult {
+  success: boolean;
+  /** AWS MessageId, present on success */
+  messageId?: string;
+  /** Error details, present on failure */
+  error?: { code: string; message: string };
+}
+
+/**
+ * Result from a bulk send operation
+ */
+export interface SesBulkResult {
+  success: boolean;
+  /** Per-destination results */
+  results: Array<{
+    success: boolean;
+    messageId?: string;
+    error?: { code: string; message: string };
+  }>;
+  /** Number of successful sends */
+  successCount: number;
+  /** Number of failed sends */
+  failureCount: number;
+}
+
+/**
+ * Result from verifySetup()
+ */
+export interface SesSetupStatus {
+  /** Whether credentials are valid and SES is accessible */
+  verified: boolean;
+  /** Whether the account is out of the SES sandbox */
+  sendingEnabled: boolean;
+  /** The configured AWS region */
+  region: string;
+  /** Error message if verification failed */
+  error?: string;
+}

package/src/sesClient.ts

@@ -0,0 +1,352 @@
+import {
+  SESv2Client,
+  SendEmailCommand,
+  SendBulkEmailCommand,
+  GetAccountCommand,
+  type SendEmailCommandInput,
+  type SendBulkEmailCommandInput,
+  type MessageTag,
+} from "@aws-sdk/client-sesv2";
+import { client } from "./schemas/client";
+import { emailSes } from "./schemas/emailSes";
+import {
+  SesTemplatedEmailParams,
+  SesBulkEmailParams,
+  SesResult,
+  SesBulkResult,
+  SesSetupStatus,
+} from "./ses-types";
+
+export interface sesClientOptions {
+  /** AWS region (defaults to AWS_REGION env var) */
+  region?: string;
+  /** Explicit credentials. Omit to use default AWS credential chain (env vars, IAM roles, etc.) */
+  credentials?: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+  };
+  /** Default "from" address when not specified per-email */
+  defaultFrom?: string;
+  /** Default SES configuration set name */
+  configurationSet?: string;
+}
+
+export class sesClient implements client {
+  private awsClient: SESv2Client;
+  private defaultFrom?: string;
+  private defaultConfigurationSet?: string;
+
+  constructor(options: sesClientOptions, awsClient?: SESv2Client) {
+    this.defaultFrom = options.defaultFrom;
+    this.defaultConfigurationSet = options.configurationSet;
+
+    this.awsClient =
+      awsClient ??
+      new SESv2Client({
+        region: options.region,
+        credentials: options.credentials,
+      });
+  }
+
+  /**
+   * Send an email via SES. Implements the base `client` interface.
+   * Returns `true` on success, `false` on failure.
+   * For richer results (messageId, error details), use `sendEmail()` instead.
+   */
+  async send(email: emailSes): Promise<boolean> {
+    const result = await this.sendEmail(email);
+    return result.success;
+  }
+
+  /**
+   * Send an email via SES with rich result including messageId and error details.
+   */
+  async sendEmail(email: emailSes): Promise<SesResult> {
+    const from = email.from || this.defaultFrom;
+    if (!from) {
+      return {
+        success: false,
+        error: {
+          code: "MISSING_FROM",
+          message:
+            "No 'from' address specified. Set it on the email or use defaultFrom in sesClientOptions.",
+        },
+      };
+    }
+
+    try {
+      const hasAttachments = email.attachments && email.attachments.length > 0;
+
+      const content = hasAttachments
+        ? { Raw: { Data: this.buildRawMimeMessage(email, from) } }
+        : {
+            Simple: {
+              Subject: { Data: email.subject, Charset: "UTF-8" },
+              Body: {
+                ...(email.text
+                  ? { Text: { Data: email.text, Charset: "UTF-8" } }
+                  : {}),
+                ...(email.html
+                  ? { Html: { Data: email.html, Charset: "UTF-8" } }
+                  : {}),
+              },
+            },
+          };
+
+      const input: SendEmailCommandInput = {
+        FromEmailAddress: from,
+        Destination: {
+          ToAddresses: email.to,
+          CcAddresses: email.cc,
+          BccAddresses: email.bcc,
+        },
+        ReplyToAddresses: email.replyTo,
+        ConfigurationSetName:
+          email.configurationSet || this.defaultConfigurationSet,
+        EmailTags: this.toMessageTags(email.tags),
+        Content: content,
+      };
+
+      const response = await this.awsClient.send(new SendEmailCommand(input));
+
+      return {
+        success: true,
+        messageId: response.MessageId,
+      };
+    } catch (err: any) {
+      return {
+        success: false,
+        error: {
+          code: err.name || err.code || "UNKNOWN",
+          message: err.message || "Unknown error",
+        },
+      };
+    }
+  }
+
+  /**
+   * Send a templated email using an SES template.
+   */
+  async sendTemplated(params: SesTemplatedEmailParams): Promise<SesResult> {
+    const from = params.from || this.defaultFrom;
+    if (!from) {
+      return {
+        success: false,
+        error: {
+          code: "MISSING_FROM",
+          message:
+            "No 'from' address specified. Set it on params or use defaultFrom in sesClientOptions.",
+        },
+      };
+    }
+
+    try {
+      const input: SendEmailCommandInput = {
+        FromEmailAddress: from,
+        Destination: {
+          ToAddresses: params.to,
+          CcAddresses: params.cc,
+          BccAddresses: params.bcc,
+        },
+        ReplyToAddresses: params.replyTo,
+        ConfigurationSetName:
+          params.configurationSet || this.defaultConfigurationSet,
+        EmailTags: this.toMessageTags(params.tags),
+        Content: {
+          Template: {
+            TemplateName: params.template,
+            TemplateData: JSON.stringify(params.templateData),
+          },
+        },
+      };
+
+      const response = await this.awsClient.send(new SendEmailCommand(input));
+
+      return {
+        success: true,
+        messageId: response.MessageId,
+      };
+    } catch (err: any) {
+      return {
+        success: false,
+        error: {
+          code: err.name || err.code || "UNKNOWN",
+          message: err.message || "Unknown error",
+        },
+      };
+    }
+  }
+
+  /**
+   * Send bulk emails using an SES template.
+   */
+  async sendBulk(params: SesBulkEmailParams): Promise<SesBulkResult> {
+    const from = params.from || this.defaultFrom;
+    if (!from) {
+      return {
+        success: false,
+        results: [],
+        successCount: 0,
+        failureCount: params.destinations.length,
+      };
+    }
+
+    try {
+      const input: SendBulkEmailCommandInput = {
+        FromEmailAddress: from,
+        ReplyToAddresses: params.replyTo,
+        ConfigurationSetName:
+          params.configurationSet || this.defaultConfigurationSet,
+        DefaultEmailTags: this.toMessageTags(params.tags),
+        DefaultContent: {
+          Template: {
+            TemplateName: params.template,
+            TemplateData: params.defaultTemplateData
+              ? JSON.stringify(params.defaultTemplateData)
+              : undefined,
+          },
+        },
+        BulkEmailEntries: params.destinations.map((dest) => ({
+          Destination: {
+            ToAddresses: dest.to,
+            CcAddresses: dest.cc,
+            BccAddresses: dest.bcc,
+          },
+          ReplacementEmailContent: dest.templateData
+            ? {
+                ReplacementTemplate: {
+                  ReplacementTemplateData: JSON.stringify(dest.templateData),
+                },
+              }
+            : undefined,
+        })),
+      };
+
+      const response = await this.awsClient.send(
+        new SendBulkEmailCommand(input)
+      );
+
+      const results = (response.BulkEmailEntryResults || []).map((entry) => {
+        const success = entry.Status === "SUCCESS";
+        return {
+          success,
+          messageId: success ? entry.MessageId : undefined,
+          error: !success
+            ? {
+                code: entry.Error || "UNKNOWN",
+                message: entry.Error || "Bulk send entry failed",
+              }
+            : undefined,
+        };
+      });
+
+      const successCount = results.filter((r) => r.success).length;
+      const failureCount = results.filter((r) => !r.success).length;
+
+      return {
+        success: failureCount === 0,
+        results,
+        successCount,
+        failureCount,
+      };
+    } catch (err: any) {
+      return {
+        success: false,
+        results: [],
+        successCount: 0,
+        failureCount: params.destinations.length,
+      };
+    }
+  }
+
+  /**
+   * Verify that the SES setup is working — checks credentials and account status.
+   */
+  async verifySetup(): Promise<SesSetupStatus> {
+    try {
+      const response = await this.awsClient.send(new GetAccountCommand({}));
+      const region =
+        (await this.awsClient.config.region()) || "unknown";
+
+      return {
+        verified: true,
+        sendingEnabled: response.ProductionAccessEnabled === true,
+        region,
+      };
+    } catch (err: any) {
+      return {
+        verified: false,
+        sendingEnabled: false,
+        region: "unknown",
+        error: err.message || "Failed to verify SES setup",
+      };
+    }
+  }
+
+  private toMessageTags(
+    tags?: Record<string, string>
+  ): MessageTag[] | undefined {
+    if (!tags) return undefined;
+    return Object.entries(tags).map(([Name, Value]) => ({ Name, Value }));
+  }
+
+  private buildRawMimeMessage(email: emailSes, from: string): Uint8Array {
+    const boundary = `----=_Part_${Date.now()}_${Math.random().toString(36).substring(2)}`;
+    const lines: string[] = [];
+
+    lines.push(`From: ${from}`);
+    lines.push(`To: ${email.to.join(", ")}`);
+    if (email.cc?.length) lines.push(`Cc: ${email.cc.join(", ")}`);
+    if (email.replyTo?.length) lines.push(`Reply-To: ${email.replyTo.join(", ")}`);
+    lines.push(`Subject: =?UTF-8?B?${Buffer.from(email.subject).toString("base64")}?=`);
+    lines.push("MIME-Version: 1.0");
+    lines.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
+    lines.push("");
+
+    // Text part
+    if (email.text) {
+      lines.push(`--${boundary}`);
+      lines.push("Content-Type: text/plain; charset=UTF-8");
+      lines.push("Content-Transfer-Encoding: 7bit");
+      lines.push("");
+      lines.push(email.text);
+      lines.push("");
+    }
+
+    // HTML part
+    if (email.html) {
+      lines.push(`--${boundary}`);
+      lines.push("Content-Type: text/html; charset=UTF-8");
+      lines.push("Content-Transfer-Encoding: 7bit");
+      lines.push("");
+      lines.push(email.html);
+      lines.push("");
+    }
+
+    // Attachments
+    for (const attachment of email.attachments || []) {
+      const contentType = attachment.contentType || "application/octet-stream";
+      const base64Content =
+        Buffer.isBuffer(attachment.content)
+          ? attachment.content.toString("base64")
+          : attachment.content;
+
+      lines.push(`--${boundary}`);
+      lines.push(
+        `Content-Type: ${contentType}; name="${attachment.filename}"`
+      );
+      lines.push(
+        `Content-Disposition: attachment; filename="${attachment.filename}"`
+      );
+      lines.push("Content-Transfer-Encoding: base64");
+      lines.push("");
+      lines.push(base64Content);
+      lines.push("");
+    }
+
+    lines.push(`--${boundary}--`);
+
+    return new TextEncoder().encode(lines.join("\r\n"));
+  }
+}