@step-func-emailer/handlers 0.2.0

package/src/lib/__tests__/unsubscribe-token.test.ts

@@ -0,0 +1,79 @@
+import { generateToken, validateToken } from "../unsubscribe-token.js";
+
+const SECRET = "test-secret-key";
+
+describe("unsubscribe-token", () => {
+  describe("generateToken", () => {
+    it("returns a base64url-encoded string", () => {
+      const token = generateToken("user@example.com", SECRET);
+      expect(token).toBeTruthy();
+      // base64url chars only
+      expect(token).toMatch(/^[A-Za-z0-9_-]+$/);
+    });
+
+    it("produces different tokens for different emails", () => {
+      const t1 = generateToken("a@example.com", SECRET);
+      const t2 = generateToken("b@example.com", SECRET);
+      expect(t1).not.toBe(t2);
+    });
+
+    it("produces different tokens for different secrets", () => {
+      const t1 = generateToken("user@example.com", "secret-1");
+      const t2 = generateToken("user@example.com", "secret-2");
+      expect(t1).not.toBe(t2);
+    });
+  });
+
+  describe("validateToken", () => {
+    it("validates a freshly generated token", () => {
+      const token = generateToken("user@example.com", SECRET);
+      const result = validateToken(token, SECRET);
+      expect(result.valid).toBe(true);
+      if (result.valid) {
+        expect(result.email).toBe("user@example.com");
+        expect(result.sendTimestamp).toBeTruthy();
+        expect(result.expiryTimestamp).toBeTruthy();
+      }
+    });
+
+    it("rejects token with wrong secret", () => {
+      const token = generateToken("user@example.com", SECRET);
+      const result = validateToken(token, "wrong-secret");
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.reason).toBe("invalid signature");
+      }
+    });
+
+    it("rejects malformed token", () => {
+      const result = validateToken("not-a-valid-token", SECRET);
+      expect(result.valid).toBe(false);
+    });
+
+    it("rejects expired token", () => {
+      // Manually craft an expired token
+      const { createHmac } = require("node:crypto");
+      const email = "user@example.com";
+      const sendTimestamp = "2020-01-01T00:00:00.000Z";
+      const expiryTimestamp = "2020-04-01T00:00:00.000Z"; // expired
+      const payload = `${email}|${sendTimestamp}|${expiryTimestamp}`;
+      const signature = createHmac("sha256", SECRET).update(payload).digest("hex");
+      const token = Buffer.from(`${payload}|${signature}`).toString("base64url");
+
+      const result = validateToken(token, SECRET);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.reason).toBe("token expired");
+      }
+    });
+
+    it("rejects token with wrong part count", () => {
+      const token = Buffer.from("a|b|c|d|e").toString("base64url");
+      const result = validateToken(token, SECRET);
+      expect(result.valid).toBe(false);
+      if (!result.valid) {
+        expect(result.reason).toBe("malformed token");
+      }
+    });
+  });
+});

package/src/lib/display-names.ts

@@ -0,0 +1,54 @@
+import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
+import { createLogger } from "./logger.js";
+
+const logger = createLogger("display-names");
+const s3 = new S3Client({});
+
+type DisplayNameMap = Record<string, Record<string, string>>;
+
+let cachedMap: { data: DisplayNameMap; fetchedAt: number } | null = null;
+const CACHE_TTL_MS = 10 * 60 * 1000;
+
+export async function loadDisplayNames(bucket: string): Promise<DisplayNameMap> {
+  if (cachedMap && Date.now() - cachedMap.fetchedAt < CACHE_TTL_MS) {
+    logger.debug("Display names cache hit");
+    return cachedMap.data;
+  }
+
+  try {
+    logger.debug("Loading display names from S3", { bucket });
+    const result = await s3.send(
+      new GetObjectCommand({
+        Bucket: bucket,
+        Key: "display-names.json",
+      }),
+    );
+    const body = (await result.Body?.transformToString()) ?? "{}";
+    const data = JSON.parse(body) as DisplayNameMap;
+    cachedMap = { data, fetchedAt: Date.now() };
+    logger.debug("Display names loaded", { mappingCount: Object.keys(data).length });
+    return data;
+  } catch {
+    logger.debug("Display names file not found, using empty map");
+    return {};
+  }
+}
+
+export function resolveDisplayNames(
+  displayNameMap: DisplayNameMap,
+  attributes: Record<string, unknown>,
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+
+  for (const [displayKey, valueMap] of Object.entries(displayNameMap)) {
+    // Convention: displayKey "platformName" maps from attribute "platform"
+    // The source attribute key is derived by removing "Name" suffix
+    const sourceKey = displayKey.replace(/Name$/, "");
+    const rawValue = attributes[sourceKey];
+    if (typeof rawValue === "string") {
+      resolved[displayKey] = valueMap[rawValue] ?? rawValue;
+    }
+  }
+
+  return resolved;
+}

