@step-func-emailer/handlers 0.2.0

package/src/handlers/engagement-handler.ts

@@ -0,0 +1,169 @@
+import type { SNSEvent } from "aws-lambda";
+import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
+import { marshall } from "@aws-sdk/util-dynamodb";
+import { subscriberPK, eventSK, EVENT_TTL_DAYS } from "@step-func-emailer/shared";
+import type { EmailEventType } from "@step-func-emailer/shared";
+import { resolveConfig } from "../lib/ssm-config.js";
+import { createLogger } from "../lib/logger.js";
+
+const logger = createLogger("engagement-handler");
+const dynamo = new DynamoDBClient({});
+
+interface SESMailHeader {
+  name: string;
+  value: string;
+}
+
+interface SESMail {
+  messageId: string;
+  destination: string[];
+  headers: SESMailHeader[];
+}
+
+interface SESDeliveryNotification {
+  eventType: "Delivery";
+  mail: SESMail;
+  delivery: { timestamp: string };
+}
+
+interface SESOpenNotification {
+  eventType: "Open";
+  mail: SESMail;
+  open: { timestamp: string; userAgent?: string };
+}
+
+interface SESClickNotification {
+  eventType: "Click";
+  mail: SESMail;
+  click: { timestamp: string; link: string; userAgent?: string };
+}
+
+interface SESBounceNotification {
+  eventType: "Bounce";
+  mail: SESMail;
+  bounce: {
+    bounceType: string;
+    bouncedRecipients: Array<{ emailAddress: string }>;
+    timestamp: string;
+  };
+}
+
+interface SESComplaintNotification {
+  eventType: "Complaint";
+  mail: SESMail;
+  complaint: {
+    complainedRecipients: Array<{ emailAddress: string }>;
+    timestamp: string;
+  };
+}
+
+type SESEventNotification =
+  | SESDeliveryNotification
+  | SESOpenNotification
+  | SESClickNotification
+  | SESBounceNotification
+  | SESComplaintNotification;
+
+function getHeader(headers: SESMailHeader[], name: string): string {
+  return headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
+}
+
+function extractRecipients(notification: SESEventNotification): string[] {
+  if (notification.eventType === "Bounce") {
+    return notification.bounce.bouncedRecipients.map((r) => r.emailAddress);
+  }
+  if (notification.eventType === "Complaint") {
+    return notification.complaint.complainedRecipients.map((r) => r.emailAddress);
+  }
+  return notification.mail.destination;
+}
+
+function extractTimestamp(notification: SESEventNotification): string {
+  switch (notification.eventType) {
+    case "Delivery":
+      return notification.delivery.timestamp;
+    case "Open":
+      return notification.open.timestamp;
+    case "Click":
+      return notification.click.timestamp;
+    case "Bounce":
+      return notification.bounce.timestamp;
+    case "Complaint":
+      return notification.complaint.timestamp;
+  }
+}
+
+const EVENT_TYPE_MAP: Record<string, EmailEventType> = {
+  Delivery: "delivery",
+  Open: "open",
+  Click: "click",
+  Bounce: "bounce",
+  Complaint: "complaint",
+};
+
+export const handler = async (event: SNSEvent): Promise<void> => {
+  logger.info("EngagementHandler invoked", { recordCount: event.Records.length });
+  const config = await resolveConfig();
+
+  for (const record of event.Records) {
+    const notification = JSON.parse(record.Sns.Message) as SESEventNotification;
+    const eventType = EVENT_TYPE_MAP[notification.eventType];
+    if (!eventType) {
+      logger.debug("Skipping unknown event type", { eventType: notification.eventType });
+      continue;
+    }
+
+    const timestamp = extractTimestamp(notification);
+    const recipients = extractRecipients(notification);
+    const subject = getHeader(notification.mail.headers, "Subject");
+    const templateKey = getHeader(notification.mail.headers, "X-Template-Key");
+    const sequenceId = getHeader(notification.mail.headers, "X-Sequence-Id") || "fire_and_forget";
+
+    const linkUrl = notification.eventType === "Click" ? notification.click.link : undefined;
+    const userAgent =
+      notification.eventType === "Open"
+        ? notification.open.userAgent
+        : notification.eventType === "Click"
+          ? notification.click.userAgent
+          : undefined;
+
+    logger.info("Processing engagement event", {
+      eventType,
+      templateKey,
+      sequenceId,
+      sesMessageId: notification.mail.messageId,
+      recipientCount: recipients.length,
+      ...(linkUrl ? { linkUrl } : {}),
+    });
+
+    const now = new Date();
+    const ttl = Math.floor(now.getTime() / 1000) + EVENT_TTL_DAYS * 86400;
+
+    for (const email of recipients) {
+      logger.debug("Writing engagement event", { email, eventType, templateKey });
+      await dynamo.send(
+        new PutItemCommand({
+          TableName: config.eventsTableName,
+          Item: marshall(
+            {
+              PK: subscriberPK(email),
+              SK: eventSK(timestamp, eventType),
+              eventType,
+              templateKey,
+              sequenceId,
+              subject,
+              ...(linkUrl ? { linkUrl } : {}),
+              ...(userAgent ? { userAgent } : {}),
+              sesMessageId: notification.mail.messageId,
+              timestamp,
+              ttl,
+            },
+            { removeUndefinedValues: true },
+          ),
+        }),
+      );
+    }
+  }
+
+  logger.info("EngagementHandler complete");
+};

