agent-inbox 0.2.2 → 0.2.4

package/test/mail/mock-mail.ts

@@ -0,0 +1,161 @@
+/**
+ * In-process mail transport for tests, plus the harness abstraction the shared
+ * contract suite runs against.
+ *
+ * A real backend's test wrapper implements MailTransportHarness too, so the
+ * same contract suite (mail-transport-contract.test.ts) validates it without
+ * modification. See docs/MAIL-INTEROP-PLAN.md §11.
+ */
+
+import type {
+  MailTransport,
+  MailCapabilities,
+  MailTransportState,
+  MailHealth,
+  OutboundMail,
+  MailSendResult,
+  InboundMail,
+  InboundHandler,
+} from "../../src/mail/types.js";
+
+const DEFAULT_CAPS: MailCapabilities = {
+  outbound: "api",
+  signsDkim: true,
+  verifiesInboundAuth: true,
+  inbound: "webhook",
+  maxMessageBytes: 25 * 1024 * 1024,
+};
+
+/**
+ * The control surface a contract test needs over any transport: drive inbound,
+ * and program the next outbound outcome. Real backends provide their own.
+ */
+export interface MailTransportHarness {
+  transport: MailTransport;
+  /** Drive one inbound message; resolves on ACK, rejects on NACK (handler throw). */
+  injectInbound(mail: InboundMail): Promise<void>;
+  /** Force the next send() to produce this result. */
+  programNextSend(result: MailSendResult): void;
+}
+
+export class MockMailTransport implements MailTransport {
+  readonly capabilities: MailCapabilities;
+  private _state: MailTransportState = "stopped";
+  private handler?: InboundHandler;
+
+  /** Recorded successfully-issued sends (one entry per external email produced). */
+  readonly sent: OutboundMail[] = [];
+  /** idempotencyKeys that have already produced a delivered external email. */
+  private delivered = new Set<string>();
+  private programmed: MailSendResult[] = [];
+
+  constructor(caps: Partial<MailCapabilities> = {}) {
+    this.capabilities = { ...DEFAULT_CAPS, ...caps };
+  }
+
+  get state(): MailTransportState {
+    return this._state;
+  }
+
+  async start(): Promise<void> {
+    if (this._state === "ready") return; // idempotent
+    this._state = "starting";
+    this._state = "ready";
+  }
+
+  async stop(): Promise<void> {
+    this._state = "stopping";
+    this._state = "stopped";
+  }
+
+  async health(): Promise<MailHealth> {
+    return { state: this._state };
+  }
+
+  onReceive(handler: InboundHandler): void {
+    this.handler = handler;
+  }
+
+  programNextSend(result: MailSendResult): void {
+    this.programmed.push(result);
+  }
+
+  async send(envelope: OutboundMail): Promise<MailSendResult> {
+    if (this._state !== "ready") {
+      throw new Error(`send() called while transport state is "${this._state}"`);
+    }
+
+    // Idempotent: a duplicate key for an already-delivered message must not
+    // produce a second external email.
+    if (this.delivered.has(envelope.idempotencyKey)) {
+      return {
+        disposition: "delivered",
+        remoteMessageId: `mock-dup-${envelope.idempotencyKey}`,
+        detail: "idempotent replay",
+      };
+    }
+
+    const result: MailSendResult =
+      this.programmed.shift() ?? {
+        disposition: "delivered",
+        remoteMessageId: `mock-${envelope.idempotencyKey}`,
+      };
+
+    if (result.disposition === "delivered") {
+      this.sent.push(envelope);
+      this.delivered.add(envelope.idempotencyKey);
+    }
+    return result;
+  }
+
+  /** Test helper: drive an inbound message through the registered handler. */
+  async deliver(mail: InboundMail): Promise<void> {
+    if (!this.handler) throw new Error("no inbound handler registered");
+    if (this._state !== "ready") {
+      throw new Error(`deliver() while state is "${this._state}"`);
+    }
+    await this.handler(mail); // throw bubbles up as a NACK
+  }
+}
+
+/** Build a MailTransportHarness around a MockMailTransport. */
+export function mockMailHarness(
+  caps?: Partial<MailCapabilities>
+): MailTransportHarness & { mock: MockMailTransport } {
+  const mock = new MockMailTransport(caps);
+  return {
+    mock,
+    transport: mock,
+    injectInbound: (mail) => mock.deliver(mail),
+    programNextSend: (result) => mock.programNextSend(result),
+  };
+}
+
+/** Minimal valid InboundMail for tests; override fields as needed. */
+export function makeInboundMail(over: Partial<InboundMail> = {}): InboundMail {
+  return {
+    envelopeFrom: "ext@example.org",
+    envelopeTo: ["agent@example.com"],
+    from: { address: "ext@example.org" },
+    to: [{ address: "agent@example.com" }],
+    subject: "hello",
+    text: "hi there",
+    headers: { raw: {} },
+    sizeBytes: 100,
+    receivedAt: new Date().toISOString(),
+    ...over,
+  };
+}
+
+/** Minimal valid OutboundMail for tests. */
+export function makeOutboundMail(over: Partial<OutboundMail> = {}): OutboundMail {
+  return {
+    idempotencyKey: "msg-1",
+    from: { address: "agent@example.com" },
+    to: [{ address: "ext@example.org" }],
+    subject: "re: hello",
+    text: "reply body",
+    headers: { messageId: "<msg-1@example.com>" },
+    ...over,
+  };
+}

