@dotcms/client 1.0.6 → 1.1.1

package/index.esm.js

@@ -1,6 +1,115 @@
 import { consola } from 'consola';
+import { BaseHttpClient, DotHttpError, DotErrorContent, DotErrorNavigation, DotErrorPage } from '@dotcms/types';
 import { graphqlToPageEntity } from './internal.esm.js';
 
+/**
+ * HTTP client implementation using the Fetch API.
+ *
+ * Extends BaseHttpClient to provide a standard interface for making HTTP requests.
+ * This implementation uses the native Fetch API and handles:
+ * - JSON and non-JSON response parsing
+ * - HTTP error response parsing and conversion to DotHttpError
+ * - Network error handling and wrapping
+ * - Content-Type detection for proper response handling
+ *
+ * @example
+ * ```typescript
+ * const client = new FetchHttpClient();
+ *
+ * // JSON request
+ * const data = await client.request<MyType>('/api/data', {
+ *   method: 'GET',
+ *   headers: { 'Authorization': 'Bearer token' }
+ * });
+ *
+ * // Non-JSON request (e.g., file download)
+ * const response = await client.request<Response>('/api/file.pdf', {
+ *   method: 'GET'
+ * });
+ * ```
+ */
+class FetchHttpClient extends BaseHttpClient {
+    /**
+     * Sends an HTTP request using the Fetch API.
+     *
+     * Implements the abstract request method from BaseHttpClient using the native Fetch API.
+     * Automatically handles response parsing based on Content-Type headers and converts
+     * HTTP errors to standardized DotHttpError instances.
+     *
+     * @template T - The expected response type. For JSON responses, T should be the parsed object type.
+     *               For non-JSON responses, T should be Response or the expected response type.
+     * @param url - The URL to send the request to.
+     * @param options - Optional fetch options including method, headers, body, etc.
+     * @returns Promise that resolves with the parsed response data or the Response object for non-JSON.
+     * @throws {DotHttpError} - Throws DotHttpError for HTTP errors (4xx/5xx status codes).
+     * @throws {DotHttpError} - Throws DotHttpError for network errors (connection issues, timeouts).
+     *
+     * @example
+     * ```typescript
+     * // JSON API request
+     * const user = await client.request<User>('/api/users/123', {
+     *   method: 'GET',
+     *   headers: { 'Accept': 'application/json' }
+     * });
+     *
+     * // POST request with JSON body
+     * const result = await client.request<CreateResult>('/api/users', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({ name: 'John', email: 'john@example.com' })
+     * });
+     *
+     * // File download (non-JSON response)
+     * const response = await client.request<Response>('/api/files/document.pdf', {
+     *   method: 'GET'
+     * });
+     * ```
+     */
+    async request(url, options) {
+        try {
+            // Use native fetch API - no additional configuration needed
+            const response = await fetch(url, options);
+            if (!response.ok) {
+                // Parse response body for error context
+                let errorBody;
+                try {
+                    const contentType = response.headers.get('content-type');
+                    if (contentType?.includes('application/json')) {
+                        errorBody = await response.json();
+                    }
+                    else {
+                        errorBody = await response.text();
+                    }
+                }
+                catch {
+                    errorBody = response.statusText;
+                }
+                // Convert headers to plain object
+                const headers = {};
+                response.headers.forEach((value, key) => {
+                    headers[key] = value;
+                });
+                throw this.createHttpError(response.status, response.statusText, headers, errorBody);
+            }
+            // Handle different response types
+            const contentType = response.headers.get('content-type');
+            if (contentType?.includes('application/json')) {
+                return response.json();
+            }
+            // For non-JSON responses, return the response object
+            // Sub-clients can handle specific response types as needed
+            return response;
+        }
+        catch (error) {
+            // Handle network errors (fetch throws TypeError for network issues)
+            if (error instanceof TypeError) {
+                throw this.createNetworkError(error);
+            }
+            throw error;
+        }
+    }
+}
+
 /******************************************************************************
 Copyright (c) Microsoft Corporation.
 
@@ -43,7 +152,13 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
  * Fields that should not be formatted when sanitizing the query.
  * These fields are essential for maintaining the integrity of the content type.
  */
-const CONTENT_TYPE_MAIN_FIELDS = ['live', 'variant', 'contentType', 'languageId'];
+const CONTENT_TYPE_MAIN_FIELDS = [
+    'live',
+    'variant',
+    'contentType',
+    'languageId',
+    'conhost'
+];
 /**
  * URL endpoint for the content API search functionality.
  */
