@step-func-emailer/handlers 0.2.0

package/src/lib/__tests__/dynamo-client.test.ts

@@ -0,0 +1,346 @@
+import { vi } from "vitest";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+
+const mockSend = vi.fn();
+class MockCommand {
+  _type: string;
+  input: unknown;
+  constructor(type: string, input: unknown) {
+    this._type = type;
+    this.input = input;
+  }
+}
+vi.mock("@aws-sdk/client-dynamodb", () => ({
+  DynamoDBClient: class {
+    send = mockSend;
+  },
+  GetItemCommand: class extends MockCommand {
+    constructor(input: unknown) {
+      super("GetItem", input);
+    }
+  },
+  PutItemCommand: class extends MockCommand {
+    constructor(input: unknown) {
+      super("PutItem", input);
+    }
+  },
+  UpdateItemCommand: class extends MockCommand {
+    constructor(input: unknown) {
+      super("UpdateItem", input);
+    }
+  },
+  DeleteItemCommand: class extends MockCommand {
+    constructor(input: unknown) {
+      super("DeleteItem", input);
+    }
+  },
+  QueryCommand: class extends MockCommand {
+    constructor(input: unknown) {
+      super("Query", input);
+    }
+  },
+}));
+
+const {
+  getSubscriberProfile,
+  upsertSubscriberProfile,
+  extractAttributes,
+  getExecution,
+  putExecution,
+  deleteExecution,
+  getAllExecutions,
+  writeSendLog,
+  hasBeenSent,
+  writeSuppression,
+  setProfileFlag,
+} = await import("../dynamo-client.js");
+
+beforeEach(() => {
+  mockSend.mockReset();
+});
+
+describe("getSubscriberProfile", () => {
+  it("returns profile when item exists", async () => {
+    const profile = {
+      PK: "SUB#user@example.com",
+      SK: "PROFILE",
+      email: "user@example.com",
+      firstName: "Jane",
+      unsubscribed: false,
+      suppressed: false,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    };
+    mockSend.mockResolvedValueOnce({ Item: marshall(profile) });
+
+    const result = await getSubscriberProfile("TestTable", "user@example.com");
+    expect(result).toEqual(profile);
+  });
+
+  it("returns null when item does not exist", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    const result = await getSubscriberProfile("TestTable", "nobody@example.com");
+    expect(result).toBeNull();
+  });
+});
+
+describe("upsertSubscriberProfile", () => {
+  it("sends UpdateItemCommand with correct key", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    await upsertSubscriberProfile("TestTable", {
+      email: "user@example.com",
+      firstName: "Jane",
+    });
+
+    expect(mockSend).toHaveBeenCalledOnce();
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd._type).toBe("UpdateItem");
+    expect(cmd.input.TableName).toBe("TestTable");
+    // Verify key contains the correct PK
+    const key = unmarshall(cmd.input.Key);
+    expect(key.PK).toBe("SUB#user@example.com");
+    expect(key.SK).toBe("PROFILE");
+  });
+
+  it("includes attribute expressions for subscriber attributes", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    await upsertSubscriberProfile("TestTable", {
+      email: "user@example.com",
+      firstName: "Jane",
+      attributes: { platform: "web", plan: "pro" },
+    });
+
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd.input.UpdateExpression).toContain("#attr_platform = :attr_platform");
+    expect(cmd.input.UpdateExpression).toContain("#attr_plan = :attr_plan");
+    expect(cmd.input.UpdateExpression).not.toContain("attributes.#attr_");
+    expect(cmd.input.ExpressionAttributeNames?.["#attr_platform"]).toBe("platform");
+  });
+});
+
+describe("extractAttributes", () => {
+  it("returns only non-system keys", () => {
+    const result = extractAttributes({
+      PK: "SUB#user@example.com",
+      SK: "PROFILE",
+      email: "user@example.com",
+      firstName: "Jane",
+      unsubscribed: false,
+      suppressed: false,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+      platform: "web",
+      country: "US",
+    });
+    expect(result).toEqual({ platform: "web", country: "US" });
+  });
+
+  it("returns empty object when no custom attributes", () => {
+    const result = extractAttributes({
+      PK: "SUB#user@example.com",
+      SK: "PROFILE",
+      email: "user@example.com",
+      firstName: "Jane",
+      unsubscribed: false,
+      suppressed: false,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    });
+    expect(result).toEqual({});
+  });
+});
+
+describe("getExecution", () => {
+  it("returns execution when found", async () => {
+    const exec = {
+      PK: "SUB#user@example.com",
+      SK: "EXEC#onboarding",
+      executionArn: "arn:aws:states:us-east-1:123:execution:abc",
+      sequenceId: "onboarding",
+      startedAt: "2026-01-01T00:00:00.000Z",
+    };
+    mockSend.mockResolvedValueOnce({ Item: marshall(exec) });
+
+    const result = await getExecution("TestTable", "user@example.com", "onboarding");
+    expect(result).toEqual(exec);
+  });
+
+  it("returns null when not found", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    const result = await getExecution("TestTable", "user@example.com", "onboarding");
+    expect(result).toBeNull();
+  });
+});
+
+describe("putExecution", () => {
+  it("stores execution with correct keys", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    await putExecution(
+      "TestTable",
+      "user@example.com",
+      "onboarding",
+      "arn:aws:states:us-east-1:123:execution:abc",
+    );
+
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd._type).toBe("PutItem");
+    const item = unmarshall(cmd.input.Item);
+    expect(item.PK).toBe("SUB#user@example.com");
+    expect(item.SK).toBe("EXEC#onboarding");
+    expect(item.executionArn).toBe("arn:aws:states:us-east-1:123:execution:abc");
+    expect(item.sequenceId).toBe("onboarding");
+    expect(item.startedAt).toBeTruthy();
+  });
+});
+
+describe("deleteExecution", () => {
+  it("deletes with correct key", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    await deleteExecution("TestTable", "user@example.com", "onboarding");
+
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd._type).toBe("DeleteItem");
+    const key = unmarshall(cmd.input.Key);
+    expect(key.PK).toBe("SUB#user@example.com");
+    expect(key.SK).toBe("EXEC#onboarding");
+  });
+});
+
+describe("getAllExecutions", () => {
+  it("returns all executions for subscriber", async () => {
+    const execs = [
+      {
+        PK: "SUB#user@example.com",
+        SK: "EXEC#onboarding",
+        executionArn: "arn:1",
+        sequenceId: "onboarding",
+        startedAt: "2026-01-01T00:00:00.000Z",
+      },
+      {
+        PK: "SUB#user@example.com",
+        SK: "EXEC#win-back",
+        executionArn: "arn:2",
+        sequenceId: "win-back",
+        startedAt: "2026-01-02T00:00:00.000Z",
+      },
+    ];
+    mockSend.mockResolvedValueOnce({
+      Items: execs.map((e) => marshall(e)),
+    });
+
+    const result = await getAllExecutions("TestTable", "user@example.com");
+    expect(result).toHaveLength(2);
+    expect(result[0].sequenceId).toBe("onboarding");
+    expect(result[1].sequenceId).toBe("win-back");
+  });
+
+  it("returns empty array when no executions exist", async () => {
+    mockSend.mockResolvedValueOnce({ Items: [] });
+
+    const result = await getAllExecutions("TestTable", "user@example.com");
+    expect(result).toEqual([]);
+  });
+});
+
+describe("writeSendLog", () => {
+  it("writes send log with TTL", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    await writeSendLog("TestTable", "user@example.com", {
+      templateKey: "onboarding/welcome",
+      sequenceId: "onboarding",
+      subject: "Welcome!",
+      sesMessageId: "msg-123",
+    });
+
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd._type).toBe("PutItem");
+    const item = unmarshall(cmd.input.Item);
+    expect(item.PK).toBe("SUB#user@example.com");
+    expect(item.SK).toMatch(/^SENT#/);
+    expect(item.templateKey).toBe("onboarding/welcome");
+    expect(item.ttl).toBeGreaterThan(0);
+  });
+});
+
+describe("hasBeenSent", () => {
+  it("returns true when matching send log exists", async () => {
+    mockSend.mockResolvedValueOnce({ Count: 1, Items: [{}] });
+
+    const result = await hasBeenSent("TestTable", "user@example.com", "onboarding/welcome");
+    expect(result).toBe(true);
+  });
+
+  it("returns false when no matching send log", async () => {
+    mockSend.mockResolvedValueOnce({ Count: 0, Items: [] });
+
+    const result = await hasBeenSent("TestTable", "user@example.com", "onboarding/welcome");
+    expect(result).toBe(false);
+  });
+});
+
+describe("writeSuppression", () => {
+  it("writes bounce suppression record", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    await writeSuppression(
+      "TestTable",
+      "user@example.com",
+      "bounce",
+      "Permanent",
+      "feedback-id-123",
+    );
+
+    const cmd = mockSend.mock.calls[0][0];
+    const item = unmarshall(cmd.input.Item);
+    expect(item.PK).toBe("SUB#user@example.com");
+    expect(item.SK).toBe("SUPPRESSION");
+    expect(item.reason).toBe("bounce");
+    expect(item.bounceType).toBe("Permanent");
+    expect(item.sesNotificationId).toBe("feedback-id-123");
+  });
+
+  it("writes complaint suppression without bounceType", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    await writeSuppression(
+      "TestTable",
+      "user@example.com",
+      "complaint",
+      undefined,
+      "feedback-id-456",
+    );
+
+    const cmd = mockSend.mock.calls[0][0];
+    const item = unmarshall(cmd.input.Item);
+    expect(item.reason).toBe("complaint");
+    expect(item.bounceType).toBeUndefined();
+  });
+});
+
+describe("setProfileFlag", () => {
+  it("sets unsubscribed flag", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    await setProfileFlag("TestTable", "user@example.com", "unsubscribed");
+
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd._type).toBe("UpdateItem");
+    expect(cmd.input.ExpressionAttributeNames?.["#flag"]).toBe("unsubscribed");
+  });
+
+  it("sets suppressed flag", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    await setProfileFlag("TestTable", "user@example.com", "suppressed");
+
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd.input.ExpressionAttributeNames?.["#flag"]).toBe("suppressed");
+  });
+});

