@dotcms/types

dotCMS Types Library

The @dotcms/types package contains TypeScript type definitions for the dotCMS ecosystem. Use it to enable type safety and an enhanced developer experience when working with dotCMS APIs and structured content.

📦 @dotcms/types on npm 🛠️ View source on GitHub

Table of Contents

• Overview
• Installation
• Commonly Used Types
• Type Hierarchy (Jump to Definitions)
  • AI Search
  • dotCMS Content & Pages
  • Universal Visual Editor (UVE)
  • Block Editor
  • Client & HTTP
  • Error Handling
• Usage Examples
  • Error Type Checking
• Support
• Contributing
• Licensing
• Changelog

Overview

When to Use It

• Building TypeScript applications with dotCMS
• Enabling type safety in your dotCMS integrations
• Getting better IDE autocomplete and error checking
• Working with dotCMS Client SDK or other SDK packages

Key Benefits

• Type Safety: Catch errors at compile time instead of runtime
• IDE Support: Rich autocomplete and inline documentation
• Better Developer Experience: Clear interfaces for all dotCMS data structures
• Framework Agnostic: Works with any TypeScript project

Installation

npm install @dotcms/types@latest --save-dev

Commonly Used Types

import {
  DotCMSPageAsset,
  DotCMSPageResponse,
  UVEEventType,
  DotCMSInlineEditingPayload,
  DotHttpClient,
  DotHttpError,
  DotErrorPage,
  DotErrorContent,
  DotErrorNavigation,
  DotErrorAISearch,
  DotCMSAISearchParams,
  DISTANCE_FUNCTIONS
} from '@dotcms/types';

Type Hierarchy (Jump to Definitions)

AI Search

⚠️ Experimental: The AI Search types are experimental and may undergo breaking changes in future releases.

AI Search Parameters:

Type	Description
DotCMSAISearchParams	Complete AI search parameters including query and AI config
DotCMSAISearchQuery	Query parameters (limit, offset, contentType, etc.)
DotCMSAIConfig	AI configuration (threshold, distanceFunction, responseLength)
DISTANCE_FUNCTIONS	Available distance functions for vector similarity

AI Search Response:

Type	Description
DotCMSAISearchResponse	AI search API response structure
DotCMSAISearchContentletData	Contentlet with AI match information
DotCMSAISearchMatch	Individual match with distance score and extracted text

AI Search Errors:

Type	Description
DotErrorAISearch	AI Search API specific error with prompt, indexName and params context

dotCMS Content & Pages

Page:

Type	Description
DotCMSPageAsset	Complete page with layout and content
DotCMSPage	Core page data
DotCMSPageResponse	API response for page requests
DotGraphQLApiResponse	GraphQL API response structure

Content:

Type	Description
DotCMSBasicContentlet	Basic contentlet structure

Site & Layout:

Type	Description
DotCMSSite	Site information
DotCMSTemplate	Page templates
DotCMSLayout	Page layout structure
DotCMSPageAssetContainer	Container definitions

Navigation:

Type	Description
DotCMSNavigationItem	Navigation structure item with hierarchy support
DotCMSVanityUrl	URL rewrites and vanity URLs
DotCMSURLContentMap	URL to content mapping

Universal Visual Editor (UVE)

Editor State:

Type	Description
UVEState	Current editor state
UVE_MODE	Editor modes (EDIT, PREVIEW, PUBLISHED)
DotCMSPageRendererMode	Page rendering modes

Editor Events:

Type	Description
UVEEventHandler	Event handler functions
UVEEventSubscriber	Event subscription management
UVEEventType	Available event types
UVEEventPayloadMap	Event payload definitions

Inline Editing:

Type	Description
DotCMSInlineEditingPayload	Inline editing data
DotCMSInlineEditingType	Types of inline editing

Block Editor

Type	Description
BlockEditorContent	Block editor content structure
BlockEditorNode	Individual blocks/nodes
BlockEditorMark	Text formatting marks

Client & HTTP

HTTP Client:

Type	Description
DotHttpClient	HTTP client interface for custom implementations
BaseHttpClient	Abstract base class with error handling utilities

