@app-vitals/agent-admin 0.0.0-stage → 0.1.0

package/src/accounts-api.ts

@@ -0,0 +1,289 @@
+/**
+ * admin/src/accounts-api.ts
+ * Admin-only /accounts API (SSP-5.1): list/get/create/patch self-serve
+ * accounts. Flag-gated (404 when SHIPWRIGHT_SELF_SERVE_ENABLED is off, checked
+ * before auth) and admin-only (admin cookie or scope "*" key); every other
+ * caller class gets 403.
+ *
+ * POST /accounts goes through AccountService.create(), which seeds the owner
+ * AccountMember row — so that owner's first login joins this account instead
+ * of creating a new one.
+ *
+ * PATCH /accounts/:id routes through AccountLifecycle.update() (SSP-8.2):
+ * status=suspended locks down the account's agents' crons, status=active
+ * restores the lockdown-disabled ones (422 if trialExpiresAt is still past).
+ */
+
+import { createRoute, OpenAPIHono } from "@hono/zod-openapi";
+import { HTTPException } from "hono/http-exception";
+import type { AccountLifecycle } from "./account-lifecycle.ts";
+import type { AccountService, UpdateAccountInput } from "./accounts.ts";
+import type { AgentTokenService } from "./agent-tokens.ts";
+import {
+  type AdminApiKey,
+  type AdminAuthEnv,
+  createAdminAuthMiddleware,
+} from "./api-auth.ts";
+import {
+  ApiError,
+  ConflictError,
+  ForbiddenError,
+  NotFoundError,
+} from "./errors.ts";
+import {
+  AccountIdParamSchema,
+  AccountResponseSchema,
+  AccountsListResponseSchema,
+  CreateAccountBodySchema,
+  ErrorSchema,
+  PatchAccountBodySchema,
+} from "./openapi-schemas.ts";
+import type { SelfServeConfig } from "./self-serve-config.ts";
+
+interface AccountsApiDeps {
+  accountService: Pick<
+    AccountService,
+    "listWithCounts" | "getWithCounts" | "create"
+  >;
+  /**
+   * PATCH goes through the lifecycle so a status change runs its cron
+   * lockdown/restore side effect (SSP-8.2).
+   */
+  accountLifecycle: Pick<AccountLifecycle, "update">;
+  selfServe?: SelfServeConfig;
+  sessionSecret: string;
+  adminApiKeys?: Map<string, AdminApiKey>;
+  agentTokenService: Pick<AgentTokenService, "validate">;
+}
+
+const jsonError = { content: { "application/json": { schema: ErrorSchema } } };
+
+const errorResponses = {
+  401: { description: "Unauthorized", ...jsonError },
+  403: { description: "Forbidden (non-admin caller)", ...jsonError },
+  404: { description: "Not found (or self-serve disabled)", ...jsonError },
+};
+
+const listAccountsRoute = createRoute({
+  method: "get",
+  path: "/accounts",
+  tags: ["accounts"],
+  summary: "List accounts",
+  description:
+    "Admin-only, flag-gated. Returns every account with agentCount and memberCount.",
+  responses: {
+    200: {
+      description: "Accounts",
+      content: { "application/json": { schema: AccountsListResponseSchema } },
+    },
+    ...errorResponses,
+  },
+});
+
+const getAccountRoute = createRoute({
+  method: "get",
+  path: "/accounts/{id}",
+  tags: ["accounts"],
+  summary: "Get an account",
+  description: "Admin-only, flag-gated.",
+  request: { params: AccountIdParamSchema },
+  responses: {
+    200: {
+      description: "Account",
+      content: { "application/json": { schema: AccountResponseSchema } },
+    },
+    ...errorResponses,
+  },
+});
+
+const createAccountRoute = createRoute({
+  method: "post",
+  path: "/accounts",
+  tags: ["accounts"],
+  summary: "Create an account",
+  description:
+    "Admin-only, flag-gated. Creates the account and seeds ownerEmail as its owner member, so that owner's first login joins this account. 409 if ownerEmail already belongs to an account.",
+  request: {
+    body: {
+      content: { "application/json": { schema: CreateAccountBodySchema } },
+    },
+  },
+  responses: {
+    201: {
+      description: "Account created",
+      content: { "application/json": { schema: AccountResponseSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+    409: { description: "Owner email already in an account", ...jsonError },
+    ...errorResponses,
+  },
+});
+
+const patchAccountRoute = createRoute({
+  method: "patch",
+  path: "/accounts/{id}",
+  tags: ["accounts"],
+  summary: "Update an account",
+  description:
+    "Admin-only, flag-gated. Updates name, maxAgents, plan, status and/or trialExpiresAt. status=suspended (or trial_expired) disables every enabled cron of the account's agents with a lockdown marker; status=active re-enables exactly those, and requires trialExpiresAt to be cleared or in the future (422 otherwise). Nothing is deleted.",
+  request: {
+    params: AccountIdParamSchema,
+    body: {
+      content: { "application/json": { schema: PatchAccountBodySchema } },
+    },
+  },
+  responses: {
+    200: {
+      description: "Account updated",
+      content: { "application/json": { schema: AccountResponseSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+    422: {
+      description: "Reactivation with trialExpiresAt still in the past",
+      ...jsonError,
+    },
+    ...errorResponses,
+  },
+});
+
+function serialize(a: {
+  id: string;
+  name: string;
+  status: string;
+  maxAgents: number;
+  plan: string | null;
+  trialExpiresAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+  agentCount: number;
+  memberCount: number;
+}) {
+  return {
+    id: a.id,
+    name: a.name,
+    status: a.status as "active" | "suspended" | "trial_expired",
+    maxAgents: a.maxAgents,
+    plan: a.plan,
+    trialExpiresAt: a.trialExpiresAt?.toISOString() ?? null,
+    createdAt: a.createdAt.toISOString(),
+    updatedAt: a.updatedAt.toISOString(),
+    agentCount: a.agentCount,
+    memberCount: a.memberCount,
+  };
+}
+
+export function createAccountsApp(
+  deps: AccountsApiDeps,
+): OpenAPIHono<AdminAuthEnv> {
+  const { accountService, selfServe } = deps;
+
+  const app = new OpenAPIHono<AdminAuthEnv>({
+    defaultHook: (result, c) => {
+      if (!result.success) {
+        const message = result.error.issues
+          .map((i) => `${i.path.join(".")}: ${i.message}`)
+          .join(", ");
+        return c.json({ error: message }, 400);
+      }
+    },
+  });
+
+  app.onError((err, c) => {
+    if (err instanceof ApiError && err.statusCode < 500) {
+      return c.json(
+        { error: err.message },
+        err.statusCode as 400 | 401 | 403 | 404 | 409 | 422,
+      );
+    }
+    if (err instanceof HTTPException && err.status < 500) {
+      return c.json({ error: err.message }, err.status as 400 | 415);
+    }
+    console.error("[accounts-api] unhandled error:", err);
+    return c.json({ error: "Internal server error" }, 500);
+  });
+
+  const authMiddleware = createAdminAuthMiddleware({
+    sessionSecret: deps.sessionSecret,
+    agentTokenService: deps.agentTokenService,
+    adminApiKeys: deps.adminApiKeys,
+  });
+
+  // Flag gate runs before auth so a disabled deployment reveals nothing.
+  const flagGate: Parameters<typeof app.use>[1] = async (c, next) => {
+    if (selfServe?.enabled !== true) return c.json({ error: "Not found" }, 404);
+    return next();
+  };
+  // "/accounts/*" also matches the bare "/accounts" path in Hono.
+  app.use("/accounts/*", flagGate);
+  app.use("/accounts/*", authMiddleware);
+
+  const requireAdmin = (c: { get: (k: "isAdmin") => unknown }) => {
+    if (c.get("isAdmin") !== true) {
+      throw new ForbiddenError("Admin access required");
+    }
+  };
+
+  app.openapi(listAccountsRoute, async (c) => {
+    requireAdmin(c);
+    const accounts = await accountService.listWithCounts();
+    return c.json({ accounts: accounts.map(serialize) }, 200);
+  });
+
+  app.openapi(getAccountRoute, async (c) => {
+    requireAdmin(c);
+    const { id } = c.req.valid("param");
+    const account = await accountService.getWithCounts(id);
+    if (!account) throw new NotFoundError(`account ${id} not found`);
+    return c.json(serialize(account), 200);
+  });
+
+  app.openapi(createAccountRoute, async (c) => {
+    requireAdmin(c);
+    const body = c.req.valid("json");
+    let createdId: string;
+    try {
+      const created = await accountService.create(body.name, body.ownerEmail, {
+        maxAgents: body.maxAgents,
+        ...(body.plan !== undefined ? { plan: body.plan } : {}),
+        ...(body.trialExpiresAt !== undefined
+          ? {
+              trialExpiresAt: body.trialExpiresAt
+                ? new Date(body.trialExpiresAt)
+                : null,
+            }
+          : {}),
+      });
+      createdId = created.id;
+    } catch (err) {
+      if ((err as { code?: string }).code === "P2002") {
+        throw new ConflictError("ownerEmail already belongs to an account");
+      }
+      throw err;
+    }
+    const account = await accountService.getWithCounts(createdId);
+    if (!account) throw new NotFoundError(`account ${createdId} not found`);
+    return c.json(serialize(account), 201);
+  });
+
+  app.openapi(patchAccountRoute, async (c) => {
+    requireAdmin(c);
+    const { id } = c.req.valid("param");
+    const body = c.req.valid("json");
+    if (!(await accountService.getWithCounts(id))) {
+      throw new NotFoundError(`account ${id} not found`);
+    }
+    const { trialExpiresAt, ...rest } = body;
+    const data: UpdateAccountInput = {
+      ...rest,
+      ...(trialExpiresAt !== undefined
+        ? { trialExpiresAt: trialExpiresAt ? new Date(trialExpiresAt) : null }
+        : {}),
+    };
+    await deps.accountLifecycle.update(id, data);
+    const account = await accountService.getWithCounts(id);
+    if (!account) throw new NotFoundError(`account ${id} not found`);
+    return c.json(serialize(account), 200);
+  });
+
+  return app;
+}

package/src/accounts-api.unit.test.ts

@@ -0,0 +1,93 @@
+/**
+ * admin/src/accounts-api.unit.test.ts
+ * Parse/reject tests for the /accounts OpenAPI schemas (SSP-5.1).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  AccountResponseSchema,
+  CreateAccountBodySchema,
+  PatchAccountBodySchema,
+} from "./openapi-schemas.ts";
+
+describe("CreateAccountBodySchema", () => {
+  test("accepts the minimal body", () => {
+    const r = CreateAccountBodySchema.safeParse({
+      name: "Acme",
+      ownerEmail: "Owner@Acme.com",
+      maxAgents: 3,
+    });
+    expect(r.success).toBe(true);
+  });
+
+  test("accepts plan and trialExpiresAt", () => {
+    const r = CreateAccountBodySchema.safeParse({
+      name: "Acme",
+      ownerEmail: "o@acme.com",
+      maxAgents: 0,
+      plan: "pro",
+      trialExpiresAt: "2030-01-01T00:00:00.000Z",
+    });
+    expect(r.success).toBe(true);
+  });
+
+  test.each([
+    ["empty name", { name: "", ownerEmail: "o@a.com", maxAgents: 1 }],
+    ["bad email", { name: "A", ownerEmail: "nope", maxAgents: 1 }],
+    ["negative maxAgents", { name: "A", ownerEmail: "o@a.com", maxAgents: -1 }],
+    [
+      "fractional maxAgents",
+      { name: "A", ownerEmail: "o@a.com", maxAgents: 1.5 },
+    ],
+    ["missing maxAgents", { name: "A", ownerEmail: "o@a.com" }],
+    [
+      "bad trialExpiresAt",
+      { name: "A", ownerEmail: "o@a.com", maxAgents: 1, trialExpiresAt: "x" },
+    ],
+  ])("rejects %s", (_label, body) => {
+    expect(CreateAccountBodySchema.safeParse(body).success).toBe(false);
+  });
+});
+
+describe("PatchAccountBodySchema", () => {
+  test("accepts partial bodies and nullable plan/trial", () => {
+    expect(PatchAccountBodySchema.safeParse({ maxAgents: 3 }).success).toBe(
+      true,
+    );
+    expect(
+      PatchAccountBodySchema.safeParse({ plan: null, trialExpiresAt: null })
+        .success,
+    ).toBe(true);
+    expect(
+      PatchAccountBodySchema.safeParse({ status: "suspended" }).success,
+    ).toBe(true);
+  });
+
+  test("rejects unknown status and negative maxAgents", () => {
+    expect(PatchAccountBodySchema.safeParse({ status: "bogus" }).success).toBe(
+      false,
+    );
+    expect(PatchAccountBodySchema.safeParse({ maxAgents: -2 }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe("AccountResponseSchema", () => {
+  test("parses a full account with counts", () => {
+    const now = new Date().toISOString();
+    const r = AccountResponseSchema.safeParse({
+      id: "a1",
+      name: "Acme",
+      status: "active",
+      maxAgents: 3,
+      plan: null,
+      trialExpiresAt: null,
+      createdAt: now,
+      updatedAt: now,
+      agentCount: 1,
+      memberCount: 2,
+    });
+    expect(r.success).toBe(true);
+  });
+});

package/src/accounts.integration.test.ts

@@ -0,0 +1,178 @@
+/**
+ * admin/src/accounts.integration.test.ts
+ * Integration tests for AccountService, AccountMemberService and
+ * AccountInviteService (SSP-1.2) against real Postgres.
+ *
+ * Requires DATABASE_URL_ADMIN_TEST to be set; skips otherwise.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { AccountInviteService } from "./account-invites.ts";
+import {
+  AccountMemberNotFoundError,
+  AccountMemberService,
+  LastOwnerError,
+} from "./account-members.ts";
+import { AccountService } from "./accounts.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+describeOrSkip("Account services (integration)", () => {
+  let prisma: PrismaClient;
+  let accounts: AccountService;
+  let members: AccountMemberService;
+  let invites: AccountInviteService;
+
+  beforeEach(async () => {
+    prisma = createAdminPrismaClient(TEST_DB as string);
+    await prisma.accountInvite.deleteMany();
+    await prisma.accountMember.deleteMany();
+    await prisma.agent.deleteMany();
+    await prisma.account.deleteMany();
+    accounts = new AccountService(prisma);
+    members = new AccountMemberService(prisma);
+    invites = new AccountInviteService(prisma);
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  describe("AccountService", () => {
+    it("create() makes the account with defaults and a lowercased owner row", async () => {
+      const account = await accounts.create("Acme", "Owner@Acme.COM");
+      expect(account.status).toBe("active");
+      expect(account.maxAgents).toBe(0);
+      const rows = await members.listByAccount(account.id);
+      expect(rows.map((r) => [r.email, r.role])).toEqual([
+        ["owner@acme.com", "owner"],
+      ]);
+    });
+
+    it("create() rolls back the account when the owner email is taken", async () => {
+      await accounts.create("A", "dup@x.com");
+      await expect(
+        (async () => accounts.create("B", "DUP@x.com"))(),
+      ).rejects.toThrow();
+      expect((await accounts.list()).map((a) => a.name)).toEqual(["A"]);
+    });
+
+    it("getByMemberEmail() is case-insensitive", async () => {
+      const account = await accounts.create("Acme", "o@acme.com");
+      expect((await accounts.getByMemberEmail("O@ACME.com"))?.id).toBe(
+        account.id,
+      );
+      expect(await accounts.getByMemberEmail("nobody@x.com")).toBeNull();
+    });
+
+    it("countAgents() counts only agents of that account", async () => {
+      const a = await accounts.create("A", "a@x.com");
+      const b = await accounts.create("B", "b@x.com");
+      await prisma.agent.create({ data: { name: "1", accountId: a.id } });
+      await prisma.agent.create({ data: { name: "2", accountId: a.id } });
+      await prisma.agent.create({ data: { name: "3", accountId: b.id } });
+      expect(await accounts.countAgents(a.id)).toBe(2);
+    });
+
+    it("existing agents keep accountId NULL and an account with agents cannot be deleted", async () => {
+      const legacy = await prisma.agent.create({ data: { name: "legacy" } });
+      expect(legacy.accountId).toBeNull();
+      const a = await accounts.create("A", "a@x.com");
+      await prisma.agent.create({ data: { name: "x", accountId: a.id } });
+      await expect(
+        (async () => prisma.account.delete({ where: { id: a.id } }))(),
+      ).rejects.toThrow();
+    });
+
+    it("update() changes fields", async () => {
+      const a = await accounts.create("A", "a@x.com");
+      const updated = await accounts.update(a.id, {
+        status: "suspended",
+        maxAgents: 3,
+      });
+      expect(updated.status).toBe("suspended");
+      expect(updated.maxAgents).toBe(3);
+    });
+  });
+
+  describe("AccountMemberService", () => {
+    it("UNIQUE(email) rejects the same email in a second account", async () => {
+      await accounts.create("A", "shared@x.com");
+      const b = await accounts.create("B", "b@x.com");
+      await expect(
+        (async () => members.add(b.id, "Shared@X.com"))(),
+      ).rejects.toThrow();
+    });
+
+    it("refuses to remove the last owner and changes nothing", async () => {
+      const a = await accounts.create("A", "o@x.com");
+      await members.add(a.id, "m@x.com");
+      await expect(
+        (async () => members.remove(a.id, "O@x.com"))(),
+      ).rejects.toBeInstanceOf(LastOwnerError);
+      expect(await members.listByAccount(a.id)).toHaveLength(2);
+    });
+
+    it("refuses to demote the last owner and changes nothing", async () => {
+      const a = await accounts.create("A", "o@x.com");
+      await expect(
+        (async () => members.demote(a.id, "o@x.com"))(),
+      ).rejects.toBeInstanceOf(LastOwnerError);
+      expect((await members.getByEmail("o@x.com"))?.role).toBe("owner");
+    });
+
+    it("allows demoting/removing an owner once another owner exists", async () => {
+      const a = await accounts.create("A", "o@x.com");
+      await members.add(a.id, "m@x.com");
+      await members.promote(a.id, "M@x.com");
+      expect((await members.demote(a.id, "o@x.com")).role).toBe("member");
+      await expect(
+        (async () => members.remove(a.id, "m@x.com"))(),
+      ).rejects.toBeInstanceOf(LastOwnerError);
+    });
+
+    it("removes a plain member and errors on unknown members", async () => {
+      const a = await accounts.create("A", "o@x.com");
+      await members.add(a.id, "m@x.com");
+      await members.remove(a.id, "m@x.com");
+      expect(await members.getByEmail("m@x.com")).toBeNull();
+      await expect(
+        (async () => members.remove(a.id, "m@x.com"))(),
+      ).rejects.toBeInstanceOf(AccountMemberNotFoundError);
+    });
+  });
+
+  describe("AccountInviteService", () => {
+    it("create() lowercases and listPending() returns it", async () => {
+      const a = await accounts.create("A", "o@x.com");
+      await invites.create(a.id, "New@X.com", "o@x.com");
+      const pending = await invites.listPending(a.id);
+      expect(pending.map((i) => i.email)).toEqual(["new@x.com"]);
+    });
+
+    it("acceptForEmail() marks accepted and returns the account; second call is a no-op", async () => {
+      const a = await accounts.create("A", "o@x.com");
+      await invites.create(a.id, "new@x.com", "o@x.com");
+      const first = await invites.acceptForEmail("NEW@x.com");
+      expect(first?.id).toBe(a.id);
+      expect(await invites.listPending(a.id)).toHaveLength(0);
+      const row = await prisma.accountInvite.findFirst({
+        where: { accountId: a.id },
+      });
+      expect(row?.acceptedAt).not.toBeNull();
+      expect(await invites.acceptForEmail("new@x.com")).toBeNull();
+    });
+
+    it("revoke() removes a pending invite", async () => {
+      const a = await accounts.create("A", "o@x.com");
+      await invites.create(a.id, "new@x.com", "o@x.com");
+      await invites.revoke(a.id, "NEW@x.com");
+      expect(await invites.listPending(a.id)).toHaveLength(0);
+      expect(await invites.acceptForEmail("new@x.com")).toBeNull();
+    });
+  });
+});