package/src/lib/__tests__/execution-stopper.test.ts

@@ -0,0 +1,68 @@
+import { vi } from "vitest";
+
+const mockSfnSend = vi.fn();
+vi.mock("@aws-sdk/client-sfn", () => ({
+  SFNClient: class {
+    send = mockSfnSend;
+  },
+  StopExecutionCommand: class {
+    input: unknown;
+    constructor(input: unknown) {
+      this.input = input;
+    }
+  },
+}));
+
+const mockGetAllExecutions = vi.fn();
+const mockDeleteExecution = vi.fn();
+vi.mock("../dynamo-client.js", () => ({
+  getAllExecutions: (...args: unknown[]) => mockGetAllExecutions(...args),
+  deleteExecution: (...args: unknown[]) => mockDeleteExecution(...args),
+}));
+
+const { stopAllExecutions } = await import("../execution-stopper.js");
+
+beforeEach(() => {
+  mockSfnSend.mockReset();
+  mockGetAllExecutions.mockReset();
+  mockDeleteExecution.mockReset();
+});
+
+describe("stopAllExecutions", () => {
+  it("stops and deletes all active executions", async () => {
+    mockGetAllExecutions.mockResolvedValueOnce([
+      { executionArn: "arn:1", sequenceId: "onboarding" },
+      { executionArn: "arn:2", sequenceId: "win-back" },
+    ]);
+    mockSfnSend.mockResolvedValue({});
+    mockDeleteExecution.mockResolvedValue(undefined);
+
+    await stopAllExecutions("TestTable", "user@example.com");
+
+    expect(mockSfnSend).toHaveBeenCalledTimes(2);
+    expect(mockDeleteExecution).toHaveBeenCalledTimes(2);
+    expect(mockDeleteExecution).toHaveBeenCalledWith("TestTable", "user@example.com", "onboarding");
+    expect(mockDeleteExecution).toHaveBeenCalledWith("TestTable", "user@example.com", "win-back");
+  });
+
+  it("does nothing when no executions exist", async () => {
+    mockGetAllExecutions.mockResolvedValueOnce([]);
+
+    await stopAllExecutions("TestTable", "user@example.com");
+
+    expect(mockSfnSend).not.toHaveBeenCalled();
+    expect(mockDeleteExecution).not.toHaveBeenCalled();
+  });
+
+  it("continues when SFN stop fails (already stopped)", async () => {
+    mockGetAllExecutions.mockResolvedValueOnce([
+      { executionArn: "arn:1", sequenceId: "onboarding" },
+    ]);
+    mockSfnSend.mockRejectedValueOnce(new Error("ExecutionDoesNotExist"));
+    mockDeleteExecution.mockResolvedValue(undefined);
+
+    await expect(stopAllExecutions("TestTable", "user@example.com")).resolves.toBeUndefined();
+
+    expect(mockDeleteExecution).toHaveBeenCalledOnce();
+  });
+});