package/test/mail/mock-postmark.ts

@@ -0,0 +1,66 @@
+/**
+ * Fake Postmark client + harness so the shared MailTransport contract suite can
+ * run against PostmarkTransport without the SDK or network. The fake produces
+ * raw Postmark responses/errors keyed by a desired disposition, and the real
+ * transport mapping turns them into MailSendResults — so the contract suite
+ * also exercises postmarkResponseToResult / postmarkErrorToResult.
+ */
+
+import {
+  PostmarkTransport,
+  type PostmarkClient,
+  type PostmarkSendResponse,
+} from "../../src/mail/provider-transport.js";
+import type { MailSendResult } from "../../src/mail/types.js";
+import type { MailTransportHarness } from "./mock-mail.js";
+
+type Disposition = MailSendResult["disposition"];
+
+export interface FakePostmarkClient extends PostmarkClient {
+  /** Raw messages passed to sendEmail. */
+  sent: Record<string, unknown>[];
+  /** Program the next send's outcome. */
+  program(disposition: Disposition): void;
+}
+
+export function fakePostmarkClient(): FakePostmarkClient {
+  const queue: Disposition[] = [];
+  const sent: Record<string, unknown>[] = [];
+  let counter = 0;
+  return {
+    sent,
+    program(d) {
+      queue.push(d);
+    },
+    async sendEmail(msg): Promise<PostmarkSendResponse> {
+      sent.push(msg);
+      const d = queue.shift() ?? "delivered";
+      if (d === "delivered") {
+        return { ErrorCode: 0, MessageID: `pm-${++counter}` };
+      }
+      if (d === "transient") {
+        throw Object.assign(new Error("rate limited"), { statusCode: 429 });
+      }
+      // permanent — inactive recipient (Postmark code 406, HTTP 422)
+      throw Object.assign(new Error("inactive recipient"), {
+        statusCode: 422,
+        code: 406,
+      });
+    },
+  };
+}
+
+export function postmarkHarness(): MailTransportHarness & {
+  client: FakePostmarkClient;
+  postmark: PostmarkTransport;
+} {
+  const client = fakePostmarkClient();
+  const transport = new PostmarkTransport({ client });
+  return {
+    client,
+    postmark: transport,
+    transport,
+    injectInbound: (mail) => transport.receiveInbound(mail),
+    programNextSend: (result) => client.program(result.disposition),
+  };
+}

package/test/mail/provider-transport.test.ts