@@ -75,6 +190,58 @@ function sanitizeQueryForContentType(query, contentType) {
             : original; // Return the field if it is a content type field
     });
 }
+/**
+ * @description
+ * Determines whether a site ID constraint should be added to a query based on existing constraints.
+ *
+ * The site ID constraint is added only when:
+ * - Query doesn't already contain a positive site constraint (+conhost)
+ * - Query doesn't explicitly exclude the specified site ID (-conhost:siteId)
+ * - Site ID is provided and configured
+ *
+ * @example
+ * ```ts
+ * const query = '+contentType:Blog +languageId:1';
+ * const siteId = '123';
+ * const shouldAdd = shouldAddSiteIdConstraint(query, siteId); // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * const query = '+contentType:Blog -conhost:123';
+ * const siteId = '123';
+ * const shouldAdd = shouldAddSiteIdConstraint(query, siteId); // false (explicitly excluded)
+ * ```
+ *
+ * @example
+ * ```ts
+ * const query = '+contentType:Blog +conhost:456';
+ * const siteId = '123';
+ * const shouldAdd = shouldAddSiteIdConstraint(query, siteId); // false (already has constraint)
+ * ```
+ *
+ * @export
+ * @param {string} query - The Lucene query string to analyze
+ * @param {string | number | null | undefined} siteId - The site ID to check for
+ * @returns {boolean} True if site ID constraint should be added, false otherwise
+ */
+function shouldAddSiteIdConstraint(query, siteId) {
+    // No site ID configured
+    if (!siteId) {
+        return false;
+    }
+    // Query already contains a positive site constraint
+    const hasExistingSiteConstraint = /\+conhost/gi.test(query);
+    if (hasExistingSiteConstraint) {
+        return false;
+    }
+    // Query explicitly excludes this specific site ID
+    const hasThisSiteIdExclusion = new RegExp(`-conhost:${siteId}`, 'gi').test(query);
+    if (hasThisSiteIdExclusion) {
+        return false;
+    }
+    return true;
+}
 
 var _Field_query;
 /**
@@ -577,7 +744,7 @@ class QueryBuilder {
 }
 _QueryBuilder_query = new WeakMap();
 
-var _CollectionBuilder_page, _CollectionBuilder_limit, _CollectionBuilder_depth, _CollectionBuilder_render, _CollectionBuilder_sortBy, _CollectionBuilder_contentType, _CollectionBuilder_defaultQuery, _CollectionBuilder_query, _CollectionBuilder_rawQuery, _CollectionBuilder_languageId, _CollectionBuilder_draft, _CollectionBuilder_serverUrl, _CollectionBuilder_requestOptions;
+var _CollectionBuilder_page, _CollectionBuilder_limit, _CollectionBuilder_depth, _CollectionBuilder_render, _CollectionBuilder_sortBy, _CollectionBuilder_contentType, _CollectionBuilder_defaultQuery, _CollectionBuilder_query, _CollectionBuilder_rawQuery, _CollectionBuilder_languageId, _CollectionBuilder_draft, _CollectionBuilder_requestOptions, _CollectionBuilder_httpClient, _CollectionBuilder_config;
 /**
  * Creates a Builder to filter and fetch content from the content API for a specific content type.
  *
@@ -589,11 +756,12 @@ class CollectionBuilder {
     /**
      * Creates an instance of CollectionBuilder.
      * @param {ClientOptions} requestOptions Options for the client request.
-     * @param {string} serverUrl The server URL.
+     * @param {DotCMSClientConfig} config The client configuration.
      * @param {string} contentType The content type to fetch.
+     * @param {DotHttpClient} httpClient HTTP client for making requests.
      * @memberof CollectionBuilder
      */
