@multiplatform.one/frappe 6.0.0

package/src/core/http.spec.ts

@@ -0,0 +1,1128 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HttpClient } from "./http";
+import { AuthType, FrappeError, HttpMethod } from "./types";
+
+describe("HttpClient", () => {
+  let client: HttpClient;
+  const baseURL = "https://api.example.com";
+  const getMockFetch = () => vi.mocked(fetch);
+  beforeEach(() => {
+    client = new HttpClient(baseURL);
+    global.fetch = vi.fn();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("constructor", () => {
+    it("should initialize with base URL", () => {
+      const httpClient = new HttpClient(baseURL);
+      expect(httpClient).toBeDefined();
+    });
+
+    it("should accept auth config", () => {
+      const httpClient = new HttpClient(baseURL, {
+        useToken: true,
+        token: "test-token",
+        type: AuthType.Bearer,
+      });
+      expect(httpClient).toBeDefined();
+    });
+
+    it("should accept retry config", () => {
+      const httpClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 5,
+        baseDelayMs: 500,
+        exponentialBackoff: false,
+      });
+      expect(httpClient).toBeDefined();
+    });
+  });
+
+  describe("request", () => {
+    it("should make basic GET request", async () => {
+      const mockPayload = { data: "test" };
+      const mockHeaders = new Headers({ "Content-Type": "application/json" });
+      const mockRes = {
+        ok: true,
+        headers: mockHeaders,
+        status: 200,
+        json: async () => mockPayload,
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      const result = await client.request<typeof mockPayload>(HttpMethod.Get, "/test", {});
+      expect(fetch).toHaveBeenCalledWith(
+        `${baseURL}/test`,
+        expect.objectContaining({
+          method: "GET",
+          credentials: "include",
+        }),
+      );
+      expect(result.payload).toEqual(mockPayload);
+      expect(result.headers).toBe(mockHeaders);
+      expect(result.status).toBe(200);
+      expect(result._res).toBe(mockRes);
+    });
+
+    it("should make POST request with JSON body", async () => {
+      const requestBody = { foo: "bar", nested: { value: 123 } };
+      const mockPayload = { success: true };
+      const mockHeaders = new Headers({ "Content-Type": "application/json" });
+      const mockRes = {
+        ok: true,
+        headers: mockHeaders,
+        status: 200,
+        json: async () => mockPayload,
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      const result = await client.request<typeof mockPayload>(HttpMethod.Post, "/test", {
+        body: requestBody,
+      });
+      expect(fetch).toHaveBeenCalledWith(
+        `${baseURL}/test`,
+        expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify(requestBody),
+          headers: expect.any(Headers),
+          credentials: "include",
+        }),
+      );
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("Content-Type")).toBe("application/json");
+      expect(result.payload).toEqual(mockPayload);
+      expect(result.status).toBe(200);
+    });
+
+    it("should handle FormData body", async () => {
+      const formData = new FormData();
+      formData.append("field", "value");
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      const result = await client.request(HttpMethod.Post, "/upload", {
+        body: formData,
+      });
+      expect(fetch).toHaveBeenCalledWith(
+        `${baseURL}/upload`,
+        expect.objectContaining({
+          method: "POST",
+          body: formData,
+          headers: expect.any(Headers),
+          credentials: "include",
+        }),
+      );
+      expect(result.payload).toEqual({ success: true });
+    });
+
+    it("should handle URLSearchParams body", async () => {
+      const params = new URLSearchParams();
+      params.append("key", "value");
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "text/plain" }),
+        status: 200,
+        text: async () => "success",
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      const result = await client.request(HttpMethod.Post, "/form", {
+        body: params,
+      });
+      expect(fetch).toHaveBeenCalledWith(
+        `${baseURL}/form`,
+        expect.objectContaining({
+          method: "POST",
+          body: params,
+          credentials: "include",
+        }),
+      );
+      expect(result.payload).toBe("success");
+    });
+
+    it("should convert object to FormData when Content-Type is multipart/form-data", async () => {
+      const requestBody = { field1: "value1", field2: "value2" };
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/test", {
+        body: requestBody,
+        headers: { "Content-Type": "multipart/form-data" },
+      });
+      const calledBody = getMockFetch().mock.calls[0]?.[1]?.body;
+      expect(calledBody).toBeInstanceOf(FormData);
+    });
+
+    it("should convert object to URLSearchParams when Content-Type is application/x-www-form-urlencoded", async () => {
+      const requestBody = { field1: "value1", field2: "value2" };
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "text/plain" }),
+        status: 200,
+        text: async () => "success",
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/test", {
+        body: requestBody,
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      });
+      const calledBody = getMockFetch().mock.calls[0]?.[1]?.body;
+      expect(calledBody).toBe("field1=value1&field2=value2");
+    });
+
+    it("should handle text response", async () => {
+      const textResponse = "Plain text response";
+      const mockHeaders = new Headers({ "Content-Type": "text/plain" });
+      const mockRes = {
+        ok: true,
+        headers: mockHeaders,
+        status: 200,
+        text: async () => textResponse,
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      const result = await client.request(HttpMethod.Get, "/text", {});
+      expect(result.payload).toBe(textResponse);
+      expect(result.headers).toBe(mockHeaders);
+      expect(result.status).toBe(200);
+    });
+
+    it("should throw FrappeError on non-ok response", async () => {
+      const errorPayload = { message: "Bad Request", details: "Invalid input" };
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        status: 400,
+        statusText: "Bad Request",
+        headers: new Headers({ "Content-Type": "application/json" }),
+        json: async () => errorPayload,
+      });
+      await expect(client.request(HttpMethod.Post, "/test", {})).rejects.toThrow(FrappeError);
+      try {
+        await client.request(HttpMethod.Post, "/test", {});
+      } catch (error) {
+        expect(error).toBeInstanceOf(FrappeError);
+        expect((error as FrappeError).status).toBe(400);
+        expect((error as FrappeError).message).toBe("Bad Request");
+        expect((error as FrappeError).data).toEqual(errorPayload);
+      }
+    });
+
+    it("should handle network errors", async () => {
+      const networkError = new Error("Network error");
+      global.fetch = vi.fn().mockRejectedValue(networkError);
+      await expect(client.request(HttpMethod.Get, "/test", {})).rejects.toThrow("Network error");
+    });
+  });
+
+  describe("authentication", () => {
+    it("should add Bearer token to headers", async () => {
+      const token = "test-bearer-token";
+      const authClient = new HttpClient(baseURL, {
+        useToken: true,
+        token,
+        type: AuthType.Bearer,
+      });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await authClient.request(HttpMethod.Get, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("Authorization")).toBe(`Bearer ${token}`);
+      expect(getMockFetch().mock.calls[0]?.[1]?.credentials).toBe("omit");
+    });
+
+    it("should add token auth to headers", async () => {
+      const token = "test-token";
+      const authClient = new HttpClient(baseURL, {
+        useToken: true,
+        token,
+        type: AuthType.Token,
+      });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await authClient.request(HttpMethod.Get, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("Authorization")).toBe(`token ${token}`);
+    });
+
+    it("should support token as function", async () => {
+      const token = "dynamic-token";
+      const authClient = new HttpClient(baseURL, {
+        useToken: true,
+        token: async () => token,
+        type: AuthType.Bearer,
+      });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await authClient.request(HttpMethod.Get, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("Authorization")).toBe(`Bearer ${token}`);
+    });
+
+    it("should add CSRF token for non-GET requests without token auth", async () => {
+      const csrfToken = "csrf-test-token";
+      Object.defineProperty(global, "document", {
+        value: { cookie: `frappe-csrf-token=${csrfToken}; path=/` },
+        writable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: {},
+        writable: true,
+      });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("X-Frappe-CSRF-Token")).toBe(csrfToken);
+      Object.defineProperty(global, "document", {
+        value: undefined,
+        configurable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: undefined,
+        configurable: true,
+      });
+    });
+
+    it("should use credentials include when not using token auth", async () => {
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Get, "/test", {});
+      expect(getMockFetch().mock.calls[0]?.[1]?.credentials).toBe("include");
+    });
+
+    it("should set token dynamically via function", async () => {
+      const tokenFn = vi.fn().mockResolvedValue("new-token");
+      const authClient = new HttpClient(baseURL, { useToken: true, token: tokenFn });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await authClient.request(HttpMethod.Get, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("Authorization")).toBe("Bearer new-token");
+      expect(tokenFn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("retry logic", () => {
+    it("should retry on retry-able status codes", async () => {
+      const retryClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 2,
+        baseDelayMs: 10,
+        retryStatusCodes: [503],
+      });
+      let attempt = 0;
+      global.fetch = vi.fn().mockImplementation(async () => {
+        attempt++;
+        if (attempt < 3) {
+          return {
+            ok: false,
+            status: 503,
+            statusText: "Service Unavailable",
+            headers: new Headers({ "Content-Type": "text/plain" }),
+            text: async () => "Service temporarily unavailable",
+          };
+        }
+        return {
+          ok: true,
+          headers: new Headers({ "Content-Type": "application/json" }),
+          status: 200,
+          json: async () => ({ success: true }),
+        };
+      });
+      const result = await retryClient.request(HttpMethod.Get, "/test", {});
+      expect(fetch).toHaveBeenCalledTimes(3);
+      expect(result.payload).toEqual({ success: true });
+    });
+
+    it("should retry on network errors when configured", async () => {
+      const retryClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 1,
+        baseDelayMs: 10,
+        retryOnNetworkError: true,
+      });
+      let attempt = 0;
+      global.fetch = vi.fn().mockImplementation(async () => {
+        attempt++;
+        if (attempt === 1) {
+          throw new Error("Network error");
+        }
+        return {
+          ok: true,
+          headers: new Headers({ "Content-Type": "application/json" }),
+          status: 200,
+          json: async () => ({ success: true }),
+        };
+      });
+      const result = await retryClient.request(HttpMethod.Get, "/test", {});
+      expect(fetch).toHaveBeenCalledTimes(2);
+      expect(result.payload).toEqual({ success: true });
+    });
+
+    it("should not retry on non-retry-able status codes", async () => {
+      const retryClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 2,
+        baseDelayMs: 10,
+        retryStatusCodes: [503],
+      });
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        status: 400,
+        statusText: "Bad Request",
+        headers: new Headers({ "Content-Type": "text/plain" }),
+        text: async () => "Bad request",
+      });
+      await expect(retryClient.request(HttpMethod.Get, "/test", {})).rejects.toThrow(FrappeError);
+      expect(fetch).toHaveBeenCalledTimes(1);
+    });
+
+    it("should use exponential backoff when configured", async () => {
+      const retryClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 3,
+        baseDelayMs: 100,
+        exponentialBackoff: true,
+        maxDelayMs: 500,
+        retryStatusCodes: [503],
+      });
+      const delays: number[] = [];
+      vi.spyOn(global, "setTimeout").mockImplementation(
+        (fn: Parameters<typeof setTimeout>[0], delay?: number) => {
+          delays.push(delay || 0);
+          if (typeof fn === "function") fn();
+          return 0 as unknown as ReturnType<typeof setTimeout>;
+        },
+      );
+      let attempt = 0;
+      global.fetch = vi.fn().mockImplementation(async () => {
+        attempt++;
+        if (attempt <= 3) {
+          return {
+            ok: false,
+            status: 503,
+            statusText: "Service Unavailable",
+            headers: new Headers({ "Content-Type": "text/plain" }),
+            text: async () => "Service unavailable",
+          };
+        }
+        return {
+          ok: true,
+          headers: new Headers({ "Content-Type": "application/json" }),
+          status: 200,
+          json: async () => ({ success: true }),
+        };
+      });
+      const result = await retryClient.request(HttpMethod.Get, "/test", {});
+      expect(delays[0]).toBe(100);
+      expect(delays[1]).toBe(200);
+      expect(delays[2]).toBe(400);
+      expect(result.payload).toEqual({ success: true });
+    });
+
+    it("should respect maxDelayMs", async () => {
+      const retryClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 3,
+        baseDelayMs: 100,
+        exponentialBackoff: true,
+        maxDelayMs: 150,
+        retryStatusCodes: [503],
+      });
+      const delays: number[] = [];
+      vi.spyOn(global, "setTimeout").mockImplementation(
+        (fn: Parameters<typeof setTimeout>[0], delay?: number) => {
+          delays.push(delay || 0);
+          if (typeof fn === "function") fn();
+          return 0 as unknown as ReturnType<typeof setTimeout>;
+        },
+      );
+      let attempt = 0;
+      global.fetch = vi.fn().mockImplementation(async () => {
+        attempt++;
+        if (attempt <= 3) {
+          return {
+            ok: false,
+            status: 503,
+            statusText: "Service Unavailable",
+            headers: new Headers({ "Content-Type": "text/plain" }),
+            text: async () => "Service unavailable",
+          };
+        }
+        return {
+          ok: true,
+          headers: new Headers({ "Content-Type": "application/json" }),
+          status: 200,
+          json: async () => ({ success: true }),
+        };
+      });
+      const result = await retryClient.request(HttpMethod.Get, "/test", {});
+      expect(delays[0]).toBe(100);
+      expect(delays[1]).toBe(150);
+      expect(delays[2]).toBe(150);
+      expect(result.payload).toEqual({ success: true });
+    });
+
+    it("should use custom shouldRetry function", async () => {
+      const shouldRetry = vi.fn((_err, attempt) => attempt < 2);
+      const retryClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 3,
+        baseDelayMs: 10,
+        shouldRetry,
+      });
+      let attempt = 0;
+      global.fetch = vi.fn().mockImplementation(async () => {
+        attempt++;
+        if (attempt < 3) {
+          return {
+            ok: false,
+            status: 500,
+            statusText: "Internal Server Error",
+            headers: new Headers({ "Content-Type": "text/plain" }),
+            text: async () => "Server error",
+          };
+        }
+        return {
+          ok: true,
+          headers: new Headers({ "Content-Type": "application/json" }),
+          status: 200,
+          json: async () => ({ success: true }),
+        };
+      });
+      const result = await retryClient.request(HttpMethod.Get, "/test", {});
+      expect(shouldRetry).toHaveBeenCalledTimes(2);
+      expect(fetch).toHaveBeenCalledTimes(3);
+      expect(result.payload).toEqual({ success: true });
+    });
+
+    it("should throw last error after max retries", async () => {
+      const retryClient = new HttpClient(baseURL, undefined, {
+        maxRetries: 2,
+        baseDelayMs: 10,
+        retryStatusCodes: [503],
+      });
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        status: 503,
+        statusText: "Service Unavailable",
+        headers: new Headers({ "Content-Type": "text/plain" }),
+        text: async () => "Service unavailable",
+      });
+      await expect(retryClient.request(HttpMethod.Get, "/test", {})).rejects.toThrow(FrappeError);
+      expect(fetch).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("convenience methods", () => {
+    beforeEach(() => {
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+    });
+
+    describe("get", () => {
+      it("should make GET request without params", async () => {
+        const result = await client.get("/test");
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test`,
+          expect.objectContaining({ method: "GET" }),
+        );
+        expect(result.payload).toEqual({ success: true });
+      });
+
+      it("should make GET request with params", async () => {
+        await client.get("/test", {
+          foo: "bar",
+          num: 123,
+          bool: true,
+          nullValue: null,
+          undefinedValue: undefined,
+        });
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test?foo=bar&num=123&bool=true`,
+          expect.objectContaining({ method: "GET" }),
+        );
+      });
+
+      it("should handle complex params", async () => {
+        await client.get("/test", {
+          array: [1, 2, 3],
+          object: { nested: "value" },
+        });
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test?array=%5B1%2C2%2C3%5D&object=%7B%22nested%22%3A%22value%22%7D`,
+          expect.objectContaining({ method: "GET" }),
+        );
+      });
+
+      it("should pass custom headers", async () => {
+        await client.get("/test", {}, { "X-Custom": "header" });
+        const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+        expect(calledHeaders?.get("X-Custom")).toBe("header");
+      });
+    });
+
+    describe("post", () => {
+      it("should make POST request without body", async () => {
+        const result = await client.post("/test");
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test`,
+          expect.objectContaining({ method: "POST" }),
+        );
+        expect(result.payload).toEqual({ success: true });
+      });
+
+      it("should make POST request with body", async () => {
+        const body = { data: "test" };
+        const result = await client.post("/test", body);
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test`,
+          expect.objectContaining({
+            method: "POST",
+            body: JSON.stringify(body),
+          }),
+        );
+        expect(result.payload).toEqual({ success: true });
+      });
+
+      it("should pass custom headers", async () => {
+        await client.post("/test", {}, { "X-Custom": "header" });
+        const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+        expect(calledHeaders?.get("X-Custom")).toBe("header");
+      });
+    });
+
+    describe("put", () => {
+      it("should make PUT request", async () => {
+        const body = { data: "test" };
+        const result = await client.put("/test", body);
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test`,
+          expect.objectContaining({
+            method: "PUT",
+            body: JSON.stringify(body),
+          }),
+        );
+        expect(result.payload).toEqual({ success: true });
+      });
+
+      it("should pass custom headers", async () => {
+        await client.put("/test", {}, { "X-Custom": "header" });
+        const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+        expect(calledHeaders?.get("X-Custom")).toBe("header");
+      });
+    });
+
+    describe("delete", () => {
+      it("should make DELETE request", async () => {
+        const result = await client.delete("/test");
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test`,
+          expect.objectContaining({ method: "DELETE" }),
+        );
+        expect(result.payload).toEqual({ success: true });
+      });
+
+      it("should make DELETE request with body", async () => {
+        const body = { id: "123" };
+        const result = await client.delete("/test", body);
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test`,
+          expect.objectContaining({
+            method: "DELETE",
+            body: JSON.stringify(body),
+          }),
+        );
+        expect(result.payload).toEqual({ success: true });
+      });
+
+      it("should pass custom headers", async () => {
+        await client.delete("/test", undefined, { "X-Custom": "header" });
+        const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+        expect(calledHeaders?.get("X-Custom")).toBe("header");
+      });
+    });
+
+    describe("head", () => {
+      it("should make HEAD request and return response", async () => {
+        const mockRes = {
+          ok: true,
+          headers: new Headers({
+            "Content-Type": "application/json",
+            "Content-Length": "1234",
+          }),
+          status: 200,
+          text: async () => "",
+          json: async () => ({}),
+        };
+        global.fetch = vi.fn().mockResolvedValue(mockRes);
+        const response = await client.head("/test");
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test`,
+          expect.objectContaining({ method: "HEAD" }),
+        );
+        expect(response.headers.get("Content-Type")).toBe("application/json");
+        expect(response.headers.get("Content-Length")).toBe("1234");
+        expect(response.status).toBe(200);
+      });
+
+      it("should make HEAD request with params", async () => {
+        const mockRes = {
+          ok: true,
+          headers: new Headers(),
+          status: 200,
+          text: async () => "",
+          json: async () => ({}),
+        };
+        global.fetch = vi.fn().mockResolvedValue(mockRes);
+        const response = await client.head("/test", { check: "true" });
+        expect(fetch).toHaveBeenCalledWith(
+          `${baseURL}/test?check=true`,
+          expect.objectContaining({ method: "HEAD" }),
+        );
+        expect(response.status).toBe(200);
+      });
+
+      it("should pass custom headers", async () => {
+        const mockRes = {
+          ok: true,
+          headers: new Headers(),
+          status: 200,
+          text: async () => "",
+          json: async () => ({}),
+        };
+        global.fetch = vi.fn().mockResolvedValue(mockRes);
+        await client.head("/test", {}, { "X-Custom": "header" });
+        const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+        expect(calledHeaders?.get("X-Custom")).toBe("header");
+      });
+
+      it("should throw FrappeError on non-ok response", async () => {
+        global.fetch = vi.fn().mockResolvedValue({
+          ok: false,
+          status: 404,
+          statusText: "Not Found",
+          headers: new Headers(),
+          text: async () => "Not found",
+        });
+        await expect(client.head("/test")).rejects.toThrow(FrappeError);
+        try {
+          await client.head("/test");
+        } catch (error) {
+          expect(error).toBeInstanceOf(FrappeError);
+          expect((error as FrappeError).status).toBe(404);
+          expect((error as FrappeError).message).toBe("Not Found");
+        }
+      });
+
+      it("should use credentials include when not using token auth", async () => {
+        const mockRes = {
+          ok: true,
+          headers: new Headers(),
+          status: 200,
+          text: async () => "",
+          json: async () => ({}),
+        };
+        global.fetch = vi.fn().mockResolvedValue(mockRes);
+        await client.head("/test");
+        expect(getMockFetch().mock.calls[0]?.[1]?.credentials).toBe("include");
+      });
+
+      it("should use credentials omit and add auth header when using token auth", async () => {
+        const authClient = new HttpClient(baseURL, {
+          useToken: true,
+          token: "test-token",
+          type: AuthType.Bearer,
+        });
+        const mockRes = {
+          ok: true,
+          headers: new Headers(),
+          status: 200,
+          text: async () => "",
+          json: async () => ({}),
+        };
+        global.fetch = vi.fn().mockResolvedValue(mockRes);
+        await authClient.head("/test");
+        expect(getMockFetch().mock.calls[0]?.[1]?.credentials).toBe("omit");
+        const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+        expect(calledHeaders?.get("Authorization")).toBe("Bearer test-token");
+      });
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle empty response", async () => {
+      const mockRes = {
+        ok: true,
+        headers: new Headers(),
+        status: 200,
+        text: async () => "",
+        json: async () => {
+          throw new Error("Invalid JSON");
+        },
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      const result = await client.request(HttpMethod.Get, "/empty", {});
+      expect(result.payload).toBe("");
+      expect(result.status).toBe(200);
+    });
+
+    it("should handle ArrayBuffer body", async () => {
+      const buffer = new ArrayBuffer(8);
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/binary", {
+        body: buffer,
+      });
+      expect(getMockFetch().mock.calls[0]?.[1]?.body).toBe(buffer);
+    });
+
+    it("should handle Blob body", async () => {
+      const blob = new Blob(["test"], { type: "text/plain" });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/blob", {
+        body: blob,
+      });
+      expect(getMockFetch().mock.calls[0]?.[1]?.body).toBe(blob);
+    });
+
+    it("should handle ArrayBufferView body", async () => {
+      const uint8Array = new Uint8Array([1, 2, 3, 4]);
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/typed-array", {
+        body: uint8Array,
+      });
+      expect(getMockFetch().mock.calls[0]?.[1]?.body).toBe(uint8Array);
+    });
+
+    it("should handle relative paths", async () => {
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Get, "relative/path", {});
+      expect(fetch).toHaveBeenCalledWith(`${baseURL}/relative/path`, expect.any(Object));
+    });
+
+    it("should handle absolute paths", async () => {
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Get, "/absolute/path", {});
+      expect(fetch).toHaveBeenCalledWith(`${baseURL}/absolute/path`, expect.any(Object));
+    });
+
+    it("should handle error response with _server_messages", async () => {
+      const errorPayload = {
+        _server_messages: "Server error messages",
+        exc: "Exception details",
+        message: "Error message",
+      };
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        status: 500,
+        statusText: "Internal Server Error",
+        headers: new Headers({ "Content-Type": "application/json" }),
+        json: async () => errorPayload,
+      });
+      try {
+        await client.request(HttpMethod.Post, "/test", {});
+      } catch (error) {
+        expect(error).toBeInstanceOf(FrappeError);
+        expect((error as FrappeError).message).toBe("Error message");
+      }
+    });
+
+    it("should handle error response with exc", async () => {
+      const errorPayload = {
+        exc: "Exception details",
+      };
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        status: 500,
+        statusText: "Internal Server Error",
+        headers: new Headers({ "Content-Type": "application/json" }),
+        json: async () => errorPayload,
+      });
+      try {
+        await client.request(HttpMethod.Post, "/test", {});
+      } catch (error) {
+        expect(error).toBeInstanceOf(FrappeError);
+        expect((error as FrappeError).message).toBe("Exception details");
+      }
+    });
+
+    it("should handle FormData with Blob values", async () => {
+      const blob = new Blob(["file content"], { type: "text/plain" });
+      const requestBody = {
+        field: "value",
+        file: blob,
+      };
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/upload", {
+        body: requestBody,
+        headers: { "Content-Type": "multipart/form-data" },
+      });
+      const calledBody = getMockFetch().mock.calls[0]?.[1]?.body;
+      expect(calledBody).toBeInstanceOf(FormData);
+    });
+
+    it("should skip non-string values in URLSearchParams conversion", async () => {
+      const requestBody = {
+        field1: "value1",
+        field2: 123,
+        field3: null,
+        field4: undefined,
+      };
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "text/plain" }),
+        status: 200,
+        text: async () => "success",
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/test", {
+        body: requestBody,
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      });
+      const calledBody = getMockFetch().mock.calls[0]?.[1]?.body;
+      expect(calledBody).toBe("field1=value1");
+    });
+
+    it("should handle ReadableStream body", async () => {
+      const stream = new ReadableStream();
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/stream", {
+        body: stream,
+      });
+      expect(getMockFetch().mock.calls[0]?.[1]?.body).toBe(stream);
+    });
+
+    it("should handle global frappe csrf token", async () => {
+      Object.defineProperty(global, "document", {
+        value: { cookie: "" },
+        writable: true,
+        configurable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: {},
+        writable: true,
+        configurable: true,
+      });
+      Object.defineProperty(global, "frappe", {
+        value: { csrf_token: "global-csrf-token" },
+        writable: true,
+        configurable: true,
+      });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("X-Frappe-CSRF-Token")).toBe("global-csrf-token");
+      Object.defineProperty(global, "document", {
+        value: undefined,
+        configurable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: undefined,
+        configurable: true,
+      });
+      Object.defineProperty(global, "frappe", {
+        value: undefined,
+        configurable: true,
+      });
+    });
+
+    it("should prefer frappe-csrf-token cookie over csrf_token", async () => {
+      Object.defineProperty(global, "document", {
+        value: { cookie: "frappe-csrf-token=preferred; csrf_token=fallback" },
+        writable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: {},
+        writable: true,
+      });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("X-Frappe-CSRF-Token")).toBe("preferred");
+      Object.defineProperty(global, "document", {
+        value: undefined,
+        configurable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: undefined,
+        configurable: true,
+      });
+    });
+
+    it("should use csrf_token cookie as fallback", async () => {
+      Object.defineProperty(global, "document", {
+        value: { cookie: "csrf_token=fallback" },
+        writable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: {},
+        writable: true,
+      });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("X-Frappe-CSRF-Token")).toBe("fallback");
+      Object.defineProperty(global, "document", {
+        value: undefined,
+        configurable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: undefined,
+        configurable: true,
+      });
+    });
+
+    it("should not add CSRF token for GET requests", async () => {
+      Object.defineProperty(global, "document", {
+        value: { cookie: "frappe-csrf-token=test-token" },
+        writable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: {},
+        writable: true,
+      });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Get, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("X-Frappe-CSRF-Token")).toBeNull();
+      Object.defineProperty(global, "document", {
+        value: undefined,
+        configurable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: undefined,
+        configurable: true,
+      });
+    });
+
+    it("should handle cookie with special characters", async () => {
+      Object.defineProperty(global, "document", {
+        value: { cookie: "frappe-csrf-token=%2Ftest%2Ftoken%3D" },
+        writable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: {},
+        writable: true,
+      });
+      const mockRes = {
+        ok: true,
+        headers: new Headers({ "Content-Type": "application/json" }),
+        status: 200,
+        json: async () => ({ success: true }),
+      };
+      global.fetch = vi.fn().mockResolvedValue(mockRes);
+      await client.request(HttpMethod.Post, "/test", {});
+      const calledHeaders = getMockFetch().mock.calls[0]?.[1]?.headers as Headers | undefined;
+      expect(calledHeaders?.get("X-Frappe-CSRF-Token")).toBe("/test/token=");
+      Object.defineProperty(global, "document", {
+        value: undefined,
+        configurable: true,
+      });
+      Object.defineProperty(global, "window", {
+        value: undefined,
+        configurable: true,
+      });
+    });
+  });
+});