package/src/lib/dynamo-client.ts

@@ -0,0 +1,301 @@
+import {
+  DynamoDBClient,
+  GetItemCommand,
+  PutItemCommand,
+  UpdateItemCommand,
+  DeleteItemCommand,
+  QueryCommand,
+} from "@aws-sdk/client-dynamodb";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+import {
+  subscriberPK,
+  PROFILE_SK,
+  executionSK,
+  sentSK,
+  SUPPRESSION_SK,
+  EXEC_SK_PREFIX,
+  SENT_SK_PREFIX,
+  SEND_LOG_TTL_DAYS,
+} from "@step-func-emailer/shared";
+import type {
+  Subscriber,
+  SubscriberProfile,
+  ActiveExecution,
+  SendLog,
+} from "@step-func-emailer/shared";
+import { createLogger } from "./logger.js";
+
+const logger = createLogger("dynamo-client");
+const dynamo = new DynamoDBClient({});
+
+// ── Subscriber profile ──────────────────────────────────────────────────────
+
+export async function getSubscriberProfile(
+  tableName: string,
+  email: string,
+): Promise<SubscriberProfile | null> {
+  logger.debug("Getting subscriber profile", { email });
+  const result = await dynamo.send(
+    new GetItemCommand({
+      TableName: tableName,
+      Key: marshall({ PK: subscriberPK(email), SK: PROFILE_SK }),
+    }),
+  );
+  const profile = result.Item ? (unmarshall(result.Item) as SubscriberProfile) : null;
+  logger.debug("Subscriber profile result", {
+    email,
+    found: !!profile,
+    unsubscribed: profile?.unsubscribed,
+    suppressed: profile?.suppressed,
+  });
+  return profile;
+}
+
+const SYSTEM_KEYS = new Set([
+  "PK",
+  "SK",
+  "email",
+  "firstName",
+  "unsubscribed",
+  "suppressed",
+  "createdAt",
+  "updatedAt",
+]);
+
+export function extractAttributes(profile: Record<string, unknown>): Record<string, unknown> {
+  const attrs: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(profile)) {
+    if (!SYSTEM_KEYS.has(key)) {
+      attrs[key] = value;
+    }
+  }
+  return attrs;
+}
+
+export async function upsertSubscriberProfile(
+  tableName: string,
+  subscriber: Subscriber,
+): Promise<void> {
+  const now = new Date().toISOString();
+  const pk = subscriberPK(subscriber.email);
+  const rawAttrs = subscriber.attributes ?? {};
+  // Filter out system keys to avoid duplicate paths in the UpdateExpression
+  const attrs: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(rawAttrs)) {
+    if (!SYSTEM_KEYS.has(key)) {
+      attrs[key] = value;
+    }
+  }
+
+  logger.info("Upserting subscriber profile", {
+    email: subscriber.email,
+    firstName: subscriber.firstName,
+    attributeCount: Object.keys(attrs).length,
+  });
+
+  // Build SET expressions — never overwrite unsubscribed or suppressed
+  const expressionParts = ["email = :email", "firstName = :firstName", "updatedAt = :updatedAt"];
+  const expressionValues: Record<string, unknown> = {
+    ":email": subscriber.email,
+    ":firstName": subscriber.firstName,
+    ":updatedAt": now,
+    ":createdAt": now,
+    ":defaultFalse": false,
+  };
+
+  const expressionNames: Record<string, string> = {};
+
+  // Write each attribute as a top-level column
+  for (const [key, value] of Object.entries(attrs)) {
+    expressionParts.push(`#attr_${key} = :attr_${key}`);
+    expressionNames[`#attr_${key}`] = key;
+    expressionValues[`:attr_${key}`] = value;
+  }
+
+  await dynamo.send(
+    new UpdateItemCommand({
+      TableName: tableName,
+      Key: marshall({ PK: pk, SK: PROFILE_SK }),
+      UpdateExpression: `SET ${expressionParts.join(", ")}, createdAt = if_not_exists(createdAt, :createdAt), unsubscribed = if_not_exists(unsubscribed, :defaultFalse), suppressed = if_not_exists(suppressed, :defaultFalse)`,
+      ExpressionAttributeValues: marshall(expressionValues),
+      ...(Object.keys(expressionNames).length > 0
+        ? { ExpressionAttributeNames: expressionNames }
+        : {}),
+    }),
+  );
+}
+
+// ── Active executions ───────────────────────────────────────────────────────
+
+export async function getExecution(
+  tableName: string,
+  email: string,
+  sequenceId: string,
+): Promise<ActiveExecution | null> {
+  logger.debug("Getting execution", { email, sequenceId });
+  const result = await dynamo.send(
+    new GetItemCommand({
+      TableName: tableName,
+      Key: marshall({
+        PK: subscriberPK(email),
+        SK: executionSK(sequenceId),
+      }),
+    }),
+  );
+  return result.Item ? (unmarshall(result.Item) as ActiveExecution) : null;
+}
+
+export async function putExecution(
+  tableName: string,
+  email: string,
+  sequenceId: string,
+  executionArn: string,
+): Promise<void> {
+  logger.info("Storing execution", { email, sequenceId, executionArn });
+  await dynamo.send(
+    new PutItemCommand({
+      TableName: tableName,
+      Item: marshall({
+        PK: subscriberPK(email),
+        SK: executionSK(sequenceId),
+        executionArn,
+        sequenceId,
+        startedAt: new Date().toISOString(),
+      }),
+    }),
+  );
+}
+
+export async function deleteExecution(
+  tableName: string,
+  email: string,
+  sequenceId: string,
+): Promise<void> {
+  logger.info("Deleting execution", { email, sequenceId });
+  await dynamo.send(
+    new DeleteItemCommand({
+      TableName: tableName,
+      Key: marshall({
+        PK: subscriberPK(email),
+        SK: executionSK(sequenceId),
+      }),
+    }),
+  );
+}
+
+export async function getAllExecutions(
+  tableName: string,
+  email: string,
+): Promise<ActiveExecution[]> {
+  logger.debug("Querying all executions", { email });
+  const result = await dynamo.send(
+    new QueryCommand({
+      TableName: tableName,
+      KeyConditionExpression: "PK = :pk AND begins_with(SK, :prefix)",
+      ExpressionAttributeValues: marshall({
+        ":pk": subscriberPK(email),
+        ":prefix": EXEC_SK_PREFIX,
+      }),
+    }),
+  );
+  const executions = (result.Items ?? []).map((item) => unmarshall(item) as ActiveExecution);
+  logger.debug("Found executions", { email, count: executions.length });
+  return executions;
+}
+
+// ── Send log ────────────────────────────────────────────────────────────────
+
+export async function writeSendLog(
+  tableName: string,
+  email: string,
+  log: Omit<SendLog, "PK" | "SK" | "ttl">,
+): Promise<void> {
+  const now = new Date();
+  const ttl = Math.floor(now.getTime() / 1000) + SEND_LOG_TTL_DAYS * 86400;
+  logger.info("Writing send log", {
+    email,
+    templateKey: log.templateKey,
+    sequenceId: log.sequenceId,
+    sesMessageId: log.sesMessageId,
+  });
+  await dynamo.send(
+    new PutItemCommand({
+      TableName: tableName,
+      Item: marshall({
+        PK: subscriberPK(email),
+        SK: sentSK(now.toISOString()),
+        ...log,
+        ttl,
+      }),
+    }),
+  );
+}
+
+export async function hasBeenSent(
+  tableName: string,
+  email: string,
+  templateKey: string,
+): Promise<boolean> {
+  logger.debug("Checking if template has been sent", { email, templateKey });
+  const result = await dynamo.send(
+    new QueryCommand({
+      TableName: tableName,
+      KeyConditionExpression: "PK = :pk AND begins_with(SK, :prefix)",
+      FilterExpression: "templateKey = :templateKey",
+      ExpressionAttributeValues: marshall({
+        ":pk": subscriberPK(email),
+        ":prefix": SENT_SK_PREFIX,
+        ":templateKey": templateKey,
+      }),
+      Limit: 1,
+    }),
+  );
+  const sent = (result.Count ?? 0) > 0;
+  logger.debug("Has been sent result", { email, templateKey, sent });
+  return sent;
+}
+
+// ── Suppression ─────────────────────────────────────────────────────────────
+
+export async function writeSuppression(
+  tableName: string,
+  email: string,
+  reason: "bounce" | "complaint",
+  bounceType: string | undefined,
+  sesNotificationId: string,
+): Promise<void> {
+  logger.warn("Writing suppression record", { email, reason, bounceType, sesNotificationId });
+  await dynamo.send(
+    new PutItemCommand({
+      TableName: tableName,
+      Item: marshall({
+        PK: subscriberPK(email),
+        SK: SUPPRESSION_SK,
+        reason,
+        ...(bounceType ? { bounceType } : {}),
+        sesNotificationId,
+        recordedAt: new Date().toISOString(),
+      }),
+    }),
+  );
+}
+
+export async function setProfileFlag(
+  tableName: string,
+  email: string,
+  flag: "unsubscribed" | "suppressed",
+): Promise<void> {
+  logger.warn("Setting profile flag", { email, flag });
+  await dynamo.send(
+    new UpdateItemCommand({
+      TableName: tableName,
+      Key: marshall({ PK: subscriberPK(email), SK: PROFILE_SK }),
+      UpdateExpression: `SET #flag = :val, updatedAt = :now`,
+      ExpressionAttributeNames: { "#flag": flag },
+      ExpressionAttributeValues: marshall({
+        ":val": true,
+        ":now": new Date().toISOString(),
+      }),
+    }),
+  );
+}