package/src/handlers/send-email.ts

@@ -0,0 +1,184 @@
+import { SFNClient, StopExecutionCommand } from "@aws-sdk/client-sfn";
+import type { SendEmailInput, RegisterOutput, SendOutput } from "@step-func-emailer/shared";
+import { resolveConfig } from "../lib/ssm-config.js";
+import {
+  getSubscriberProfile,
+  upsertSubscriberProfile,
+  extractAttributes,
+  getExecution,
+  putExecution,
+  deleteExecution,
+  writeSendLog,
+} from "../lib/dynamo-client.js";
+import { renderTemplate } from "../lib/template-renderer.js";
+import { sendEmail } from "../lib/ses-sender.js";
+import { generateToken } from "../lib/unsubscribe-token.js";
+import { loadDisplayNames, resolveDisplayNames } from "../lib/display-names.js";
+import { createLogger } from "../lib/logger.js";
+
+const logger = createLogger("send-email");
+const sfn = new SFNClient({});
+
+export const handler = async (
+  event: SendEmailInput,
+): Promise<RegisterOutput | SendOutput | { completed: true }> => {
+  logger.info("SendEmail invoked", { action: event.action, email: event.subscriber.email });
+  const config = await resolveConfig();
+
+  switch (event.action) {
+    case "register":
+      return handleRegister(event, config);
+    case "send":
+      return handleSend(event, config, event.sequenceId ?? "unknown");
+    case "fire_and_forget":
+      logger.info("Fire and forget", {
+        email: event.subscriber.email,
+        templateKey: event.templateKey,
+      });
+      await upsertSubscriberProfile(config.tableName, event.subscriber);
+      return handleSend(
+        {
+          action: "send",
+          templateKey: event.templateKey,
+          subject: event.subject,
+          subscriber: event.subscriber,
+        },
+        config,
+        "fire_and_forget",
+      );
+    case "complete":
+      logger.info("Completing sequence", {
+        email: event.subscriber.email,
+        sequenceId: event.sequenceId,
+      });
+      await deleteExecution(config.tableName, event.subscriber.email, event.sequenceId);
+      return { completed: true };
+  }
+};
+
+async function handleRegister(
+  event: Extract<SendEmailInput, { action: "register" }>,
+  config: Awaited<ReturnType<typeof resolveConfig>>,
+): Promise<RegisterOutput> {
+  logger.info("Registering subscriber for sequence", {
+    email: event.subscriber.email,
+    sequenceId: event.sequenceId,
+    executionArn: event.executionArn,
+  });
+
+  await upsertSubscriberProfile(config.tableName, event.subscriber);
+
+  // Check for existing execution and stop it
+  const existing = await getExecution(config.tableName, event.subscriber.email, event.sequenceId);
+  if (existing) {
+    logger.warn("Stopping existing execution before registering new one", {
+      email: event.subscriber.email,
+      sequenceId: event.sequenceId,
+      oldArn: existing.executionArn,
+      newArn: event.executionArn,
+    });
+    try {
+      await sfn.send(
+        new StopExecutionCommand({
+          executionArn: existing.executionArn,
+          cause: "Replaced by new execution",
+        }),
+      );
+    } catch {
+      // Execution may already be stopped
+    }
+    await deleteExecution(config.tableName, event.subscriber.email, event.sequenceId);
+  }
+
+  await putExecution(
+    config.tableName,
+    event.subscriber.email,
+    event.sequenceId,
+    event.executionArn,
+  );
+
+  logger.info("Registration complete", {
+    email: event.subscriber.email,
+    sequenceId: event.sequenceId,
+  });
+  return { registered: true };
+}
+
+async function handleSend(
+  event: Extract<SendEmailInput, { action: "send" }>,
+  config: Awaited<ReturnType<typeof resolveConfig>>,
+  sequenceId: string = "unknown",
+): Promise<SendOutput> {
+  logger.info("Processing send", {
+    email: event.subscriber.email,
+    templateKey: event.templateKey,
+    subject: event.subject,
+    sequenceId,
+  });
+
+  const profile = await getSubscriberProfile(config.tableName, event.subscriber.email);
+
+  // Pre-send checks
+  if (profile?.unsubscribed) {
+    logger.info("Skipping send — subscriber unsubscribed", { email: event.subscriber.email });
+    return { sent: false, reason: "unsubscribed" };
+  }
+  if (profile?.suppressed) {
+    logger.info("Skipping send — subscriber suppressed", { email: event.subscriber.email });
+    return { sent: false, reason: "suppressed" };
+  }
+
+  // Load display names and build context
+  const displayNameMap = await loadDisplayNames(config.templateBucket);
+  const attributes =
+    (profile ? extractAttributes(profile) : null) ?? event.subscriber.attributes ?? {};
+  const displayNames = resolveDisplayNames(displayNameMap, attributes as Record<string, unknown>);
+
+  const unsubscribeUrl = `${config.unsubscribeBaseUrl}?token=${generateToken(event.subscriber.email, config.unsubscribeSecret)}`;
+
+  const context = {
+    email: event.subscriber.email,
+    firstName: event.subscriber.firstName,
+    ...attributes,
+    ...displayNames,
+    unsubscribeUrl,
+    currentYear: new Date().getFullYear(),
+  };
+
+  const htmlBody = await renderTemplate(
+    config.templateBucket,
+    event.templateKey,
+    context as Parameters<typeof renderTemplate>[2],
+  );
+
+  const fromAddress = config.defaultFromName
+    ? `${config.defaultFromName} <${config.defaultFromEmail}>`
+    : config.defaultFromEmail;
+
+  const messageId = await sendEmail({
+    from: fromAddress,
+    to: event.subscriber.email,
+    subject: event.subject,
+    htmlBody,
+    configurationSetName: config.sesConfigSet,
+    unsubscribeUrl,
+    replyToAddress: config.replyToEmail || undefined,
+    templateKey: event.templateKey,
+    sequenceId,
+  });
+
+  await writeSendLog(config.tableName, event.subscriber.email, {
+    templateKey: event.templateKey,
+    sequenceId,
+    subject: event.subject,
+    sesMessageId: messageId,
+  });
+
+  logger.info("Send complete", {
+    email: event.subscriber.email,
+    templateKey: event.templateKey,
+    messageId,
+    sequenceId,
+  });
+  return { sent: true, messageId };
+}