Client Configuration:

Type	Description
DotCMSClientConfig	Client configuration options
DotRequestOptions	HTTP request options
DotCMSPageRequestParams	Page request parameters
DotCMSGraphQLParams	GraphQL query parameters
DotCMSNavigationRequestParams	Navigation request options

Error Handling

Base Error Types:

Type	Description
HttpErrorDetails	HTTP error details interface
DotHttpError	Standardized HTTP error class

Domain-Specific Errors:

Type	Description
DotErrorPage	Page API errors with GraphQL context
DotErrorContent	Content API specific error handling
DotErrorNavigation	Navigation API error handling
DotErrorAISearch	AI Search API error handling with prompt and params

Usage Examples

Error Type Checking

import {
  DotHttpError,
  DotErrorPage,
  DotErrorContent,
  DotErrorNavigation,
  DotErrorAISearch
} from '@dotcms/types';

// Type-safe error handling
if (error instanceof DotHttpError) {
  // Access standardized HTTP error properties
  console.error(`HTTP ${error.status}: ${error.statusText}`);
  console.error('Response data:', error.data);
}

if (error instanceof DotErrorPage) {
  // Page-specific error with GraphQL context
  console.error('GraphQL query:', error.graphql?.query);
}

if (error instanceof DotErrorContent) {
  // Content-specific error context
  console.error(`${error.operation} failed for ${error.contentType}`);
}

if (error instanceof DotErrorAISearch) {
  // AI Search-specific error context
  console.error('AI Search failed for prompt:', error.prompt);
  console.error('Index name:', error.indexName);
  console.error('Search params:', error.params);
}

Note: For complete implementation examples and usage patterns, see the @dotcms/client package documentation.

Support

We offer multiple channels to get help with the dotCMS Types library:

• GitHub Issues: For bug reports and feature requests, please open an issue in the GitHub repository
• Community Forum: Join our community discussions to ask questions and share solutions
• Stack Overflow: Use the tag dotcms-types when posting questions
• Enterprise Support: Enterprise customers can access premium support through the dotCMS Support Portal

When reporting issues, please include:

• Package version you're using
• TypeScript version
• Minimal reproduction steps
• Expected vs. actual behavior

Contributing

GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the dotCMS Types library! If you'd like to contribute, please follow these steps:

• Fork the repository dotCMS/core
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Please ensure your code follows the existing style and includes appropriate tests.

Changelog

[1.3.0]

✨ Added - AI Search Types (Experimental)

⚠️ Experimental: AI Search types are experimental and may undergo breaking changes in future releases.

New AI Search Types:

• DotCMSAISearchParams - Complete AI search parameters including query and AI config
• DotCMSAISearchQuery - Query parameters (limit, offset, contentType, etc.)
• DotCMSAIConfig - AI configuration (threshold, distanceFunction, responseLength)
• DotCMSAISearchResponse<T> - AI search API response structure
• DotCMSAISearchContentletData<T> - Contentlet with AI match information
• DotCMSAISearchMatch - Individual match with distance score and extracted text
• DotErrorAISearch - AI Search API specific error with prompt, indexName, and params context
• DISTANCE_FUNCTIONS - Available distance functions for vector similarity (cosine, L2, inner product, etc.)

[1.1.1]

Added

• DotHttpClient interface for custom HTTP client implementations
• BaseHttpClient abstract class with built-in error handling utilities
• DotHttpError class for standardized HTTP error handling
• DotErrorPage class for page-specific errors with GraphQL query context
• DotErrorContent class for content API errors with operation details
• DotErrorNavigation class for navigation-specific error handling
• DotGraphQLApiResponse interface for GraphQL API responses
• HttpErrorDetails interface for HTTP error standardization
• All error classes include toJSON() methods for easy logging and serialization

Changed

• Renamed RequestOptions to DotRequestOptions for better naming consistency
• Renamed DotCMSGraphQLPageResponse to DotGraphQLApiResponse for clarity
• Enhanced DotCMSClientConfig to support custom httpClient implementations

Licensing

dotCMS comes in multiple editions and as such is dual-licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization, and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see the feature page.

This package is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).