feat: Adds filter-by-email on /users/_get endpoint for admin calls (#10928)

* adds filter by email on users get for admins

* swagger update

* Update apps/api/pages/api/users/_get.ts

Co-authored-by: Omar López <zomars@me.com>

* .parse is required, also fixed some other issues

---------

Co-authored-by: Omar López <zomars@me.com>
Co-authored-by: Alex van Andel <me@alexvanandel.com>

apps/api/lib/validations/shared/queryUserEmail.ts

@@ -0,0 +1,20 @@
+import { withValidation } from "next-validations";
+import { z } from "zod";
+
+import { baseApiParams } from "./baseApiParams";
+
+// Extracted out as utility function so can be reused
+// at different endpoints that require this validation.
+export const schemaQueryUserEmail = baseApiParams.extend({
+  email: z.string().email(),
+});
+
+export const schemaQuerySingleOrMultipleUserEmails = z.object({
+  email: z.union([z.string().email(), z.array(z.string().email())]),
+});
+
+export const withValidQueryUserEmail = withValidation({
+  schema: schemaQueryUserEmail,
+  type: "Zod",
+  mode: "query",
+});

apps/api/pages/api/users/_get.ts

@@ -4,6 +4,7 @@ import type { NextApiRequest } from "next";
 import { defaultResponder } from "@calcom/lib/server";
 
 import { withMiddleware } from "~/lib/helpers/withMiddleware";
+import { schemaQuerySingleOrMultipleUserEmails } from "~/lib/validations/shared/queryUserEmail";
 import { schemaUsersReadPublic } from "~/lib/validations/user";
 
 /**
@@ -19,6 +20,17 @@ import { schemaUsersReadPublic } from "~/lib/validations/user";
  *         schema:
  *           type: string
  *         description: Your API key
+ *       - in: query
+ *         name: email
+ *         required: false
+ *         schema:
+ *          type: array
+ *          items:
+ *            type: string
+ *            format: email
+ *         style: form
+ *         explode: true
+ *         description: The email address or an array of email addresses to filter by
  *     tags:
  *     - users
  *     responses:
@@ -39,6 +51,14 @@ export async function getHandler(req: NextApiRequest) {
   const where: Prisma.UserWhereInput = {};
   // If user is not ADMIN, return only his data.
   if (!isAdmin) where.id = userId;
+
+  if (req.query.email) {
+    const validationResult = schemaQuerySingleOrMultipleUserEmails.parse(req.query);
+    where.email = {
+      in: Array.isArray(validationResult.email) ? validationResult.email : [validationResult.email],
+    };
+  }
+
   const [total, data] = await prisma.$transaction([
     prisma.user.count({ where }),
     prisma.user.findMany({ where, take, skip }),