@step-func-emailer/handlers 0.2.0

package/src/handlers/__tests__/send-email.test.ts

@@ -0,0 +1,279 @@
+import { vi } from "vitest";
+
+const mockResolveConfig = vi.fn();
+const mockGetSubscriberProfile = vi.fn();
+const mockUpsertSubscriberProfile = vi.fn();
+const mockGetExecution = vi.fn();
+const mockPutExecution = vi.fn();
+const mockDeleteExecution = vi.fn();
+const mockWriteSendLog = vi.fn();
+const mockRenderTemplate = vi.fn();
+const mockSendEmail = vi.fn();
+const mockGenerateToken = vi.fn();
+const mockLoadDisplayNames = vi.fn();
+const mockResolveDisplayNames = vi.fn();
+
+const mockSfnSend = vi.fn();
+vi.mock("@aws-sdk/client-sfn", () => ({
+  SFNClient: class {
+    send = mockSfnSend;
+  },
+  StopExecutionCommand: class {
+    input: unknown;
+    constructor(input: unknown) {
+      this.input = input;
+    }
+  },
+}));
+
+vi.mock("../../lib/ssm-config.js", () => ({
+  resolveConfig: () => mockResolveConfig(),
+}));
+
+vi.mock("../../lib/dynamo-client.js", () => ({
+  getSubscriberProfile: (...args: unknown[]) => mockGetSubscriberProfile(...args),
+  upsertSubscriberProfile: (...args: unknown[]) => mockUpsertSubscriberProfile(...args),
+  extractAttributes: (profile: Record<string, unknown>) => {
+    const SYSTEM_KEYS = new Set([
+      "PK",
+      "SK",
+      "email",
+      "firstName",
+      "unsubscribed",
+      "suppressed",
+      "createdAt",
+      "updatedAt",
+    ]);
+    const attrs: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(profile)) {
+      if (!SYSTEM_KEYS.has(key)) attrs[key] = value;
+    }
+    return attrs;
+  },
+  getExecution: (...args: unknown[]) => mockGetExecution(...args),
+  putExecution: (...args: unknown[]) => mockPutExecution(...args),
+  deleteExecution: (...args: unknown[]) => mockDeleteExecution(...args),
+  writeSendLog: (...args: unknown[]) => mockWriteSendLog(...args),
+}));
+
+vi.mock("../../lib/template-renderer.js", () => ({
+  renderTemplate: (...args: unknown[]) => mockRenderTemplate(...args),
+}));
+
+vi.mock("../../lib/ses-sender.js", () => ({
+  sendEmail: (...args: unknown[]) => mockSendEmail(...args),
+}));
+
+vi.mock("../../lib/unsubscribe-token.js", () => ({
+  generateToken: (...args: unknown[]) => mockGenerateToken(...args),
+}));
+
+vi.mock("../../lib/display-names.js", () => ({
+  loadDisplayNames: (...args: unknown[]) => mockLoadDisplayNames(...args),
+  resolveDisplayNames: (...args: unknown[]) => mockResolveDisplayNames(...args),
+}));
+
+const { handler } = await import("../send-email.js");
+
+const CONFIG = {
+  tableName: "TestTable",
+  eventsTableName: "EventsTable",
+  templateBucket: "my-bucket",
+  defaultFromEmail: "noreply@example.com",
+  defaultFromName: "Example",
+  sesConfigSet: "my-config-set",
+  unsubscribeBaseUrl: "https://unsub.example.com",
+  unsubscribeSecret: "test-secret",
+};
+
+beforeEach(() => {
+  mockResolveConfig.mockReset().mockResolvedValue(CONFIG);
+  mockGetSubscriberProfile.mockReset();
+  mockUpsertSubscriberProfile.mockReset().mockResolvedValue(undefined);
+  mockGetExecution.mockReset();
+  mockPutExecution.mockReset().mockResolvedValue(undefined);
+  mockDeleteExecution.mockReset().mockResolvedValue(undefined);
+  mockWriteSendLog.mockReset().mockResolvedValue(undefined);
+  mockRenderTemplate.mockReset().mockResolvedValue("<h1>Hello</h1>");
+  mockSendEmail.mockReset().mockResolvedValue("msg-123");
+  mockGenerateToken.mockReset().mockReturnValue("token-abc");
+  mockLoadDisplayNames.mockReset().mockResolvedValue({});
+  mockResolveDisplayNames.mockReset().mockReturnValue({});
+  mockSfnSend.mockReset();
+});
+
+describe("send-email handler", () => {
+  describe("register action", () => {
+    const registerEvent = {
+      action: "register" as const,
+      sequenceId: "onboarding",
+      subscriber: { email: "user@example.com", firstName: "Jane" },
+      executionArn: "arn:aws:states:us-east-1:123:execution:new",
+    };
+
+    it("upserts profile and stores execution", async () => {
+      mockGetExecution.mockResolvedValueOnce(null);
+
+      const result = await handler(registerEvent);
+
+      expect(result).toEqual({ registered: true });
+      expect(mockUpsertSubscriberProfile).toHaveBeenCalledWith(
+        "TestTable",
+        registerEvent.subscriber,
+      );
+      expect(mockPutExecution).toHaveBeenCalledWith(
+        "TestTable",
+        "user@example.com",
+        "onboarding",
+        registerEvent.executionArn,
+      );
+    });
+
+    it("stops existing execution before registering new one", async () => {
+      mockGetExecution.mockResolvedValueOnce({
+        executionArn: "arn:aws:states:us-east-1:123:execution:old",
+        sequenceId: "onboarding",
+      });
+      mockSfnSend.mockResolvedValueOnce({});
+
+      const result = await handler(registerEvent);
+
+      expect(result).toEqual({ registered: true });
+      expect(mockSfnSend).toHaveBeenCalledOnce();
+      expect(mockDeleteExecution).toHaveBeenCalledWith(
+        "TestTable",
+        "user@example.com",
+        "onboarding",
+      );
+      expect(mockPutExecution).toHaveBeenCalled();
+    });
+
+    it("handles already-stopped execution gracefully", async () => {
+      mockGetExecution.mockResolvedValueOnce({
+        executionArn: "arn:old",
+        sequenceId: "onboarding",
+      });
+      mockSfnSend.mockRejectedValueOnce(new Error("ExecutionDoesNotExist"));
+
+      const result = await handler(registerEvent);
+
+      expect(result).toEqual({ registered: true });
+      expect(mockDeleteExecution).toHaveBeenCalled();
+    });
+  });
+
+  describe("send action", () => {
+    const sendEvent = {
+      action: "send" as const,
+      templateKey: "onboarding/welcome",
+      subject: "Welcome!",
+      subscriber: { email: "user@example.com", firstName: "Jane" },
+    };
+
+    it("sends email successfully", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce({
+        email: "user@example.com",
+        firstName: "Jane",
+        unsubscribed: false,
+        suppressed: false,
+      });
+
+      const result = await handler(sendEvent);
+
+      expect(result).toEqual({ sent: true, messageId: "msg-123" });
+      expect(mockRenderTemplate).toHaveBeenCalled();
+      expect(mockSendEmail).toHaveBeenCalled();
+      expect(mockWriteSendLog).toHaveBeenCalled();
+    });
+
+    it("skips send when subscriber is unsubscribed", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce({
+        email: "user@example.com",
+        firstName: "Jane",
+        unsubscribed: true,
+        suppressed: false,
+      });
+
+      const result = await handler(sendEvent);
+
+      expect(result).toEqual({ sent: false, reason: "unsubscribed" });
+      expect(mockSendEmail).not.toHaveBeenCalled();
+    });
+
+    it("skips send when subscriber is suppressed", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce({
+        email: "user@example.com",
+        firstName: "Jane",
+        unsubscribed: false,
+        suppressed: true,
+      });
+
+      const result = await handler(sendEvent);
+
+      expect(result).toEqual({ sent: false, reason: "suppressed" });
+      expect(mockSendEmail).not.toHaveBeenCalled();
+    });
+
+    it("sends when profile does not exist yet", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce(null);
+
+      const result = await handler(sendEvent);
+
+      expect(result).toEqual({ sent: true, messageId: "msg-123" });
+    });
+
+    it("formats from address with display name", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce(null);
+
+      await handler(sendEvent);
+
+      const sendCall = mockSendEmail.mock.calls[0][0];
+      expect(sendCall.from).toBe("Example <noreply@example.com>");
+    });
+
+    it("generates unsubscribe URL with token", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce(null);
+
+      await handler(sendEvent);
+
+      expect(mockGenerateToken).toHaveBeenCalledWith("user@example.com", "test-secret");
+      const sendCall = mockSendEmail.mock.calls[0][0];
+      expect(sendCall.unsubscribeUrl).toBe("https://unsub.example.com?token=token-abc");
+    });
+  });
+
+  describe("fire_and_forget action", () => {
+    it("upserts profile then sends email", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce(null);
+
+      const result = await handler({
+        action: "fire_and_forget",
+        templateKey: "promo/sale",
+        subject: "Sale!",
+        subscriber: { email: "user@example.com", firstName: "Jane" },
+      });
+
+      expect(result).toEqual({ sent: true, messageId: "msg-123" });
+      expect(mockUpsertSubscriberProfile).toHaveBeenCalled();
+      expect(mockSendEmail).toHaveBeenCalled();
+    });
+  });
+
+  describe("complete action", () => {
+    it("deletes execution and returns completed", async () => {
+      const result = await handler({
+        action: "complete",
+        sequenceId: "onboarding",
+        subscriber: { email: "user@example.com" },
+        executionArn: "arn:aws:states:us-east-1:123:execution:abc",
+      });
+
+      expect(result).toEqual({ completed: true });
+      expect(mockDeleteExecution).toHaveBeenCalledWith(
+        "TestTable",
+        "user@example.com",
+        "onboarding",
+      );
+    });
+  });
+});