@@ -0,0 +1,381 @@
+import { describe, it, expect } from "vitest";
+import {
+  PostmarkTransport,
+  outboundToPostmark,
+  postmarkInboundToMail,
+  postmarkBounceToInbound,
+  postmarkResponseToResult,
+  postmarkErrorToResult,
+  parseAuthResults,
+  type PostmarkInbound,
+} from "../../src/mail/provider-transport.js";
+import * as http from "node:http";
+import { makeOutboundMail } from "./mock-mail.js";
+import { fakePostmarkClient } from "./mock-postmark.js";
+
+function post(
+  port: number,
+  path: string,
+  body: unknown,
+  headers: Record<string, string> = {}
+): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const data = Buffer.from(JSON.stringify(body));
+    const req = http.request(
+      {
+        host: "127.0.0.1",
+        port,
+        path,
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "content-length": data.length,
+          ...headers,
+        },
+      },
+      (res) => {
+        res.resume();
+        res.on("end", () => resolve(res.statusCode ?? 0));
+      }
+    );
+    req.on("error", reject);
+    req.end(data);
+  });
+}
+
+describe("postmarkResponseToResult / postmarkErrorToResult", () => {
+  it("maps ErrorCode 0 to delivered with the provider message id", () => {
+    expect(postmarkResponseToResult({ ErrorCode: 0, MessageID: "pm-9" })).toEqual({
+      disposition: "delivered",
+      remoteMessageId: "pm-9",
+    });
+  });
+
+  it("maps 429 to transient", () => {
+    expect(postmarkErrorToResult({ statusCode: 429, message: "rate" }).disposition).toBe(
+      "transient"
+    );
+  });
+
+  it("maps 5xx to transient", () => {
+    expect(postmarkErrorToResult({ statusCode: 500 }).disposition).toBe("transient");
+  });
+
+  it("maps inactive-recipient (422/406) to permanent", () => {
+    const r = postmarkErrorToResult({ statusCode: 422, code: 406, message: "inactive" });
+    expect(r.disposition).toBe("permanent");
+    expect(r.code).toBe(406);
+  });
+
+  it("maps invalid-email (300) to permanent", () => {
+    expect(postmarkErrorToResult({ statusCode: 422, code: 300 }).disposition).toBe(
+      "permanent"
+    );
+  });
+
+  it("treats unknown errors as transient", () => {
+    expect(postmarkErrorToResult({ message: "boom" }).disposition).toBe("transient");
+  });
+});
+
+describe("outboundToPostmark", () => {
+  it("maps addresses, body, and threading headers", () => {
+    const msg = outboundToPostmark(
+      makeOutboundMail({
+        from: { address: "alice@example.com", name: "Alice" },
+        to: [{ address: "ext@other.org" }],
+        cc: [{ address: "c@other.org" }],
+        subject: "subject",
+        text: "body",
+        html: "<p>body</p>",
+        headers: {
+          messageId: "<m@example.com>",
+          inReplyTo: "<p@other.org>",
+          references: ["<r1@other.org>", "<p@other.org>"],
+        },
+      })
+    );
+    expect(msg.From).toBe('"Alice" <alice@example.com>');
+    expect(msg.To).toBe("ext@other.org");
+    expect(msg.Cc).toBe("c@other.org");
+    expect(msg.Subject).toBe("subject");
+    expect(msg.TextBody).toBe("body");
+    expect(msg.HtmlBody).toBe("<p>body</p>");
+    expect(msg.Headers).toContainEqual({ Name: "Message-ID", Value: "<m@example.com>" });
+    expect(msg.Headers).toContainEqual({ Name: "In-Reply-To", Value: "<p@other.org>" });
+    expect(msg.Headers).toContainEqual({
+      Name: "References",
+      Value: "<r1@other.org> <p@other.org>",
+    });
+  });
+
+  it("includes base64 attachment content when resolved", () => {
+    const msg = outboundToPostmark(
+      makeOutboundMail({
+        attachments: [
+          {
+            filename: "a.txt",
+            contentType: "text/plain",
+            contentRef: "sha256:abc",
+            sizeBytes: 3,
+          },
+        ],
+      }),
+      new Map([["sha256:abc", "Zm9v"]])
+    );
+    expect(msg.Attachments).toEqual([
+      { Name: "a.txt", ContentType: "text/plain", ContentID: undefined, Content: "Zm9v" },
+    ]);
+  });
+});
+
+describe("postmarkInboundToMail", () => {
+  const payload: PostmarkInbound = {
+    FromFull: { Email: "ext@other.org", Name: "Ext" },
+    ToFull: [{ Email: "alice@example.com" }],
+    CcFull: [{ Email: "bob@example.com" }],
+    OriginalRecipient: "alice+scope@example.com",
+    Subject: "hi",
+    TextBody: "hello",
+    HtmlBody: "<p>hello</p>",
+    Date: "2026-02-02T10:00:00Z",
+    Headers: [
+      { Name: "Message-ID", Value: "<m1@other.org>" },
+      { Name: "In-Reply-To", Value: "<p0@other.org>" },
+      { Name: "References", Value: "<root@other.org> <p0@other.org>" },
+      {
+        Name: "Authentication-Results",
+        Value: "mx.example.com; spf=pass; dkim=pass; dmarc=pass",
+      },
+    ],
+  };
+
+  it("maps core fields and threading headers", () => {
+    const mail = postmarkInboundToMail(payload);
+    expect(mail.from).toEqual({ address: "ext@other.org", name: "Ext" });
+    expect(mail.to).toEqual([{ address: "alice@example.com", name: undefined }]);
+    expect(mail.cc).toEqual([{ address: "bob@example.com", name: undefined }]);
+    expect(mail.subject).toBe("hi");
+    expect(mail.text).toBe("hello");
+    expect(mail.html).toBe("<p>hello</p>");
+    expect(mail.headers.messageId).toBe("<m1@other.org>");
+    expect(mail.headers.inReplyTo).toBe("<p0@other.org>");
+    expect(mail.headers.references).toEqual(["<root@other.org>", "<p0@other.org>"]);
+    expect(mail.envelopeTo).toEqual(["alice+scope@example.com"]);
+  });
+
+  it("extracts auth results from the Authentication-Results header", () => {
+    const mail = postmarkInboundToMail(payload);
+    expect(mail.authResults).toEqual({ spf: "pass", dkim: "pass", dmarc: "pass" });
+  });
+
+  it("attaches stored attachment metadata", () => {
+    const mail = postmarkInboundToMail(payload, {
+      attachments: [
+        { filename: "x.pdf", contentType: "application/pdf", contentRef: "sha256:z", sizeBytes: 9 },
+      ],
+    });
+    expect(mail.attachments).toHaveLength(1);
+  });
+
+  it("counts attachment bytes toward sizeBytes (consistent with the SMTP path)", () => {
+    const bodyOnly = postmarkInboundToMail({ TextBody: "hi" });
+    const withAttachment = postmarkInboundToMail({
+      TextBody: "hi",
+      Attachments: [
+        { Name: "big.bin", Content: "", ContentType: "application/octet-stream", ContentLength: 100_000 },
+      ],
+    });
+    expect(withAttachment.sizeBytes).toBe(bodyOnly.sizeBytes + 100_000);
+  });
+});
+
+describe("postmarkBounceToInbound", () => {
+  it("maps a hard bounce to a failed DSN", () => {
+    const mail = postmarkBounceToInbound({
+      RecordType: "Bounce",
+      Type: "HardBounce",
+      TypeCode: 1,
+      Email: "user@dead.example",
+      MessageID: "pm-123",
+      Description: "The server was unable to deliver",
+      Details: "550 no such user",
+    });
+    expect(mail.bounce).toEqual({
+      action: "failed",
+      recipient: "user@dead.example",
+      status: "1",
+      originalMessageId: "pm-123",
+      diagnostic: "550 no such user",
+    });
+  });
+
+  it("maps a soft bounce to a delayed DSN", () => {
+    const mail = postmarkBounceToInbound({ Type: "SoftBounce", Email: "u@x" });
+    expect(mail.bounce?.action).toBe("delayed");
+  });
+});
+
+describe("parseAuthResults", () => {
+  it("returns undefined without a header", () => {
+    expect(parseAuthResults(undefined)).toBeUndefined();
+  });
+  it("parses a mixed verdict", () => {
+    expect(parseAuthResults("x; spf=fail; dkim=none; dmarc=fail")).toEqual({
+      spf: "fail",
+      dkim: "none",
+      dmarc: "fail",
+    });
+  });
+});
+
+describe("PostmarkTransport send (fake client)", () => {
+  it("sends via the client and maps a delivered response", async () => {
+    const client = fakePostmarkClient();
+    const t = new PostmarkTransport({ client });
+    await t.start();
+    const res = await t.send(makeOutboundMail({ idempotencyKey: "k1" }));
+    expect(res.disposition).toBe("delivered");
+    expect(client.sent).toHaveLength(1);
+  });
+
+  it("is idempotent: a duplicate key does not re-send", async () => {
+    const client = fakePostmarkClient();
+    const t = new PostmarkTransport({ client });
+    await t.start();
+    const env = makeOutboundMail({ idempotencyKey: "dup" });
+    await t.send(env);
+    const second = await t.send(env);
+    expect(second.detail).toMatch(/idempotent|replay/i);
+    expect(client.sent).toHaveLength(1);
+  });
+
+  it("ingests an inbound webhook payload and ACKs after the handler", async () => {
+    const client = fakePostmarkClient();
+    const t = new PostmarkTransport({ client });
+    const order: string[] = [];
+    t.onReceive(async (mail) => {
+      order.push(`handler:${mail.subject}`);
+    });
+    await t.start();
+    await t.ingestInboundWebhook({
+      FromFull: { Email: "ext@other.org" },
+      ToFull: [{ Email: "alice@example.com" }],
+      Subject: "webhook subject",
+      TextBody: "body",
+      Headers: [{ Name: "Message-ID", Value: "<w1@other.org>" }],
+    });
+    expect(order).toEqual(["handler:webhook subject"]);
+  });
+
+  it("propagates a handler throw from a bounce webhook (NACK)", async () => {
+    const client = fakePostmarkClient();
+    const t = new PostmarkTransport({ client });
+    t.onReceive(async () => {
+      throw new Error("commit failed");
+    });
+    await t.start();
+    await expect(
+      t.ingestBounceWebhook({ Type: "HardBounce", Email: "u@x", MessageID: "pm-1" })
+    ).rejects.toThrow(/commit failed/);
+  });
+});
+
+describe("PostmarkTransport built-in webhook listener", () => {
+  it("returns 200 after the inbound handler commits, 500 on throw", async () => {
+    const port = 31000 + Math.floor(Math.random() * 4000);
+    const client = fakePostmarkClient();
+    let shouldThrow = false;
+    const received: string[] = [];
+    const t = new PostmarkTransport({
+      client,
+      webhook: { port, inboundPath: "/in", bouncePath: "/bounce" },
+    });
+    t.onReceive(async (mail) => {
+      if (shouldThrow) throw new Error("commit failed");
+      received.push(mail.subject ?? "");
+    });
+    await t.start();
+    try {
+      const ok = await post(port, "/in", {
+        FromFull: { Email: "ext@other.org" },
+        ToFull: [{ Email: "alice@example.com" }],
+        Subject: "http subject",
+        TextBody: "b",
+        Headers: [{ Name: "Message-ID", Value: "<h1@x>" }],
+      });
+      expect(ok).toBe(200);
+      expect(received).toEqual(["http subject"]);
+
+      shouldThrow = true;
+      const fail = await post(port, "/in", {
+        FromFull: { Email: "ext@other.org" },
+        ToFull: [{ Email: "alice@example.com" }],
+        Subject: "will fail",
+        Headers: [{ Name: "Message-ID", Value: "<h2@x>" }],
+      });
+      expect(fail).toBe(500);
+    } finally {
+      await t.stop();
+    }
+  });
+
+  it("enforces Basic Auth on the webhook when configured", async () => {
+    const port = 31000 + Math.floor(Math.random() * 4000);
+    const received: string[] = [];
+    const t = new PostmarkTransport({
+      client: fakePostmarkClient(),
+      webhook: {
+        port,
+        inboundPath: "/in",
+        basicAuth: { user: "pm", pass: "secret" },
+      },
+    });
+    t.onReceive(async (mail) => {
+      received.push(mail.subject ?? "");
+    });
+    await t.start();
+    try {
+      const body = {
+        FromFull: { Email: "ext@other.org" },
+        ToFull: [{ Email: "alice@example.com" }],
+        Subject: "authed",
+        Headers: [{ Name: "Message-ID", Value: "<a1@x>" }],
+      };
+      // No credentials → 401, handler not called.
+      expect(await post(port, "/in", body)).toBe(401);
+      // Wrong credentials → 401.
+      const wrong = "Basic " + Buffer.from("pm:nope").toString("base64");
+      expect(await post(port, "/in", body, { authorization: wrong })).toBe(401);
+      expect(received).toHaveLength(0);
+      // Correct credentials → 200, handler called.
+      const right = "Basic " + Buffer.from("pm:secret").toString("base64");
+      expect(await post(port, "/in", body, { authorization: right })).toBe(200);
+      expect(received).toEqual(["authed"]);
+    } finally {
+      await t.stop();
+    }
+  });
+
+  it("rejects an oversized webhook body with 413", async () => {
+    const port = 31000 + Math.floor(Math.random() * 4000);
+    const received: string[] = [];
+    // Small maxMessageBytes → maxBody falls to the 1 MiB floor.
+    const t = new PostmarkTransport({
+      client: fakePostmarkClient(),
+      maxMessageBytes: 1000,
+      webhook: { port, inboundPath: "/in" },
+    });
+    t.onReceive(async (mail) => {
+      received.push(mail.subject ?? "");
+    });
+    await t.start();
+    try {
+      const huge = { TextBody: "x".repeat(1_200_000), Subject: "too big" };
+      expect(await post(port, "/in", huge)).toBe(413);
+      expect(received).toHaveLength(0);
+    } finally {
+      await t.stop();
+    }
+  });
+});