package/src/lib/execution-stopper.ts

@@ -0,0 +1,40 @@
+import { SFNClient, StopExecutionCommand } from "@aws-sdk/client-sfn";
+import { getAllExecutions, deleteExecution } from "./dynamo-client.js";
+import { createLogger } from "./logger.js";
+
+const logger = createLogger("execution-stopper");
+const sfn = new SFNClient({});
+
+export async function stopAllExecutions(tableName: string, email: string): Promise<void> {
+  const executions = await getAllExecutions(tableName, email);
+  logger.info("Stopping all executions for subscriber", {
+    email,
+    executionCount: executions.length,
+  });
+
+  await Promise.all(
+    executions.map(async (exec) => {
+      try {
+        await sfn.send(
+          new StopExecutionCommand({
+            executionArn: exec.executionArn,
+            cause: "Subscriber unsubscribed or suppressed",
+          }),
+        );
+        logger.info("Stopped execution", {
+          email,
+          sequenceId: exec.sequenceId,
+          executionArn: exec.executionArn,
+        });
+      } catch (err) {
+        logger.warn("Failed to stop execution (may already be stopped)", {
+          email,
+          sequenceId: exec.sequenceId,
+          executionArn: exec.executionArn,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+      await deleteExecution(tableName, email, exec.sequenceId);
+    }),
+  );
+}

package/src/lib/logger.ts

@@ -0,0 +1,10 @@
+import { Logger } from "@aws-lambda-powertools/logger";
+
+/**
+ * Creates a Logger instance scoped to a service name.
+ * LOG_LEVEL is controlled via environment variable (default: INFO).
+ * Set LOG_LEVEL=DEBUG for verbose tracing.
+ */
+export function createLogger(serviceName: string): Logger {
+  return new Logger({ serviceName });
+}

package/src/lib/ses-sender.ts

@@ -0,0 +1,102 @@
+import { SESv2Client, SendEmailCommand } from "@aws-sdk/client-sesv2";
+import { createLogger } from "./logger.js";
+
+const logger = createLogger("ses-sender");
+const ses = new SESv2Client({});
+
+export interface SendEmailParams {
+  from: string;
+  to: string;
+  subject: string;
+  htmlBody: string;
+  configurationSetName: string;
+  unsubscribeUrl: string;
+  replyToAddress?: string;
+  templateKey: string;
+  sequenceId: string;
+}
+
+/**
+ * Strip HTML to plain text for the text/plain MIME part.
+ * Handles common email HTML patterns without requiring an external dependency.
+ */
+function htmlToPlainText(html: string): string {
+  return html
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p>/gi, "\n\n")
+    .replace(/<\/div>/gi, "\n")
+    .replace(/<\/tr>/gi, "\n")
+    .replace(/<\/li>/gi, "\n")
+    .replace(/<li[^>]*>/gi, "  - ")
+    .replace(/<a[^>]+href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, "$2 ($1)")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export async function sendEmail(params: SendEmailParams): Promise<string> {
+  logger.info("Sending email via SES", {
+    to: params.to,
+    subject: params.subject,
+    templateKey: params.templateKey,
+    sequenceId: params.sequenceId,
+  });
+
+  const textBody = htmlToPlainText(params.htmlBody);
+
+  const result = await ses.send(
+    new SendEmailCommand({
+      FromEmailAddress: params.from,
+      Destination: { ToAddresses: [params.to] },
+      ...(params.replyToAddress ? { ReplyToAddresses: [params.replyToAddress] } : {}),
+      Content: {
+        Simple: {
+          Subject: { Data: params.subject, Charset: "UTF-8" },
+          Body: {
+            Html: { Data: params.htmlBody, Charset: "UTF-8" },
+            Text: { Data: textBody, Charset: "UTF-8" },
+          },
+          Headers: [
+            {
+              Name: "List-Unsubscribe",
+              Value: `<${params.unsubscribeUrl}>`,
+            },
+            {
+              Name: "List-Unsubscribe-Post",
+              Value: "List-Unsubscribe=One-Click",
+            },
+            {
+              Name: "X-Template-Key",
+              Value: params.templateKey,
+            },
+            {
+              Name: "X-Sequence-Id",
+              Value: params.sequenceId,
+            },
+          ],
+        },
+      },
+      ConfigurationSetName: params.configurationSetName,
+      EmailTags: [
+        { Name: "templateKey", Value: params.templateKey.replace(/\//g, "--") },
+        { Name: "sequenceId", Value: params.sequenceId },
+      ],
+    }),
+  );
+
+  const messageId = result.MessageId ?? "unknown";
+  logger.info("Email sent successfully", {
+    messageId,
+    to: params.to,
+    templateKey: params.templateKey,
+  });
+  return messageId;
+}

package/src/lib/ses-suppression.ts

@@ -0,0 +1,30 @@
+import {
+  SESv2Client,
+  PutSuppressedDestinationCommand,
+  type SuppressionListReason,
+} from "@aws-sdk/client-sesv2";
+import { createLogger } from "./logger.js";
+
+const logger = createLogger("ses-suppression");
+const ses = new SESv2Client({});
+
+export async function addToSuppressionList(
+  email: string,
+  reason: "BOUNCE" | "COMPLAINT",
+): Promise<void> {
+  try {
+    await ses.send(
+      new PutSuppressedDestinationCommand({
+        EmailAddress: email,
+        Reason: reason as SuppressionListReason,
+      }),
+    );
+    logger.info("Added to SES suppression list", { email, reason });
+  } catch (error) {
+    logger.warn("Failed to add to SES suppression list", {
+      email,
+      reason,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}

package/src/lib/ssm-config.ts

@@ -0,0 +1,81 @@
+import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";
+import { createLogger } from "./logger.js";
+
+const logger = createLogger("ssm-config");
+const ssm = new SSMClient({});
+const cache = new Map<string, { value: string; fetchedAt: number }>();
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+export async function getParameter(name: string): Promise<string> {
+  const cached = cache.get(name);
+  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+    logger.debug("SSM cache hit", { parameter: name });
+    return cached.value;
+  }
+
+  logger.debug("Fetching SSM parameter", { parameter: name });
+  const result = await ssm.send(new GetParameterCommand({ Name: name, WithDecryption: true }));
+
+  const value = result.Parameter?.Value;
+  if (!value) {
+    logger.error("SSM parameter not found", { parameter: name });
+    throw new Error(`SSM parameter not found: ${name}`);
+  }
+
+  cache.set(name, { value, fetchedAt: Date.now() });
+  return value;
+}
+
+export interface ResolvedConfig {
+  tableName: string;
+  eventsTableName: string;
+  templateBucket: string;
+  defaultFromEmail: string;
+  defaultFromName: string;
+  replyToEmail: string;
+  sesConfigSet: string;
+  unsubscribeBaseUrl: string;
+  unsubscribeSecret: string;
+}
+
+const SSM_PREFIX = process.env.SSM_PREFIX ?? "/step-func-emailer";
+
+export async function resolveConfig(): Promise<ResolvedConfig> {
+  logger.debug("Resolving config", { prefix: SSM_PREFIX });
+
+  const [
+    tableName,
+    eventsTableName,
+    templateBucket,
+    defaultFromEmail,
+    defaultFromName,
+    replyToEmail,
+    sesConfigSet,
+    unsubscribeBaseUrl,
+    unsubscribeSecret,
+  ] = await Promise.all([
+    getParameter(`${SSM_PREFIX}/table-name`),
+    getParameter(`${SSM_PREFIX}/events-table-name`),
+    getParameter(`${SSM_PREFIX}/template-bucket`),
+    getParameter(`${SSM_PREFIX}/default-from-email`),
+    getParameter(`${SSM_PREFIX}/default-from-name`),
+    getParameter(`${SSM_PREFIX}/reply-to-email`).catch(() => ""),
+    getParameter(`${SSM_PREFIX}/ses-config-set`),
+    getParameter(`${SSM_PREFIX}/unsubscribe-base-url`),
+    getParameter(`${SSM_PREFIX}/unsubscribe-secret`),
+  ]);
+
+  logger.debug("Config resolved", { tableName, templateBucket });
+
+  return {
+    tableName,
+    eventsTableName,
+    templateBucket,
+    defaultFromEmail,
+    defaultFromName,
+    replyToEmail,
+    sesConfigSet,
+    unsubscribeBaseUrl,
+    unsubscribeSecret,
+  };
+}