agent-inbox 0.2.4 → 0.2.5

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

@@ -1,381 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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
-  });
-});

package/test/mail/router-mail-integration.test.ts

@@ -1,138 +0,0 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import { EventEmitter } from "node:events";
-import { InMemoryStorage } from "../../src/storage/memory.js";
-import {
-  MessageRouter,
-  type MailEgress,
-} from "../../src/router/message-router.js";
-import { MailGateway } from "../../src/mail/mail-gateway.js";
-import { MockMailTransport } from "./mock-mail.js";
-import type { Agent, Message } from "../../src/types.js";
-
-function agent(id: string): Agent {
-  return {
-    agent_id: id,
-    scope: "default",
-    status: "active",
-    metadata: {},
-    registered_at: new Date().toISOString(),
-    last_active_at: new Date().toISOString(),
-  };
-}
-
-const tick = () => new Promise((r) => setImmediate(r));
-
-describe("router ↔ mail integration", () => {
-  let storage: InMemoryStorage;
-  let events: EventEmitter;
-  let router: MessageRouter;
-  let transport: MockMailTransport;
-  let gateway: MailGateway;
-
-  beforeEach(async () => {
-    storage = new InMemoryStorage();
-    events = new EventEmitter();
-    router = new MessageRouter(storage, events);
-    storage.putAgent(agent("alice"));
-    storage.putAgent(agent("bob"));
-    transport = new MockMailTransport();
-    await transport.start();
-    gateway = new MailGateway({
-      transport,
-      storage,
-      router,
-      events,
-      config: {
-        identity: {
-          localDomains: ["example.com"],
-          mappings: [{ agentId: "alice", address: "alice@example.com" }],
-        },
-        routableDomains: ["external.org"],
-      },
-    });
-    router.setMail(gateway);
-  });
-
-  it("routes external mail recipients to the gateway, not local delivery", async () => {
-    const msg = await router.routeMessage({
-      from: "alice",
-      to: [{ agent_id: "user@external.org", kind: "to" }],
-      payload: "hello world",
-    });
-    await tick();
-
-    expect(transport.sent).toHaveLength(1);
-    expect(transport.sent[0].to).toEqual([{ address: "user@external.org" }]);
-    // The mail recipient is not treated as a delivered local agent.
-    const stored = storage.getMessage(msg.id)!;
-    expect(stored.recipients[0].delivered_at).toBeTruthy(); // set by gateway on send
-  });
-
-  it("delivers local recipients locally and mail recipients via the gateway", async () => {
-    await router.routeMessage({
-      from: "alice",
-      to: [
-        { agent_id: "bob", kind: "to" },
-        { agent_id: "user@external.org", kind: "to" },
-      ],
-      payload: "mixed",
-    });
-    await tick();
-
-    expect(storage.getInbox("bob")).toHaveLength(1);
-    expect(transport.sent).toHaveLength(1);
-  });
-
-  it("does not send local-only messages through mail", async () => {
-    await router.routeMessage({
-      from: "alice",
-      to: [{ agent_id: "bob", kind: "to" }],
-      payload: "local only",
-    });
-    await tick();
-    expect(transport.sent).toHaveLength(0);
-  });
-
-  it("sends non-mail remote recipients to federation, not mail", async () => {
-    const routed: Message[] = [];
-    const fakeFederation = {
-      route: async (m: Message) => {
-        routed.push(m);
-        return { delivered: false };
-      },
-    };
-    // Cast: the router only calls .route() on the federation handle.
-    router.setFederation(fakeFederation as never);
-
-    await router.routeMessage({
-      from: "alice",
-      to: [{ agent_id: "carol@system-2", kind: "to" }],
-      payload: "federated",
-    });
-    await tick();
-
-    expect(routed).toHaveLength(1);
-    expect(transport.sent).toHaveLength(0);
-  });
-
-  it("ownsRecipient distinguishes mail domains from federation systems", () => {
-    expect(gateway.ownsRecipient("user@external.org")).toBe(true);
-    expect(gateway.ownsRecipient("user@example.com")).toBe(true);
-    expect(gateway.ownsRecipient("carol@system-2")).toBe(false);
-    expect(gateway.ownsRecipient("bob")).toBe(false);
-  });
-});
-
-describe("MailEgress contract shape", () => {
-  it("MailGateway satisfies MailEgress", () => {
-    const eg: MailEgress = new MailGateway({
-      transport: new MockMailTransport(),
-      storage: new InMemoryStorage(),
-      router: new MessageRouter(new InMemoryStorage(), new EventEmitter()),
-      events: new EventEmitter(),
-      config: { identity: { localDomains: ["x.com"], mappings: [] } },
-    });
-    expect(typeof eg.ownsRecipient).toBe("function");
-    expect(typeof eg.send).toBe("function");
-  });
-});

