@dotcms/client 1.0.6 → 1.1.1

package/internal.cjs.js

@@ -12,10 +12,9 @@
  * const pageEntity = graphqlToPageEntity(graphQLPageResponse);
  * ```
  */
-const graphqlToPageEntity = (graphQLPageResponse) => {
-    const { page } = graphQLPageResponse;
+const graphqlToPageEntity = (page) => {
     // If there is no page, return null
-    if (!page) {
+    if (!page || (typeof page === 'object' && Object.keys(page).length === 0)) {
         return null;
     }
     const { layout, template, containers, urlContentMap, viewAs, host, vanityUrl, runningExperimentId, _map, ...pageAsset } = page;
@@ -55,7 +54,7 @@ const graphqlToPageEntity = (graphQLPageResponse) => {
 const parseContainers = (containers = []) => {
     return containers.reduce((acc, container) => {
         const { path, identifier, containerStructures, containerContentlets, ...rest } = container;
-        const key = (path || identifier);
+        const key = path || identifier;
         acc[key] = {
             containerStructures,
             container: {

package/internal.esm.js

@@ -10,10 +10,9 @@
  * const pageEntity = graphqlToPageEntity(graphQLPageResponse);
  * ```
  */
-const graphqlToPageEntity = (graphQLPageResponse) => {
-    const { page } = graphQLPageResponse;
+const graphqlToPageEntity = (page) => {
     // If there is no page, return null
-    if (!page) {
+    if (!page || (typeof page === 'object' && Object.keys(page).length === 0)) {
         return null;
     }
     const { layout, template, containers, urlContentMap, viewAs, host, vanityUrl, runningExperimentId, _map, ...pageAsset } = page;
@@ -53,7 +52,7 @@ const graphqlToPageEntity = (graphQLPageResponse) => {
 const parseContainers = (containers = []) => {
     return containers.reduce((acc, container) => {
         const { path, identifier, containerStructures, containerContentlets, ...rest } = container;
-        const key = (path || identifier);
+        const key = path || identifier;
         acc[key] = {
             containerStructures,
             container: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/client",
-  "version": "1.0.6",
+  "version": "1.1.1",
   "description": "Official JavaScript library for interacting with DotCMS REST APIs.",
   "repository": {
     "type": "git",

package/src/lib/client/adapters/fetch-http-client.d.ts

@@ -0,0 +1,66 @@
+import { BaseHttpClient, DotRequestOptions } from '@dotcms/types';
+/**
+ * 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'
+ * });
+ * ```
+ */
+export declare 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'
+     * });
+     * ```
+     */
+    request<T = unknown>(url: string, options?: DotRequestOptions): Promise<T>;
+}

package/src/lib/client/client.d.ts

@@ -9,6 +9,7 @@ import { PageClient } from './page/page-api';
 declare class DotCMSClient {
     private config;
     private requestOptions;
+    private httpClient;
     /**
      * Client for content-related operations.
      */

package/src/lib/client/content/builders/collection/collection.d.ts

@@ -1,5 +1,5 @@
-import { GetCollectionResponse, BuildQuery, SortBy, GetCollectionError, OnFullfilled, OnRejected } from '../../shared/types';
-export type ClientOptions = Omit<RequestInit, 'body' | 'method'>;
+import { DotHttpClient, DotRequestOptions, DotCMSClientConfig, DotErrorContent } from '@dotcms/types';
+import { GetCollectionResponse, BuildQuery, SortBy, OnFullfilled, OnRejected } from '../../shared/types';
 /**
  * Creates a Builder to filter and fetch content from the content API for a specific content type.
  *
@@ -12,11 +12,12 @@ export declare class CollectionBuilder<T = unknown> {
     /**
      * 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: ClientOptions, serverUrl: string, contentType: string);
+    constructor(requestOptions: DotRequestOptions, config: DotCMSClientConfig, contentType: string, httpClient: DotHttpClient);
     /**
      * Returns the sort query in the format: field order, field order, ...
      *
@@ -41,6 +42,14 @@ export declare class CollectionBuilder<T = unknown> {
      * @memberof CollectionBuilder
      */
     private get url();
+    /**
+     * Returns the site ID from the configuration.
+     *
+     * @readonly
+     * @private
+     * @memberof CollectionBuilder
+     */
+    private get siteId();
     /**
      * Returns the current query built.
      *
@@ -202,10 +211,10 @@ export declare class CollectionBuilder<T = unknown> {
      *
      * @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?: OnFullfilled<T>, onrejected?: OnRejected): Promise<GetCollectionResponse<T> | GetCollectionError>;
+    then(onfulfilled?: OnFullfilled<T>, onrejected?: OnRejected): Promise<GetCollectionResponse<T> | DotErrorContent>;
     /**
      * Formats the response to the desired format.
      *
@@ -219,8 +228,45 @@ export declare class CollectionBuilder<T = unknown> {
      * 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
      */
     private fetch;
+    /**
+     * 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)
+     */
+    private getFinalQuery;
 }

package/src/lib/client/content/content-api.d.ts

@@ -1,4 +1,4 @@
-import { RequestOptions } from '@dotcms/types';
+import { DotRequestOptions, DotHttpClient, DotCMSClientConfig } from '@dotcms/types';
 import { CollectionBuilder } from './builders/collection/collection';
 /**
  * Creates a builder to filter and fetch a collection of content items.
@@ -53,10 +53,11 @@ export declare class Content {
     #private;
     /**
      * 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: RequestOptions, serverUrl: string);
+    constructor(config: DotCMSClientConfig, requestOptions: DotRequestOptions, httpClient: DotHttpClient);
     /**
      * Takes a content type and returns a builder to filter and fetch the collection.
      * @param {string} contentType - The content type to get the collection.

package/src/lib/client/content/shared/types.d.ts

@@ -1,4 +1,4 @@
-import { Contentlet } from '@dotcms/types';
+import { Contentlet, DotErrorContent } from '@dotcms/types';
 import { Equals } from '../builders/query/lucene-syntax';
 import { QueryBuilder } from '../builders/query/query';
 /**
@@ -28,17 +28,17 @@ export type BuildQuery = (qb: QueryBuilder) => Equals;
  * @template T - The type of the response.
  * @callback OnFullfilled
  * @param {GetCollectionResponse<T>} value - The response value.
- * @returns {GetCollectionResponse<T> | PromiseLike<GetCollectionResponse<T>> | void} The processed response or a promise.
+ * @returns {GetCollectionResponse<T> | PromiseLike<GetCollectionResponse<T>>} The processed response or a promise.
  */
-export type OnFullfilled<T> = ((value: GetCollectionResponse<T>) => GetCollectionResponse<T> | PromiseLike<GetCollectionResponse<T>> | void) | undefined | null;
+export type OnFullfilled<T> = ((value: GetCollectionResponse<T>) => GetCollectionResponse<T> | PromiseLike<GetCollectionResponse<T>>) | undefined | null;
 /**
  * Callback for a rejected promise.
  *
  * @callback OnRejected
- * @param {GetCollectionError} error - The error object.
- * @returns {GetCollectionError | PromiseLike<GetCollectionError> | void} The processed error or a promise.
+ * @param {DotErrorContent} error - The content error object.
+ * @returns {DotErrorContent | PromiseLike<DotErrorContent>} The processed error or a promise.
  */
-export type OnRejected = ((error: GetCollectionError) => GetCollectionError | PromiseLike<GetCollectionError> | void) | undefined | null;
+export type OnRejected = ((error: DotErrorContent) => DotErrorContent | PromiseLike<DotErrorContent>) | undefined | null;
 /**
  * Response of the get collection method.
  *
@@ -85,13 +85,3 @@ export interface GetCollectionRawResponse<T> {
         resultsSize: number;
     };
 }
-/**
- * Error object for the get collection method.
- */
-export interface GetCollectionError {
-    /**
-     * The status code of the error.
-     */
-    status: number;
-    [key: string]: unknown;
-}

package/src/lib/client/content/shared/utils.d.ts

@@ -18,3 +18,39 @@
  * @returns {string} The sanitized query string.
  */
 export declare function sanitizeQueryForContentType(query: string, contentType: string): string;
+/**
+ * @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
+ */
+export declare function shouldAddSiteIdConstraint(query: string, siteId: string | number | null | undefined): boolean;

package/src/lib/client/navigation/navigation-api.d.ts

@@ -1,13 +1,15 @@
-import { DotCMSClientConfig, DotCMSNavigationRequestParams, RequestOptions, DotCMSNavigationItem } from '@dotcms/types';
+import { DotCMSClientConfig, DotCMSNavigationRequestParams, DotRequestOptions, DotCMSNavigationItem, DotHttpClient } from '@dotcms/types';
 export declare class NavigationClient {
     private requestOptions;
     private BASE_URL;
-    constructor(config: DotCMSClientConfig, requestOptions: RequestOptions);
+    private httpClient;
+    constructor(config: DotCMSClientConfig, requestOptions: DotRequestOptions, httpClient: DotHttpClient);
     /**
      * 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.
      */
     get(path: string, params?: DotCMSNavigationRequestParams): Promise<DotCMSNavigationItem[]>;
     private mapToBackendParams;

package/src/lib/client/page/page-api.d.ts

@@ -1,4 +1,4 @@
-import { DotCMSClientConfig, DotCMSComposedPageResponse, DotCMSExtendedPageResponse, DotCMSPageResponse, DotCMSPageRequestParams, RequestOptions } from '@dotcms/types';
+import { DotCMSClientConfig, DotCMSPageRequestParams, DotCMSPageResponse, DotCMSExtendedPageResponse, DotCMSComposedPageResponse, DotHttpClient, DotRequestOptions } from '@dotcms/types';
 /**
  * Client for interacting with the DotCMS Page API.
  * Provides methods to retrieve and manipulate pages.
@@ -19,11 +19,17 @@ export declare class PageClient {
      * @private
      */
     private dotcmsUrl;
+    /**
+     * HTTP client for making requests.
+     * @private
+     */
+    private httpClient;
     /**
      * 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(
@@ -36,11 +42,12 @@ export declare class PageClient {
      *     headers: {
      *       Authorization: 'Bearer your-auth-token'
      *     }
-     *   }
+     *   },
+     *   httpClient
      * );
      * ```
      */
-    constructor(config: DotCMSClientConfig, requestOptions: RequestOptions);
+    constructor(config: DotCMSClientConfig, requestOptions: DotRequestOptions, httpClient: DotHttpClient);
     /**
      * Retrieves a page from DotCMS using GraphQL.
      *
@@ -48,6 +55,7 @@ export declare 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

package/src/lib/client/page/utils.d.ts

@@ -1,3 +1,4 @@
+import { DotHttpClient, DotGraphQLApiResponse } from '@dotcms/types';
 /**
  * Builds a GraphQL query for retrieving page content from DotCMS.
  *
@@ -20,22 +21,24 @@ export declare function buildQuery(queryData: Record<string, string>): string;
 /**
  * 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
  */
-export declare function mapResponseData(responseData: Record<string, string>, keys: string[]): Record<string, string>;
+export declare function mapContentResponse(responseData: Record<string, unknown> | undefined, keys: string[]): Record<string, unknown> | undefined;
 /**
  * Executes a GraphQL query against the DotCMS API.
  *
  * @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)
  */
-export declare function fetchGraphQL({ baseURL, body, headers }: {
+export declare function fetchGraphQL({ baseURL, body, headers, httpClient }: {
     baseURL: string;
     body: string;
-    headers: Record<string, string>;
-}): Promise<any>;
+    headers?: HeadersInit;
+    httpClient: DotHttpClient;
+}): Promise<DotGraphQLApiResponse>;

package/src/lib/utils/graphql/transforms.d.ts

@@ -1,4 +1,4 @@
-import { DotCMSGraphQLPageResponse, DotCMSPageAsset } from '@dotcms/types';
+import { DotCMSGraphQLPage, DotCMSPageAsset } from '@dotcms/types';
 /**
  * Transforms a GraphQL Page response to a Page Entity.
  *
@@ -10,4 +10,4 @@ import { DotCMSGraphQLPageResponse, DotCMSPageAsset } from '@dotcms/types';
  * const pageEntity = graphqlToPageEntity(graphQLPageResponse);
  * ```
  */
-export declare const graphqlToPageEntity: (graphQLPageResponse: DotCMSGraphQLPageResponse) => DotCMSPageAsset | null;
+export declare const graphqlToPageEntity: (page: DotCMSGraphQLPage) => DotCMSPageAsset | null;