@dotcms/client 26.9.29-1 → 26.9.29-1-next.2806

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.29-1";
+const SDK_VERSION = "26.9.29-1-next.2806";
 
 const DOTCMS_VERSION_HEADER = 'x-dotcms-version';
 const DOTCMS_MIN_SDK_HEADER = 'x-dotcms-min-sdk';
@@ -96,8 +96,9 @@ const checkSdkCompatibility = (headers, ownVersion) => {
  * - JSON response parsing
  * - HTTP error response parsing and conversion to DotHttpError
  * - Network error handling and wrapping
- * - 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
+ * - Diagnosing misconfiguration: a response in a format other than JSON, a request that was
+ *   redirected to another origin, or one that got no response at all is named as such in the
+ *   error message, leading with the dotcmsUrl fix where the SDK can tell what it is
  *
  * Every SDK caller talks to a dotCMS JSON endpoint, so a successful response with a
  * non-JSON content type is rejected rather than returned.
@@ -167,16 +168,14 @@ class FetchHttpClient extends types.BaseHttpClient {
                 catch {
                     errorBody = response.statusText;
                 }
-                // 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);
+                // The status alone hides the cause, so name what else went wrong. A redirect to
+                // another origin explains the failure on its own (and any HTML the far side
+                // answered with), so it replaces the status line; the format is the fallback.
                 const status = `HTTP ${response.status}: ${response.statusText}`;
-                const message = hints.length ? `${status}. ${hints.join(' ')}` : status;
+                const message = describeCrossOriginRedirect(url, response) ??
+                    (contentType && !isJson
+                        ? `${status}. 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.`
+                        : status);
                 throw this.createHttpError(response.status, response.statusText, toPlainHeaders(response.headers), errorBody, message);
             }
             if (isJson) {
@@ -194,16 +193,13 @@ class FetchHttpClient extends types.BaseHttpClient {
                 catch {
                     body = undefined;
                 }
-                const crossOriginRedirect = describeCrossOriginRedirect(url, response);
-                const sameOriginRedirect = !crossOriginRedirect && response.redirected && response.url
+                // A redirect to another origin is the whole story; the format is the only
+                // signal otherwise (a same-origin login page, a proxy's HTML).
+                const sameOriginRedirect = 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(' ');
+                const message = describeCrossOriginRedirect(url, response) ??
+                    `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.`;
                 // 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.
@@ -213,9 +209,12 @@ class FetchHttpClient extends types.BaseHttpClient {
             return response;
         }
         catch (error) {
-            // Handle network errors (fetch throws TypeError for network issues)
-            if (error instanceof TypeError) {
-                throw this.createNetworkError(error);
+            // fetch rejects with a TypeError when no response arrives at all. Match on the name
+            // too: Node's fetch creates it in its own realm, which fails instanceof inside a VM
+            // context (Vitest's vmForks pool, for one).
+            if (error instanceof TypeError ||
+                error?.name === 'TypeError') {
+                throw this.createHttpError(0, 'Network Error', undefined, error, describeNetworkError(url, error));
             }
             throw error;
         }
@@ -230,23 +229,62 @@ class FetchHttpClient extends types.BaseHttpClient {
  * 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.
  *
+ * The message leads with the fix. When only the origin changed (same path and query), the
+ * new origin is the value dotcmsUrl should have. When the path changed too, the far side is
+ * something else (an SSO login page, say), so its origin is not a dotcmsUrl to recommend.
+ *
  * @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.
+ * @returns The fix plus one sentence of why, or undefined.
  */
 function describeCrossOriginRedirect(requestUrl, response) {
     if (!response.redirected || !response.url) {
         return undefined;
     }
+    let from;
+    let to;
     try {
-        if (new URL(requestUrl).origin === new URL(response.url).origin) {
-            return undefined;
-        }
+        from = new URL(requestUrl);
+        to = new URL(response.url);
     }
     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.`;
+    if (from.origin === to.origin) {
+        return undefined;
+    }
+    const fix = from.pathname + from.search === to.pathname + to.search
+        ? `dotcmsUrl is '${from.origin}' but the server redirected to '${to.origin}'. Set dotcmsUrl to '${to.origin}'.`
+        : `dotcmsUrl is '${from.origin}' but the server redirected '${requestUrl}' to '${response.url}'. Set dotcmsUrl to the URL your dotCMS instance answers on directly.`;
+    return `${fix} A redirect to another origin drops the Authorization header and can turn a POST into a GET (HTTP ${response.status} after the redirect).`;
+}
+/**
+ * Explains a request that got no response at all: the full URL, the reason, and where to look.
+ *
+ * Node puts the system error in `cause` (`ENOTFOUND`, `ECONNREFUSED`, a TLS code, ...), so its
+ * code and the host are named. A browser gives only "Failed to fetch" and keeps the reason in
+ * the console, since a CORS rejection, a blocked redirect and a DNS failure all look the same
+ * to the page; the message lists those causes and points there.
+ *
+ * @param url - The URL the SDK asked for.
+ * @param error - The TypeError fetch rejected with.
+ * @returns The message for the network DotHttpError.
+ */
+function describeNetworkError(url, error) {
+    const code = error.cause?.code;
+    let host = url;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        // A relative URL: keep it as given.
+    }
+    const reason = typeof code === 'string' ? `${code} ${host}` : error.message;
+    const summary = `Couldn't reach '${url}' (${reason}).`;
+    if (typeof window !== 'undefined' && typeof window.document !== 'undefined') {
+        return `${summary} Check dotcmsUrl: the scheme may be wrong (the browser blocks a redirect from http to https), the host may not resolve, or dotCMS may not allow this origin (CORS). The browser console shows the exact reason.`;
+    }
+    return `${summary} Check the scheme, host and port in dotcmsUrl, and that dotCMS is reachable at that address.`;
 }
 /**
  * Copies fetch Headers into a plain object, the shape createHttpError expects.

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.29-1";
+const SDK_VERSION = "26.9.29-1-next.2806";
 
 const DOTCMS_VERSION_HEADER = 'x-dotcms-version';
 const DOTCMS_MIN_SDK_HEADER = 'x-dotcms-min-sdk';
@@ -94,8 +94,9 @@ const checkSdkCompatibility = (headers, ownVersion) => {
  * - JSON response parsing
  * - HTTP error response parsing and conversion to DotHttpError
  * - Network error handling and wrapping
- * - 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
+ * - Diagnosing misconfiguration: a response in a format other than JSON, a request that was
+ *   redirected to another origin, or one that got no response at all is named as such in the
+ *   error message, leading with the dotcmsUrl fix where the SDK can tell what it is
  *
  * Every SDK caller talks to a dotCMS JSON endpoint, so a successful response with a
  * non-JSON content type is rejected rather than returned.
@@ -165,16 +166,14 @@ class FetchHttpClient extends BaseHttpClient {
                 catch {
                     errorBody = response.statusText;
                 }
-                // 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);
+                // The status alone hides the cause, so name what else went wrong. A redirect to
+                // another origin explains the failure on its own (and any HTML the far side
+                // answered with), so it replaces the status line; the format is the fallback.
                 const status = `HTTP ${response.status}: ${response.statusText}`;
-                const message = hints.length ? `${status}. ${hints.join(' ')}` : status;
+                const message = describeCrossOriginRedirect(url, response) ??
+                    (contentType && !isJson
+                        ? `${status}. 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.`
+                        : status);
                 throw this.createHttpError(response.status, response.statusText, toPlainHeaders(response.headers), errorBody, message);
             }
             if (isJson) {
@@ -192,16 +191,13 @@ class FetchHttpClient extends BaseHttpClient {
                 catch {
                     body = undefined;
                 }
-                const crossOriginRedirect = describeCrossOriginRedirect(url, response);
-                const sameOriginRedirect = !crossOriginRedirect && response.redirected && response.url
+                // A redirect to another origin is the whole story; the format is the only
+                // signal otherwise (a same-origin login page, a proxy's HTML).
+                const sameOriginRedirect = 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(' ');
+                const message = describeCrossOriginRedirect(url, response) ??
+                    `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.`;
                 // 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.
@@ -211,9 +207,12 @@ class FetchHttpClient extends BaseHttpClient {
             return response;
         }
         catch (error) {
-            // Handle network errors (fetch throws TypeError for network issues)
-            if (error instanceof TypeError) {
-                throw this.createNetworkError(error);
+            // fetch rejects with a TypeError when no response arrives at all. Match on the name
+            // too: Node's fetch creates it in its own realm, which fails instanceof inside a VM
+            // context (Vitest's vmForks pool, for one).
+            if (error instanceof TypeError ||
+                error?.name === 'TypeError') {
+                throw this.createHttpError(0, 'Network Error', undefined, error, describeNetworkError(url, error));
             }
             throw error;
         }
@@ -228,23 +227,62 @@ class FetchHttpClient extends BaseHttpClient {
  * 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.
  *
+ * The message leads with the fix. When only the origin changed (same path and query), the
+ * new origin is the value dotcmsUrl should have. When the path changed too, the far side is
+ * something else (an SSO login page, say), so its origin is not a dotcmsUrl to recommend.
+ *
  * @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.
+ * @returns The fix plus one sentence of why, or undefined.
  */
 function describeCrossOriginRedirect(requestUrl, response) {
     if (!response.redirected || !response.url) {
         return undefined;
     }
+    let from;
+    let to;
     try {
-        if (new URL(requestUrl).origin === new URL(response.url).origin) {
-            return undefined;
-        }
+        from = new URL(requestUrl);
+        to = new URL(response.url);
     }
     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.`;
+    if (from.origin === to.origin) {
+        return undefined;
+    }
+    const fix = from.pathname + from.search === to.pathname + to.search
+        ? `dotcmsUrl is '${from.origin}' but the server redirected to '${to.origin}'. Set dotcmsUrl to '${to.origin}'.`
+        : `dotcmsUrl is '${from.origin}' but the server redirected '${requestUrl}' to '${response.url}'. Set dotcmsUrl to the URL your dotCMS instance answers on directly.`;
+    return `${fix} A redirect to another origin drops the Authorization header and can turn a POST into a GET (HTTP ${response.status} after the redirect).`;
+}
+/**
+ * Explains a request that got no response at all: the full URL, the reason, and where to look.
+ *
+ * Node puts the system error in `cause` (`ENOTFOUND`, `ECONNREFUSED`, a TLS code, ...), so its
+ * code and the host are named. A browser gives only "Failed to fetch" and keeps the reason in
+ * the console, since a CORS rejection, a blocked redirect and a DNS failure all look the same
+ * to the page; the message lists those causes and points there.
+ *
+ * @param url - The URL the SDK asked for.
+ * @param error - The TypeError fetch rejected with.
+ * @returns The message for the network DotHttpError.
+ */
+function describeNetworkError(url, error) {
+    const code = error.cause?.code;
+    let host = url;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        // A relative URL: keep it as given.
+    }
+    const reason = typeof code === 'string' ? `${code} ${host}` : error.message;
+    const summary = `Couldn't reach '${url}' (${reason}).`;
+    if (typeof window !== 'undefined' && typeof window.document !== 'undefined') {
+        return `${summary} Check dotcmsUrl: the scheme may be wrong (the browser blocks a redirect from http to https), the host may not resolve, or dotCMS may not allow this origin (CORS). The browser console shows the exact reason.`;
+    }
+    return `${summary} Check the scheme, host and port in dotcmsUrl, and that dotCMS is reachable at that address.`;
 }
 /**
  * Copies fetch Headers into a plain object, the shape createHttpError expects.

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@dotcms/client",
-  "version": "26.9.29-1",
+  "version": "26.9.29-1-next.2806",
   "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.29-1"
+    "@dotcms/types": "26.9.29-1-next.2806"
   },
   "dependencies": {
     "consola": "^3.4.2"
   },
   "devDependencies": {
-    "@dotcms/types": "26.9.29-1"
+    "@dotcms/types": "26.9.29-1-next.2806"
   },
   "keywords": [
     "dotCMS",

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

@@ -7,8 +7,9 @@ import { BaseHttpClient, DotRequestOptions } from '@dotcms/types';
  * - JSON response parsing
  * - HTTP error response parsing and conversion to DotHttpError
  * - Network error handling and wrapping
- * - 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
+ * - Diagnosing misconfiguration: a response in a format other than JSON, a request that was
+ *   redirected to another origin, or one that got no response at all is named as such in the
+ *   error message, leading with the dotcmsUrl fix where the SDK can tell what it is
  *
  * Every SDK caller talks to a dotCMS JSON endpoint, so a successful response with a
  * non-JSON content type is rejected rather than returned.