package/src/handlers/__tests__/unsubscribe.test.ts

@@ -0,0 +1,111 @@
+import { vi } from "vitest";
+import type { APIGatewayProxyStructuredResultV2 } from "aws-lambda";
+
+const mockResolveConfig = vi.fn();
+const mockValidateToken = vi.fn();
+const mockSetProfileFlag = vi.fn();
+const mockStopAllExecutions = vi.fn();
+const mockAddToSuppressionList = vi.fn();
+
+vi.mock("../../lib/ssm-config.js", () => ({
+  resolveConfig: () => mockResolveConfig(),
+}));
+
+vi.mock("../../lib/unsubscribe-token.js", () => ({
+  validateToken: (...args: unknown[]) => mockValidateToken(...args),
+}));
+
+vi.mock("../../lib/dynamo-client.js", () => ({
+  setProfileFlag: (...args: unknown[]) => mockSetProfileFlag(...args),
+}));
+
+vi.mock("../../lib/execution-stopper.js", () => ({
+  stopAllExecutions: (...args: unknown[]) => mockStopAllExecutions(...args),
+}));
+
+vi.mock("../../lib/ses-suppression.js", () => ({
+  addToSuppressionList: (...args: unknown[]) => mockAddToSuppressionList(...args),
+}));
+
+const { handler } = await import("../unsubscribe.js");
+
+const CONFIG = {
+  tableName: "TestTable",
+  unsubscribeSecret: "test-secret",
+};
+
+beforeEach(() => {
+  mockResolveConfig.mockReset().mockResolvedValue(CONFIG);
+  mockValidateToken.mockReset();
+  mockSetProfileFlag.mockReset().mockResolvedValue(undefined);
+  mockStopAllExecutions.mockReset().mockResolvedValue(undefined);
+  mockAddToSuppressionList.mockReset().mockResolvedValue(undefined);
+});
+
+describe("unsubscribe handler", () => {
+  it("returns 400 when no token is provided", async () => {
+    const result = (await handler({
+      queryStringParameters: {},
+    })) as APIGatewayProxyStructuredResultV2;
+
+    expect(result.statusCode).toBe(400);
+    expect(result.body).toContain("No unsubscribe token provided");
+  });
+
+  it("returns 400 when queryStringParameters is undefined", async () => {
+    const result = (await handler({})) as APIGatewayProxyStructuredResultV2;
+
+    expect(result.statusCode).toBe(400);
+  });
+
+  it("returns 400 for invalid token", async () => {
+    mockValidateToken.mockReturnValueOnce({
+      valid: false,
+      reason: "invalid signature",
+    });
+
+    const result = (await handler({
+      queryStringParameters: { token: "bad-token" },
+    })) as APIGatewayProxyStructuredResultV2;
+
+    expect(result.statusCode).toBe(400);
+    expect(result.body).toContain("invalid");
+  });
+
+  it("returns 400 for expired token", async () => {
+    mockValidateToken.mockReturnValueOnce({
+      valid: false,
+      reason: "token expired",
+    });
+
+    const result = (await handler({
+      queryStringParameters: { token: "expired-token" },
+    })) as APIGatewayProxyStructuredResultV2;
+
+    expect(result.statusCode).toBe(400);
+    expect(result.body).toContain("expired");
+  });
+
+  it("unsubscribes and stops executions for valid token", async () => {
+    mockValidateToken.mockReturnValueOnce({
+      valid: true,
+      email: "user@example.com",
+      sendTimestamp: "2026-01-01T00:00:00.000Z",
+      expiryTimestamp: "2026-04-01T00:00:00.000Z",
+    });
+
+    const result = (await handler({
+      queryStringParameters: { token: "valid-token" },
+    })) as APIGatewayProxyStructuredResultV2;
+
+    expect(result.statusCode).toBe(200);
+    expect(result.body).toContain("unsubscribed");
+    expect(mockSetProfileFlag).toHaveBeenCalledWith(
+      "TestTable",
+      "user@example.com",
+      "unsubscribed",
+    );
+    expect(mockStopAllExecutions).toHaveBeenCalledWith("TestTable", "user@example.com");
+    expect(mockAddToSuppressionList).toHaveBeenCalledWith("user@example.com", "COMPLAINT");
+  });
+});

