@flink-app/email-plugin 2.0.0-alpha.73 → 2.0.0-alpha.75

package/spec/sesClient.spec.ts

@@ -0,0 +1,464 @@
+import { sesClient, sesClientOptions } from "../src/sesClient";
+import { emailSes } from "../src/schemas/emailSes";
+
+// Mock AWS SESv2Client
+function createMockAwsClient(overrides?: {
+  sendResponse?: any;
+  sendError?: any;
+  configRegion?: string;
+}) {
+  const mock = {
+    send: jasmine
+      .createSpy("send")
+      .and.callFake(async (command: any) => {
+        if (overrides?.sendError) throw overrides.sendError;
+        return overrides?.sendResponse || { MessageId: "mock-message-id-123" };
+      }),
+    config: {
+      region: () => Promise.resolve(overrides?.configRegion || "eu-north-1"),
+    },
+  };
+  return mock as any;
+}
+
+describe("sesClient", () => {
+  describe("send()", () => {
+    it("should send a simple email and return true", async () => {
+      const mockAws = createMockAwsClient();
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      const result = await client.send({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        html: "<p>Hello</p>",
+      });
+
+      expect(result).toBe(true);
+      expect(mockAws.send).toHaveBeenCalledTimes(1);
+
+      const command = mockAws.send.calls.first().args[0];
+      expect(command.input.FromEmailAddress).toBe("sender@example.com");
+      expect(command.input.Destination.ToAddresses).toEqual([
+        "recipient@example.com",
+      ]);
+      expect(command.input.Content.Simple.Subject.Data).toBe("Test");
+      expect(command.input.Content.Simple.Body.Html.Data).toBe("<p>Hello</p>");
+    });
+
+    it("should return false on AWS error", async () => {
+      const mockAws = createMockAwsClient({
+        sendError: { name: "MessageRejected", message: "Email rejected" },
+      });
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      const result = await client.send({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        html: "<p>Hello</p>",
+      });
+
+      expect(result).toBe(false);
+    });
+
+    it("should use defaultFrom when email has no from", async () => {
+      const mockAws = createMockAwsClient();
+      const client = new sesClient(
+        { region: "eu-north-1", defaultFrom: "default@example.com" },
+        mockAws
+      );
+
+      await client.send({
+        from: "",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+      } as any);
+
+      // send will use defaultFrom since from is falsy
+      const command = mockAws.send.calls.first().args[0];
+      expect(command.input.FromEmailAddress).toBe("default@example.com");
+    });
+
+    it("should return false when no from address is available", async () => {
+      const mockAws = createMockAwsClient();
+      const client = new sesClient({ region: "eu-north-1" }, mockAws);
+
+      const result = await client.send({
+        from: "",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+      } as any);
+
+      expect(result).toBe(false);
+      expect(mockAws.send).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("sendEmail()", () => {
+    it("should return rich result with messageId on success", async () => {
+      const mockAws = createMockAwsClient({
+        sendResponse: { MessageId: "ses-msg-456" },
+      });
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      const result = await client.sendEmail({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.messageId).toBe("ses-msg-456");
+      expect(result.error).toBeUndefined();
+    });
+
+    it("should return structured error on failure", async () => {
+      const mockAws = createMockAwsClient({
+        sendError: {
+          name: "AccountSendingPausedException",
+          message: "Sending is paused",
+        },
+      });
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      const result = await client.sendEmail({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        html: "<p>Hello</p>",
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("AccountSendingPausedException");
+      expect(result.error?.message).toBe("Sending is paused");
+    });
+
+    it("should send both text and html", async () => {
+      const mockAws = createMockAwsClient();
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      await client.sendEmail({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello plain",
+        html: "<p>Hello html</p>",
+      });
+
+      const command = mockAws.send.calls.first().args[0];
+      expect(command.input.Content.Simple.Body.Text.Data).toBe("Hello plain");
+      expect(command.input.Content.Simple.Body.Html.Data).toBe(
+        "<p>Hello html</p>"
+      );
+    });
+
+    it("should include cc, bcc, and replyTo", async () => {
+      const mockAws = createMockAwsClient();
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      await client.sendEmail({
+        from: "sender@example.com",
+        to: ["to@example.com"],
+        cc: ["cc@example.com"],
+        bcc: ["bcc@example.com"],
+        replyTo: ["reply@example.com"],
+        subject: "Test",
+        text: "Hello",
+      });
+
+      const command = mockAws.send.calls.first().args[0];
+      expect(command.input.Destination.CcAddresses).toEqual([
+        "cc@example.com",
+      ]);
+      expect(command.input.Destination.BccAddresses).toEqual([
+        "bcc@example.com",
+      ]);
+      expect(command.input.ReplyToAddresses).toEqual(["reply@example.com"]);
+    });
+
+    it("should pass configuration set and tags", async () => {
+      const mockAws = createMockAwsClient();
+      const client = new sesClient(
+        { region: "eu-north-1", configurationSet: "default-set" },
+        mockAws
+      );
+
+      await client.sendEmail({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+        tags: { campaign: "welcome", env: "prod" },
+      });
+
+      const command = mockAws.send.calls.first().args[0];
+      expect(command.input.ConfigurationSetName).toBe("default-set");
+      expect(command.input.EmailTags).toEqual([
+        { Name: "campaign", Value: "welcome" },
+        { Name: "env", Value: "prod" },
+      ]);
+    });
+
+    it("should override default configuration set per-email", async () => {
+      const mockAws = createMockAwsClient();
+      const client = new sesClient(
+        { region: "eu-north-1", configurationSet: "default-set" },
+        mockAws
+      );
+
+      await client.sendEmail({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        text: "Hello",
+        configurationSet: "override-set",
+      });
+
+      const command = mockAws.send.calls.first().args[0];
+      expect(command.input.ConfigurationSetName).toBe("override-set");
+    });
+
+    it("should use Raw content for emails with attachments", async () => {
+      const mockAws = createMockAwsClient();
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      await client.sendEmail({
+        from: "sender@example.com",
+        to: ["recipient@example.com"],
+        subject: "Test",
+        html: "<p>See attached</p>",
+        attachments: [
+          {
+            filename: "test.txt",
+            content: Buffer.from("hello world"),
+            contentType: "text/plain",
+          },
+        ],
+      });
+
+      const command = mockAws.send.calls.first().args[0];
+      expect(command.input.Content.Raw).toBeDefined();
+      expect(command.input.Content.Simple).toBeUndefined();
+
+      // Verify MIME message contains expected parts
+      const rawMessage = new TextDecoder().decode(command.input.Content.Raw.Data);
+      expect(rawMessage).toContain("From: sender@example.com");
+      expect(rawMessage).toContain("To: recipient@example.com");
+      expect(rawMessage).toContain("multipart/mixed");
+      expect(rawMessage).toContain("text/html");
+      expect(rawMessage).toContain("<p>See attached</p>");
+      expect(rawMessage).toContain('filename="test.txt"');
+      expect(rawMessage).toContain(
+        Buffer.from("hello world").toString("base64")
+      );
+    });
+  });
+
+  describe("sendTemplated()", () => {
+    it("should send a templated email", async () => {
+      const mockAws = createMockAwsClient({
+        sendResponse: { MessageId: "tmpl-msg-789" },
+      });
+      const client = new sesClient(
+        { region: "eu-north-1", defaultFrom: "noreply@example.com" },
+        mockAws
+      );
+
+      const result = await client.sendTemplated({
+        to: ["recipient@example.com"],
+        template: "WelcomeEmail",
+        templateData: { name: "Joel", company: "Frost" },
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.messageId).toBe("tmpl-msg-789");
+
+      const command = mockAws.send.calls.first().args[0];
+      expect(command.input.FromEmailAddress).toBe("noreply@example.com");
+      expect(command.input.Content.Template.TemplateName).toBe("WelcomeEmail");
+      expect(command.input.Content.Template.TemplateData).toBe(
+        JSON.stringify({ name: "Joel", company: "Frost" })
+      );
+    });
+
+    it("should return error when no from address", async () => {
+      const mockAws = createMockAwsClient();
+      const client = new sesClient({ region: "eu-north-1" }, mockAws);
+
+      const result = await client.sendTemplated({
+        to: ["recipient@example.com"],
+        template: "WelcomeEmail",
+        templateData: { name: "Joel" },
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("MISSING_FROM");
+    });
+  });
+
+  describe("sendBulk()", () => {
+    it("should send bulk emails", async () => {
+      const mockAws = createMockAwsClient({
+        sendResponse: {
+          BulkEmailEntryResults: [
+            { Status: "SUCCESS", MessageId: "bulk-1" },
+            { Status: "SUCCESS", MessageId: "bulk-2" },
+          ],
+        },
+      });
+      const client = new sesClient(
+        { region: "eu-north-1", defaultFrom: "noreply@example.com" },
+        mockAws
+      );
+
+      const result = await client.sendBulk({
+        template: "Newsletter",
+        defaultTemplateData: { company: "Frost" },
+        destinations: [
+          { to: ["a@example.com"], templateData: { name: "Alice" } },
+          { to: ["b@example.com"], templateData: { name: "Bob" } },
+        ],
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.successCount).toBe(2);
+      expect(result.failureCount).toBe(0);
+      expect(result.results.length).toBe(2);
+      expect(result.results[0].messageId).toBe("bulk-1");
+
+      const command = mockAws.send.calls.first().args[0];
+      expect(command.input.DefaultContent.Template.TemplateName).toBe(
+        "Newsletter"
+      );
+      expect(command.input.BulkEmailEntries.length).toBe(2);
+    });
+
+    it("should handle partial failures", async () => {
+      const mockAws = createMockAwsClient({
+        sendResponse: {
+          BulkEmailEntryResults: [
+            { Status: "SUCCESS", MessageId: "bulk-1" },
+            { Status: "FAILED", Error: "MailFromDomainNotVerified" },
+          ],
+        },
+      });
+      const client = new sesClient(
+        { region: "eu-north-1", defaultFrom: "noreply@example.com" },
+        mockAws
+      );
+
+      const result = await client.sendBulk({
+        template: "Newsletter",
+        destinations: [
+          { to: ["a@example.com"] },
+          { to: ["b@example.com"] },
+        ],
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.successCount).toBe(1);
+      expect(result.failureCount).toBe(1);
+      expect(result.results[0].success).toBe(true);
+      expect(result.results[1].success).toBe(false);
+      expect(result.results[1].error?.code).toBe("MailFromDomainNotVerified");
+    });
+
+    it("should handle complete AWS failure", async () => {
+      const mockAws = createMockAwsClient({
+        sendError: { name: "ServiceUnavailable", message: "Try later" },
+      });
+      const client = new sesClient(
+        { region: "eu-north-1", defaultFrom: "noreply@example.com" },
+        mockAws
+      );
+
+      const result = await client.sendBulk({
+        template: "Newsletter",
+        destinations: [{ to: ["a@example.com"] }],
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.successCount).toBe(0);
+      expect(result.failureCount).toBe(1);
+    });
+  });
+
+  describe("verifySetup()", () => {
+    it("should return verified status", async () => {
+      const mockAws = createMockAwsClient({
+        sendResponse: { ProductionAccessEnabled: true },
+        configRegion: "eu-north-1",
+      });
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      const status = await client.verifySetup();
+
+      expect(status.verified).toBe(true);
+      expect(status.sendingEnabled).toBe(true);
+      expect(status.region).toBe("eu-north-1");
+      expect(status.error).toBeUndefined();
+    });
+
+    it("should report sandbox mode", async () => {
+      const mockAws = createMockAwsClient({
+        sendResponse: { ProductionAccessEnabled: false },
+      });
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      const status = await client.verifySetup();
+
+      expect(status.verified).toBe(true);
+      expect(status.sendingEnabled).toBe(false);
+    });
+
+    it("should handle credential errors", async () => {
+      const mockAws = createMockAwsClient({
+        sendError: {
+          name: "InvalidClientTokenId",
+          message: "The security token included in the request is invalid",
+        },
+      });
+      const client = new sesClient(
+        { region: "eu-north-1" },
+        mockAws
+      );
+
+      const status = await client.verifySetup();
+
+      expect(status.verified).toBe(false);
+      expect(status.sendingEnabled).toBe(false);
+      expect(status.error).toContain("security token");
+    });
+  });
+});

package/spec/support/jasmine.json

@@ -0,0 +1,7 @@
+{
+  "spec_dir": "spec",
+  "spec_files": ["**/*[sS]pec.ts"],
+  "helpers": ["helpers/**/*.ts"],
+  "stopSpecOnExpectationFailure": false,
+  "random": true
+}

package/src/index.ts

@@ -2,8 +2,11 @@ import { FlinkApp, FlinkPlugin } from "@flink-app/flink";
 import { client } from "./schemas/client";
 export { sendgridClient } from "./sendgridClient";
 export { smtpClient } from "./smtpClient";
-export { flowMailerClient } from "./flowmailerClient"
+export { flowMailerClient } from "./flowmailerClient";
+export { sesClient } from "./sesClient";
 export type { email } from "./schemas/email";
+export type { emailSes } from "./schemas/emailSes";
+export * from "./ses-types";
 
 export type emailPluginOptions = {
   /**

package/src/schemas/client.ts

@@ -1,7 +1,8 @@
 import { email } from "./email";
 import { emailFlowmailer } from "./emailFlowmailer";
 import { emailSendgrid } from "./emailSendgrid";
+import { emailSes } from "./emailSes";
 
 export interface client {
-  send(email: email | emailSendgrid | emailFlowmailer): Promise<boolean>;
+  send(email: email | emailSendgrid | emailFlowmailer | emailSes): Promise<boolean>;
 }

package/src/schemas/emailSes.ts

@@ -0,0 +1,73 @@
+export type emailSes = {
+  /**
+   * From address used to send the email
+   */
+  from: string;
+
+  /**
+   * Email addresses to send to
+   */
+  to: string[];
+
+  /**
+   * Reply-to addresses
+   */
+  replyTo?: string[];
+
+  /**
+   * CC addresses
+   */
+  cc?: string[];
+
+  /**
+   * Email addresses to add as BCC
+   */
+  bcc?: string[];
+
+  /**
+   * Subject of email
+   */
+  subject: string;
+
+  /**
+   * Plain text body
+   */
+  text?: string;
+
+  /**
+   * HTML body
+   */
+  html?: string;
+
+  /**
+   * File attachments
+   */
+  attachments?: SesAttachment[];
+
+  /**
+   * SES configuration set for tracking (opens, clicks, bounces)
+   */
+  configurationSet?: string;
+
+  /**
+   * SES tags for event filtering
+   */
+  tags?: Record<string, string>;
+};
+
+export interface SesAttachment {
+  /**
+   * Filename shown to recipient
+   */
+  filename: string;
+
+  /**
+   * Raw content as Buffer or base64 string
+   */
+  content: Buffer | string;
+
+  /**
+   * MIME content type (e.g. "application/pdf"). Defaults to "application/octet-stream"
+   */
+  contentType?: string;
+}

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;
+}