@step-func-emailer/handlers 0.2.0

package/dist/lib/unsubscribe-token.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateToken = generateToken;
+exports.validateToken = validateToken;
+const node_crypto_1 = require("node:crypto");
+const EXPIRY_DAYS = 90;
+function generateToken(email, secret) {
+    const sendTimestamp = new Date().toISOString();
+    const expiry = new Date(Date.now() + EXPIRY_DAYS * 24 * 3600 * 1000).toISOString();
+    const payload = `${email}|${sendTimestamp}|${expiry}`;
+    const signature = (0, node_crypto_1.createHmac)("sha256", secret).update(payload).digest("hex");
+    const token = Buffer.from(`${payload}|${signature}`).toString("base64url");
+    return token;
+}
+function validateToken(token, secret) {
+    try {
+        const decoded = Buffer.from(token, "base64url").toString("utf8");
+        const parts = decoded.split("|");
+        if (parts.length !== 4) {
+            return { valid: false, reason: "malformed token" };
+        }
+        const [email, sendTimestamp, expiryTimestamp, signature] = parts;
+        const payload = `${email}|${sendTimestamp}|${expiryTimestamp}`;
+        const expectedSignature = (0, node_crypto_1.createHmac)("sha256", secret).update(payload).digest("hex");
+        if (signature !== expectedSignature) {
+            return { valid: false, reason: "invalid signature" };
+        }
+        if (new Date(expiryTimestamp) < new Date()) {
+            return { valid: false, reason: "token expired" };
+        }
+        return { valid: true, email, sendTimestamp, expiryTimestamp };
+    }
+    catch {
+        return { valid: false, reason: "invalid token format" };
+    }
+}
+//# sourceMappingURL=unsubscribe-token.js.map

