@dotcms/client 1.5.1-next.1965 → 1.5.1-next.1972

package/README.md

@@ -699,13 +699,14 @@ createDotCMSClient(config: DotCMSClientConfig): DotCMSClient
 
 #### Parameters
 
-| Option           | Type              | Required | Description                                                   |
-| ---------------- | ----------------- | -------- | ------------------------------------------------------------- |
-| `dotcmsUrl`      | string            | ✅       | Your dotCMS instance URL                                      |
-| `authToken`      | string            | ✅       | Authentication token                                          |
-| `siteId`         | string            | ❌       | Site identifier (falls back to default site if not specified) |
-| `requestOptions` | DotRequestOptions | ❌       | Additional request options                                    |
-| `httpClient`     | DotHttpClient     | ❌       | Custom HTTP client implementation                             |
+| Option           | Type                       | Required | Description                                                   |
+| ---------------- | -------------------------- | -------- | ------------------------------------------------------------- |
+| `dotcmsUrl`      | string                     | ✅       | Your dotCMS instance URL                                      |
+| `authToken`      | string                     | ✅       | Authentication token                                          |
+| `siteId`         | string                     | ❌       | Site identifier (falls back to default site if not specified) |
+| `requestOptions` | DotRequestOptions          | ❌       | Additional request options                                    |
+| `httpClient`     | DotHttpClient              | ❌       | Custom HTTP client implementation                             |
+| `logLevel`       | `'default'` \| `'verbose'` | ❌       | Controls log verbosity. `'verbose'` adds status, code, and variables to error logs. Defaults to `'default'` |
 
 #### Example
 ```typescript
@@ -713,10 +714,14 @@ const client = createDotCMSClient({
     dotcmsUrl: 'https://your-dotcms-instance.com',
     authToken: 'your-auth-token',
     siteId: 'your-site-id',
-    httpClient: customHttpClient // Optional: provide custom HTTP client
+    httpClient: customHttpClient, // Optional: provide custom HTTP client
+    logLevel: 'verbose'           // Optional: enable detailed error logs
 });
 ```
 
+> [!TIP]
+> Enable `logLevel: 'verbose'` during development to see HTTP status codes, error codes, and request variables in error logs. In verbose mode, error logs also include a hint to access the full GraphQL query via `error.graphql.query`. Keep it at `'default'` (or omit it) in production to avoid noisy logs.
+
 ### HTTP Client Configuration
 
 The SDK now supports custom HTTP client implementations for advanced use cases. By default, it uses the built-in `FetchHttpClient` based on the native Fetch API.

package/index.cjs.js

@@ -2107,8 +2107,8 @@ const DEFAULT_PAGE_CONTENTLETS_CONTENT = `
  * @param {string} additionalQueries - Additional GraphQL queries to include in the main query
  * @returns {string} Complete GraphQL query string for page content
  */
-const buildPageQuery = ({ page, fragments, additionalQueries }) => {
-    if (!page) {
+const buildPageQuery = ({ page, fragments, additionalQueries, verbose = false }) => {
+    if (!page && verbose) {
         consola.consola.warn("[DotCMS Client]: No page query was found, so we're loading all content using _map. This might slow things down. For better performance, we recommend adding a specific query in the page attribute.");
     }
     return `
@@ -2373,6 +2373,11 @@ async function fetchGraphQL({ baseURL, body, headers, httpClient }) {
     });
 }
 