package/src/handlers/unsubscribe.ts

@@ -0,0 +1,70 @@
+import type { APIGatewayProxyResultV2 } from "aws-lambda";
+import { resolveConfig } from "../lib/ssm-config.js";
+import { validateToken } from "../lib/unsubscribe-token.js";
+import { 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("unsubscribe");
+
+const HTML_HEADERS = {
+  "Content-Type": "text/html; charset=utf-8",
+};
+
+function htmlPage(title: string, body: string): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title}</title>
+<style>body{font-family:-apple-system,system-ui,sans-serif;max-width:480px;margin:60px auto;padding:0 20px;text-align:center;color:#333}h1{font-size:24px}p{font-size:16px;line-height:1.5;color:#666}</style>
+</head><body>${body}</body></html>`;
+}
+
+export const handler = async (event: {
+  queryStringParameters?: Record<string, string | undefined>;
+}): Promise<APIGatewayProxyResultV2> => {
+  const token = event.queryStringParameters?.token;
+  if (!token) {
+    logger.warn("Unsubscribe request with no token");
+    return {
+      statusCode: 400,
+      headers: HTML_HEADERS,
+      body: htmlPage(
+        "Invalid Request",
+        "<h1>Invalid Request</h1><p>No unsubscribe token provided.</p>",
+      ),
+    };
+  }
+
+  const config = await resolveConfig();
+  const result = validateToken(token, config.unsubscribeSecret);
+
+  if (!result.valid) {
+    logger.warn("Invalid unsubscribe token", { reason: result.reason });
+    return {
+      statusCode: 400,
+      headers: HTML_HEADERS,
+      body: htmlPage(
+        "Invalid Link",
+        `<h1>Invalid Link</h1><p>This unsubscribe link is ${result.reason === "token expired" ? "expired" : "invalid"}. Please contact support if you need help.</p>`,
+      ),
+    };
+  }
+
+  logger.info("Processing unsubscribe", { email: result.email });
+
+  await setProfileFlag(config.tableName, result.email, "unsubscribed");
+  await stopAllExecutions(config.tableName, result.email);
+  await addToSuppressionList(result.email, "COMPLAINT");
+
+  logger.info("Unsubscribe complete", { email: result.email });
+
+  return {
+    statusCode: 200,
+    headers: HTML_HEADERS,
+    body: htmlPage(
+      "Unsubscribed",
+      "<h1>You've been unsubscribed</h1><p>You won't receive any more emails from us. If this was a mistake, please contact support.</p>",
+    ),
+  };
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+import * as path from "node:path";
+
+export { handler as sendEmailHandler } from "./handlers/send-email.js";
+export { handler as checkConditionHandler } from "./handlers/check-condition.js";
+export { handler as unsubscribeHandler } from "./handlers/unsubscribe.js";
+export { handler as bounceHandlerHandler } from "./handlers/bounce-handler.js";
+export { handler as engagementHandlerHandler } from "./handlers/engagement-handler.js";
+
+/** Absolute path to the handlers TypeScript source directory. Used by CDK constructs. */
+export const HANDLERS_SRC_DIR = path.join(__dirname, "../src");

package/src/lib/__tests__/display-names.test.ts

@@ -0,0 +1,52 @@
+import { resolveDisplayNames } from "../display-names.js";
+
+describe("resolveDisplayNames", () => {
+  const displayNameMap = {
+    platformName: {
+      web: "Web App",
+      ios: "iPhone App",
+      android: "Android App",
+    },
+    roleName: {
+      admin: "Administrator",
+      user: "Standard User",
+    },
+  };
+
+  it("resolves known values to display names", () => {
+    const result = resolveDisplayNames(displayNameMap, {
+      platform: "web",
+      role: "admin",
+    });
+    expect(result).toEqual({
+      platformName: "Web App",
+      roleName: "Administrator",
+    });
+  });
+
+  it("falls back to raw value if no mapping exists", () => {
+    const result = resolveDisplayNames(displayNameMap, {
+      platform: "desktop",
+    });
+    expect(result).toEqual({ platformName: "desktop" });
+  });
+
+  it("skips non-string attribute values", () => {
+    const result = resolveDisplayNames(displayNameMap, {
+      platform: 123,
+    });
+    expect(result).toEqual({});
+  });
+
+  it("returns empty object when no attributes match", () => {
+    const result = resolveDisplayNames(displayNameMap, {
+      unrelatedField: "value",
+    });
+    expect(result).toEqual({});
+  });
+
+  it("handles empty inputs", () => {
+    expect(resolveDisplayNames({}, {})).toEqual({});
+    expect(resolveDisplayNames(displayNameMap, {})).toEqual({});
+  });
+});