@dotcms/client 26.9.23-2 → 26.9.24-1-next.2772

package/index.cjs.js

@@ -4,7 +4,7 @@ var consola = require('consola');
 var types = require('@dotcms/types');
 var internal = require('./internal.cjs.js');
 
-const SDK_VERSION = "26.9.23-2";
+const SDK_VERSION = "26.9.24-1-next.2772";
 
 const DOTCMS_VERSION_HEADER = 'x-dotcms-version';
 const DOTCMS_MIN_SDK_HEADER = 'x-dotcms-min-sdk';
@@ -93,25 +93,23 @@ const checkSdkCompatibility = (headers, ownVersion) => {
  *
  * 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
+ * - JSON response parsing
  * - HTTP error response parsing and conversion to DotHttpError
  * - Network error handling and wrapping
- * - Content-Type detection for proper response handling
+ * - Diagnosing misconfiguration: a response in a format other than JSON, or a request
+ *   that was redirected to another origin, is named as such in the error message
+ *
+ * Every SDK caller talks to a dotCMS JSON endpoint, so a successful response with a
+ * non-JSON content type is rejected rather than returned.
  *
  * @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 {
@@ -122,12 +120,13 @@ class FetchHttpClient extends types.BaseHttpClient {
      * 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.
+     * @template T - The parsed JSON body 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.
+     * @returns Promise that resolves with the parsed JSON body, or the Response object when the
+     *          response carries no content type at all.
      * @throws {DotHttpError} - Throws DotHttpError for HTTP errors (4xx/5xx status codes).
+     * @throws {DotHttpError} - Throws DotHttpError (status 502) for a successful response whose content type is not JSON.
      * @throws {DotHttpError} - Throws DotHttpError for network errors (connection issues, timeouts).
      *
      * @example
@@ -144,11 +143,6 @@ class FetchHttpClient extends types.BaseHttpClient {
      *   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) {
@@ -160,35 +154,62 @@ class FetchHttpClient extends types.BaseHttpClient {
             // e.g. an older server) and never throws, so this can't affect the actual
             // request/response handling below.
             checkSdkCompatibility(response.headers, SDK_VERSION);
+            const contentType = response.headers.get('content-type');
+            // application/json and the structured-syntax variants (problem+json,
+            // graphql-response+json, ...), in any case.
+            const isJson = /^application\/([\w.-]+\+)?json\b/i.test(contentType ?? '');
             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();
-                    }
+                    errorBody = isJson ? await response.json() : 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);
+                // The status alone hides the cause, so name what else went wrong: the redirect
+                // first (it is usually the root cause), then the unexpected format.
+                const hints = [
+                    describeCrossOriginRedirect(url, response),
+                    contentType && !isJson
+                        ? `The response was '${contentType}', not JSON, so it may not have come from the dotCMS API: a proxy, a load balancer or another server can answer this way.`
+                        : undefined
+                ].filter(Boolean);
+                const status = `HTTP ${response.status}: ${response.statusText}`;
+                const message = hints.length ? `${status}. ${hints.join(' ')}` : status;
+                throw this.createHttpError(response.status, response.statusText, toPlainHeaders(response.headers), errorBody, message);
             }
-            // Handle different response types
-            const contentType = response.headers.get('content-type');
-            if (contentType?.includes('application/json')) {
+            if (isJson) {
                 return response.json();
             }
-            // For non-JSON responses, return the response object
-            // Sub-clients can handle specific response types as needed
+            // Every SDK caller talks to a JSON endpoint, so a successful answer in another
+            // format means something other than the dotCMS API answered (a login page, a
+            // proxy, the wrong port). Returning the Response would only move the failure
+            // downstream.
+            if (contentType) {
+                let body;
+                try {
+                    body = await response.text();
+                }
+                catch {
+                    body = undefined;
+                }
+                const crossOriginRedirect = describeCrossOriginRedirect(url, response);
+                const sameOriginRedirect = !crossOriginRedirect && response.redirected && response.url
+                    ? ` after a redirect to '${response.url}'`
+                    : '';
+                const message = [
+                    `Expected a JSON response from '${url}' but received '${contentType}' (HTTP ${response.status})${sameOriginRedirect}, which is not JSON. dotCMS API endpoints answer in JSON, so something other than the dotCMS API answered (a login page, a proxy or another server): check that dotcmsUrl points at your dotCMS instance.`,
+                    crossOriginRedirect
+                ]
+                    .filter(Boolean)
+                    .join(' ');
+                // Reported as 502 Bad Gateway, not the real 2xx: callers forward error.status
+                // as their own response status, and an error must never read as success. The
+                // real status is in the message and the body in data.
+                throw this.createHttpError(502, 'Bad Gateway', toPlainHeaders(response.headers), body, message);
+            }
+            // No content type at all: hand back the Response untouched.
             return response;
         }
         catch (error) {
@@ -200,6 +221,46 @@ class FetchHttpClient extends types.BaseHttpClient {
         }
     }
 }
+/**
+ * Explains a redirect that took the request to a different origin, or returns undefined
+ * when there was no redirect, it stayed on the same origin, or either URL can't be parsed.
+ *
+ * A changed origin almost always means `dotcmsUrl` names a scheme or host the server moves
+ * away from (e.g. `http://` answered with a 301 to `https://`), and the hop itself breaks the
+ * request: fetch drops the Authorization header on a cross-origin redirect, and a 301, 302 or
+ * 303 turns a POST into a GET without its body.
+ *
+ * @param requestUrl - The URL the SDK asked for.
+ * @param response - The response fetch ended on after following redirects.
+ * @returns A sentence naming both URLs and `dotcmsUrl`, or undefined.
+ */
+function describeCrossOriginRedirect(requestUrl, response) {
+    if (!response.redirected || !response.url) {
+        return undefined;
+    }
+    try {
+        if (new URL(requestUrl).origin === new URL(response.url).origin) {
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return `The request to '${requestUrl}' was redirected to '${response.url}', a different origin. Check that dotcmsUrl uses the exact scheme and host your dotCMS instance serves: a cross-origin redirect drops the Authorization header, and a 301, 302 or 303 turns a POST into a GET without its body.`;
+}
+/**
+ * Copies fetch Headers into a plain object, the shape createHttpError expects.
+ *
+ * @param headers - The response headers.
+ * @returns The headers keyed by lower-case name.
+ */
+function toPlainHeaders(headers) {
+    const plain = {};
+    headers.forEach((value, key) => {
+        plain[key] = value;
+    });
+    return plain;
+}
 
 /*! *****************************************************************************
 Copyright (c) Microsoft Corporation.

package/index.esm.js

@@ -2,7 +2,7 @@ import { consola } from 'consola';
 import { BaseHttpClient, DISTANCE_FUNCTIONS, DotHttpError, DotErrorAISearch, DotErrorContent, DotErrorNavigation, UVE_MODE, DotErrorPage } from '@dotcms/types';
 import { graphqlToPageEntity } from './internal.esm.js';
 
-const SDK_VERSION = "26.9.23-2";
+const SDK_VERSION = "26.9.24-1-next.2772";
 
 const DOTCMS_VERSION_HEADER = 'x-dotcms-version';
 const DOTCMS_MIN_SDK_HEADER = 'x-dotcms-min-sdk';
@@ -91,25 +91,23 @@ const checkSdkCompatibility = (headers, ownVersion) => {
  *
  * 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
+ * - JSON response parsing
  * - HTTP error response parsing and conversion to DotHttpError
  * - Network error handling and wrapping
- * - Content-Type detection for proper response handling
+ * - Diagnosing misconfiguration: a response in a format other than JSON, or a request
+ *   that was redirected to another origin, is named as such in the error message
+ *
+ * Every SDK caller talks to a dotCMS JSON endpoint, so a successful response with a
+ * non-JSON content type is rejected rather than returned.
  *
  * @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 {
@@ -120,12 +118,13 @@ class FetchHttpClient extends BaseHttpClient {
      * 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.
+     * @template T - The parsed JSON body 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.
+     * @returns Promise that resolves with the parsed JSON body, or the Response object when the
+     *          response carries no content type at all.
      * @throws {DotHttpError} - Throws DotHttpError for HTTP errors (4xx/5xx status codes).
+     * @throws {DotHttpError} - Throws DotHttpError (status 502) for a successful response whose content type is not JSON.
      * @throws {DotHttpError} - Throws DotHttpError for network errors (connection issues, timeouts).
      *
      * @example
@@ -142,11 +141,6 @@ class FetchHttpClient extends BaseHttpClient {
      *   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) {
@@ -158,35 +152,62 @@ class FetchHttpClient extends BaseHttpClient {
             // e.g. an older server) and never throws, so this can't affect the actual
             // request/response handling below.
             checkSdkCompatibility(response.headers, SDK_VERSION);
+            const contentType = response.headers.get('content-type');
+            // application/json and the structured-syntax variants (problem+json,
+            // graphql-response+json, ...), in any case.
+            const isJson = /^application\/([\w.-]+\+)?json\b/i.test(contentType ?? '');
             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();
-                    }
+                    errorBody = isJson ? await response.json() : 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);
+                // The status alone hides the cause, so name what else went wrong: the redirect
+                // first (it is usually the root cause), then the unexpected format.
+                const hints = [
+                    describeCrossOriginRedirect(url, response),
+                    contentType && !isJson
+                        ? `The response was '${contentType}', not JSON, so it may not have come from the dotCMS API: a proxy, a load balancer or another server can answer this way.`
+                        : undefined
+                ].filter(Boolean);
+                const status = `HTTP ${response.status}: ${response.statusText}`;
+                const message = hints.length ? `${status}. ${hints.join(' ')}` : status;
+                throw this.createHttpError(response.status, response.statusText, toPlainHeaders(response.headers), errorBody, message);
             }
-            // Handle different response types
-            const contentType = response.headers.get('content-type');
-            if (contentType?.includes('application/json')) {
+            if (isJson) {
                 return response.json();
             }
-            // For non-JSON responses, return the response object
-            // Sub-clients can handle specific response types as needed
+            // Every SDK caller talks to a JSON endpoint, so a successful answer in another
+            // format means something other than the dotCMS API answered (a login page, a
+            // proxy, the wrong port). Returning the Response would only move the failure
+            // downstream.
+            if (contentType) {
+                let body;
+                try {
+                    body = await response.text();
+                }
+                catch {
+                    body = undefined;
+                }
+                const crossOriginRedirect = describeCrossOriginRedirect(url, response);
+                const sameOriginRedirect = !crossOriginRedirect && response.redirected && response.url
+                    ? ` after a redirect to '${response.url}'`
+                    : '';
+                const message = [
+                    `Expected a JSON response from '${url}' but received '${contentType}' (HTTP ${response.status})${sameOriginRedirect}, which is not JSON. dotCMS API endpoints answer in JSON, so something other than the dotCMS API answered (a login page, a proxy or another server): check that dotcmsUrl points at your dotCMS instance.`,
+                    crossOriginRedirect
+                ]
+                    .filter(Boolean)
+                    .join(' ');
+                // Reported as 502 Bad Gateway, not the real 2xx: callers forward error.status
+                // as their own response status, and an error must never read as success. The
+                // real status is in the message and the body in data.
+                throw this.createHttpError(502, 'Bad Gateway', toPlainHeaders(response.headers), body, message);
+            }
+            // No content type at all: hand back the Response untouched.
             return response;
         }
         catch (error) {
@@ -198,6 +219,46 @@ class FetchHttpClient extends BaseHttpClient {
         }
     }
 }
+/**
+ * Explains a redirect that took the request to a different origin, or returns undefined
+ * when there was no redirect, it stayed on the same origin, or either URL can't be parsed.
+ *
+ * A changed origin almost always means `dotcmsUrl` names a scheme or host the server moves
+ * away from (e.g. `http://` answered with a 301 to `https://`), and the hop itself breaks the
+ * request: fetch drops the Authorization header on a cross-origin redirect, and a 301, 302 or
+ * 303 turns a POST into a GET without its body.
+ *
+ * @param requestUrl - The URL the SDK asked for.
+ * @param response - The response fetch ended on after following redirects.
+ * @returns A sentence naming both URLs and `dotcmsUrl`, or undefined.
+ */
+function describeCrossOriginRedirect(requestUrl, response) {
+    if (!response.redirected || !response.url) {
+        return undefined;
+    }
+    try {
+        if (new URL(requestUrl).origin === new URL(response.url).origin) {
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return `The request to '${requestUrl}' was redirected to '${response.url}', a different origin. Check that dotcmsUrl uses the exact scheme and host your dotCMS instance serves: a cross-origin redirect drops the Authorization header, and a 301, 302 or 303 turns a POST into a GET without its body.`;
+}
+/**
+ * Copies fetch Headers into a plain object, the shape createHttpError expects.
+ *
+ * @param headers - The response headers.
+ * @returns The headers keyed by lower-case name.
+ */
+function toPlainHeaders(headers) {
+    const plain = {};
+    headers.forEach((value, key) => {
+        plain[key] = value;
+    });
+    return plain;
+}
 
 /*! *****************************************************************************
 Copyright (c) Microsoft Corporation.

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@dotcms/client",
-  "version": "26.9.23-2",
+  "version": "26.9.24-1-next.2772",
   "description": "Official JavaScript library for interacting with DotCMS REST APIs.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dotCMS/core.git#main"
   },
   "peerDependencies": {
-    "@dotcms/types": "26.9.23-2"
+    "@dotcms/types": "26.9.24-1-next.2772"
   },
   "dependencies": {
     "consola": "^3.4.2"
   },
   "devDependencies": {
-    "@dotcms/types": "26.9.23-2"
+    "@dotcms/types": "26.9.24-1-next.2772"
   },
   "keywords": [
     "dotCMS",

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

@@ -4,25 +4,23 @@ import { BaseHttpClient, DotRequestOptions } from '@dotcms/types';
  *
  * 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
+ * - JSON response parsing
  * - HTTP error response parsing and conversion to DotHttpError
  * - Network error handling and wrapping
- * - Content-Type detection for proper response handling
+ * - Diagnosing misconfiguration: a response in a format other than JSON, or a request
+ *   that was redirected to another origin, is named as such in the error message
+ *
+ * Every SDK caller talks to a dotCMS JSON endpoint, so a successful response with a
+ * non-JSON content type is rejected rather than returned.
  *
  * @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 {
@@ -33,12 +31,13 @@ export declare class FetchHttpClient extends BaseHttpClient {
      * 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.
+     * @template T - The parsed JSON body 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.
+     * @returns Promise that resolves with the parsed JSON body, or the Response object when the
+     *          response carries no content type at all.
      * @throws {DotHttpError} - Throws DotHttpError for HTTP errors (4xx/5xx status codes).
+     * @throws {DotHttpError} - Throws DotHttpError (status 502) for a successful response whose content type is not JSON.
      * @throws {DotHttpError} - Throws DotHttpError for network errors (connection issues, timeouts).
      *
      * @example
@@ -55,11 +54,6 @@ export declare class FetchHttpClient extends BaseHttpClient {
      *   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>;