package/src/handlers/bounce-handler.ts

@@ -0,0 +1,91 @@
+import type { SNSEvent } from "aws-lambda";
+import { resolveConfig } from "../lib/ssm-config.js";
+import { writeSuppression, setProfileFlag } from "../lib/dynamo-client.js";
+import { stopAllExecutions } from "../lib/execution-stopper.js";
+import { addToSuppressionList } from "../lib/ses-suppression.js";
+import { createLogger } from "../lib/logger.js";
+
+const logger = createLogger("bounce-handler");
+
+interface SESBounceNotification {
+  notificationType: "Bounce";
+  bounce: {
+    bounceType: "Permanent" | "Transient";
+    bouncedRecipients: Array<{ emailAddress: string }>;
+    feedbackId: string;
+  };
+}
+
+interface SESComplaintNotification {
+  notificationType: "Complaint";
+  complaint: {
+    complainedRecipients: Array<{ emailAddress: string }>;
+    feedbackId: string;
+  };
+}
+
+type SESNotification = SESBounceNotification | SESComplaintNotification;
+
+export const handler = async (event: SNSEvent): Promise<void> => {
+  logger.info("BounceHandler invoked", { recordCount: event.Records.length });
+  const config = await resolveConfig();
+
+  for (const record of event.Records) {
+    const notification = JSON.parse(record.Sns.Message) as SESNotification;
+
+    if (notification.notificationType === "Bounce") {
+      if (notification.bounce.bounceType === "Transient") {
+        logger.debug("Ignoring transient bounce", {
+          feedbackId: notification.bounce.feedbackId,
+          recipients: notification.bounce.bouncedRecipients.map((r) => r.emailAddress),
+        });
+        continue;
+      }
+
+      logger.warn("Processing permanent bounce", {
+        bounceType: notification.bounce.bounceType,
+        feedbackId: notification.bounce.feedbackId,
+        recipientCount: notification.bounce.bouncedRecipients.length,
+      });
+
+      for (const recipient of notification.bounce.bouncedRecipients) {
+        const email = recipient.emailAddress;
+        logger.warn("Suppressing bounced subscriber", { email });
+        await writeSuppression(
+          config.tableName,
+          email,
+          "bounce",
+          notification.bounce.bounceType,
+          notification.bounce.feedbackId,
+        );
+        await setProfileFlag(config.tableName, email, "suppressed");
+        await stopAllExecutions(config.tableName, email);
+        await addToSuppressionList(email, "BOUNCE");
+      }
+    }
+
+    if (notification.notificationType === "Complaint") {
+      logger.warn("Processing complaint", {
+        feedbackId: notification.complaint.feedbackId,
+        recipientCount: notification.complaint.complainedRecipients.length,
+      });
+
+      for (const recipient of notification.complaint.complainedRecipients) {
+        const email = recipient.emailAddress;
+        logger.warn("Suppressing complained subscriber", { email });
+        await writeSuppression(
+          config.tableName,
+          email,
+          "complaint",
+          undefined,
+          notification.complaint.feedbackId,
+        );
+        await setProfileFlag(config.tableName, email, "suppressed");
+        await stopAllExecutions(config.tableName, email);
+        await addToSuppressionList(email, "COMPLAINT");
+      }
+    }
+  }
+
+  logger.info("BounceHandler complete");
+};