-    constructor(requestOptions, serverUrl, contentType) {
+    constructor(requestOptions, config, contentType, httpClient) {
         _CollectionBuilder_page.set(this, 1);
         _CollectionBuilder_limit.set(this, 10);
         _CollectionBuilder_depth.set(this, 0);
@@ -605,11 +773,14 @@ class CollectionBuilder {
         _CollectionBuilder_rawQuery.set(this, void 0);
         _CollectionBuilder_languageId.set(this, 1);
         _CollectionBuilder_draft.set(this, false);
-        _CollectionBuilder_serverUrl.set(this, void 0);
         _CollectionBuilder_requestOptions.set(this, void 0);
+        _CollectionBuilder_httpClient.set(this, void 0);
+        _CollectionBuilder_config.set(this, void 0);
         __classPrivateFieldSet(this, _CollectionBuilder_requestOptions, requestOptions, "f");
-        __classPrivateFieldSet(this, _CollectionBuilder_serverUrl, serverUrl, "f");
+        __classPrivateFieldSet(this, _CollectionBuilder_config, config, "f");
         __classPrivateFieldSet(this, _CollectionBuilder_contentType, contentType, "f");
+        __classPrivateFieldSet(this, _CollectionBuilder_httpClient, httpClient, "f");
+        __classPrivateFieldSet(this, _CollectionBuilder_config, config, "f");
         // Build the default query with the contentType field
         __classPrivateFieldSet(this, _CollectionBuilder_defaultQuery, new QueryBuilder().field('contentType').equals(__classPrivateFieldGet(this, _CollectionBuilder_contentType, "f")), "f");
     }
@@ -641,7 +812,17 @@ class CollectionBuilder {
      * @memberof CollectionBuilder
      */
     get url() {
-        return `${__classPrivateFieldGet(this, _CollectionBuilder_serverUrl, "f")}${CONTENT_API_URL}`;
+        return `${__classPrivateFieldGet(this, _CollectionBuilder_config, "f").dotcmsUrl}${CONTENT_API_URL}`;
+    }
+    /**
+     * Returns the site ID from the configuration.
+     *
+     * @readonly
+     * @private
+     * @memberof CollectionBuilder
+     */
+    get siteId() {
+        return __classPrivateFieldGet(this, _CollectionBuilder_config, "f").siteId;
     }
     /**
      * Returns the current query built.
@@ -826,26 +1007,36 @@ class CollectionBuilder {
      *
      * @param {OnFullfilled} [onfulfilled] A callback that is called when the fetch is successful.
      * @param {OnRejected} [onrejected] A callback that is called when the fetch fails.
-     * @return {Promise<GetCollectionResponse<T> | GetCollectionError>} A promise that resolves to the content or rejects with an error.
+     * @return {Promise<GetCollectionResponse<T> | DotErrorContent>} A promise that resolves to the content or rejects with an error.
      * @memberof CollectionBuilder
      */
     then(onfulfilled, onrejected) {
-        return this.fetch().then(async (response) => {
-            const data = await response.json();
-            if (response.ok) {
-                const formattedResponse = this.formatResponse(data);
-                const finalResponse = typeof onfulfilled === 'function'
-                    ? onfulfilled(formattedResponse)
-                    : formattedResponse;
-                return finalResponse;
+        return this.fetch().then((data) => {
+            const formattedResponse = this.formatResponse(data);
+            if (typeof onfulfilled === 'function') {
+                const result = onfulfilled(formattedResponse);
+                // Ensure we always return a value, fallback to formattedResponse if callback returns undefined
+                return result ?? formattedResponse;
+            }
+            return formattedResponse;
+        }, (error) => {
+            // Wrap error in DotCMSContentError
+            let contentError;
+            if (error instanceof DotHttpError) {
+                contentError = new DotErrorContent(`Content API failed for '${__classPrivateFieldGet(this, _CollectionBuilder_contentType, "f")}' (fetch): ${error.message}`, __classPrivateFieldGet(this, _CollectionBuilder_contentType, "f"), 'fetch', error, this.getFinalQuery());
             }
             else {
-                return {
-                    status: response.status,
-                    ...data
-                };
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                contentError = new DotErrorContent(`Content API failed for '${__classPrivateFieldGet(this, _CollectionBuilder_contentType, "f")}' (fetch): ${errorMessage}`, __classPrivateFieldGet(this, _CollectionBuilder_contentType, "f"), 'fetch', undefined, this.getFinalQuery());
             }
-        }, onrejected);
+            if (typeof onrejected === 'function') {
+                const result = onrejected(contentError);
+                // Ensure we always return a value, fallback to original error if callback returns undefined
+                return result ?? contentError;
+            }
+            // Throw the wrapped error to trigger .catch()
+            throw contentError;
+        });
     }
     /**
      * Formats the response to the desired format.
@@ -875,19 +1066,15 @@ class CollectionBuilder {
      * Calls the content API to fetch the content.
      *
      * @private
-     * @return {Promise<Response>} The fetch response.
+     * @return {Promise<GetCollectionRawResponse<T>>} The fetch response data.
+     * @throws {DotHttpError} When the HTTP request fails.
      * @memberof CollectionBuilder
      */
     fetch() {
-        const finalQuery = this.currentQuery
-            .field('languageId')
-            .equals(__classPrivateFieldGet(this, _CollectionBuilder_languageId, "f").toString())
-            .field('live')
-            .equals((!__classPrivateFieldGet(this, _CollectionBuilder_draft, "f")).toString())
-            .build();
+        const finalQuery = this.getFinalQuery();
         const sanitizedQuery = sanitizeQueryForContentType(finalQuery, __classPrivateFieldGet(this, _CollectionBuilder_contentType, "f"));
         const query = __classPrivateFieldGet(this, _CollectionBuilder_rawQuery, "f") ? `${sanitizedQuery} ${__classPrivateFieldGet(this, _CollectionBuilder_rawQuery, "f")}` : sanitizedQuery;
-        return fetch(this.url, {
+        return __classPrivateFieldGet(this, _CollectionBuilder_httpClient, "f").request(this.url, {
             ...__classPrivateFieldGet(this, _CollectionBuilder_requestOptions, "f"),
             method: 'POST',
             headers: {
@@ -906,10 +1093,62 @@ class CollectionBuilder {
             })
         });
     }
+    /**
+     * Builds the final Lucene query string by combining the base query with required system constraints.
+     *
+     * This method constructs the complete query by:
+     * 1. Adding language ID filter to ensure content matches the specified language
+     * 2. Adding live/draft status filter based on the draft flag
+     * 3. Optionally adding site ID constraint if conditions are met
+     *
+     * Site ID constraint is added only when:
+     * - Query doesn't already contain a positive site constraint (+conhost)
+     * - Query doesn't explicitly exclude the current site ID (-conhost:currentSiteId)
+     * - Site ID is configured in the system
+     *
+     * @private
+     * @returns {string} The complete Lucene query string ready for the Content API
+     * @memberof CollectionBuilder
+     *
+     * @example
+     * // For live content in language 1 with site ID 123:
+     * // Returns: "+contentType:Blog +languageId:1 +live:true +conhost:123"
+     *
+     * @example
+     * // For draft content without site constraint:
+     * // Returns: "+contentType:Blog +languageId:1 +live:false"
+     *
+     * @example
+     * // For content with explicit exclusion of current site (site ID 123):
+     * // Query: "+contentType:Blog -conhost:123"
+     * // Returns: "+contentType:Blog -conhost:123 +languageId:1 +live:true" (no site ID added)
+     *
+     * @example
+     * // For content with exclusion of different site (site ID 456, current is 123):
+     * // Query: "+contentType:Blog -conhost:456"
+     * // Returns: "+contentType:Blog -conhost:456 +languageId:1 +live:true +conhost:123" (site ID still added)
+     */
+    getFinalQuery() {
+        // Build base query with language and live/draft constraints
+        const baseQuery = this.currentQuery
+            .field('languageId')
+            .equals(__classPrivateFieldGet(this, _CollectionBuilder_languageId, "f").toString())
+            .field('live')
+            .equals((!__classPrivateFieldGet(this, _CollectionBuilder_draft, "f")).toString())
+            .build();
+        // Check if site ID constraint should be added using utility function
+        const shouldAddSiteId = shouldAddSiteIdConstraint(baseQuery, this.siteId);
+        // Add site ID constraint if needed
+        if (shouldAddSiteId) {
+            const queryWithSiteId = `${baseQuery} +conhost:${this.siteId}`;
+            return sanitizeQuery(queryWithSiteId);
+        }
+        return baseQuery;
+    }
 }
-_CollectionBuilder_page = new WeakMap(), _CollectionBuilder_limit = new WeakMap(), _CollectionBuilder_depth = new WeakMap(), _CollectionBuilder_render = new WeakMap(), _CollectionBuilder_sortBy = new WeakMap(), _CollectionBuilder_contentType = new WeakMap(), _CollectionBuilder_defaultQuery = new WeakMap(), _CollectionBuilder_query = new WeakMap(), _CollectionBuilder_rawQuery = new WeakMap(), _CollectionBuilder_languageId = new WeakMap(), _CollectionBuilder_draft = new WeakMap(), _CollectionBuilder_serverUrl = new WeakMap(), _CollectionBuilder_requestOptions = new WeakMap();
+_CollectionBuilder_page = new WeakMap(), _CollectionBuilder_limit = new WeakMap(), _CollectionBuilder_depth = new WeakMap(), _CollectionBuilder_render = new WeakMap(), _CollectionBuilder_sortBy = new WeakMap(), _CollectionBuilder_contentType = new WeakMap(), _CollectionBuilder_defaultQuery = new WeakMap(), _CollectionBuilder_query = new WeakMap(), _CollectionBuilder_rawQuery = new WeakMap(), _CollectionBuilder_languageId = new WeakMap(), _CollectionBuilder_draft = new WeakMap(), _CollectionBuilder_requestOptions = new WeakMap(), _CollectionBuilder_httpClient = new WeakMap(), _CollectionBuilder_config = new WeakMap();
 
-var _Content_requestOptions, _Content_serverUrl;
+var _Content_requestOptions, _Content_httpClient, _Content_config;
 /**
  * Creates a builder to filter and fetch a collection of content items.
  * @param contentType - The content type to retrieve.
@@ -962,14 +1201,17 @@ var _Content_requestOptions, _Content_serverUrl;
 class Content {
     /**
      * Creates an instance of Content.
-     * @param {RequestOptions} requestOptions - The options for the client request.
+     * @param {DotRequestOptions} requestOptions - The options for the client request.
      * @param {string} serverUrl - The server URL.
+     * @param {DotHttpClient} httpClient - HTTP client for making requests.
      */
-    constructor(requestOptions, serverUrl) {
+    constructor(config, requestOptions, httpClient) {
         _Content_requestOptions.set(this, void 0);
-        _Content_serverUrl.set(this, void 0);
+        _Content_httpClient.set(this, void 0);
+        _Content_config.set(this, void 0);
         __classPrivateFieldSet(this, _Content_requestOptions, requestOptions, "f");
-        __classPrivateFieldSet(this, _Content_serverUrl, serverUrl, "f");
+        __classPrivateFieldSet(this, _Content_config, config, "f");
+        __classPrivateFieldSet(this, _Content_httpClient, httpClient, "f");
     }
     /**
      * Takes a content type and returns a builder to filter and fetch the collection.
@@ -1037,35 +1279,44 @@ class Content {
      *
      */
     getCollection(contentType) {
-        return new CollectionBuilder(__classPrivateFieldGet(this, _Content_requestOptions, "f"), __classPrivateFieldGet(this, _Content_serverUrl, "f"), contentType);
+        return new CollectionBuilder(__classPrivateFieldGet(this, _Content_requestOptions, "f"), __classPrivateFieldGet(this, _Content_config, "f"), contentType, __classPrivateFieldGet(this, _Content_httpClient, "f"));
     }
 }
-_Content_requestOptions = new WeakMap(), _Content_serverUrl = new WeakMap();
+_Content_requestOptions = new WeakMap(), _Content_httpClient = new WeakMap(), _Content_config = new WeakMap();
 
 class NavigationClient {
-    constructor(config, requestOptions) {
+    constructor(config, requestOptions, httpClient) {
         this.requestOptions = requestOptions;
         this.BASE_URL = `${config?.dotcmsUrl}/api/v1/nav`;
+        this.httpClient = httpClient;
     }
     /**
      * Retrieves information about the dotCMS file and folder tree.
-     * @param {NavigationApiOptions} options - The options for the Navigation API call. Defaults to `{ depth: 0, path: '/', languageId: 1 }`.
+     * @param {string} path - The path to retrieve navigation for.
+     * @param {DotCMSNavigationRequestParams} params - The options for the Navigation API call.
      * @returns {Promise<DotCMSNavigationItem[]>} - A Promise that resolves to the response from the DotCMS API.
-     * @throws {Error} - Throws an error if the options are not valid.
+     * @throws {DotErrorNavigation} - Throws a navigation-specific error if the request fails.
      */
     async get(path, params) {
         if (!path) {
-            throw new Error("The 'path' parameter is required for the Navigation API");
+            throw new DotErrorNavigation("The 'path' parameter is required for the Navigation API", path);
         }
         const navParams = params ? this.mapToBackendParams(params) : {};
         const urlParams = new URLSearchParams(navParams).toString();
         const parsedPath = path.replace(/^\/+/, '/').replace(/\/+$/, '/');
         const url = `${this.BASE_URL}${parsedPath}${urlParams ? `?${urlParams}` : ''}`;
-        const response = await fetch(url, this.requestOptions);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch navigation data: ${response.statusText} - ${response.status}`);
+        try {
+            const response = await this.httpClient.request(url, this.requestOptions);
+            return response.entity;
+        }
+        catch (error) {
+            // Handle DotHttpError instances from httpClient.request
+            if (error instanceof DotHttpError) {
+                throw new DotErrorNavigation(`Navigation API failed for path '${parsedPath}': ${error.message}`, parsedPath, error);
+            }
+            // Handle other errors (validation, network, etc.)
+            throw new DotErrorNavigation(`Navigation API failed for path '${parsedPath}': ${error instanceof Error ? error.message : 'Unknown error'}`, parsedPath);
         }
-        return response.json().then((data) => data.entity);
     }
     mapToBackendParams(params) {
         const backendParams = {};
@@ -1079,26 +1330,6 @@ class NavigationClient {
     }
 }
 
-/**
- * A record of HTTP status codes and their corresponding error messages.
- *
- * @type {Record<number, string>}
- * @property {string} 401 - Unauthorized. Check the token and try again.
- * @property {string} 403 - Forbidden. Check the permissions and try again.
- * @property {string} 404 - Not Found. Check the URL and try again.
- * @property {string} 500 - Internal Server Error. Try again later.
- * @property {string} 502 - Bad Gateway. Try again later.
- * @property {string} 503 - Service Unavailable. Try again later.
- */
-const ErrorMessages = {
-    401: 'Unauthorized. Check the token and try again.',
-    403: 'Forbidden. Check the permissions and try again.',
-    404: 'Not Found. Check the URL and try again.',
-    500: 'Internal Server Error. Try again later.',
-    502: 'Bad Gateway. Try again later.',
-    503: 'Service Unavailable. Try again later.'
-};
-
 const DEFAULT_PAGE_CONTENTLETS_CONTENT = `
           publishDate
           inode
@@ -1314,11 +1545,14 @@ function buildQuery(queryData) {
 /**
  * Filters response data to include only specified keys.
  *
- * @param {Record<string, string>} responseData - Original response data object
+ * @param {Record<string, unknown> | undefined} responseData - Original response data object
  * @param {string[]} keys - Array of keys to extract from the response data
- * @returns {Record<string, string>} New object containing only the specified keys
+ * @returns {Record<string, unknown> | undefined} New object containing only the specified keys
  */
-function mapResponseData(responseData, keys) {
+function mapContentResponse(responseData, keys) {
+    if (!responseData) {
+        return undefined;
+    }
     return keys.reduce((accumulator, key) => {
         if (responseData[key] !== undefined) {
             accumulator[key] = responseData[key];
@@ -1332,25 +1566,19 @@ function mapResponseData(responseData, keys) {
  * @param {Object} options - Options for the fetch request
  * @param {string} options.body - GraphQL query string
  * @param {Record<string, string>} options.headers - HTTP headers for the request
- * @returns {Promise<any>} Parsed JSON response from the GraphQL API
- * @throws {Error} If the HTTP response is not successful
+ * @param {DotHttpClient} options.httpClient - HTTP client for making requests
+ * @returns {Promise<DotGraphQLApiResponse>} Parsed JSON response from the GraphQL API
+ * @throws {DotHttpError} If the HTTP request fails (non-2xx status or network error)
  */
-async function fetchGraphQL({ baseURL, body, headers }) {
+async function fetchGraphQL({ baseURL, body, headers, httpClient }) {
     const url = new URL(baseURL);
     url.pathname = '/api/v1/graphql';
-    const response = await fetch(url.toString(), {
+    // httpClient.request throws DotHttpError on failure, so we just return the response directly
+    return await httpClient.request(url.toString(), {
         method: 'POST',
         body,
         headers
     });
-    if (!response.ok) {
-        const error = {
-            status: response.status,
-            message: ErrorMessages[response.status] || response.statusText
-        };
-        throw error;
-    }
-    return await response.json();
 }
 
 /**
@@ -1362,7 +1590,8 @@ class PageClient {
      * Creates a new PageClient instance.
      *
      * @param {DotCMSClientConfig} config - Configuration options for the DotCMS client
-     * @param {RequestOptions} requestOptions - Options for fetch requests including authorization headers
+     * @param {DotRequestOptions} requestOptions - Options for fetch requests including authorization headers
+     * @param {DotHttpClient} httpClient - HTTP client for making requests
      * @example
      * ```typescript
      * const pageClient = new PageClient(
@@ -1375,14 +1604,16 @@ class PageClient {
      *     headers: {
      *       Authorization: 'Bearer your-auth-token'
      *     }
-     *   }
+     *   },
+     *   httpClient
      * );
      * ```
      */
-    constructor(config, requestOptions) {
+    constructor(config, requestOptions, httpClient) {
         this.requestOptions = requestOptions;
         this.siteId = config.siteId || '';
         this.dotcmsUrl = config.dotcmsUrl;
+        this.httpClient = httpClient;
     }
     /**
      * Retrieves a page from DotCMS using GraphQL.
@@ -1391,6 +1622,7 @@ class PageClient {
      * @param {DotCMSPageRequestParams} [options] - Options for the request
      * @template T - The type of the page and content, defaults to DotCMSBasicPage and Record<string, unknown> | unknown
      * @returns {Promise<DotCMSComposedPageResponse<T>>} A Promise that resolves to the page data
+     * @throws {DotErrorPage} - Throws a page-specific error if the request fails or page is not found
      *
      * @example Using GraphQL
      * ```typescript
@@ -1458,21 +1690,26 @@ class PageClient {
         const requestHeaders = this.requestOptions.headers;
         const requestBody = JSON.stringify({ query: completeQuery, variables: requestVariables });
         try {
-            const { data, errors } = await fetchGraphQL({
+            const response = await fetchGraphQL({
                 baseURL: this.dotcmsUrl,
                 body: requestBody,
-                headers: requestHeaders
+                headers: requestHeaders,
+                httpClient: this.httpClient
             });
-            if (errors) {
-                errors.forEach((error) => {
+            // The GQL endpoint can return errors and data, we need to handle both
+            if (response.errors) {
+                response.errors.forEach((error) => {
                     consola.error('[DotCMS GraphQL Error]: ', error.message);
                 });
             }
-            const pageResponse = graphqlToPageEntity(data);
+            const pageResponse = graphqlToPageEntity(response.data.page);
             if (!pageResponse) {
-                throw new Error('No page data found');
+                throw new DotErrorPage(`Page ${url} not found. Check the page URL and permissions.`, undefined, {
+                    query: completeQuery,
+                    variables: requestVariables
+                });
             }
-            const contentResponse = mapResponseData(data, Object.keys(content));
+            const contentResponse = mapContentResponse(response.data, Object.keys(content));
             return {
                 pageAsset: pageResponse,
                 content: contentResponse,
@@ -1483,15 +1720,18 @@ class PageClient {
             };
         }
         catch (error) {
-            const errorMessage = {
-                error,
-                message: 'Failed to retrieve page data',
-                graphql: {
+            // Handle DotHttpError instances from httpClient.request
+            if (error instanceof DotHttpError) {
+                throw new DotErrorPage(`Page request failed for URL '${url}': ${error.message}`, error, {
                     query: completeQuery,
                     variables: requestVariables
-                }
-            };
-            throw errorMessage;
+                });
+            }
+            // Handle other errors (GraphQL errors, validation errors, etc.)
+            throw new DotErrorPage(`Page request failed for URL '${url}': ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, {
+                query: completeQuery,
+                variables: requestVariables
+            });
         }
     }
 }
@@ -1532,11 +1772,12 @@ class DotCMSClient {
      */
     constructor(config = defaultConfig) {
         this.config = config;
+        this.httpClient = config.httpClient || new FetchHttpClient();
         this.requestOptions = this.createAuthenticatedRequestOptions(this.config);
-        // Initialize clients
-        this.page = new PageClient(this.config, this.requestOptions);
-        this.nav = new NavigationClient(this.config, this.requestOptions);
-        this.content = new Content(this.requestOptions, this.config.dotcmsUrl);
+        // Initialize clients with httpClient
+        this.page = new PageClient(this.config, this.requestOptions, this.httpClient);
+        this.nav = new NavigationClient(this.config, this.requestOptions, this.httpClient);
+        this.content = new Content(this.config, this.requestOptions, this.httpClient);
     }
     /**
      * Creates request options with authentication headers.