feat: organization endpoints (#5076)

Co-authored-by: Dhruwang <dhruwangjariwala18@gmail.com>
Co-authored-by: pandeymangg <anshuman.pandey9999@gmail.com>

apps/web/modules/api/v2/auth/api-wrapper.ts

@@ -0,0 +1,102 @@
+import { checkRateLimitAndThrowError } from "@/modules/api/v2/lib/rate-limit";
+import { formatZodError, handleApiError } from "@/modules/api/v2/lib/utils";
+import { ZodRawShape, z } from "zod";
+import { TAuthenticationApiKey } from "@formbricks/types/auth";
+import { authenticateRequest } from "./authenticate-request";
+
+export type HandlerFn<TInput = Record<string, unknown>> = ({
+  authentication,
+  parsedInput,
+  request,
+}: {
+  authentication: TAuthenticationApiKey;
+  parsedInput: TInput;
+  request: Request;
+}) => Promise<Response>;
+
+export type ExtendedSchemas = {
+  body?: z.ZodObject<ZodRawShape>;
+  query?: z.ZodObject<ZodRawShape>;
+  params?: z.ZodObject<ZodRawShape>;
+};
+
+// Define a type that returns separate keys for each input type.
+export type ParsedSchemas<S extends ExtendedSchemas | undefined> = {
+  body?: S extends { body: z.ZodObject<any> } ? z.infer<S["body"]> : undefined;
+  query?: S extends { query: z.ZodObject<any> } ? z.infer<S["query"]> : undefined;
+  params?: S extends { params: z.ZodObject<any> } ? z.infer<S["params"]> : undefined;
+};
+
+export const apiWrapper = async <S extends ExtendedSchemas>({
+  request,
+  schemas,
+  externalParams,
+  rateLimit = true,
+  handler,
+}: {
+  request: Request;
+  schemas?: S;
+  externalParams?: Promise<Record<string, any>>;
+  rateLimit?: boolean;
+  handler: HandlerFn<ParsedSchemas<S>>;
+}): Promise<Response> => {
+  const authentication = await authenticateRequest(request);
+  if (!authentication.ok) {
+    return handleApiError(request, authentication.error);
+  }
+
+  let parsedInput: ParsedSchemas<S> = {} as ParsedSchemas<S>;
+
+  if (schemas?.body) {
+    const bodyData = await request.json();
+    const bodyResult = schemas.body.safeParse(bodyData);
+
+    if (!bodyResult.success) {
+      return handleApiError(request, {
+        type: "unprocessable_entity",
+        details: formatZodError(bodyResult.error),
+      });
+    }
+    parsedInput.body = bodyResult.data as ParsedSchemas<S>["body"];
+  }
+
+  if (schemas?.query) {
+    const url = new URL(request.url);
+    const queryObject = Object.fromEntries(url.searchParams.entries());
+    const queryResult = schemas.query.safeParse(queryObject);
+    if (!queryResult.success) {
+      return handleApiError(request, {
+        type: "unprocessable_entity",
+        details: formatZodError(queryResult.error),
+      });
+    }
+    parsedInput.query = queryResult.data as ParsedSchemas<S>["query"];
+  }
+
+  if (schemas?.params) {
+    const paramsObject = (await externalParams) || {};
+    const paramsResult = schemas.params.safeParse(paramsObject);
+    if (!paramsResult.success) {
+      return handleApiError(request, {
+        type: "unprocessable_entity",
+        details: formatZodError(paramsResult.error),
+      });
+    }
+    parsedInput.params = paramsResult.data as ParsedSchemas<S>["params"];
+  }
+
+  if (rateLimit) {
+    const rateLimitResponse = await checkRateLimitAndThrowError({
+      identifier: authentication.data.hashedApiKey,
+    });
+    if (!rateLimitResponse.ok) {
+      return handleApiError(request, rateLimitResponse.error);
+    }
+  }
+
+  return handler({
+    authentication: authentication.data,
+    parsedInput,
+    request,
+  });
+};

apps/web/modules/api/v2/auth/authenticate-request.ts

@@ -0,0 +1,34 @@
+import { hashApiKey } from "@/modules/api/v2/management/lib/utils";
+import { ApiErrorResponseV2 } from "@/modules/api/v2/types/api-error";
+import { getApiKeyWithPermissions } from "@/modules/organization/settings/api-keys/lib/api-key";
+import { TAuthenticationApiKey } from "@formbricks/types/auth";
+import { Result, err, ok } from "@formbricks/types/error-handlers";
+
+export const authenticateRequest = async (
+  request: Request
+): Promise<Result<TAuthenticationApiKey, ApiErrorResponseV2>> => {
+  const apiKey = request.headers.get("x-api-key");
+  if (!apiKey) return err({ type: "unauthorized" });
+
+  const apiKeyData = await getApiKeyWithPermissions(apiKey);
+
+  if (!apiKeyData) return err({ type: "unauthorized" });
+
+  const hashedApiKey = hashApiKey(apiKey);
+
+  const authentication: TAuthenticationApiKey = {
+    type: "apiKey",
+    environmentPermissions: apiKeyData.apiKeyEnvironments.map((env) => ({
+      environmentId: env.environmentId,
+      environmentType: env.environment.type,
+      permission: env.permission,
+      projectId: env.environment.projectId,
+      projectName: env.environment.project.name,
+    })),
+    hashedApiKey,
+    apiKeyId: apiKeyData.id,
+    organizationId: apiKeyData.organizationId,
+    organizationAccess: apiKeyData.organizationAccess,
+  };
+  return ok(authentication);
+};

apps/web/modules/api/v2/auth/authenticated-api-client.ts

@@ -0,0 +1,42 @@
+import { handleApiError, logApiRequest } from "@/modules/api/v2/lib/utils";
+import { ApiErrorResponseV2 } from "@/modules/api/v2/types/api-error";
+import { ExtendedSchemas, HandlerFn, ParsedSchemas, apiWrapper } from "./api-wrapper";
+
+export const authenticatedApiClient = async <S extends ExtendedSchemas>({
+  request,
+  schemas,
+  externalParams,
+  rateLimit = true,
+  handler,
+}: {
+  request: Request;
+  schemas?: S;
+  externalParams?: Promise<Record<string, any>>;
+  rateLimit?: boolean;
+  handler: HandlerFn<ParsedSchemas<S>>;
+}): Promise<Response> => {
+  try {
+    const response = await apiWrapper({
+      request,
+      schemas,
+      externalParams,
+      rateLimit,
+      handler,
+    });
+
+    if (response.ok) {
+      logApiRequest(request, response.status);
+    }
+
+    return response;
+  } catch (err) {
+    if ("type" in err) {
+      return handleApiError(request, err as ApiErrorResponseV2);
+    }
+
+    return handleApiError(request, {
+      type: "internal_server_error",
+      details: [{ field: "error", issue: "An error occurred while processing your request." }],
+    });
+  }
+};

apps/web/modules/api/v2/auth/tests/api-wrapper.test.ts

@@ -0,0 +1,305 @@
+import { apiWrapper } from "@/modules/api/v2/auth/api-wrapper";
+import { authenticateRequest } from "@/modules/api/v2/auth/authenticate-request";
+import { checkRateLimitAndThrowError } from "@/modules/api/v2/lib/rate-limit";
+import { handleApiError } from "@/modules/api/v2/lib/utils";
+import { ApiErrorResponseV2 } from "@/modules/api/v2/types/api-error";
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { err, ok, okVoid } from "@formbricks/types/error-handlers";
+
+vi.mock("../authenticate-request", () => ({
+  authenticateRequest: vi.fn(),
+}));
+
+vi.mock("@/modules/api/v2/lib/rate-limit", () => ({
+  checkRateLimitAndThrowError: vi.fn(),
+}));
+
+vi.mock("@/modules/api/v2/lib/utils", () => ({
+  handleApiError: vi.fn(),
+}));
+
+vi.mock("@/modules/api/v2/lib/utils", () => ({
+  formatZodError: vi.fn(),
+  handleApiError: vi.fn(),
+}));
+
+describe("apiWrapper", () => {
+  it("should handle request and return response", async () => {
+    const request = new Request("http://localhost", {
+      headers: { "x-api-key": "valid-api-key" },
+    });
+
+    vi.mocked(authenticateRequest).mockResolvedValue(
+      ok({
+        type: "apiKey",
+        environmentId: "env-id",
+        hashedApiKey: "hashed-api-key",
+      })
+    );
+    vi.mocked(checkRateLimitAndThrowError).mockResolvedValue(okVoid());
+
+    const handler = vi.fn().mockResolvedValue(new Response("ok", { status: 200 }));
+    const response = await apiWrapper({
+      request,
+      handler,
+    });
+
+    expect(response.status).toBe(200);
+    expect(handler).toHaveBeenCalled();
+  });
+
+  it("should handle errors and return error response", async () => {
+    const request = new Request("http://localhost", {
+      headers: { "x-api-key": "invalid-api-key" },
+    });
+
+    vi.mocked(authenticateRequest).mockResolvedValue(err({ type: "unauthorized" }));
+    vi.mocked(handleApiError).mockResolvedValue(new Response("error", { status: 401 }));
+
+    const handler = vi.fn();
+    const response = await apiWrapper({
+      request,
+      handler,
+    });
+
+    expect(response.status).toBe(401);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("should parse body schema correctly", async () => {
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: JSON.stringify({ key: "value" }),
+      headers: { "Content-Type": "application/json" },
+    });
+
+    vi.mocked(authenticateRequest).mockResolvedValue(
+      ok({
+        type: "apiKey",
+        environmentId: "env-id",
+        hashedApiKey: "hashed-api-key",
+      })
+    );
+
+    const bodySchema = z.object({ key: z.string() });
+    const handler = vi.fn().mockResolvedValue(new Response("ok", { status: 200 }));
+
+    const response = await apiWrapper({
+      request,
+      schemas: { body: bodySchema },
+      rateLimit: false,
+      handler,
+    });
+
+    expect(response.status).toBe(200);
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        parsedInput: { body: { key: "value" } },
+      })
+    );
+  });
+
+  it("should handle body schema errors", async () => {
+    const request = new Request("http://localhost", {
+      method: "POST",
+      body: JSON.stringify({ key: 123 }),
+      headers: { "Content-Type": "application/json" },
+    });
+
+    vi.mocked(authenticateRequest).mockResolvedValue(
+      ok({
+        type: "apiKey",
+        environmentId: "env-id",
+        hashedApiKey: "hashed-api-key",
+      })
+    );
+
+    vi.mocked(handleApiError).mockResolvedValue(new Response("error", { status: 400 }));
+
+    const bodySchema = z.object({ key: z.string() });
+    const handler = vi.fn();
+
+    const response = await apiWrapper({
+      request,
+      schemas: { body: bodySchema },
+      rateLimit: false,
+      handler,
+    });
+
+    expect(response.status).toBe(400);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("should parse query schema correctly", async () => {
+    const request = new Request("http://localhost?key=value");
+
+    vi.mocked(authenticateRequest).mockResolvedValue(
+      ok({
+        type: "apiKey",
+        environmentId: "env-id",
+        hashedApiKey: "hashed-api-key",
+      })
+    );
+
+    const querySchema = z.object({ key: z.string() });
+    const handler = vi.fn().mockResolvedValue(new Response("ok", { status: 200 }));
+
+    const response = await apiWrapper({
+      request,
+      schemas: { query: querySchema },
+      rateLimit: false,
+      handler,
+    });
+
+    expect(response.status).toBe(200);
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        parsedInput: { query: { key: "value" } },
+      })
+    );
+  });
+
+  it("should handle query schema errors", async () => {
+    const request = new Request("http://localhost?foo%ZZ=abc");
+
+    vi.mocked(authenticateRequest).mockResolvedValue(
+      ok({
+        type: "apiKey",
+        environmentId: "env-id",
+        hashedApiKey: "hashed-api-key",
+      })
+    );
+
+    vi.mocked(handleApiError).mockResolvedValue(new Response("error", { status: 400 }));
+
+    const querySchema = z.object({ key: z.string() });
+    const handler = vi.fn();
+
+    const response = await apiWrapper({
+      request,
+      schemas: { query: querySchema },
+      rateLimit: false,
+      handler,
+    });
+
+    expect(response.status).toBe(400);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("should parse params schema correctly", async () => {
+    const request = new Request("http://localhost");
+
+    vi.mocked(authenticateRequest).mockResolvedValue(
+      ok({
+        type: "apiKey",
+        environmentId: "env-id",
+        hashedApiKey: "hashed-api-key",
+      })
+    );
+
+    const paramsSchema = z.object({ key: z.string() });
+    const handler = vi.fn().mockResolvedValue(new Response("ok", { status: 200 }));
+
+    const response = await apiWrapper({
+      request,
+      schemas: { params: paramsSchema },
+      externalParams: Promise.resolve({ key: "value" }),
+      rateLimit: false,
+      handler,
+    });
+
+    expect(response.status).toBe(200);
+    expect(handler).toHaveBeenCalledWith(
+      expect.objectContaining({
+        parsedInput: { params: { key: "value" } },
+      })
+    );
+  });
+
+  it("should handle no external params", async () => {
+    const request = new Request("http://localhost");
+
+    vi.mocked(authenticateRequest).mockResolvedValue(
+      ok({
+        type: "apiKey",
+        environmentId: "env-id",
+        hashedApiKey: "hashed-api-key",
+      })
+    );
+
+    vi.mocked(handleApiError).mockResolvedValue(new Response("error", { status: 400 }));
+
+    const paramsSchema = z.object({ key: z.string() });
+    const handler = vi.fn();
+
+    const response = await apiWrapper({
+      request,
+      schemas: { params: paramsSchema },
+      externalParams: undefined,
+      rateLimit: false,
+      handler,
+    });
+
+    expect(response.status).toBe(400);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("should handle params schema errors", async () => {
+    const request = new Request("http://localhost");
+
+    vi.mocked(authenticateRequest).mockResolvedValue(
+      ok({
+        type: "apiKey",
+        environmentId: "env-id",
+        hashedApiKey: "hashed-api-key",
+      })
+    );
+
+    vi.mocked(handleApiError).mockResolvedValue(new Response("error", { status: 400 }));
+
+    const paramsSchema = z.object({ key: z.string() });
+    const handler = vi.fn();
+
+    const response = await apiWrapper({
+      request,
+      schemas: { params: paramsSchema },
+      externalParams: Promise.resolve({ notKey: "value" }),
+      rateLimit: false,
+      handler,
+    });
+
+    expect(response.status).toBe(400);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("should handle rate limit errors", async () => {
+    const request = new Request("http://localhost", {
+      headers: { "x-api-key": "valid-api-key" },
+    });
+
+    vi.mocked(authenticateRequest).mockResolvedValue(
+      ok({
+        type: "apiKey",
+        environmentId: "env-id",
+        hashedApiKey: "hashed-api-key",
+      })
+    );
+    vi.mocked(checkRateLimitAndThrowError).mockResolvedValue(
+      err({ type: "rateLimitExceeded" } as unknown as ApiErrorResponseV2)
+    );
+    vi.mocked(handleApiError).mockImplementation(
+      (_request: Request, _error: ApiErrorResponseV2): Response =>
+        new Response("rate limit exceeded", { status: 429 })
+    );
+
+    const handler = vi.fn();
+    const response = await apiWrapper({
+      request,
+      handler,
+    });
+
+    expect(response.status).toBe(429);
+    expect(handler).not.toHaveBeenCalled();
+  });
+});

apps/web/modules/api/v2/auth/tests/authenticate-request.test.ts

@@ -0,0 +1,114 @@
+import { hashApiKey } from "@/modules/api/v2/management/lib/utils";
+import { describe, expect, it, vi } from "vitest";
+import { prisma } from "@formbricks/database";
+import { authenticateRequest } from "../authenticate-request";
+
+vi.mock("@formbricks/database", () => ({
+  prisma: {
+    apiKey: {
+      findUnique: vi.fn(),
+      update: vi.fn(),
+    },
+  },
+}));
+
+vi.mock("@/modules/api/v2/management/lib/utils", () => ({
+  hashApiKey: vi.fn(),
+}));
+
+describe("authenticateRequest", () => {
+  it("should return authentication data if apiKey is valid", async () => {
+    const request = new Request("http://localhost", {
+      headers: { "x-api-key": "valid-api-key" },
+    });
+
+    const mockApiKeyData = {
+      id: "api-key-id",
+      organizationId: "org-id",
+      createdAt: new Date(),
+      createdBy: "user-id",
+      lastUsedAt: null,
+      label: "Test API Key",
+      hashedKey: "hashed-api-key",
+      apiKeyEnvironments: [
+        {
+          environmentId: "env-id-1",
+          permission: "manage",
+          environment: {
+            id: "env-id-1",
+            projectId: "project-id-1",
+            type: "development",
+            project: { name: "Project 1" },
+          },
+        },
+        {
+          environmentId: "env-id-2",
+          permission: "read",
+          environment: {
+            id: "env-id-2",
+            projectId: "project-id-2",
+            type: "production",
+            project: { name: "Project 2" },
+          },
+        },
+      ],
+    };
+
+    vi.mocked(hashApiKey).mockReturnValue("hashed-api-key");
+    vi.mocked(prisma.apiKey.findUnique).mockResolvedValue(mockApiKeyData);
+    vi.mocked(prisma.apiKey.update).mockResolvedValue(mockApiKeyData);
+
+    const result = await authenticateRequest(request);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data).toEqual({
+        type: "apiKey",
+        environmentPermissions: [
+          {
+            environmentId: "env-id-1",
+            permission: "manage",
+            environmentType: "development",
+            projectId: "project-id-1",
+            projectName: "Project 1",
+          },
+          {
+            environmentId: "env-id-2",
+            permission: "read",
+            environmentType: "production",
+            projectId: "project-id-2",
+            projectName: "Project 2",
+          },
+        ],
+        hashedApiKey: "hashed-api-key",
+        apiKeyId: "api-key-id",
+        organizationId: "org-id",
+      });
+    }
+  });
+
+  it("should return unauthorized error if apiKey is not found", async () => {
+    const request = new Request("http://localhost", {
+      headers: { "x-api-key": "invalid-api-key" },
+    });
+    vi.mocked(prisma.apiKey.findUnique).mockResolvedValue(null);
+
+    const result = await authenticateRequest(request);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toEqual({ type: "unauthorized" });
+    }
+  });
+
+  it("should return unauthorized error if apiKey is missing", async () => {
+    const request = new Request("http://localhost");
+
+    const result = await authenticateRequest(request);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toEqual({ type: "unauthorized" });
+    }
+  });
+});

apps/web/modules/api/v2/auth/tests/authenticated-api-client.test.ts

@@ -0,0 +1,32 @@
+import { logApiRequest } from "@/modules/api/v2/lib/utils";
+import { describe, expect, it, vi } from "vitest";
+import { apiWrapper } from "../api-wrapper";
+import { authenticatedApiClient } from "../authenticated-api-client";
+
+vi.mock("../api-wrapper", () => ({
+  apiWrapper: vi.fn(),
+}));
+
+vi.mock("@/modules/api/v2/lib/utils", () => ({
+  logApiRequest: vi.fn(),
+}));
+
+describe("authenticatedApiClient", () => {
+  it("should log request and return response", async () => {
+    const request = new Request("http://localhost", {
+      headers: { "x-api-key": "valid-api-key" },
+    });
+
+    vi.mocked(apiWrapper).mockResolvedValue(new Response("ok", { status: 200 }));
+    vi.mocked(logApiRequest).mockReturnValue();
+
+    const handler = vi.fn().mockResolvedValue(new Response("ok", { status: 200 }));
+    const response = await authenticatedApiClient({
+      request,
+      handler,
+    });
+
+    expect(response.status).toBe(200);
+    expect(logApiRequest).toHaveBeenCalled();
+  });
+});