Skip to content

The open-source app everyone uses to manage agents at work

5.8 KB
Raw Blame
import express from "express";
import request from "supertest";
import type { Db } from "@paperclipai/db";
import { describe, expect, it, vi } from "vitest";
import { forbidden } from "../errors.js";
import { errorHandler } from "../middleware/error-handler.js";
import { emailRoutes } from "../routes/email.js";
import { agentmailApi } from "../services/agentmail-api.js";
import type { EmailChannelService } from "../services/email-channels.js";

const companyId = "11111111-1111-4111-8111-111111111111";
const agentId = "22222222-2222-4222-8222-222222222222";
const setupPath = `/api/companies/${companyId}/email/inboxes`;
const setupInput = {
  assignedAgentId: agentId,
  apiKey: "private-api-key",
  username: "ralph",
  receiveMode: "websocket",
  idempotencyKey: "33333333-3333-4333-8333-333333333333",
};

function app(setup: () => Promise<unknown>) {
  const instance = express();
  instance.use(express.json());
  instance.use((req, _res, next) => {
    req.actor = { type: "board", source: "local_implicit", userId: "board" };
    next();
  });
  instance.use("/api", emailRoutes({} as Db, { setup, inspect: setup } as unknown as EmailChannelService));
  instance.use(errorHandler);
  return instance;
}

describe("AgentMail provider errors at the HTTP boundary", () => {
  it("explains a key-creation 404 without claiming the allocated address is missing", async () => {
    const api = agentmailApi("private-api-key", vi.fn(async () => Response.json({ code: "not_found" }, { status: 404 })));
    const response = await request(app(() => api.createInboxKey("[email protected]")))
      .post(setupPath).send(setupInput).expect(422);
    expect(response.body.error).toBe("AgentMail could not create an access key for this inbox. The email address was saved; try finishing the connection again.");
    expect(response.body.details).toMatchObject({ providerStatus: 404, operation: "create_inbox_key" });
  });

  it.each(["resource_taken", "already_exists"])("identifies %s on inbox creation even when AgentMail returns 403", async (code) => {
    const api = agentmailApi("private-api-key", vi.fn(async () => Response.json({
      code, message: "private provider message", fix: "private-api-key", docs: "https://untrusted.invalid",
    }, { status: 403 })));
    const response = await request(app(() => api.createInbox({ username: "ralph" })))
      .post(setupPath).send(setupInput).expect(409);
    expect(response.body).toMatchObject({
      code: "agentmail_address_taken", error: "This email address is already in use. Choose a different address.",
      details: { field: "username", providerStatus: 403, operation: "create_inbox" },
    });
    expect(response.text).not.toMatch(/private|untrusted/);
  });

  it("does not mislabel a taken resource during another operation as a taken address", async () => {
    const api = agentmailApi("private-api-key", vi.fn(async () => Response.json({ code: "resource_taken" }, { status: 403 })));
    const response = await request(app(() => api.createInboxKey("[email protected]")))
      .post(setupPath).send(setupInput).expect(422);
    expect(response.body.code).toBe("agentmail_request_failed");
    expect(response.body.error).not.toContain("already in use");
  });

  it.each([
    [401, 422, "AgentMail rejected the API key"],
    [403, 422, "AgentMail did not allow Paperclip to create the email address"],
    [400, 422, "Try a different address"],
    [409, 422, "Try a different address"],
    [422, 422, "Try a different address"],
    [404, 422, "could not find the requested inbox or resource"],
    [429, 429, "rate limiting"],
    [503, 502, "temporarily unavailable"],
  ])("explains provider %i without exposing the provider body", async (providerStatus, status, message) => {
    const fetcher = vi.fn(async () => new Response("private provider body and private-api-key", {
      status: providerStatus,
      headers: { "Retry-After": "12" },
    }));
    const api = agentmailApi("private-api-key", fetcher);
    const response = await request(app(() => api.createInbox({ username: "ralph" })))
      .post(setupPath).send(setupInput);
    expect(response.status).toBe(status);
    expect(response.body.error).toContain(message);
    expect(response.body.details).toEqual({
      code: "agentmail_request_failed", providerStatus, operation: "create_inbox",
    });
    expect(response.text).not.toMatch(/private|Internal server error/);
    if (providerStatus === 429) expect(response.headers["retry-after"]).toBe("12");
  });

  it("explains a denied runtime-key creation without suggesting a different address", async () => {
    const api = agentmailApi("private-api-key", vi.fn(async () => new Response(null, { status: 403 })));
    const response = await request(app(() => api.createInboxKey("[email protected]")))
      .post(setupPath).send(setupInput).expect(422);
    expect(response.body.error).toContain("create an inbox-scoped API key");
    expect(response.body.error).not.toContain("different address");
    expect(response.body.details.operation).toBe("create_inbox_key");
  });

  it("keeps a rejected provider key distinct from Paperclip session authentication", async () => {
    const api = agentmailApi("private-api-key", vi.fn(async () => new Response(null, { status: 401 })));
    const response = await request(app(() => api.whoami()))
      .post(`/api/companies/${companyId}/email/inspect`).send({ apiKey: "private-api-key" }).expect(422);
    expect(response.body.error).toContain("AgentMail rejected the API key");
    expect(response.body.details.operation).toBe("inspect_key");
  });

  it("preserves Paperclip authorization errors", async () => {
    const response = await request(app(async () => { throw forbidden("Missing permission: tools:manage_connections"); }))
      .post(setupPath).send(setupInput).expect(403);
    expect(response.body.error).toBe("Missing permission: tools:manage_connections");
    expect(response.body.details).toBeUndefined();
  });
});