+function logVerboseError(url, message, details) {
+    const statusLine = details.status !== undefined ? `\n  status: ${details.status} | code: ${details.code}` : '';
+    const variables = JSON.stringify(details.variables, null, 2).replace(/\n/g, '\n  ');
+    consola.consola.error(`[DotCMS GraphQL Error] ${url}: ${message}${statusLine}\n\n  variables:\n  ${variables}\n\n  (full query available at error.graphql.query)`);
+}
 /**
  * Client for interacting with the DotCMS Page API.
  * Provides methods to retrieve and manipulate pages.
@@ -2458,15 +2463,18 @@ class PageClient extends BaseApiClient {
     async get(url, options) {
         const { languageId = '1', mode = 'LIVE', siteId = this.siteId, fireRules = false, personaId, publishDate, variantName, graphql = {} } = options || {};
         const { page, content = {}, variables, fragments } = graphql;
+        const verbose = this.config.logLevel === 'verbose';
         const contentQuery = buildQuery(content);
         const completeQuery = buildPageQuery({
             page,
             fragments,
-            additionalQueries: contentQuery
+            additionalQueries: contentQuery,
+            verbose
         });
+        const normalizedUrl = url.startsWith('/') ? url : `/${url}`;
         const requestVariables = {
             // The url is expected to have a leading slash to comply on VanityURL Matching, some frameworks like Angular will not add the leading slash
-            url: url.startsWith('/') ? url : `/${url}`,
+            url: normalizedUrl,
             mode,
             languageId,
             personaId,
@@ -2485,33 +2493,77 @@ class PageClient extends BaseApiClient {
                 headers: requestHeaders,
                 httpClient: this.httpClient
             });
-            // 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);
+            // 1. Log unstructured GraphQL errors (structured ones are logged with enriched messages below)
+            if (response.errors?.length) {
+                response.errors
+                    .filter((error) => !error.extensions?.code)
+                    .forEach((error) => {
+                    if (verbose) {
+                        logVerboseError(normalizedUrl, error.message, {
+                            variables: requestVariables
+                        });
+                    }
+                    else {
+                        consola.consola.error(`[DotCMS GraphQL Error] ${normalizedUrl}: `, error.message);
+                    }
                 });
-                const pageError = response.errors.find((error) => error.message.includes('DotPage'));
-                if (pageError) {
-                    // Throw HTTP error - will be caught and wrapped in DotErrorPage below
-                    throw new types.DotHttpError({
-                        status: 400,
-                        statusText: 'Bad Request',
-                        message: `GraphQL query failed for URL '${url}': ${pageError.message}`,
-                        data: response.errors
+            }
+            // 2. BAD QUERY — data is null/undefined means the entire query failed
+            //    (syntax error, unknown type, validation error)
+            //    Must check BEFORE accessing response.data.page
+            if (!response.data) {
+                const firstError = response.errors?.[0];
+                throw new types.DotErrorPage(firstError?.message ?? 'GraphQL query failed', 400, 'BAD_REQUEST', new types.DotHttpError({
+                    status: 400,
+                    statusText: 'Bad Request',
+                    message: firstError?.message ?? 'GraphQL query failed',
+                    data: response.errors
+                }), { query: completeQuery, variables: requestVariables });
+            }
+            // 3. STRUCTURED ERRORS — check extensions.code for NOT_FOUND, PERMISSION_DENIED, etc.
+            //    Only fatal when the page itself failed (data.page is null/undefined).
+            //    If data.page exists, partial errors (e.g. secondary content) surface via errors[].
+            if (response.errors?.length && !response.data.page) {
+                const structuredError = response.errors.find((error) => error.extensions?.code);
+                if (structuredError) {
+                    const code = structuredError.extensions.code;
+                    const status = structuredError.extensions.status ??
+                        (code === 'NOT_FOUND' ? 404 : code === 'PERMISSION_DENIED' ? 403 : 400);
+                    const message = code === 'NOT_FOUND'
+                        ? `Page '${normalizedUrl}' was not found`
+                        : code === 'PERMISSION_DENIED'
+                            ? `Permission denied: you do not have access to page '${normalizedUrl}'. Verify the page permissions in dotCMS and that the auth token has sufficient access.`
+                            : `Page '${normalizedUrl}' could not be loaded (${code})`;
+                    if (verbose) {
+                        logVerboseError(normalizedUrl, message, {
+                            status,
+                            code,
+                            variables: requestVariables
+                        });
+                    }
+                    else {
+                        consola.consola.error(`[DotCMS GraphQL Error] ${normalizedUrl}: `, message);
+                    }
+                    throw new types.DotErrorPage(message, status, code, undefined, {
+                        query: completeQuery,
+                        variables: requestVariables
                     });
                 }
             }
-            const pageResponse = internal.graphqlToPageEntity(response.data.page);
+            // 4. Transform and check page — null page with no structured error = 404
+            const pageResponse = response.data.page
+                ? internal.graphqlToPageEntity(response.data.page)
+                : null;
             if (!pageResponse) {
-                // Throw HTTP error - will be caught and wrapped in DotErrorPage below
-                throw new types.DotHttpError({
+                throw new types.DotErrorPage(`Page '${normalizedUrl}' was not found`, 404, 'NOT_FOUND', new types.DotHttpError({
                     status: 404,
                     statusText: 'Not Found',
-                    message: `Page ${url} not found. Check the page URL and permissions.`,
+                    message: `Page '${normalizedUrl}' was not found`,
                     data: response.errors
-                });
+                }), { query: completeQuery, variables: requestVariables });
             }
             const styleEditorSchemas = await fetchStyleEditorSchemas(pageResponse.page.identifier, this.config, this.requestOptions, this.httpClient);
+            // 5. Build response — include any non-fatal errors for consumers to inspect
             const contentResponse = mapContentResponse(response.data, Object.keys(content));
             return {
                 pageAsset: pageResponse,
@@ -2520,22 +2572,18 @@ class PageClient extends BaseApiClient {
                     query: completeQuery,
                     variables: requestVariables
                 },
+                errors: response.errors?.length ? response.errors : undefined,
                 ...(styleEditorSchemas.length > 0 && { styleEditorSchemas })
             };
         }
         catch (error) {
-            // Handle DotHttpError instances
+            if (error instanceof types.DotErrorPage) {
+                throw error;
+            }
             if (error instanceof types.DotHttpError) {
-                throw new types.DotErrorPage(`Page request failed for URL '${url}': ${error.message}`, error, {
-                    query: completeQuery,
-                    variables: requestVariables
-                });
+                throw new types.DotErrorPage(`Page request failed for URL '${normalizedUrl}': ${error.message}`, error.status, 'UNKNOWN', error, { query: completeQuery, variables: requestVariables });
             }
-            // 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
-            });
+            throw new types.DotErrorPage(`Page request failed for URL '${normalizedUrl}': ${error instanceof Error ? error.message : 'Unknown error'}`, 500, 'UNKNOWN', undefined, { query: completeQuery, variables: requestVariables });
         }
     }
 }

package/index.esm.js

@@ -2105,8 +2105,8 @@ const DEFAULT_PAGE_CONTENTLETS_CONTENT = `
  * @param {string} additionalQueries - Additional GraphQL queries to include in the main query
  * @returns {string} Complete GraphQL query string for page content
  */