package/dist/lib/unsubscribe-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsubscribe-token.js","sourceRoot":"","sources":["../../src/lib/unsubscribe-token.ts"],"names":[],"mappings":";;AAIA,sCASC;AAcD,sCAyBC;AApDD,6CAAyC;AAEzC,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB,SAAgB,aAAa,CAAC,KAAa,EAAE,MAAc;IACzD,MAAM,aAAa,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IAEnF,MAAM,OAAO,GAAG,GAAG,KAAK,IAAI,aAAa,IAAI,MAAM,EAAE,CAAC;IACtD,MAAM,SAAS,GAAG,IAAA,wBAAU,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE7E,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC3E,OAAO,KAAK,CAAC;AACf,CAAC;AAcD,SAAgB,aAAa,CAAC,KAAa,EAAE,MAAc;IACzD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QACrD,CAAC;QAED,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;QAEjE,MAAM,OAAO,GAAG,GAAG,KAAK,IAAI,aAAa,IAAI,eAAe,EAAE,CAAC;QAC/D,MAAM,iBAAiB,GAAG,IAAA,wBAAU,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAErF,IAAI,SAAS,KAAK,iBAAiB,EAAE,CAAC;YACpC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;QACvD,CAAC;QAED,IAAI,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;YAC3C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;QACnD,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC1D,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@step-func-emailer/handlers",
+  "version": "0.2.0",
+  "description": "Lambda handlers for step-func-emailer",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mdwt/step-func-emailer.git",
+    "directory": "packages/handlers"
+  },
+  "dependencies": {
+    "@aws-lambda-powertools/logger": "^2.31.0",
+    "@aws-sdk/client-dynamodb": "^3.1009.0",
+    "@aws-sdk/client-s3": "^3.1009.0",
+    "@aws-sdk/client-sesv2": "^3.1009.0",
+    "@aws-sdk/client-sfn": "^3.1009.0",
+    "@aws-sdk/client-ssm": "^3.1009.0",
+    "@aws-sdk/util-dynamodb": "^3.996.2",
+    "liquidjs": "^10.25.0",
+    "@step-func-emailer/shared": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/aws-lambda": "^8.10.161"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}

package/src/handlers/__tests__/bounce-handler.test.ts

@@ -0,0 +1,173 @@
+import { vi } from "vitest";
+import type { SNSEvent } from "aws-lambda";
+
+const mockResolveConfig = vi.fn();
+const mockWriteSuppression = 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/dynamo-client.js", () => ({
+  writeSuppression: (...args: unknown[]) => mockWriteSuppression(...args),
+  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("../bounce-handler.js");
+
+const CONFIG = { tableName: "TestTable" };
+
+function snsEvent(message: unknown): SNSEvent {
+  return {
+    Records: [
+      {
+        Sns: { Message: JSON.stringify(message) },
+      },
+    ],
+  } as SNSEvent;
+}
+
+beforeEach(() => {
+  mockResolveConfig.mockReset().mockResolvedValue(CONFIG);
+  mockWriteSuppression.mockReset().mockResolvedValue(undefined);
+  mockSetProfileFlag.mockReset().mockResolvedValue(undefined);
+  mockStopAllExecutions.mockReset().mockResolvedValue(undefined);
+  mockAddToSuppressionList.mockReset().mockResolvedValue(undefined);
+});
+
+describe("bounce-handler", () => {
+  it("suppresses subscriber on permanent bounce", async () => {
+    const event = snsEvent({
+      notificationType: "Bounce",
+      bounce: {
+        bounceType: "Permanent",
+        bouncedRecipients: [{ emailAddress: "bounced@example.com" }],
+        feedbackId: "feedback-1",
+      },
+    });
+
+    await handler(event);
+
+    expect(mockWriteSuppression).toHaveBeenCalledWith(
+      "TestTable",
+      "bounced@example.com",
+      "bounce",
+      "Permanent",
+      "feedback-1",
+    );
+    expect(mockSetProfileFlag).toHaveBeenCalledWith(
+      "TestTable",
+      "bounced@example.com",
+      "suppressed",
+    );
+    expect(mockStopAllExecutions).toHaveBeenCalledWith("TestTable", "bounced@example.com");
+    expect(mockAddToSuppressionList).toHaveBeenCalledWith("bounced@example.com", "BOUNCE");
+  });
+
+  it("ignores transient bounces", async () => {
+    const event = snsEvent({
+      notificationType: "Bounce",
+      bounce: {
+        bounceType: "Transient",
+        bouncedRecipients: [{ emailAddress: "user@example.com" }],
+        feedbackId: "feedback-2",
+      },
+    });
+
+    await handler(event);
+
+    expect(mockWriteSuppression).not.toHaveBeenCalled();
+    expect(mockSetProfileFlag).not.toHaveBeenCalled();
+    expect(mockStopAllExecutions).not.toHaveBeenCalled();
+    expect(mockAddToSuppressionList).not.toHaveBeenCalled();
+  });
+
+  it("suppresses subscriber on complaint", async () => {
+    const event = snsEvent({
+      notificationType: "Complaint",
+      complaint: {
+        complainedRecipients: [{ emailAddress: "complainer@example.com" }],
+        feedbackId: "feedback-3",
+      },
+    });
+
+    await handler(event);
+
+    expect(mockWriteSuppression).toHaveBeenCalledWith(
+      "TestTable",
+      "complainer@example.com",
+      "complaint",
+      undefined,
+      "feedback-3",
+    );
+    expect(mockSetProfileFlag).toHaveBeenCalledWith(
+      "TestTable",
+      "complainer@example.com",
+      "suppressed",
+    );
+    expect(mockStopAllExecutions).toHaveBeenCalledWith("TestTable", "complainer@example.com");
+    expect(mockAddToSuppressionList).toHaveBeenCalledWith("complainer@example.com", "COMPLAINT");
+  });
+
+  it("handles multiple recipients in a bounce", async () => {
+    const event = snsEvent({
+      notificationType: "Bounce",
+      bounce: {
+        bounceType: "Permanent",
+        bouncedRecipients: [{ emailAddress: "a@example.com" }, { emailAddress: "b@example.com" }],
+        feedbackId: "feedback-4",
+      },
+    });
+
+    await handler(event);
+
+    expect(mockWriteSuppression).toHaveBeenCalledTimes(2);
+    expect(mockSetProfileFlag).toHaveBeenCalledTimes(2);
+    expect(mockStopAllExecutions).toHaveBeenCalledTimes(2);
+  });
+
+  it("handles multiple SNS records", async () => {
+    const event: SNSEvent = {
+      Records: [
+        {
+          Sns: {
+            Message: JSON.stringify({
+              notificationType: "Bounce",
+              bounce: {
+                bounceType: "Permanent",
+                bouncedRecipients: [{ emailAddress: "a@example.com" }],
+                feedbackId: "f1",
+              },
+            }),
+          },
+        },
+        {
+          Sns: {
+            Message: JSON.stringify({
+              notificationType: "Complaint",
+              complaint: {
+                complainedRecipients: [{ emailAddress: "b@example.com" }],
+                feedbackId: "f2",
+              },
+            }),
+          },
+        },
+      ],
+    } as SNSEvent;
+
+    await handler(event);
+
+    expect(mockWriteSuppression).toHaveBeenCalledTimes(2);
+  });
+});

package/src/handlers/__tests__/check-condition.test.ts

@@ -0,0 +1,172 @@
+import { vi } from "vitest";
+
+const mockResolveConfig = vi.fn();
+const mockGetSubscriberProfile = vi.fn();
+const mockHasBeenSent = vi.fn();
+
+vi.mock("../../lib/ssm-config.js", () => ({
+  resolveConfig: () => mockResolveConfig(),
+}));
+
+vi.mock("../../lib/dynamo-client.js", () => ({
+  getSubscriberProfile: (...args: unknown[]) => mockGetSubscriberProfile(...args),
+  hasBeenSent: (...args: unknown[]) => mockHasBeenSent(...args),
+}));
+
+const { handler } = await import("../check-condition.js");
+
+const CONFIG = { tableName: "TestTable" };
+
+beforeEach(() => {
+  mockResolveConfig.mockReset().mockResolvedValue(CONFIG);
+  mockGetSubscriberProfile.mockReset();
+  mockHasBeenSent.mockReset();
+});
+
+describe("check-condition handler", () => {
+  describe("subscriber_field_exists", () => {
+    it("returns true when field exists and has a value", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce({
+        platform: "web",
+      });
+
+      const result = await handler({
+        check: "subscriber_field_exists",
+        field: "platform",
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: true });
+    });
+
+    it("returns false when field is empty string", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce({
+        platform: "",
+      });
+
+      const result = await handler({
+        check: "subscriber_field_exists",
+        field: "platform",
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: false });
+    });
+
+    it("returns false when field is undefined", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce({});
+
+      const result = await handler({
+        check: "subscriber_field_exists",
+        field: "platform",
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: false });
+    });
+
+    it("returns false when profile does not exist", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce(null);
+
+      const result = await handler({
+        check: "subscriber_field_exists",
+        field: "platform",
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: false });
+    });
+  });
+
+  describe("subscriber_field_equals", () => {
+    it("returns true when field matches value", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce({
+        plan: "pro",
+      });
+
+      const result = await handler({
+        check: "subscriber_field_equals",
+        field: "plan",
+        value: "pro",
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: true });
+    });
+
+    it("returns false when field does not match", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce({
+        plan: "free",
+      });
+
+      const result = await handler({
+        check: "subscriber_field_equals",
+        field: "plan",
+        value: "pro",
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: false });
+    });
+
+    it("returns false when profile is null", async () => {
+      mockGetSubscriberProfile.mockResolvedValueOnce(null);
+
+      const result = await handler({
+        check: "subscriber_field_equals",
+        field: "plan",
+        value: "pro",
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: false });
+    });
+  });
+
+  describe("has_been_sent", () => {
+    it("returns true when template has been sent", async () => {
+      mockHasBeenSent.mockResolvedValueOnce(true);
+
+      const result = await handler({
+        check: "has_been_sent",
+        templateKey: "onboarding/welcome",
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: true });
+    });
+
+    it("returns false when template has not been sent", async () => {
+      mockHasBeenSent.mockResolvedValueOnce(false);
+
+      const result = await handler({
+        check: "has_been_sent",
+        templateKey: "onboarding/welcome",
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: false });
+    });
+
+    it("returns false when templateKey is missing", async () => {
+      const result = await handler({
+        check: "has_been_sent",
+        subscriber: { email: "user@example.com" },
+      } as any);
+
+      expect(result).toEqual({ result: false });
+      expect(mockHasBeenSent).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("unknown check", () => {
+    it("returns false for unknown check type", async () => {
+      const result = await handler({
+        check: "unknown_check" as any,
+        subscriber: { email: "user@example.com" },
+      });
+
+      expect(result).toEqual({ result: false });
+    });
+  });
+});

package/src/handlers/__tests__/engagement-handler.test.ts

@@ -0,0 +1,161 @@
+import { vi } from "vitest";
+import type { SNSEvent } from "aws-lambda";
+
+const mockResolveConfig = vi.fn();
+const mockSend = vi.fn();
+
+vi.mock("../../lib/ssm-config.js", () => ({
+  resolveConfig: () => mockResolveConfig(),
+}));
+
+vi.mock("@aws-sdk/client-dynamodb", () => ({
+  DynamoDBClient: class {
+    send = mockSend;
+  },
+  PutItemCommand: class {
+    input: unknown;
+    constructor(input: unknown) {
+      this.input = input;
+    }
+  },
+}));
+
+// Re-export real marshall/unmarshall
+vi.mock("@aws-sdk/util-dynamodb", async () => {
+  const actual = await vi.importActual("@aws-sdk/util-dynamodb");
+  return actual;
+});
+
+const { handler } = await import("../engagement-handler.js");
+
+const CONFIG = {
+  tableName: "TestTable",
+  eventsTableName: "EventsTable",
+};
+
+function snsEvent(message: unknown): SNSEvent {
+  return {
+    Records: [{ Sns: { Message: JSON.stringify(message) } }],
+  } as SNSEvent;
+}
+
+const baseHeaders = [
+  { name: "Subject", value: "Welcome!" },
+  { name: "X-Template-Key", value: "onboarding/welcome" },
+  { name: "X-Sequence-Id", value: "onboarding" },
+];
+
+beforeEach(() => {
+  mockResolveConfig.mockReset().mockResolvedValue(CONFIG);
+  mockSend.mockReset().mockResolvedValue({});
+});
+
+describe("engagement-handler", () => {
+  it("writes delivery event to events table", async () => {
+    const event = snsEvent({
+      eventType: "Delivery",
+      mail: {
+        messageId: "msg-1",
+        destination: ["user@example.com"],
+        headers: baseHeaders,
+      },
+      delivery: { timestamp: "2026-01-15T10:00:00.000Z" },
+    });
+
+    await handler(event);
+
+    expect(mockSend).toHaveBeenCalledOnce();
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd.input.TableName).toBe("EventsTable");
+  });
+
+  it("writes click event with link URL", async () => {
+    const event = snsEvent({
+      eventType: "Click",
+      mail: {
+        messageId: "msg-2",
+        destination: ["user@example.com"],
+        headers: baseHeaders,
+      },
+      click: {
+        timestamp: "2026-01-15T10:00:00.000Z",
+        link: "https://example.com/promo",
+        userAgent: "Mozilla/5.0",
+      },
+    });
+
+    await handler(event);
+
+    expect(mockSend).toHaveBeenCalledOnce();
+  });
+
+  it("writes open event with user agent", async () => {
+    const event = snsEvent({
+      eventType: "Open",
+      mail: {
+        messageId: "msg-3",
+        destination: ["user@example.com"],
+        headers: baseHeaders,
+      },
+      open: {
+        timestamp: "2026-01-15T10:00:00.000Z",
+        userAgent: "Apple Mail",
+      },
+    });
+
+    await handler(event);
+
+    expect(mockSend).toHaveBeenCalledOnce();
+  });
+
+  it("handles bounce event with multiple recipients", async () => {
+    const event = snsEvent({
+      eventType: "Bounce",
+      mail: {
+        messageId: "msg-4",
+        destination: ["a@example.com"],
+        headers: baseHeaders,
+      },
+      bounce: {
+        bounceType: "Permanent",
+        bouncedRecipients: [{ emailAddress: "a@example.com" }, { emailAddress: "b@example.com" }],
+        timestamp: "2026-01-15T10:00:00.000Z",
+      },
+    });
+
+    await handler(event);
+
+    expect(mockSend).toHaveBeenCalledTimes(2);
+  });
+
+  it("defaults sequenceId to fire_and_forget when header missing", async () => {
+    const event = snsEvent({
+      eventType: "Delivery",
+      mail: {
+        messageId: "msg-5",
+        destination: ["user@example.com"],
+        headers: [{ name: "Subject", value: "Hello" }],
+      },
+      delivery: { timestamp: "2026-01-15T10:00:00.000Z" },
+    });
+
+    await handler(event);
+
+    expect(mockSend).toHaveBeenCalledOnce();
+  });
+
+  it("skips unknown event types", async () => {
+    const event = snsEvent({
+      eventType: "UnknownType",
+      mail: {
+        messageId: "msg-6",
+        destination: ["user@example.com"],
+        headers: baseHeaders,
+      },
+    });
+
+    await handler(event);
+
+    expect(mockSend).not.toHaveBeenCalled();
+  });
+});