package/src/lib/__tests__/ses-sender.test.ts

@@ -0,0 +1,85 @@
+import { vi } from "vitest";
+
+const mockSend = vi.fn();
+vi.mock("@aws-sdk/client-sesv2", () => ({
+  SESv2Client: class {
+    send = mockSend;
+  },
+  SendEmailCommand: class {
+    input: unknown;
+    constructor(input: unknown) {
+      this.input = input;
+    }
+  },
+}));
+
+const { sendEmail } = await import("../ses-sender.js");
+
+beforeEach(() => {
+  mockSend.mockReset();
+});
+
+describe("sendEmail", () => {
+  const defaultParams = {
+    from: "Test <noreply@example.com>",
+    to: "user@example.com",
+    subject: "Welcome!",
+    htmlBody: "<h1>Hello</h1>",
+    configurationSetName: "my-config-set",
+    unsubscribeUrl: "https://unsub.example.com?token=abc",
+    templateKey: "onboarding/welcome",
+    sequenceId: "onboarding",
+  };
+
+  it("sends email and returns messageId", async () => {
+    mockSend.mockResolvedValueOnce({ MessageId: "ses-msg-123" });
+
+    const messageId = await sendEmail(defaultParams);
+
+    expect(messageId).toBe("ses-msg-123");
+    expect(mockSend).toHaveBeenCalledOnce();
+  });
+
+  it("returns 'unknown' when MessageId is missing", async () => {
+    mockSend.mockResolvedValueOnce({});
+
+    const messageId = await sendEmail(defaultParams);
+    expect(messageId).toBe("unknown");
+  });
+
+  it("includes List-Unsubscribe headers", async () => {
+    mockSend.mockResolvedValueOnce({ MessageId: "msg-1" });
+
+    await sendEmail(defaultParams);
+
+    const cmd = mockSend.mock.calls[0][0];
+    const headers = cmd.input.Content.Simple.Headers;
+    expect(headers).toContainEqual({
+      Name: "List-Unsubscribe",
+      Value: `<${defaultParams.unsubscribeUrl}>`,
+    });
+    expect(headers).toContainEqual({
+      Name: "List-Unsubscribe-Post",
+      Value: "List-Unsubscribe=One-Click",
+    });
+  });
+
+  it("sets correct destination and from address", async () => {
+    mockSend.mockResolvedValueOnce({ MessageId: "msg-1" });
+
+    await sendEmail(defaultParams);
+
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd.input.FromEmailAddress).toBe(defaultParams.from);
+    expect(cmd.input.Destination.ToAddresses).toEqual([defaultParams.to]);
+  });
+
+  it("uses the configuration set name", async () => {
+    mockSend.mockResolvedValueOnce({ MessageId: "msg-1" });
+
+    await sendEmail(defaultParams);
+
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd.input.ConfigurationSetName).toBe("my-config-set");
+  });
+});