-const buildPageQuery = ({ page, fragments, additionalQueries }) => {
-    if (!page) {
+const buildPageQuery = ({ page, fragments, additionalQueries, verbose = false }) => {
+    if (!page && verbose) {
         consola.warn("[DotCMS Client]: No page query was found, so we're loading all content using _map. This might slow things down. For better performance, we recommend adding a specific query in the page attribute.");
     }
     return `
@@ -2371,6 +2371,11 @@ async function fetchGraphQL({ baseURL, body, headers, httpClient }) {
     });
 }
 
+function logVerboseError(url, message, details) {
+    const statusLine = details.status !== undefined ? `\n  status: ${details.status} | code: ${details.code}` : '';
+    const variables = JSON.stringify(details.variables, null, 2).replace(/\n/g, '\n  ');
+    consola.error(`[DotCMS GraphQL Error] ${url}: ${message}${statusLine}\n\n  variables:\n  ${variables}\n\n  (full query available at error.graphql.query)`);
+}
 /**
  * Client for interacting with the DotCMS Page API.
  * Provides methods to retrieve and manipulate pages.
@@ -2456,15 +2461,18 @@ class PageClient extends BaseApiClient {
     async get(url, options) {
         const { languageId = '1', mode = 'LIVE', siteId = this.siteId, fireRules = false, personaId, publishDate, variantName, graphql = {} } = options || {};
         const { page, content = {}, variables, fragments } = graphql;
+        const verbose = this.config.logLevel === 'verbose';
         const contentQuery = buildQuery(content);
         const completeQuery = buildPageQuery({
             page,
             fragments,
-            additionalQueries: contentQuery
+            additionalQueries: contentQuery,
+            verbose
         });
+        const normalizedUrl = url.startsWith('/') ? url : `/${url}`;
         const requestVariables = {
             // The url is expected to have a leading slash to comply on VanityURL Matching, some frameworks like Angular will not add the leading slash
-            url: url.startsWith('/') ? url : `/${url}`,
+            url: normalizedUrl,
             mode,
             languageId,
             personaId,
@@ -2483,33 +2491,77 @@ class PageClient extends BaseApiClient {
                 headers: requestHeaders,
                 httpClient: this.httpClient
             });
-            // 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);
+            // 1. Log unstructured GraphQL errors (structured ones are logged with enriched messages below)
+            if (response.errors?.length) {
+                response.errors
+                    .filter((error) => !error.extensions?.code)
+                    .forEach((error) => {
+                    if (verbose) {
+                        logVerboseError(normalizedUrl, error.message, {
+                            variables: requestVariables
+                        });
+                    }
+                    else {
+                        consola.error(`[DotCMS GraphQL Error] ${normalizedUrl}: `, error.message);
+                    }
                 });
-                const pageError = response.errors.find((error) => error.message.includes('DotPage'));
-                if (pageError) {
-                    // Throw HTTP error - will be caught and wrapped in DotErrorPage below
-                    throw new DotHttpError({
-                        status: 400,
-                        statusText: 'Bad Request',
-                        message: `GraphQL query failed for URL '${url}': ${pageError.message}`,
-                        data: response.errors
+            }
+            // 2. BAD QUERY — data is null/undefined means the entire query failed
+            //    (syntax error, unknown type, validation error)
+            //    Must check BEFORE accessing response.data.page
+            if (!response.data) {
+                const firstError = response.errors?.[0];
+                throw new DotErrorPage(firstError?.message ?? 'GraphQL query failed', 400, 'BAD_REQUEST', new DotHttpError({
+                    status: 400,
+                    statusText: 'Bad Request',
+                    message: firstError?.message ?? 'GraphQL query failed',
+                    data: response.errors
+                }), { query: completeQuery, variables: requestVariables });
+            }
+            // 3. STRUCTURED ERRORS — check extensions.code for NOT_FOUND, PERMISSION_DENIED, etc.
+            //    Only fatal when the page itself failed (data.page is null/undefined).
+            //    If data.page exists, partial errors (e.g. secondary content) surface via errors[].
+            if (response.errors?.length && !response.data.page) {
+                const structuredError = response.errors.find((error) => error.extensions?.code);
+                if (structuredError) {
+                    const code = structuredError.extensions.code;
+                    const status = structuredError.extensions.status ??
+                        (code === 'NOT_FOUND' ? 404 : code === 'PERMISSION_DENIED' ? 403 : 400);
+                    const message = code === 'NOT_FOUND'
+                        ? `Page '${normalizedUrl}' was not found`
+                        : code === 'PERMISSION_DENIED'
+                            ? `Permission denied: you do not have access to page '${normalizedUrl}'. Verify the page permissions in dotCMS and that the auth token has sufficient access.`
+                            : `Page '${normalizedUrl}' could not be loaded (${code})`;
+                    if (verbose) {
+                        logVerboseError(normalizedUrl, message, {
+                            status,
+                            code,
+                            variables: requestVariables
+                        });
+                    }
+                    else {
+                        consola.error(`[DotCMS GraphQL Error] ${normalizedUrl}: `, message);
+                    }
+                    throw new DotErrorPage(message, status, code, undefined, {
+                        query: completeQuery,
+                        variables: requestVariables
                     });
                 }
             }
-            const pageResponse = graphqlToPageEntity(response.data.page);
+            // 4. Transform and check page — null page with no structured error = 404
+            const pageResponse = response.data.page
+                ? graphqlToPageEntity(response.data.page)
+                : null;
             if (!pageResponse) {
-                // Throw HTTP error - will be caught and wrapped in DotErrorPage below
-                throw new DotHttpError({
+                throw new DotErrorPage(`Page '${normalizedUrl}' was not found`, 404, 'NOT_FOUND', new DotHttpError({
                     status: 404,
                     statusText: 'Not Found',
-                    message: `Page ${url} not found. Check the page URL and permissions.`,
+                    message: `Page '${normalizedUrl}' was not found`,
                     data: response.errors
-                });
+                }), { query: completeQuery, variables: requestVariables });
             }
             const styleEditorSchemas = await fetchStyleEditorSchemas(pageResponse.page.identifier, this.config, this.requestOptions, this.httpClient);
+            // 5. Build response — include any non-fatal errors for consumers to inspect
             const contentResponse = mapContentResponse(response.data, Object.keys(content));
             return {
                 pageAsset: pageResponse,
@@ -2518,22 +2570,18 @@ class PageClient extends BaseApiClient {
                     query: completeQuery,
                     variables: requestVariables
                 },
+                errors: response.errors?.length ? response.errors : undefined,
                 ...(styleEditorSchemas.length > 0 && { styleEditorSchemas })
             };
         }
         catch (error) {
-            // Handle DotHttpError instances
+            if (error instanceof DotErrorPage) {
+                throw error;
+            }
             if (error instanceof DotHttpError) {
-                throw new DotErrorPage(`Page request failed for URL '${url}': ${error.message}`, error, {
-                    query: completeQuery,
-                    variables: requestVariables
-                });
+                throw new DotErrorPage(`Page request failed for URL '${normalizedUrl}': ${error.message}`, error.status, 'UNKNOWN', error, { query: completeQuery, variables: requestVariables });
             }
-            // 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
-            });
+            throw new DotErrorPage(`Page request failed for URL '${normalizedUrl}': ${error instanceof Error ? error.message : 'Unknown error'}`, 500, 'UNKNOWN', undefined, { query: completeQuery, variables: requestVariables });
         }
     }
 }

package/package.json

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

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

@@ -7,10 +7,11 @@ import { StyleEditorFormSchema } from '@dotcms/types/internal';
  * @param {string} additionalQueries - Additional GraphQL queries to include in the main query
  * @returns {string} Complete GraphQL query string for page content
  */
-export declare const buildPageQuery: ({ page, fragments, additionalQueries }: {
+export declare const buildPageQuery: ({ page, fragments, additionalQueries, verbose }: {
     page?: string;
     fragments?: string[];
     additionalQueries?: string;
+    verbose?: boolean;
 }) => string;
 /**
  * Converts a record of query strings into a single GraphQL query string.