package/test/mail/rate-limiter.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { RateLimiter } from "../../src/mail/rate-limiter.js";
+
+describe("RateLimiter", () => {
+  it("allows up to max events in the window", () => {
+    const rl = new RateLimiter(1000, 3);
+    expect(rl.tryAcquire("a", 0)).toBe(true);
+    expect(rl.tryAcquire("a", 1)).toBe(true);
+    expect(rl.tryAcquire("a", 2)).toBe(true);
+    expect(rl.tryAcquire("a", 3)).toBe(false); // 4th in window
+  });
+
+  it("tracks keys independently", () => {
+    const rl = new RateLimiter(1000, 1);
+    expect(rl.tryAcquire("a", 0)).toBe(true);
+    expect(rl.tryAcquire("b", 0)).toBe(true);
+    expect(rl.tryAcquire("a", 0)).toBe(false);
+  });
+
+  it("frees capacity as events age out of the window", () => {
+    const rl = new RateLimiter(1000, 2);
+    expect(rl.tryAcquire("a", 0)).toBe(true);
+    expect(rl.tryAcquire("a", 500)).toBe(true);
+    expect(rl.tryAcquire("a", 600)).toBe(false);
+    // At t=1001 the t=0 event has aged out (cutoff = 1, 0 <= 1).
+    expect(rl.tryAcquire("a", 1001)).toBe(true);
+  });
+
+  it("treats max <= 0 as fully closed", () => {
+    const rl = new RateLimiter(1000, 0);
+    expect(rl.tryAcquire("a", 0)).toBe(false);
+  });
+
+  it("prune drops idle keys", () => {
+    const rl = new RateLimiter(1000, 5);
+    rl.tryAcquire("a", 0);
+    rl.prune(5000);
+    expect(rl.count("a", 5000)).toBe(0);
+  });
+
+  it("count reflects events within the window", () => {
+    const rl = new RateLimiter(1000, 5);
+    rl.tryAcquire("a", 0);
+    rl.tryAcquire("a", 100);
+    expect(rl.count("a", 200)).toBe(2);
+    expect(rl.count("a", 1050)).toBe(1); // t=0 aged out (cutoff=50), t=100 remains
+  });
+});