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

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,13 @@ 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 { postmarkClient } from "./postmarkClient";
 export type { email } from "./schemas/email";
+export type { emailSes } from "./schemas/emailSes";
+export type { emailPostmark, PostmarkAttachment } from "./schemas/emailPostmark";
+export * from "./ses-types";
 
 export type emailPluginOptions = {
   /**
@@ -12,7 +17,7 @@ export type emailPluginOptions = {
   client: client;
 };
 
-export interface emailPluginContext {
+export interface EmailPluginContext {
   emailPlugin: {
     client: client;
   };

package/src/postmarkClient.ts

@@ -0,0 +1,53 @@
+import { ServerClient } from "postmark";
+import { emailPostmark as email } from "./schemas/emailPostmark";
+import { client } from "./schemas/client";
+
+export interface postmarkClientOptions {
+  /**
+   * Postmark server token
+   */
+  serverToken: string;
+
+  /**
+   * Default Postmark message stream, defaults to "outbound"
+   */
+  defaultMessageStream?: string;
+}
+
+export class postmarkClient implements client {
+  postmark: ServerClient;
+  defaultMessageStream: string;
+
+  constructor(options: postmarkClientOptions) {
+    this.postmark = new ServerClient(options.serverToken);
+    this.defaultMessageStream = options.defaultMessageStream ?? "outbound";
+  }
+
+  async send(email: email) {
+    try {
+      await this.postmark.sendEmail({
+        From: email.from,
+        To: email.to.join(","),
+        Cc: email.cc?.join(","),
+        Bcc: email.bcc?.join(","),
+        ReplyTo: email.replyTo,
+        Subject: email.subject,
+        HtmlBody: "html" in email ? email.html : undefined,
+        TextBody: "text" in email ? email.text : undefined,
+        MessageStream: email.messageStream ?? this.defaultMessageStream,
+        Tag: email.tag,
+        Metadata: email.metadata,
+        Attachments: email.attachments?.map(a => ({
+          Name: a.filename,
+          Content: a.content,
+          ContentType: a.contentType ?? "application/octet-stream",
+          ContentID: a.contentId ?? "",
+        })),
+      });
+    } catch (ex) {
+      console.log(JSON.stringify(ex));
+      return false;
+    }
+    return true;
+  }
+}

package/src/schemas/client.ts

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

package/src/schemas/emailPostmark.ts

@@ -0,0 +1,73 @@
+export type emailPostmark = {
+  /**
+   * From address used to send the email
+   */
+  from: string;
+
+  /**
+   * Email addresses to send to
+   */
+  to: string[];
+
+  /**
+   * Reply-to address
+   */
+  replyTo?: string;
+
+  /**
+   * CC addresses
+   */
+  cc?: string[];
+
+  /**
+   * BCC addresses
+   */
+  bcc?: string[];
+
+  /**
+   * Subject of email
+   */
+  subject: string;
+
+  /**
+   * Postmark message stream id, defaults to "outbound"
+   */
+  messageStream?: string;
+
+  /**
+   * Postmark tag for categorization
+   */
+  tag?: string;
+
+  /**
+   * Custom metadata sent along with the email
+   */
+  metadata?: Record<string, string>;
+
+  /**
+   * File attachments
+   */
+  attachments?: PostmarkAttachment[];
+} & ({ text: string } | { html: string } | { text: string; html: string });
+
+export interface PostmarkAttachment {
+  /**
+   * Base64 encoded content
+   */
+  content: string;
+
+  /**
+   * Filename shown to recipient
+   */
+  filename: string;
+
+  /**
+   * MIME content type (e.g. "application/pdf"). Defaults to "application/octet-stream"
+   */
+  contentType?: string;
+
+  /**
+   * Content-ID for inline attachments, e.g. "cid:image1"
+   */
+  contentId?: string;
+}

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