agent-inbox 0.2.4 → 0.2.5

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

@@ -1,134 +0,0 @@
-/**
- * Shared MailTransport contract suite.
- *
- * Any backend that provides a MailTransportHarness must pass this suite
- * unchanged — it encodes the hardening guarantees from §2/§3 of the plan.
- * Run it against new backends by adding another `runMailTransportContract(...)`.
- */
-
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import type { MailTransportHarness } from "./mock-mail.js";
-import { mockMailHarness, makeInboundMail, makeOutboundMail } from "./mock-mail.js";
-import { postmarkHarness } from "./mock-postmark.js";
-
-export function runMailTransportContract(
-  name: string,
-  makeHarness: () => MailTransportHarness
-): void {
-  describe(`MailTransport contract: ${name}`, () => {
-    let h: MailTransportHarness;
-
-    beforeEach(async () => {
-      h = makeHarness();
-      await h.transport.start();
-    });
-
-    afterEach(async () => {
-      await h.transport.stop();
-    });
-
-    it("start() leaves the transport in a ready state", async () => {
-      expect(h.transport.state).toBe("ready");
-      expect((await h.transport.health()).state).toBe("ready");
-    });
-
-    it("start() is idempotent", async () => {
-      await h.transport.start();
-      await h.transport.start();
-      expect(h.transport.state).toBe("ready");
-    });
-
-    it("send() returns delivered (never throws) on success", async () => {
-      h.programNextSend({ disposition: "delivered", remoteMessageId: "x" });
-      const res = await h.transport.send(makeOutboundMail());
-      expect(res.disposition).toBe("delivered");
-    });
-
-    it("send() returns — does not throw — on transient failure", async () => {
-      h.programNextSend({ disposition: "transient", code: 451 });
-      const res = await h.transport.send(makeOutboundMail());
-      expect(res.disposition).toBe("transient");
-    });
-
-    it("send() returns — does not throw — on permanent failure", async () => {
-      h.programNextSend({ disposition: "permanent", code: 550 });
-      const res = await h.transport.send(makeOutboundMail());
-      expect(res.disposition).toBe("permanent");
-    });
-
-    it("is idempotent on idempotencyKey: a duplicate delivered send produces no second email", async () => {
-      const env = makeOutboundMail({ idempotencyKey: "dup-1" });
-      const first = await h.transport.send(env);
-      const second = await h.transport.send(env);
-      expect(first.disposition).toBe("delivered");
-      expect(second.disposition).toBe("delivered");
-      // Both report delivered, but the second is a replay, not a new email.
-      expect(second.detail).toMatch(/idempotent|replay/i);
-    });
-
-    it("ACKs inbound only after the handler resolves", async () => {
-      const order: string[] = [];
-      h.transport.onReceive(async () => {
-        order.push("handler-start");
-        await Promise.resolve();
-        order.push("handler-end");
-      });
-      await h.injectInbound(makeInboundMail());
-      // injectInbound resolving (the ACK) must come strictly after handler-end.
-      expect(order).toEqual(["handler-start", "handler-end"]);
-    });
-
-    it("NACKs inbound (rejects) when the handler throws", async () => {
-      h.transport.onReceive(async () => {
-        throw new Error("storage commit failed");
-      });
-      await expect(h.injectInbound(makeInboundMail())).rejects.toThrow(
-        /storage commit failed/
-      );
-    });
-
-    it("delivers the inbound message to the handler intact", async () => {
-      let received: unknown;
-      h.transport.onReceive(async (mail) => {
-        received = mail;
-      });
-      const mail = makeInboundMail({ subject: "specific-subject" });
-      await h.injectInbound(mail);
-      expect((received as { subject: string }).subject).toBe("specific-subject");
-    });
-  });
-}
-
-// Run the contract against the in-process mock and the Postmark provider
-// backend (via a fake client). Real SMTP I/O is covered by smtp-e2e.test.ts.
-runMailTransportContract("MockMailTransport", () => mockMailHarness());
-runMailTransportContract("PostmarkTransport", () => postmarkHarness());
-
-describe("MockMailTransport specifics", () => {
-  let h: ReturnType<typeof mockMailHarness>;
-
-  beforeEach(async () => {
-    h = mockMailHarness();
-    await h.transport.start();
-  });
-
-  it("send() throws (programmer error) when not started", async () => {
-    const fresh = mockMailHarness();
-    await expect(fresh.transport.send(makeOutboundMail())).rejects.toThrow(
-      /state/
-    );
-  });
-
-  it("records one entry in sent per delivered email and dedups replays", async () => {
-    const env = makeOutboundMail({ idempotencyKey: "k1" });
-    await h.transport.send(env);
-    await h.transport.send(env);
-    expect(h.mock.sent).toHaveLength(1);
-  });
-
-  it("does not record sent for a transient failure", async () => {
-    h.programNextSend({ disposition: "transient" });
-    await h.transport.send(makeOutboundMail({ idempotencyKey: "k2" }));
-    expect(h.mock.sent).toHaveLength(0);
-  });
-});

package/test/mail/mock-mail.ts

@@ -1,161 +0,0 @@
-/**
- * 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

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