@dotcms/types 1.5.1-next.1964 → 1.5.1-next.1972

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.1964",
+  "version": "1.5.1-next.1972",
   "keywords": [
     "dotCMS",
     "CMS",

package/src/internal.d.ts

@@ -3,3 +3,4 @@ export * from './lib/events/internal';
 export * from './lib/editor/internal';
 export * from './lib/ai/internal';
 export * from './lib/client/internal';
+export * from './lib/style-editor/internal';

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

@@ -1,4 +1,5 @@
 import { DotHttpError } from '../client/public';
+import { StyleEditorFormSchema } from '../style-editor/internal';
 /**
  * Represents a map of style property keys and their corresponding values
  * for use in the style editor.
@@ -1128,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;
     };
 }
 /**
@@ -1157,11 +1184,16 @@ 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>;
     };
+    styleEditorSchemas?: StyleEditorFormSchema[];
 }
 export type DotCMSExtendedPageResponse = Partial<Pick<DotCMSPageResponse, 'pageAsset' | 'content'>>;
 export type DotCMSComposedPageAsset<T extends DotCMSExtendedPageResponse> = T['pageAsset'] extends DotCMSPageResponse['pageAsset'] ? DotCMSPageResponse['pageAsset'] & T['pageAsset'] : DotCMSPageResponse['pageAsset'];
@@ -1176,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>;
     });
@@ -1191,6 +1225,8 @@ export declare class DotErrorPage extends Error {
     toJSON(): {
         name: string;
         message: string;
+        status: number;
+        code: "UNKNOWN" | DotCMSGraphQLErrorCode;
         httpError: {
             name: string;
             message: string;

package/src/lib/style-editor/internal.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Available field types for the style editor.
+ */
+export type StyleEditorFieldType = 'input' | 'dropdown' | 'radio' | 'checkboxGroup';
+/**
+ * Available input types for input fields in the style editor.
+ */
+export type StyleEditorFieldInputType = 'text' | 'number';
+/**
+ * Base option object with label and value properties.
+ */
+export interface StyleEditorOptionObject {
+    label: string;
+    value: string;
+}
+/**
+ * Extended option object for radio fields with optional image support.
+ */
+export interface StyleEditorRadioOptionObject extends StyleEditorOptionObject {
+    imageURL?: string;
+}
+/**
+ * Option type for dropdown fields.
+ */
+export type StyleEditorOption = StyleEditorOptionObject;
+/**
+ * Option type for radio fields (supports optional image).
+ */
+export type StyleEditorRadioOption = StyleEditorRadioOptionObject;
+/**
+ * Checkbox option with a key identifier instead of value.
+ */
+export interface StyleEditorCheckboxOption {
+    label: string;
+    key: string;
+}
+/**
+ * Configuration object for normalized field schemas sent to UVE.
+ */
+export interface StyleEditorFieldSchemaConfig {
+    inputType?: StyleEditorFieldInputType;
+    placeholder?: string;
+    options?: StyleEditorRadioOptionObject[];
+    columns?: 1 | 2;
+}
+/**
+ * Normalized field schema sent to UVE.
+ */
+export interface StyleEditorFieldSchema {
+    id: string;
+    type: StyleEditorFieldType;
+    label: string;
+    config: StyleEditorFieldSchemaConfig;
+}
+/**
+ * Normalized section schema sent to UVE.
+ */
+export interface StyleEditorSectionSchema {
+    title: string;
+    fields: StyleEditorFieldSchema[];
+}
+/**
+ * Complete normalized form schema sent to UVE.
+ * This is the output format after processing a style editor form definition.
+ */
+export interface StyleEditorFormSchema {
+    contentType: string;
+    sections: StyleEditorSectionSchema[];
+}