package/src/lib/__tests__/ssm-config.test.ts

@@ -0,0 +1,85 @@
+import { vi } from "vitest";
+
+const mockSend = vi.fn();
+vi.mock("@aws-sdk/client-ssm", () => ({
+  SSMClient: class {
+    send = mockSend;
+  },
+  GetParameterCommand: class {
+    input: unknown;
+    constructor(input: unknown) {
+      this.input = input;
+    }
+  },
+}));
+
+// Must import after mock setup
+const { getParameter, resolveConfig } = await import("../ssm-config.js");
+
+beforeEach(() => {
+  mockSend.mockReset();
+});
+
+describe("getParameter", () => {
+  it("fetches from SSM and returns value", async () => {
+    mockSend.mockResolvedValueOnce({
+      Parameter: { Value: "my-table" },
+    });
+
+    const value = await getParameter("/test/param");
+    expect(value).toBe("my-table");
+    expect(mockSend).toHaveBeenCalledOnce();
+  });
+
+  it("throws when parameter not found", async () => {
+    mockSend.mockResolvedValueOnce({ Parameter: {} });
+
+    await expect(getParameter("/test/missing")).rejects.toThrow("SSM parameter not found");
+  });
+
+  it("caches values for subsequent calls", async () => {
+    mockSend.mockResolvedValueOnce({
+      Parameter: { Value: "cached-value" },
+    });
+
+    const v1 = await getParameter("/test/cached");
+    const v2 = await getParameter("/test/cached");
+
+    expect(v1).toBe("cached-value");
+    expect(v2).toBe("cached-value");
+    expect(mockSend).toHaveBeenCalledOnce();
+  });
+});
+
+describe("resolveConfig", () => {
+  it("resolves all 8 SSM parameters", async () => {
+    const params: Record<string, string> = {
+      "table-name": "MainTable",
+      "events-table-name": "EventsTable",
+      "template-bucket": "my-bucket",
+      "default-from-email": "noreply@example.com",
+      "default-from-name": "Example",
+      "ses-config-set": "my-config-set",
+      "unsubscribe-base-url": "https://unsub.example.com",
+      "unsubscribe-secret": "secret123",
+    };
+
+    mockSend.mockImplementation(async (cmd: { input: { Name: string } }) => {
+      const suffix = cmd.input.Name.split("/").pop()!;
+      const value = params[suffix];
+      if (!value) throw new Error(`Unexpected param: ${cmd.input.Name}`);
+      return { Parameter: { Value: value } };
+    });
+
+    const config = await resolveConfig();
+
+    expect(config.tableName).toBe("MainTable");
+    expect(config.eventsTableName).toBe("EventsTable");
+    expect(config.templateBucket).toBe("my-bucket");
+    expect(config.defaultFromEmail).toBe("noreply@example.com");
+    expect(config.defaultFromName).toBe("Example");
+    expect(config.sesConfigSet).toBe("my-config-set");
+    expect(config.unsubscribeBaseUrl).toBe("https://unsub.example.com");
+    expect(config.unsubscribeSecret).toBe("secret123");
+  });
+});

