refactor: split src into domain / application / infrastructure layers

Replace the history-driven lib/ + utils/ split with DDD layers:
- domain/: aggregate, repositories, value objects, pure parsers/format
- application/: feed-service, email-processor, feed-fetcher, stats
- infrastructure/: logging, auth, KV/R2 adapters, HTTP, framework glue

Pure file relocation; imports updated mechanically. Behaviour unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

src/domain/email-parser.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from "vitest";
+import { EmailParser } from "./email-parser";
+
+describe("EmailParser.extractFeedId", () => {
+  it("extracts a valid feed ID from an email address", () => {
+    expect(EmailParser.extractFeedId("river.castle.42@example.com")).toBe(
+      "river.castle.42",
+    );
+  });
+
+  it("is case-insensitive for the local part", () => {
+    expect(EmailParser.extractFeedId("River.Castle.42@example.com")).toBe(
+      "River.Castle.42",
+    );
+  });
+
+  it("returns null for an address with no feed ID format", () => {
+    expect(EmailParser.extractFeedId("user@example.com")).toBeNull();
+  });
+
+  it("returns null for a plain string without @", () => {
+    expect(EmailParser.extractFeedId("notanemail")).toBeNull();
+  });
+
+  it("returns null when the numeric suffix is only one digit", () => {
+    expect(EmailParser.extractFeedId("river.castle.4@example.com")).toBeNull();
+  });
+
+  it("returns null when the numeric suffix has more than two digits", () => {
+    expect(
+      EmailParser.extractFeedId("river.castle.123@example.com"),
+    ).toBeNull();
+  });
+});
+
+describe("EmailParser.decodeEncodedWords", () => {
+  it("returns plain text unchanged", () => {
+    expect(EmailParser.decodeEncodedWords("Hello World")).toBe("Hello World");
+  });
+
+  it("returns empty string for empty input", () => {
+    expect(EmailParser.decodeEncodedWords("")).toBe("");
+  });
+
+  it("decodes a Base64-encoded word (UTF-8 subject)", () => {
+    // =?UTF-8?B?SGVsbG8=?= → "Hello"
+    expect(EmailParser.decodeEncodedWords("=?UTF-8?B?SGVsbG8=?=")).toBe(
+      "Hello",
+    );
+  });
+
+  it("decodes a quoted-printable encoded word", () => {
+    // =?UTF-8?Q?caf=C3=A9?= → "café" (but decodeQuotedPrintable works byte-by-byte)
+    // Use a simple ASCII QP sequence to stay charset-agnostic in tests
+    // =?US-ASCII?Q?Hello=20World?= → "Hello World" (=20 → space, _ → space)
+    expect(EmailParser.decodeEncodedWords("=?US-ASCII?Q?Hello=20World?=")).toBe(
+      "Hello World",
+    );
+  });
+
+  it("decodes underscores as spaces in QP encoding", () => {
+    expect(EmailParser.decodeEncodedWords("=?US-ASCII?Q?Hello_World?=")).toBe(
+      "Hello World",
+    );
+  });
+
+  it("leaves unrecognised encoded-word syntax unchanged", () => {
+    expect(EmailParser.decodeEncodedWords("=?UTF-8?X?something?=")).toBe(
+      "=?UTF-8?X?something?=",
+    );
+  });
+});
+
+describe("EmailParser.parseForwardEmailPayload", () => {
+  it("throws on null payload", () => {
+    expect(() => EmailParser.parseForwardEmailPayload(null)).toThrow(
+      "Missing or invalid webhook payload",
+    );
+  });
+
+  it("throws on undefined payload", () => {
+    expect(() => EmailParser.parseForwardEmailPayload(undefined)).toThrow();
+  });
+
+  it("parses subject, from, and HTML content", () => {
+    const payload = {
+      subject: "Test Subject",
+      from: { text: "sender@example.com" },
+      html: "<p>Hello</p>",
+      date: "2024-01-15T10:00:00.000Z",
+    };
+    const result = EmailParser.parseForwardEmailPayload(payload);
+    expect(result.subject).toBe("Test Subject");
+    expect(result.from).toBe("sender@example.com");
+    expect(result.content).toBe("<p>Hello</p>");
+    expect(result.receivedAt).toBe(
+      new Date("2024-01-15T10:00:00.000Z").getTime(),
+    );
+  });
+
+  it("prefers HTML content over plain text", () => {
+    const payload = {
+      from: { text: "a@b.com" },
+      html: "<b>HTML</b>",
+      text: "Plain",
+    };
+    expect(EmailParser.parseForwardEmailPayload(payload).content).toBe(
+      "<b>HTML</b>",
+    );
+  });
+
+  it("falls back to plain text when HTML is absent", () => {
+    const payload = {
+      from: { text: "a@b.com" },
+      text: "Plain text",
+    };
+    expect(EmailParser.parseForwardEmailPayload(payload).content).toBe(
+      "Plain text",
+    );
+  });
+
+  it("uses structured from.value when from.text is absent", () => {
+    const payload = {
+      from: {
+        value: [{ name: "Alice", address: "alice@example.com" }],
+      },
+      html: "",
+    };
+    const result = EmailParser.parseForwardEmailPayload(payload);
+    expect(result.from).toBe("Alice <alice@example.com>");
+  });
+
+  it("falls back to Unknown Sender when from is absent", () => {
+    const result = EmailParser.parseForwardEmailPayload({ html: "" });
+    expect(result.from).toBe("Unknown Sender");
+  });
+
+  it("uses Date.now() when date field is absent", () => {
+    const before = Date.now();
+    const result = EmailParser.parseForwardEmailPayload({
+      from: { text: "x@y.com" },
+    });
+    const after = Date.now();
+    expect(result.receivedAt).toBeGreaterThanOrEqual(before);
+    expect(result.receivedAt).toBeLessThanOrEqual(after);
+  });
+
+  it("defaults subject to 'No Subject' when absent", () => {
+    const result = EmailParser.parseForwardEmailPayload({
+      from: { text: "x@y.com" },
+    });
+    expect(result.subject).toBe("No Subject");
+  });
+
+  it("extracts headers from headerLines array", () => {
+    const payload = {
+      from: { text: "x@y.com" },
+      headerLines: [
+        { key: "X-Custom", line: "X-Custom: my-value" },
+        { key: "List-ID", line: "List-ID: <list.example.com>" },
+      ],
+    };
+    const result = EmailParser.parseForwardEmailPayload(payload);
+    expect(result.headers["x-custom"]).toBe("my-value");
+    expect(result.headers["list-id"]).toBe("<list.example.com>");
+  });
+
+  it("extracts headers from raw headers string", () => {
+    const payload = {
+      from: { text: "x@y.com" },
+      headers: "X-Foo: bar\r\nX-Baz: qux",
+    };
+    const result = EmailParser.parseForwardEmailPayload(payload);
+    expect(result.headers["x-foo"]).toBe("bar");
+    expect(result.headers["x-baz"]).toBe("qux");
+  });
+
+  it("decodes RFC 2047 encoded-word subjects", () => {
+    const payload = {
+      from: { text: "x@y.com" },
+      subject: "=?UTF-8?B?SGVsbG8=?=",
+    };
+    expect(EmailParser.parseForwardEmailPayload(payload).subject).toBe("Hello");
+  });
+});

