@dotcms/types 1.5.1-next.1965 → 1.5.1-next.1977

package/index.cjs.js

@@ -156,9 +156,11 @@ exports.UVEEventType = void 0;
  * Wraps HTTP errors and adds page-specific context including GraphQL information
  */
 class DotErrorPage extends Error {
-  constructor(message, httpError, graphql) {
+  constructor(message, status = 500, code = 'UNKNOWN', httpError, graphql) {
     super(message);
     this.name = 'DotCMSPageError';
+    this.status = status;
+    this.code = code;
     this.httpError = httpError;
     this.graphql = graphql;
     // Ensure proper prototype chain for instanceof checks
@@ -171,6 +173,8 @@ class DotErrorPage extends Error {
     return {
       name: this.name,
       message: this.message,
+      status: this.status,
+      code: this.code,
       httpError: this.httpError?.toJSON(),
       graphql: this.graphql,
       stack: this.stack

package/index.esm.js

@@ -154,9 +154,11 @@ var UVEEventType;
  * Wraps HTTP errors and adds page-specific context including GraphQL information
  */
 class DotErrorPage extends Error {
-  constructor(message, httpError, graphql) {
+  constructor(message, status = 500, code = 'UNKNOWN', httpError, graphql) {
     super(message);
     this.name = 'DotCMSPageError';
+    this.status = status;
+    this.code = code;
     this.httpError = httpError;
     this.graphql = graphql;
     // Ensure proper prototype chain for instanceof checks
@@ -169,6 +171,8 @@ class DotErrorPage extends Error {
     return {
       name: this.name,
       message: this.message,
+      status: this.status,
+      code: this.code,
       httpError: this.httpError?.toJSON(),
       graphql: this.graphql,
       stack: this.stack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/types",
-  "version": "1.5.1-next.1965",
+  "version": "1.5.1-next.1977",
   "keywords": [
     "dotCMS",
     "CMS",

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

@@ -315,4 +315,11 @@ export interface DotCMSClientConfig {
      * @example `{ httpClient: new AxiosHttpClient() }`
      */
     httpClient?: DotHttpClient;
+    /**
+     * Controls the verbosity of error logs from the SDK.
+     * - `'default'`: logs the error message only (default)
+     * - `'verbose'`: also logs the HTTP status, error code, and the GraphQL query and variables
+     * @example `logLevel: 'verbose'`
+     */
+    logLevel?: 'default' | 'verbose';
 }

package/src/lib/page/public.d.ts

@@ -1129,27 +1129,53 @@ export interface DotCMSPageContainerContentlets {
     contentlets: DotCMSBasicContentlet[];
 }
 /**
- * dotCMS's GraphQL API response with a page and content query
+ * Raw GraphQL API response for a dotCMS page query.
+ *
+ * Shape varies by failure mode:
+ * - Success:          { data: { page: DotCMSGraphQLPage, ... }, errors: undefined }
+ * - Page not found:   { data: { page: null }, errors: [{ extensions: { code: 'NOT_FOUND' } }] }
+ * - Bad query:        { data: null, errors: [{ message: '...' }] }
+ * - Partial failure:  { data: { page: DotCMSGraphQLPage, ... }, errors: [...] }
+ *                     (page loaded but secondary content queries failed)
+ *
+ * Always check `errors` even when `data` is present — partial failures surface both.
  */
 export interface DotGraphQLApiResponse {
     data: {
-        page: DotCMSGraphQLPage;
+        page: DotCMSGraphQLPage | null;
         content?: Record<string, unknown>;
-    };
+    } | null;
     errors?: DotCMSGraphQLError[];
 }
+/**
+ * Error codes returned by the DotCMS GraphQL API.
+ * - NOT_FOUND: The requested page or resource does not exist (HTTP 404)
+ * - PERMISSION_DENIED: The user lacks permission or is not authenticated (always HTTP 403 — dotCMS does not distinguish 401 vs 403 at the GraphQL layer)
+ * - INVALID_LANGUAGE: The languageId provided is not a valid language (HTTP 400)
+ * - BAD_REQUEST: The GraphQL query itself is malformed or invalid (HTTP 400)
+ */
+export type DotCMSGraphQLErrorCode = 'NOT_FOUND' | 'PERMISSION_DENIED' | 'INVALID_LANGUAGE' | 'BAD_REQUEST';
 /**
  * Represents a GraphQL error
  * @interface DotCMSGraphQLError
  */
 export interface DotCMSGraphQLError {
     message: string;
-    locations: {
+    locations?: {
         line: number;
         column: number;
     }[];
-    extensions: {
-        classification: string;
+    path?: string[];
+    extensions?: {
+        classification?: string;
+        /** Structured error code from DotCMS backend — use this for programmatic error handling */
+        code?: DotCMSGraphQLErrorCode;
+        /** HTTP status hint from backend (e.g. 404, 400) */
+        status?: number;
+        /** The type of resource that was not found, if applicable */
+        resourceType?: string;
+        /** The identifier of the resource that was not found, if applicable */
+        resourceId?: string;
     };
 }
 /**
@@ -1158,7 +1184,11 @@ export interface DotCMSGraphQLError {
 export interface DotCMSPageResponse {
     pageAsset: DotCMSPageAsset;
     content?: Record<string, unknown> | unknown;
+    /**
+     * @deprecated Use `errors` instead. Will be removed in August 2026. Kept for backward compatibility — represents the first GraphQL error when present.
+     */
     error?: DotCMSGraphQLError;
+    errors?: DotCMSGraphQLError[];
     graphql: {
         query: string;
         variables: Record<string, unknown>;
@@ -1178,12 +1208,14 @@ export type DotCMSClientPageGetResponse<T extends DotCMSExtendedPageResponse> =
  * Wraps HTTP errors and adds page-specific context including GraphQL information
  */
 export declare class DotErrorPage extends Error {
+    readonly status: number;
+    readonly code: DotCMSGraphQLErrorCode | 'UNKNOWN';
     readonly httpError?: DotHttpError;
     readonly graphql?: {
         query: string;
         variables: Record<string, unknown>;
     };
-    constructor(message: string, httpError?: DotHttpError, graphql?: {
+    constructor(message: string, status?: number, code?: DotCMSGraphQLErrorCode | 'UNKNOWN', httpError?: DotHttpError, graphql?: {
         query: string;
         variables: Record<string, unknown>;
     });
@@ -1193,6 +1225,8 @@ export declare class DotErrorPage extends Error {
     toJSON(): {
         name: string;
         message: string;
+        status: number;
+        code: "UNKNOWN" | DotCMSGraphQLErrorCode;
         httpError: {
             name: string;
             message: string;