package/src/lib/__tests__/template-renderer.test.ts

@@ -0,0 +1,96 @@
+import { vi } from "vitest";
+
+const mockSend = vi.fn();
+vi.mock("@aws-sdk/client-s3", () => ({
+  S3Client: class {
+    send = mockSend;
+  },
+  GetObjectCommand: class {
+    input: unknown;
+    constructor(input: unknown) {
+      this.input = input;
+    }
+  },
+}));
+
+const { renderTemplate } = await import("../template-renderer.js");
+
+beforeEach(() => {
+  mockSend.mockReset();
+});
+
+describe("renderTemplate", () => {
+  it("fetches template from S3 and renders with LiquidJS", async () => {
+    mockSend.mockResolvedValueOnce({
+      Body: {
+        transformToString: () => Promise.resolve("<h1>Hello {{ firstName }}</h1>"),
+      },
+    });
+
+    const result = await renderTemplate("my-bucket", "welcome", {
+      email: "user@example.com",
+      firstName: "Jane",
+      unsubscribeUrl: "https://unsub.example.com",
+      currentYear: 2026,
+    });
+
+    expect(result).toBe("<h1>Hello Jane</h1>");
+  });
+
+  it("fetches template with .html extension", async () => {
+    mockSend.mockResolvedValueOnce({
+      Body: {
+        transformToString: () => Promise.resolve("<p>Hi</p>"),
+      },
+    });
+
+    await renderTemplate("my-bucket", "onboarding/step1", {
+      email: "user@example.com",
+      firstName: "Jane",
+      unsubscribeUrl: "https://unsub.example.com",
+      currentYear: 2026,
+    });
+
+    const cmd = mockSend.mock.calls[0][0];
+    expect(cmd.input.Bucket).toBe("my-bucket");
+    expect(cmd.input.Key).toBe("onboarding/step1.html");
+  });
+
+  it("renders multiple Liquid variables", async () => {
+    mockSend.mockResolvedValueOnce({
+      Body: {
+        transformToString: () =>
+          Promise.resolve(
+            "Hi {{ firstName }}, your email is {{ email }}. Year: {{ currentYear }}. <a href='{{ unsubscribeUrl }}'>Unsub</a>",
+          ),
+      },
+    });
+
+    const result = await renderTemplate("my-bucket", "multi-var", {
+      email: "jane@example.com",
+      firstName: "Jane",
+      unsubscribeUrl: "https://unsub.example.com?token=abc",
+      currentYear: 2026,
+    });
+
+    expect(result).toContain("Jane");
+    expect(result).toContain("jane@example.com");
+    expect(result).toContain("2026");
+    expect(result).toContain("https://unsub.example.com?token=abc");
+  });
+
+  it("handles empty template body gracefully", async () => {
+    mockSend.mockResolvedValueOnce({
+      Body: { transformToString: () => Promise.resolve("") },
+    });
+
+    const result = await renderTemplate("my-bucket", "empty", {
+      email: "user@example.com",
+      firstName: "Jane",
+      unsubscribeUrl: "https://unsub.example.com",
+      currentYear: 2026,
+    });
+
+    expect(result).toBe("");
+  });
+});