src/domain/email-parser.ts

@@ -0,0 +1,83 @@
+import { EmailData } from "../types";
+import { FeedId } from "../domain/value-objects/feed-id";
+
+export class EmailParser {
+  // Matches noun1.noun2.XY (the feed ID format) before the @ symbol
+  static extractFeedId(emailAddress: string): string | null {
+    return FeedId.parse(emailAddress)?.value ?? null;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static parseForwardEmailPayload(payload: any): EmailData {
+    if (!payload) {
+      throw new Error("Missing or invalid webhook payload");
+    }
+
+    const fromAddress =
+      payload.from?.text ||
+      (payload.from?.value?.[0]?.address
+        ? `${payload.from.value[0].name || ""} <${payload.from.value[0].address}>`
+        : "Unknown Sender");
+
+    const subject = this.decodeEncodedWords(payload.subject || "No Subject");
+    const content = payload.html || payload.text || "";
+
+    return {
+      subject,
+      from: fromAddress,
+      content,
+      receivedAt: payload.date ? new Date(payload.date).getTime() : Date.now(),
+      headers: this.extractHeaders(payload),
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private static extractHeaders(payload: any): Record<string, string> {
+    const headers: Record<string, string> = {};
+
+    if (payload.headerLines && Array.isArray(payload.headerLines)) {
+      payload.headerLines.forEach((h: { key: string; line: string }) => {
+        const key = h.key.toLowerCase();
+        const value = h.line
+          .replace(new RegExp(`^${h.key}:\\s*`, "i"), "")
+          .trim();
+        headers[key] = value;
+      });
+    } else if (typeof payload.headers === "string") {
+      payload.headers.split(/\r?\n/).forEach((line: string) => {
+        const match = line.match(/^([^:]+):\s*(.*)$/);
+        if (match) {
+          headers[match[1].toLowerCase()] = match[2];
+        }
+      });
+    }
+
+    return headers;
+  }
+
+  static decodeEncodedWords(text: string): string {
+    if (!text) return "";
+
+    return text.replace(
+      /=\?([^?]+)\?([BQ])\?([^?]+)\?=/gi,
+      (_, charset, encoding, text) => {
+        if (encoding.toUpperCase() === "B") {
+          try {
+            return atob(text);
+          } catch {
+            return text;
+          }
+        } else if (encoding.toUpperCase() === "Q") {
+          return this.decodeQuotedPrintable(text.replace(/_/g, " "));
+        }
+        return text;
+      },
+    );
+  }
+
+  private static decodeQuotedPrintable(text: string): string {
+    return text.replace(/=([0-9A-F]{2})/gi, (_, hex) => {
+      return String.fromCharCode(parseInt(hex, 16));
+    });
+  }
+}

src/domain/feed-repository.ts

@@ -10,7 +10,7 @@ import { FEEDS_LIST_KEY } from "../config/constants";
 import { feedKeys } from "./feed-keys";
 import { Feed } from "./feed.aggregate";
 import { FeedId } from "./value-objects/feed-id";
-import { logger } from "../lib/logger";
+import { logger } from "../infrastructure/logger";
 
 /**
  * Single source of truth for KV access to the Feed aggregate. The key schema

src/domain/format.ts

@@ -0,0 +1,8 @@
+/** Human-readable byte size (B / KB / MB / GB). */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024)
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}

src/domain/websub-subscription-repository.ts

@@ -1,6 +1,6 @@
 import { Env, WebSubSubscription } from "../types";
 import { feedKeys } from "./feed-keys";
-import { logger } from "../lib/logger";
+import { logger } from "../infrastructure/logger";
 
 /**
  * KV access for per-feed WebSub subscriber lists (`websub:subs:<feedId>`).