@dotcms/client 1.0.6-next.3 → 1.0.6-next.4

package/index.cjs.js

@@ -1,8 +1,117 @@
 'use strict';
 
 var consola = require('consola');
+var types = require('@dotcms/types');
 var internal = require('./internal.cjs.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 types.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.
 
@@ -637,7 +746,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_requestOptions, _CollectionBuilder_config;
+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.
  *
@@ -651,9 +760,10 @@ class CollectionBuilder {
      * @param {ClientOptions} requestOptions Options for the client request.
      * @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, config, contentType) {
+    constructor(requestOptions, config, contentType, httpClient) {
         _CollectionBuilder_page.set(this, 1);
         _CollectionBuilder_limit.set(this, 10);
         _CollectionBuilder_depth.set(this, 0);
@@ -666,10 +776,13 @@ class CollectionBuilder {
         _CollectionBuilder_languageId.set(this, 1);
         _CollectionBuilder_draft.set(this, false);
         _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_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");
     }
@@ -896,26 +1009,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 types.DotHttpError) {
+                contentError = new types.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 types.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.
@@ -945,14 +1068,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.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: {
@@ -1024,9 +1148,9 @@ class CollectionBuilder {
         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_requestOptions = new WeakMap(), _CollectionBuilder_config = 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_config;
+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.
@@ -1079,14 +1203,17 @@ var _Content_requestOptions, _Content_config;
 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(config, requestOptions) {
+    constructor(config, requestOptions, httpClient) {
         _Content_requestOptions.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_config, config, "f");
+        __classPrivateFieldSet(this, _Content_httpClient, httpClient, "f");
     }
     /**
      * Takes a content type and returns a builder to filter and fetch the collection.
@@ -1154,35 +1281,44 @@ class Content {
      *
      */
     getCollection(contentType) {
-        return new CollectionBuilder(__classPrivateFieldGet(this, _Content_requestOptions, "f"), __classPrivateFieldGet(this, _Content_config, "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_config = 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 types.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 types.DotHttpError) {
+                throw new types.DotErrorNavigation(`Navigation API failed for path '${parsedPath}': ${error.message}`, parsedPath, error);
+            }
+            // Handle other errors (validation, network, etc.)
+            throw new types.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 = {};
@@ -1196,26 +1332,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
@@ -1431,11 +1547,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];
@@ -1449,25 +1568,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();
 }
 
 /**
@@ -1479,7 +1592,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(
@@ -1492,14 +1606,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.
@@ -1508,6 +1624,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
@@ -1575,21 +1692,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.consola.error('[DotCMS GraphQL Error]: ', error.message);
                 });
             }
-            const pageResponse = internal.graphqlToPageEntity(data);
+            const pageResponse = internal.graphqlToPageEntity(response.data.page);
             if (!pageResponse) {
-                throw new Error('No page data found');
+                throw new types.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,
@@ -1600,15 +1722,18 @@ class PageClient {
             };
         }
         catch (error) {
-            const errorMessage = {
-                error,
-                message: 'Failed to retrieve page data',
-                graphql: {
+            // Handle DotHttpError instances from httpClient.request
+            if (error instanceof types.DotHttpError) {
+                throw new types.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 types.DotErrorPage(`Page request failed for URL '${url}': ${error instanceof Error ? error.message : 'Unknown error'}`, undefined, {
+                query: completeQuery,
+                variables: requestVariables
+            });
         }
     }
 }
@@ -1649,11 +1774,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.config, this.requestOptions);
+        // 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.