feat: site settings - users (#225)

Author: hugodutka

CLAUDE.md

@@ -0,0 +1,5 @@
+Use `bun` for all package management, test running, building, etc.
+
+Use `bun run typecheck` to run type checking.
+
+Use `bunx biome check <path-to-file>` to run lint when you modify code.

internal/api/src/client-helper.ts

@@ -37,8 +37,8 @@ export const assertResponseStatus = async <T extends number>(
 };
 
 export const schemaPaginatedRequest = z.object({
-  per_page: z.number().int().positive().max(100).default(10).optional(),
-  page: z.number().int().nonnegative().default(0).optional(),
+  per_page: z.coerce.number().int().positive().max(100).default(10).optional(),
+  page: z.coerce.number().int().nonnegative().default(0).optional(),
 });
 
 /**

internal/api/src/client.browser.ts

@@ -1,3 +1,4 @@
+import AdminUsers from "./routes/admin/users.client";
 import Agents from "./routes/agents/agents.client";
 import Auth from "./routes/auth/auth.client";
 import Chats from "./routes/chats/chats.client";
@@ -21,6 +22,9 @@ export default class Client {
   protected readonly baseURL: URL;
   private readonly fetch?: typeof globalThis.fetch;
 
+  public readonly admin = {
+    users: new AdminUsers(this),
+  };
   public readonly auth: Auth;
   public readonly chats = new Chats(this);
 
@@ -98,6 +102,7 @@ export default class Client {
   }
 }
 
+export * from "./routes/admin/users.client";
 export * from "./routes/agents/agents.client";
 export * from "./routes/agents/traces.client";
 export * from "./routes/chats/chats.client";

internal/api/src/middleware.ts

@@ -205,6 +205,29 @@ function readAuthTokenFromRequest(
 
 export const withAuth = createAuthMiddleware();
 
+/**
+ * Middleware to ensure the user is a site admin.
+ * Automatically calls withAuth first.
+ */
+export const withSiteAdmin: MiddlewareHandler<{
+  Bindings: Bindings;
+  Variables: {
+    user_id: string;
+    api_key?: ApiKey;
+    auth_type: "session" | "api_key";
+  };
+}> = async (c, next) => {
+  await withAuth(c, async () => {
+    const db = await c.env.database();
+    const userId = c.get("user_id");
+    const user = await db.selectUserByID(userId);
+    if (!user || user.site_role !== "admin") {
+      throw new HTTPException(403, { message: "Forbidden" });
+    }
+    await next();
+  });
+};
+
 export const withDevhookAuth: MiddlewareHandler<{
   Bindings: Bindings;
   Variables: {

internal/api/src/routes/admin/users.client.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import type Client from "../../client.browser";
+import {
+  assertResponseStatus,
+  schemaPaginatedRequest,
+  schemaPaginatedResponse,
+} from "../../client-helper";
+
+export const schemaSiteRole = z.enum(["admin", "member"]);
+
+export type SiteRole = z.infer<typeof schemaSiteRole>;
+
+const schemaSiteUser = z.object({
+  id: z.uuid(),
+  created_at: z.date(),
+  updated_at: z.date(),
+  display_name: z.string().nullable(),
+  email: z.email(),
+  avatar_url: z.url().nullable(),
+  username: z.string(),
+  organization_id: z.uuid(),
+  site_role: schemaSiteRole,
+});
+
+export type SiteUser = z.infer<typeof schemaSiteUser>;
+
+export const schemaListSiteUsersRequest = schemaPaginatedRequest.extend({
+  query: z.string().optional(),
+  site_role: schemaSiteRole.optional(),
+});
+
+export type ListSiteUsersRequest = z.infer<typeof schemaListSiteUsersRequest>;
+
+const schemaListSiteUsersResponse = schemaPaginatedResponse(schemaSiteUser);
+
+export type ListSiteUsersResponse = z.infer<typeof schemaListSiteUsersResponse>;
+
+export default class AdminUsers {
+  private readonly client: Client;
+
+  public constructor(client: Client) {
+    this.client = client;
+  }
+
+  /**
+   * List all users in the site (admin only).
+   *
+   * @param request - The request body.
+   * @returns The list of users.
+   */
+  public async list(
+    request: ListSiteUsersRequest = {}
+  ): Promise<ListSiteUsersResponse> {
+    const query = new URLSearchParams();
+    if (request.per_page) {
+      query.set("per_page", request.per_page.toString());
+    }
+    if (request.page) {
+      query.set("page", request.page.toString());
+    }
+    if (request.query) {
+      query.set("query", request.query);
+    }
+    if (request.site_role) {
+      query.set("site_role", request.site_role);
+    }
+    const resp = await this.client.request(
+      "GET",
+      `/api/admin/users?${query.toString()}`
+    );
+    await assertResponseStatus(resp, 200);
+    return resp.json();
+  }
+}

internal/api/src/routes/admin/users.server.ts

@@ -0,0 +1,65 @@
+import type { UserWithPersonalOrganization } from "@blink.so/database/schema";
+import { validator } from "hono/validator";
+import { withPagination, withSiteAdmin } from "../../middleware";
+import type { APIServer } from "../../server";
+import {
+  type ListSiteUsersResponse,
+  type SiteUser,
+  schemaListSiteUsersRequest,
+} from "./users.client";
+
+export default function mountAdminUsers(server: APIServer) {
+  // List all users (site admin only).
+  server.get(
+    "/",
+    withSiteAdmin,
+    withPagination,
+    validator("query", (value) => {
+      return schemaListSiteUsersRequest.parse(value);
+    }),
+    async (c) => {
+      const db = await c.env.database();
+      const { query, site_role } = c.req.valid("query");
+
+      const users = await db.selectAllUsers({
+        page: c.get("page"),
+        per_page: c.get("per_page"),
+        query: query || undefined,
+        siteRole: site_role || undefined,
+      });
+
+      const resp: ListSiteUsersResponse = {
+        has_more: users.has_more,
+        items: users.items.map((u) => convertSiteUser(u)),
+      };
+      return c.json(resp);
+    }
+  );
+}
+
+const convertSiteUser = (
+  user: Pick<
+    UserWithPersonalOrganization,
+    | "id"
+    | "created_at"
+    | "updated_at"
+    | "display_name"
+    | "email"
+    | "avatar_url"
+    | "username"
+    | "organization_id"
+    | "site_role"
+  >
+): SiteUser => {
+  return {
+    id: user.id,
+    created_at: user.created_at,
+    updated_at: user.updated_at,
+    display_name: user.display_name,
+    email: user.email ?? "",
+    avatar_url: user.avatar_url,
+    username: user.username,
+    organization_id: user.organization_id,
+    site_role: user.site_role,
+  };
+};

internal/api/src/routes/admin/users.test.ts

@@ -0,0 +1,75 @@
+import { expect, test } from "bun:test";
+import Client from "../../client.node";
+import { serve } from "../../test";
+
+test("GET /api/admin/users returns 403 for non-admin user", async () => {
+  const { helpers } = await serve();
+  const { client } = await helpers.createUser({ site_role: "member" });
+
+  await expect(client.admin.users.list()).rejects.toThrow("Forbidden");
+});
+
+test("GET /api/admin/users returns users for site admin", async () => {
+  const { helpers } = await serve();
+  const { client: adminClient } = await helpers.createUser({
+    site_role: "admin",
+  });
+  const { user: regularUser } = await helpers.createUser({
+    site_role: "member",
+  });
+
+  const response = await adminClient.admin.users.list();
+
+  expect(response.items).toBeDefined();
+  expect(response.items.length).toBeGreaterThanOrEqual(2);
+
+  const regularUserInList = response.items.find((u) => u.id === regularUser.id);
+  expect(regularUserInList).toBeDefined();
+  expect(regularUserInList?.site_role).toBe("member");
+});
+
+test("GET /api/admin/users returns 401 for unauthenticated request", async () => {
+  const { url } = await serve();
+
+  const unauthClient = new Client({
+    baseURL: url.toString(),
+  });
+
+  await expect(unauthClient.admin.users.list()).rejects.toThrow("Unauthorized");
+});
+
+test("GET /api/admin/users filters by site_role", async () => {
+  const { helpers } = await serve();
+  const { client: adminClient, user: adminUser } = await helpers.createUser({
+    site_role: "admin",
+  });
+  const { user: memberUser } = await helpers.createUser({
+    site_role: "member",
+  });
+
+  const adminOnly = await adminClient.admin.users.list({ site_role: "admin" });
+
+  expect(adminOnly.items.every((u) => u.site_role === "admin")).toBe(true);
+  expect(adminOnly.items.some((u) => u.id === adminUser.id)).toBe(true);
+  expect(adminOnly.items.some((u) => u.id === memberUser.id)).toBe(false);
+});
+
+test("GET /api/admin/users filters by query", async () => {
+  const { helpers } = await serve();
+  const { client: adminClient, user: adminUser } = await helpers.createUser({
+    site_role: "admin",
+    email: "admin-unique-email@example.com",
+  });
+  const { user: otherUser } = await helpers.createUser({
+    site_role: "member",
+    email: "other-user@example.com",
+  });
+
+  const results = await adminClient.admin.users.list({
+    query: "admin-unique-email",
+  });
+
+  expect(results.items.length).toBeGreaterThanOrEqual(1);
+  expect(results.items.some((u) => u.id === adminUser.id)).toBe(true);
+  expect(results.items.some((u) => u.id === otherUser.id)).toBe(false);
+});