package/src/handlers/check-condition.ts

@@ -0,0 +1,77 @@
+import type { CheckConditionInput, CheckConditionOutput } from "@step-func-emailer/shared";
+import { resolveConfig } from "../lib/ssm-config.js";
+import { getSubscriberProfile, hasBeenSent } from "../lib/dynamo-client.js";
+import { createLogger } from "../lib/logger.js";
+
+const logger = createLogger("check-condition");
+
+export const handler = async (event: CheckConditionInput): Promise<CheckConditionOutput> => {
+  logger.info("CheckCondition invoked", {
+    check: event.check,
+    email: event.subscriber.email,
+    field: event.field,
+    value: event.value,
+    templateKey: event.templateKey,
+  });
+
+  const config = await resolveConfig();
+
+  switch (event.check) {
+    case "subscriber_field_exists": {
+      const profile = await getSubscriberProfile(config.tableName, event.subscriber.email);
+      if (!profile || !event.field) {
+        logger.debug("Field exists check — no profile or no field", {
+          profileFound: !!profile,
+          field: event.field,
+        });
+        return { result: false };
+      }
+      const value = profile[event.field];
+      const result = value !== undefined && value !== null && value !== "";
+      logger.info("Field exists check result", {
+        email: event.subscriber.email,
+        field: event.field,
+        result,
+      });
+      return { result };
+    }
+
+    case "subscriber_field_equals": {
+      const profile = await getSubscriberProfile(config.tableName, event.subscriber.email);
+      if (!profile || !event.field) {
+        logger.debug("Field equals check — no profile or no field", {
+          profileFound: !!profile,
+          field: event.field,
+        });
+        return { result: false };
+      }
+      const result = profile[event.field] === event.value;
+      logger.info("Field equals check result", {
+        email: event.subscriber.email,
+        field: event.field,
+        expectedValue: event.value,
+        actualValue: profile[event.field],
+        result,
+      });
+      return { result };
+    }
+
+    case "has_been_sent": {
+      if (!event.templateKey) {
+        logger.debug("Has been sent check — no templateKey provided");
+        return { result: false };
+      }
+      const sent = await hasBeenSent(config.tableName, event.subscriber.email, event.templateKey);
+      logger.info("Has been sent check result", {
+        email: event.subscriber.email,
+        templateKey: event.templateKey,
+        result: sent,
+      });
+      return { result: sent };
+    }
+
+    default:
+      logger.warn("Unknown check type", { check: event.check });
+      return { result: false };
+  }
+};