@podosoft/podokit 1.2.0 → 1.3.0

package/dist/templates/modules/admin-dashboard/files/apps/api/src/admin-users/admin-users.routes.spec.ts

@@ -0,0 +1,76 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { SQL } from "bun";
+import { AppException } from "@podosoft/podokit-contracts";
+import { Elysia } from "elysia";
+import type { AuthService, AuthSession } from "../auth/auth.service";
+import { adminUserRoutes } from "./admin-users.routes";
+import { AdminUsersService } from "./admin-users.service";
+
+// Callers identify themselves with a test header; only "admin" passes.
+const auth: Pick<AuthService, "requireAdmin"> = {
+  requireAdmin: async (request: Request): Promise<AuthSession> => {
+    const role = request.headers.get("x-test-role");
+    if (!role) throw new AppException("AUTH_REQUIRED", "Authentication is required", 401);
+    if (role !== "admin") throw new AppException("ADMIN_REQUIRED", "Administrator access is required", 403);
+    return { user: { id: "admin-1", role: "admin" }, session: {} };
+  },
+};
+
+describe("admin user routes", () => {
+  let db: SQL;
+  let handle: (path: string, role?: string) => Promise<Response>;
+
+  beforeEach(async () => {
+    db = new SQL(":memory:");
+    await db`
+      CREATE TABLE "user" (
+        "id" TEXT PRIMARY KEY, "name" TEXT NOT NULL, "email" TEXT NOT NULL,
+        "emailVerified" INTEGER NOT NULL, "createdAt" DATE NOT NULL, "role" TEXT,
+        "banned" INTEGER, "banReason" TEXT, "banExpires" DATE, "signupApproved" INTEGER
+      )
+    `;
+    await db`
+      INSERT INTO "user" VALUES
+        ('u1', 'Ada', 'ada@example.com', 1, '2026-01-01T00:00:01.000Z', 'admin', 0, NULL, NULL, 1),
+        ('u2', 'Bob', 'bob@example.com', 1, '2026-01-01T00:00:02.000Z', 'admin', 1, 'spam', NULL, 1)
+    `;
+    const app = new Elysia()
+      .onError(({ code, error, set }) => {
+        if (error instanceof AppException) {
+          set.status = error.statusCode;
+          return { code: error.code };
+        }
+        if (code === "VALIDATION") {
+          set.status = 400;
+          return { code: "VALIDATION_ERROR" };
+        }
+        return undefined;
+      })
+      .use(adminUserRoutes({ auth, users: new AdminUsersService(db, "sqlite") }));
+    handle = (path, role) =>
+      app.handle(new Request(`http://localhost${path}`, { headers: role ? { "x-test-role": role } : {} }));
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  test("requires an administrator", async () => {
+    expect((await handle("/admin/users")).status).toBe(401);
+    expect((await handle("/admin/users", "user")).status).toBe(403);
+  });
+
+  test("applies role and status together", async () => {
+    const response = await handle("/admin/users?role=admin&status=active&limit=10&offset=0", "admin");
+    expect(response.status).toBe(200);
+    const page = await response.json() as { items: Array<{ id: string; banned: boolean }>; total: number };
+    expect(page.items).toEqual([expect.objectContaining({ id: "u1", banned: false })]);
+    expect(page.total).toBe(1);
+  });
+
+  test("rejects unknown sort fields, statuses, and out-of-range limits", async () => {
+    for (const query of ["sortBy=password", "status=deleted", "sortDirection=up", "limit=0", "limit=101", "offset=-1", "searchField=role"]) {
+      expect((await handle(`/admin/users?${query}`, "admin")).status, query).toBe(400);
+    }
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/admin-users/admin-users.routes.ts

@@ -0,0 +1,41 @@
+import { Elysia, t } from "elysia";
+import type { AuthService } from "../auth/auth.service";
+import type { ElysiaPlugin } from "../core/services";
+import {
+  ADMIN_USER_SORT_FIELDS,
+  ADMIN_USER_STATUSES,
+  ADMIN_USERS_MAX_LIMIT,
+  type AdminUsersService,
+} from "./admin-users.service";
+
+export interface AdminUserRoutesOptions {
+  auth: Pick<AuthService, "requireAdmin">;
+  users: AdminUsersService;
+}
+
+export function adminUserRoutes({ auth, users }: AdminUserRoutesOptions): ElysiaPlugin {
+  return new Elysia({ name: "podokit.admin.users" })
+    .get("/admin/users", async ({ request, query }) => {
+      await auth.requireAdmin(request);
+      return users.list(query);
+    }, {
+      query: t.Object({
+        limit: t.Optional(t.Numeric({ minimum: 1, maximum: ADMIN_USERS_MAX_LIMIT })),
+        offset: t.Optional(t.Numeric({ minimum: 0 })),
+        search: t.Optional(t.String({ maxLength: 200 })),
+        searchField: t.Optional(t.Union([t.Literal("email"), t.Literal("name")])),
+        role: t.Optional(t.String({ minLength: 1, maxLength: 64 })),
+        status: t.Optional(t.Union(ADMIN_USER_STATUSES.map((status) => t.Literal(status)))),
+        sortBy: t.Optional(t.Union(ADMIN_USER_SORT_FIELDS.map((field) => t.Literal(field)))),
+        sortDirection: t.Optional(t.Union([t.Literal("asc"), t.Literal("desc")])),
+      }),
+      detail: {
+        tags: ["admin"],
+        summary: "List users",
+        description:
+          "Administrators only. Offset-paged with `limit` and `offset`; newest first unless " +
+          "`sortBy`/`sortDirection` say otherwise. `search` matches `searchField` (email by " +
+          "default) case-insensitively. `role` and `status` (active, pending, banned) combine.",
+      },
+    });
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/admin-users/admin-users.service.spec.ts

@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { SQL } from "bun";
+import { AdminUsersService, type AdminUserQuery } from "./admin-users.service";
+
+interface SeedUser {
+  id: string;
+  name: string;
+  email: string;
+  role?: string | null;
+  banned?: boolean | null;
+  signupApproved?: boolean | null;
+  emailVerified?: boolean;
+  createdAt: string;
+}
+
+// Better Auth stores booleans as 0 or 1 and dates as ISO text on SQLite.
+async function createSchema(db: SQL): Promise<void> {
+  await db`
+    CREATE TABLE "user" (
+      "id" TEXT PRIMARY KEY, "name" TEXT NOT NULL, "email" TEXT NOT NULL,
+      "emailVerified" INTEGER NOT NULL, "image" TEXT, "createdAt" DATE NOT NULL,
+      "updatedAt" DATE NOT NULL, "role" TEXT, "banned" INTEGER, "banReason" TEXT,
+      "banExpires" DATE, "signupApproved" INTEGER
+    )
+  `;
+}
+
+function flag(value: boolean | null | undefined): number | null {
+  return value === undefined || value === null ? null : value ? 1 : 0;
+}
+
+async function seed(db: SQL, users: SeedUser[]): Promise<void> {
+  for (const user of users) {
+    await db`
+      INSERT INTO "user" ("id", "name", "email", "emailVerified", "createdAt", "updatedAt",
+                          "role", "banned", "banReason", "signupApproved")
+      VALUES (${user.id}, ${user.name}, ${user.email}, ${user.emailVerified ? 1 : 0},
+              ${user.createdAt}, ${user.createdAt}, ${user.role ?? null}, ${flag(user.banned)},
+              ${user.banned ? "spam" : null}, ${flag(user.signupApproved)})
+    `;
+  }
+}
+
+const at = (minute: number): string => `2026-01-01T00:${String(minute).padStart(2, "0")}:00.000Z`;
+
+const USERS: SeedUser[] = [
+  { id: "u1", name: "Ada Admin", email: "ada@example.com", role: "admin", signupApproved: true, createdAt: at(1) },
+  { id: "u2", name: "Bob", email: "bob@example.com", role: "user", signupApproved: true, createdAt: at(2) },
+  { id: "u3", name: "Cy Banned", email: "cy@example.com", role: "user", banned: true, signupApproved: true, createdAt: at(3) },
+  { id: "u4", name: "Di Pending", email: "di@example.com", role: "user", signupApproved: false, createdAt: at(4) },
+  { id: "u5", name: "Eve Banned Admin", email: "eve@example.com", role: "admin,user", banned: true, createdAt: at(5) },
+  { id: "u6", name: "Fay Legacy", email: "fay@example.com", role: null, banned: null, signupApproved: null, createdAt: at(6) },
+];
+
+describe("AdminUsersService", () => {
+  let db: SQL;
+  let service: AdminUsersService;
+
+  beforeEach(async () => {
+    db = new SQL(":memory:");
+    await createSchema(db);
+    await seed(db, USERS);
+    service = new AdminUsersService(db, "sqlite");
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  const ids = async (query: AdminUserQuery): Promise<string[]> =>
+    (await service.list(query)).items.map((user) => user.id);
+
+  test("pages newest first by default with a total", async () => {
+    const page = await service.list({ limit: 2, offset: 2 });
+    expect(page.items.map((user) => user.id)).toEqual(["u4", "u3"]);
+    expect(page.total).toBe(6);
+  });
+
+  test("combines the role and status filters", async () => {
+    expect(await ids({ role: "admin", status: "banned" })).toEqual(["u5"]);
+    expect(await ids({ role: "admin", status: "active" })).toEqual(["u1"]);
+    expect(await ids({ role: "user", status: "pending" })).toEqual(["u4"]);
+    expect((await service.list({ role: "user", status: "active" })).total).toBe(1);
+  });
+
+  test("treats unset approval and ban flags as an active user", async () => {
+    expect(await ids({ status: "active" })).toEqual(["u6", "u2", "u1"]);
+    expect(await ids({ status: "banned" })).toEqual(["u5", "u3"]);
+    expect(await ids({ status: "pending" })).toEqual(["u4"]);
+  });
+
+  test("matches one role in a comma-separated role list", async () => {
+    expect(await ids({ role: "user" })).toEqual(["u5", "u4", "u3", "u2"]);
+    expect(await ids({ role: "use" })).toEqual([]);
+  });
+
+  test("searches email or name case-insensitively with literal wildcards", async () => {
+    expect(await ids({ search: "ADA@EXAMPLE", searchField: "email" })).toEqual(["u1"]);
+    expect(await ids({ search: "banned", searchField: "name" })).toEqual(["u5", "u3"]);
+    expect(await ids({ search: "%", searchField: "name" })).toEqual([]);
+    expect(await ids({ search: "banned", searchField: "name", status: "banned", role: "admin" })).toEqual(["u5"]);
+  });
+
+  test("sorts by an allowed column with the id as a tiebreaker", async () => {
+    expect(await ids({ sortBy: "name", sortDirection: "asc", limit: 3 })).toEqual(["u1", "u2", "u3"]);
+    expect(await ids({ sortBy: "email", sortDirection: "desc", limit: 2 })).toEqual(["u6", "u5"]);
+  });
+
+  test("returns booleans and ISO dates without exposing other columns", async () => {
+    const [pending] = (await service.list({ status: "pending" })).items;
+    expect(pending).toEqual({
+      id: "u4",
+      name: "Di Pending",
+      email: "di@example.com",
+      role: "user",
+      emailVerified: false,
+      signupApproved: false,
+      banned: false,
+      banReason: null,
+      banExpires: null,
+      createdAt: at(4),
+    });
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/admin-users/admin-users.service.ts

@@ -0,0 +1,153 @@
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import type { SQL } from "bun";
+
+export const ADMIN_USERS_DEFAULT_LIMIT = 15;
+export const ADMIN_USERS_MAX_LIMIT = 100;
+export const ADMIN_USER_SORT_FIELDS = ["createdAt", "name", "email", "role"] as const;
+export const ADMIN_USER_STATUSES = ["active", "pending", "banned"] as const;
+
+export type AdminUserSortField = (typeof ADMIN_USER_SORT_FIELDS)[number];
+export type AdminUserStatus = (typeof ADMIN_USER_STATUSES)[number];
+
+/** A user as the admin list shows it. Credentials and sessions stay on the server. */
+export interface AdminUserView {
+  id: string;
+  name: string;
+  email: string;
+  role: string | null;
+  emailVerified: boolean;
+  signupApproved: boolean;
+  banned: boolean;
+  banReason: string | null;
+  banExpires: string | null;
+  createdAt: string;
+}
+
+export interface AdminUserPage {
+  items: AdminUserView[];
+  total: number;
+}
+
+export interface AdminUserQuery {
+  limit?: number;
+  offset?: number;
+  search?: string;
+  searchField?: "email" | "name";
+  role?: string;
+  status?: AdminUserStatus;
+  sortBy?: AdminUserSortField;
+  sortDirection?: "asc" | "desc";
+}
+
+type Flag = boolean | number | null;
+
+interface UserRow {
+  id: string;
+  name: string;
+  email: string;
+  role: string | null;
+  emailVerified: Flag;
+  signupApproved: Flag;
+  banned: Flag;
+  banReason: string | null;
+  banExpires: Date | string | null;
+  createdAt: Date | string;
+}
+
+// SQLite stores booleans as 0 or 1. An unset approval predates sign-up approval.
+function flag(value: Flag, unset: boolean): boolean {
+  return value === null ? unset : value === true || value === 1;
+}
+
+function iso(value: Date | string): string {
+  return (value instanceof Date ? value : new Date(value)).toISOString();
+}
+
+function likePattern(search: string): string {
+  return `%${search.replace(/[\\%_]/g, (character) => `\\${character}`)}%`;
+}
+
+/**
+ * Lists users for the admin console with every filter applied in one query.
+ * Better Auth `listUsers` accepts a single filter, so role and status could not
+ * combine there. Mutations stay on Better Auth so its permission checks and the
+ * audit hooks still run.
+ */
+export class AdminUsersService {
+  constructor(
+    private readonly sql: SQL,
+    private readonly provider: DatabaseProviderName,
+  ) {}
+
+  async list(query: AdminUserQuery = {}): Promise<AdminUserPage> {
+    const limit = Math.min(Math.max(query.limit ?? ADMIN_USERS_DEFAULT_LIMIT, 1), ADMIN_USERS_MAX_LIMIT);
+    const offset = Math.max(query.offset ?? 0, 0);
+    const search = query.search?.trim() ?? "";
+    const filters = (): SQL.Query<unknown> => this.sql`
+      WHERE 1 = 1
+      ${search ? this.searchFilter(query.searchField ?? "email", likePattern(search)) : this.sql``}
+      ${query.role ? this.sql`AND (',' || u."role" || ',') LIKE ${`%,${query.role},%`}` : this.sql``}
+      ${query.status ? this.statusFilter(query.status) : this.sql``}
+    `;
+    const [rows, totals] = await Promise.all([
+      this.sql<UserRow[]>`
+        SELECT u."id", u."name", u."email", u."role", u."emailVerified", u."signupApproved",
+               u."banned", u."banReason", u."banExpires", u."createdAt"
+        FROM "user" u
+        ${filters()}
+        ${this.order(query.sortBy ?? "createdAt", query.sortDirection ?? "desc")}
+        LIMIT ${limit} OFFSET ${offset}
+      `,
+      this.sql<Array<{ total: number | string | bigint }>>`
+        SELECT COUNT(*) AS "total" FROM "user" u ${filters()}
+      `,
+    ]);
+    return {
+      items: rows.map((row) => ({
+        id: row.id,
+        name: row.name,
+        email: row.email,
+        role: row.role,
+        emailVerified: flag(row.emailVerified, false),
+        signupApproved: flag(row.signupApproved, true),
+        banned: flag(row.banned, false),
+        banReason: row.banReason,
+        banExpires: row.banExpires === null ? null : iso(row.banExpires),
+        createdAt: iso(row.createdAt),
+      })),
+      total: Number(totals[0]?.total ?? 0),
+    };
+  }
+
+  private searchFilter(field: "email" | "name", pattern: string): SQL.Query<unknown> {
+    const column = field === "name" ? this.sql`u."name"` : this.sql`u."email"`;
+    // SQLite LIKE ignores ASCII case; PostgreSQL needs ILIKE.
+    return this.provider === "sqlite"
+      ? this.sql`AND ${column} LIKE ${pattern} ESCAPE '\\'`
+      : this.sql`AND ${column} ILIKE ${pattern} ESCAPE '\\'`;
+  }
+
+  private statusFilter(status: AdminUserStatus): SQL.Query<unknown> {
+    switch (status) {
+      case "pending":
+        return this.sql`AND u."signupApproved" = FALSE`;
+      case "banned":
+        return this.sql`AND u."banned" = TRUE`;
+      case "active":
+        return this.sql`AND COALESCE(u."banned", FALSE) = FALSE AND COALESCE(u."signupApproved", TRUE) = TRUE`;
+    }
+  }
+
+  private order(field: AdminUserSortField, direction: "asc" | "desc"): SQL.Query<unknown> {
+    const column = {
+      createdAt: this.sql`u."createdAt"`,
+      name: this.sql`u."name"`,
+      email: this.sql`u."email"`,
+      role: this.sql`u."role"`,
+    }[field];
+    // The id breaks ties so offset pages neither skip nor repeat users.
+    return direction === "asc"
+      ? this.sql`ORDER BY ${column} ASC, u."id" ASC`
+      : this.sql`ORDER BY ${column} DESC, u."id" DESC`;
+  }
+}

package/dist/templates/modules/admin-dashboard/files/apps/api/src/admin.module.ts

@@ -8,6 +8,8 @@ import { Elysia, t } from "elysia";
 import { adminSessionRoutes } from "./admin-sessions/admin-sessions.routes";
 import { createSessionRevoker, type RevokeUserSessionApi } from "./admin-sessions/admin-sessions.revoker";
 import { AdminSessionsService } from "./admin-sessions/admin-sessions.service";
+import { adminUserRoutes } from "./admin-users/admin-users.routes";
+import { AdminUsersService } from "./admin-users/admin-users.service";
 import { AUTH } from "./auth/auth.module";
 import { getAuth } from "./auth/auth-provider";
 import {
@@ -30,6 +32,7 @@ import { validateSiteSetting } from "./site-settings/site-settings.validation";
 export const SITE_SETTINGS = Symbol("site-settings") as ServiceKey<SiteSettingsService>;
 export const PROFILE_IMAGES = Symbol("profile-images") as ServiceKey<ProfileImageService>;
 export const ADMIN_SESSIONS = Symbol("admin-sessions") as ServiceKey<AdminSessionsService>;
+export const ADMIN_USERS = Symbol("admin-users") as ServiceKey<AdminUsersService>;
 
 const ICON_TYPES = new Set([
   "image/svg+xml",
@@ -54,6 +57,7 @@ const adminPlugin: AppPlugin = ({ services }) => {
       sessions: services.resolve(ADMIN_SESSIONS),
       revoke: createSessionRevoker(() => getAuth().api as unknown as RevokeUserSessionApi),
     }))
+    .use(adminUserRoutes({ auth, users: services.resolve(ADMIN_USERS) }))
     .use(siteAssetRoutes(site, profileImages))
     .get("/site/settings", async () => {
       // The favicon fields are site.* rows too, so one read serves the response.
@@ -127,6 +131,7 @@ export const adminModule: PodokitModule = {
   configure: (_env, services): void => {
     const database = services.resolve(DATABASE);
     services.register(ADMIN_SESSIONS, new AdminSessionsService(database.sql, database.provider));
+    services.register(ADMIN_USERS, new AdminUsersService(database.sql, database.provider));
     const storage = services.resolve(OBJECT_STORAGE);
     const site = new SiteSettingsService(services.resolve(DATABASE).sql, storage);
     const profileImages = new ProfileImageService(storage, services.resolve(LOGGER));

package/dist/templates/modules/admin-dashboard/files/apps/api/src/bootstrap-admin-runtime.ts

@@ -0,0 +1,60 @@
+// Bundled entry for scripts/bootstrap-admin.mjs. The build bundles only its
+// top-level targets, so the script cannot import auth modules from dist directly.
+// The command runs against a migrated schema and reports a missing table from its
+// own query. Better Auth's asynchronous startup check would only race the
+// connection the command closes when it finishes.
+import "./auth/skip-schema-validation";
+import { verifyPassword } from "better-auth/crypto";
+import { auth } from "./auth/auth";
+import { closeAuthDatabase, postgresPool, sqliteDatabase } from "./auth/db";
+
+export interface BootstrapUser {
+  id: string;
+  email: string;
+  role: string | null;
+  emailVerified: boolean;
+  signupApproved: boolean;
+  passwordHash: string | null;
+}
+
+interface BootstrapUserRow extends Omit<BootstrapUser, "emailVerified" | "signupApproved"> {
+  // SQLite stores booleans as 0 or 1.
+  emailVerified: boolean | number | null;
+  signupApproved: boolean | number | null;
+}
+
+function userQuery(placeholder: string): string {
+  return `SELECT u.id,
+                 u.email,
+                 u.role,
+                 u."emailVerified" AS "emailVerified",
+                 u."signupApproved" AS "signupApproved",
+                 a.password AS "passwordHash"
+            FROM "user" AS u
+       LEFT JOIN "account" AS a
+              ON a."userId" = u.id
+             AND a."providerId" = 'credential'
+           WHERE lower(u.email) = lower(${placeholder})
+           LIMIT 1`;
+}
+
+function flag(value: boolean | number | null): boolean {
+  return value === true || value === 1;
+}
+
+export async function findBootstrapUser(email: string): Promise<BootstrapUser | null> {
+  let row: BootstrapUserRow | undefined;
+  if (postgresPool) {
+    row = (await postgresPool.query<BootstrapUserRow>(userQuery("$1"), [email])).rows[0];
+  } else if (sqliteDatabase) {
+    row = sqliteDatabase.query<BootstrapUserRow, [string]>(userQuery("?1")).get(email) ?? undefined;
+  }
+  if (!row) return null;
+  return {
+    ...row,
+    emailVerified: flag(row.emailVerified),
+    signupApproved: flag(row.signupApproved),
+  };
+}
+
+export { auth, closeAuthDatabase, verifyPassword };

package/dist/templates/modules/admin-dashboard/files/apps/api/src/migrations/1792060000000-IndexSessionCreatedAt.ts

@@ -0,0 +1,35 @@
+import type { MigrationInterface, QueryRunner } from "typeorm";
+
+// The admin session list pages active sessions newest first with a keyset on
+// ("createdAt", "id"). Better Auth's schema indexes only "userId" and "token",
+// so without this index every page sorts the whole session table.
+const INDEX = "IDX_session_createdAt_id";
+
+export class IndexSessionCreatedAt1792060000000 implements MigrationInterface {
+  name = "IndexSessionCreatedAt1792060000000";
+  // CONCURRENTLY cannot run inside a transaction block. The runner therefore
+  // uses the "each" transaction mode. SQLite migrations always use one.
+  transaction = false;
+
+  async up(queryRunner: QueryRunner): Promise<void> {
+    if (queryRunner.connection.options.type !== "postgres") {
+      await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${INDEX}" ON "session" ("createdAt", "id")`);
+      return;
+    }
+    // Sign-ins keep writing sessions while the index builds. An interrupted
+    // build leaves an invalid index that IF NOT EXISTS would keep.
+    const invalid = await queryRunner.query(
+      `SELECT 1 AS "invalid" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid`,
+      [`"${INDEX}"`],
+    ) as unknown[];
+    if (invalid.length > 0) await queryRunner.query(`DROP INDEX CONCURRENTLY IF EXISTS "${INDEX}"`);
+    await queryRunner.query(
+      `CREATE INDEX CONCURRENTLY IF NOT EXISTS "${INDEX}" ON "session" ("createdAt", "id")`,
+    );
+  }
+
+  // A revert runs inside a transaction, so it uses a plain statement.
+  async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP INDEX IF EXISTS "${INDEX}"`);
+  }
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/users.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { keepLatestFilter, listUsersQuery, type UserListState } from "./users";
+import {
+  adminUsersQuery,
+  keepLatestFilter,
+  listAdminUsers,
+  listUsersQuery,
+  type UserListState,
+} from "./users";
 
 const base: UserListState = {
   page: 1,
@@ -11,9 +17,9 @@ const base: UserListState = {
   status: "",
 };
 
-describe("listUsersQuery", () => {
+describe("adminUsersQuery", () => {
   it("pages newest first by default", () => {
-    expect(listUsersQuery({ ...base, page: 3 })).toEqual({
+    expect(adminUsersQuery({ ...base, page: 3 })).toEqual({
       limit: 15,
       offset: 30,
       sortBy: "createdAt",
@@ -22,54 +28,75 @@ describe("listUsersQuery", () => {
   });
 
   it("sorts by a table column on the server", () => {
-    expect(listUsersQuery({ ...base, sort: { key: "name", dir: "asc" } })).toMatchObject({
+    expect(adminUsersQuery({ ...base, sort: { key: "name", dir: "asc" } })).toMatchObject({
       sortBy: "name",
       sortDirection: "asc",
     });
-    expect(listUsersQuery({ ...base, sort: { key: "status", dir: "asc" } })).toMatchObject({
+    expect(adminUsersQuery({ ...base, sort: { key: "status", dir: "asc" } })).toMatchObject({
       sortBy: "createdAt",
       sortDirection: "desc",
     });
   });
 
-  it("searches email case-insensitively and names as typed", () => {
-    expect(listUsersQuery({ ...base, search: "  Ada@Example.COM " })).toMatchObject({
-      searchValue: "ada@example.com",
+  it("searches the chosen field with the text trimmed", () => {
+    expect(adminUsersQuery({ ...base, search: "  Ada@Example.COM " })).toMatchObject({
+      search: "Ada@Example.COM",
       searchField: "email",
-      searchOperator: "contains",
     });
-    expect(listUsersQuery({ ...base, search: "Ada", searchField: "name" })).toMatchObject({
-      searchValue: "Ada",
+    expect(adminUsersQuery({ ...base, search: "Ada", searchField: "name" })).toMatchObject({
+      search: "Ada",
       searchField: "name",
     });
-    expect(listUsersQuery({ ...base, search: "   " })).not.toHaveProperty("searchValue");
+    expect(adminUsersQuery({ ...base, search: "   " })).not.toHaveProperty("search");
   });
 
-  it("maps the role and status filters to the single server filter", () => {
-    expect(listUsersQuery({ ...base, role: "admin" })).toMatchObject({
-      filterField: "role",
-      filterValue: "admin",
-      filterOperator: "eq",
+  it("sends the role and status filters together", () => {
+    expect(adminUsersQuery({ ...base, role: "admin", status: "active" })).toMatchObject({
+      role: "admin",
+      status: "active",
     });
-    expect(listUsersQuery({ ...base, status: "pending" })).toMatchObject({
-      filterField: "signupApproved",
-      filterValue: false,
-    });
-    expect(listUsersQuery({ ...base, status: "banned" })).toMatchObject({
-      filterField: "banned",
-      filterValue: true,
-    });
-    expect(listUsersQuery(base)).not.toHaveProperty("filterField");
+    expect(adminUsersQuery({ ...base, status: "pending" })).toMatchObject({ status: "pending" });
+    expect(adminUsersQuery({ ...base, status: "deleted" })).not.toHaveProperty("status");
+    expect(adminUsersQuery(base)).not.toHaveProperty("role");
+  });
+});
+
+describe("listAdminUsers", () => {
+  it("asks GET /admin/users for one page", async () => {
+    const paths: string[] = [];
+    const client = {
+      get: <T>(path: string): Promise<T> => {
+        paths.push(path);
+        return Promise.resolve({ items: [], total: 0 } as unknown as T);
+      },
+    };
+
+    await listAdminUsers(client, adminUsersQuery({ ...base, page: 2, search: "ada", role: "admin", status: "banned" }));
+    await listAdminUsers(client, adminUsersQuery(base));
+
+    expect(paths).toEqual([
+      "/admin/users?limit=15&offset=15&sortBy=createdAt&sortDirection=desc&search=ada&searchField=email&role=admin&status=banned",
+      "/admin/users?limit=15&offset=0&sortBy=createdAt&sortDirection=desc",
+    ]);
   });
 });
 
-describe("keepLatestFilter", () => {
-  it("keeps whichever filter changed last", () => {
+// Application-owned users pages from 1.2 still import these.
+describe("deprecated listUsers helpers", () => {
+  it("still builds the single-filter Better Auth query", () => {
+    expect(listUsersQuery({ ...base, page: 2, search: " Ada@Example.COM ", status: "banned" })).toEqual({
+      limit: 15,
+      offset: 15,
+      sortBy: "createdAt",
+      sortDirection: "desc",
+      searchValue: "ada@example.com",
+      searchField: "email",
+      searchOperator: "contains",
+      filterField: "banned",
+      filterValue: true,
+      filterOperator: "eq",
+    });
     expect(keepLatestFilter({ role: "admin", status: "" }, { role: "admin", status: "banned" }))
       .toEqual({ role: "", status: "banned" });
-    expect(keepLatestFilter({ role: "", status: "banned" }, { role: "user", status: "banned" }))
-      .toEqual({ role: "user", status: "" });
-    expect(keepLatestFilter({ role: "", status: "" }, { role: "user", status: "" }))
-      .toEqual({ role: "user", status: "" });
   });
 });