package/test/mail/smtp-e2e.test.ts

@@ -1,98 +0,0 @@
-import { describe, it, expect, afterEach } from "vitest";
-import { SmtpTransport } from "../../src/mail/smtp-transport.js";
-import { makeOutboundMail } from "./mock-mail.js";
-import type { InboundMail } from "../../src/mail/types.js";
-
-// These libs are optional peer deps; skip the real-socket e2e if absent.
-const haveLibs = await Promise.all([
-  import("smtp-server").then(() => true).catch(() => false),
-  import("nodemailer").then(() => true).catch(() => false),
-  import("mailparser").then(() => true).catch(() => false),
-]).then((r) => r.every(Boolean));
-
-const randomPort = () => 30000 + Math.floor(Math.random() * 5000);
-
-describe.skipIf(!haveLibs)("SmtpTransport e2e (loopback)", () => {
-  const transports: SmtpTransport[] = [];
-  afterEach(async () => {
-    for (const t of transports) await t.stop().catch(() => {});
-    transports.length = 0;
-  });
-
-  it("delivers a message from one transport to another and ACKs after commit", async () => {
-    const recvPort = randomPort();
-
-    // Receiver: captures inbound and resolves only after a simulated commit.
-    const received: InboundMail[] = [];
-    const committed: string[] = [];
-    const receiver = new SmtpTransport({ listenPort: recvPort });
-    receiver.onReceive(async (mail) => {
-      received.push(mail);
-      await new Promise((r) => setTimeout(r, 5)); // simulate async storage commit
-      committed.push("done");
-    });
-    transports.push(receiver);
-    await receiver.start();
-
-    // Sender: listens on a different port, relays to the receiver.
-    const sender = new SmtpTransport({
-      listenPort: randomPort(),
-      relay: { host: "127.0.0.1", port: recvPort, secure: false },
-    });
-    transports.push(sender);
-    await sender.start();
-
-    const result = await sender.send(
-      makeOutboundMail({
-        idempotencyKey: "e2e-1",
-        from: { address: "alice@example.com" },
-        to: [{ address: "bob@receiver.test" }],
-        subject: "e2e subject",
-        text: "e2e body",
-        headers: { messageId: "<e2e-1@example.com>" },
-      })
-    );
-
-    expect(result.disposition).toBe("delivered");
-
-    // Allow the receiver's onData/handler to run.
-    await new Promise((r) => setTimeout(r, 100));
-
-    expect(received).toHaveLength(1);
-    expect(received[0].subject).toBe("e2e subject");
-    expect(received[0].text?.trim()).toBe("e2e body");
-    expect(received[0].headers.messageId).toBe("<e2e-1@example.com>");
-    // The handler's commit ran (ACK happened after it).
-    expect(committed).toEqual(["done"]);
-  });
-
-  it("is idempotent on the sender for a repeated idempotencyKey", async () => {
-    const recvPort = randomPort();
-    const received: InboundMail[] = [];
-    const receiver = new SmtpTransport({ listenPort: recvPort });
-    receiver.onReceive(async (mail) => {
-      received.push(mail);
-    });
-    transports.push(receiver);
-    await receiver.start();
-
-    const sender = new SmtpTransport({
-      listenPort: randomPort(),
-      relay: { host: "127.0.0.1", port: recvPort, secure: false },
-    });
-    transports.push(sender);
-    await sender.start();
-
-    const env = makeOutboundMail({
-      idempotencyKey: "dup-key",
-      to: [{ address: "bob@receiver.test" }],
-      headers: { messageId: "<dup-key@example.com>" },
-    });
-    await sender.send(env);
-    const second = await sender.send(env);
-
-    expect(second.detail).toMatch(/idempotent|replay/i);
-    await new Promise((r) => setTimeout(r, 100));
-    expect(received).toHaveLength(1); // not delivered twice
-  });
-});