@dotcms/types 1.0.6-next.3 → 1.0.6-next.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +162 -42
- package/index.cjs.js +239 -0
- package/index.esm.js +235 -1
- package/package.json +1 -1
- package/src/index.d.ts +2 -0
- package/src/lib/client/public.d.ts +214 -21
- package/src/lib/content/public.d.ts +31 -0
- package/src/lib/nav/public.d.ts +76 -0
- package/src/lib/page/public.d.ts +46 -41
package/README.md
CHANGED
|
@@ -13,6 +13,22 @@ npm install @dotcms/types@latest --save-dev
|
|
|
13
13
|
|
|
14
14
|
This 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.
|
|
15
15
|
|
|
16
|
+
## Table of Contents
|
|
17
|
+
|
|
18
|
+
- [Installation](#installation)
|
|
19
|
+
- [Overview](#overview)
|
|
20
|
+
- [Commonly Used Types](#commonly-used-types)
|
|
21
|
+
- [Type Hierarchy (Jump to Definitions)](#type-hierarchy-jump-to-definitions)
|
|
22
|
+
- [dotCMS Content & Pages](#dotcms-content--pages)
|
|
23
|
+
- [Universal Visual Editor (UVE)](#universal-visual-editor-uve)
|
|
24
|
+
- [Block Editor](#block-editor)
|
|
25
|
+
- [Client & HTTP](#client--http)
|
|
26
|
+
- [Error Handling](#error-handling)
|
|
27
|
+
- [Type Usage](#type-usage)
|
|
28
|
+
- [Error Type Checking](#error-type-checking)
|
|
29
|
+
- [About](#about)
|
|
30
|
+
- [Changelog](#changelog)
|
|
31
|
+
|
|
16
32
|
## Commonly Used Types
|
|
17
33
|
|
|
18
34
|
```ts
|
|
@@ -20,68 +36,152 @@ import {
|
|
|
20
36
|
DotCMSPageAsset,
|
|
21
37
|
DotCMSPageResponse,
|
|
22
38
|
UVEEventType,
|
|
23
|
-
DotCMSInlineEditingPayload
|
|
39
|
+
DotCMSInlineEditingPayload,
|
|
40
|
+
DotHttpClient,
|
|
41
|
+
DotHttpError,
|
|
42
|
+
DotErrorPage,
|
|
43
|
+
DotErrorContent,
|
|
44
|
+
DotErrorNavigation
|
|
24
45
|
} from '@dotcms/types';
|
|
25
46
|
```
|
|
26
47
|
|
|
27
48
|
## Type Hierarchy (Jump to Definitions)
|
|
28
49
|
|
|
29
|
-
###
|
|
50
|
+
### dotCMS Content & Pages
|
|
51
|
+
|
|
52
|
+
**Page:**
|
|
53
|
+
|
|
54
|
+
| Type | Description |
|
|
55
|
+
|------|-------------|
|
|
56
|
+
| [DotCMSPageAsset](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L18) | Complete page with layout and content |
|
|
57
|
+
| [DotCMSPage](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L515) | Core page data |
|
|
58
|
+
| [DotCMSPageResponse](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1175) | API response for page requests |
|
|
59
|
+
| [DotGraphQLApiResponse](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1186) | GraphQL API response structure |
|
|
60
|
+
|
|
61
|
+
**Content:**
|
|
62
|
+
|
|
63
|
+
| Type | Description |
|
|
64
|
+
|------|-------------|
|
|
65
|
+
| [DotCMSBasicContentlet](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1141) | Basic contentlet structure |
|
|
66
|
+
|
|
67
|
+
**Site & Layout:**
|
|
68
|
+
|
|
69
|
+
| Type | Description |
|
|
70
|
+
|------|-------------|
|
|
71
|
+
| [DotCMSSite](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L733) | Site information |
|
|
72
|
+
| [DotCMSTemplate](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L432) | Page templates |
|
|
73
|
+
| [DotCMSLayout](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L622) | Page layout structure |
|
|
74
|
+
| [DotCMSPageAssetContainer](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L138) | Container definitions |
|
|
75
|
+
|
|
76
|
+
**Navigation:**
|
|
77
|
+
|
|
78
|
+
| Type | Description |
|
|
79
|
+
|------|-------------|
|
|
80
|
+
| [DotCMSNavigationItem](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/nav/public.ts#L73) | Navigation structure item with hierarchy support |
|
|
81
|
+
| [DotCMSVanityUrl](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L80) | URL rewrites and vanity URLs |
|
|
82
|
+
| [DotCMSURLContentMap](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L41) | URL to content mapping |
|
|
83
|
+
|
|
84
|
+
### Universal Visual Editor (UVE)
|
|
85
|
+
|
|
86
|
+
**Editor State:**
|
|
30
87
|
|
|
31
|
-
|
|
88
|
+
| Type | Description |
|
|
89
|
+
|------|-------------|
|
|
90
|
+
| [UVEState](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L30) | Current editor state |
|
|
91
|
+
| [UVE_MODE](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L55) | Editor modes (EDIT, PREVIEW, PUBLISHED) |
|
|
92
|
+
| [DotCMSPageRendererMode](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L44) | Page rendering modes |
|
|
32
93
|
|
|
33
|
-
|
|
34
|
-
* [DotCMSPageAssetContainer](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L138)
|
|
35
|
-
* [DotCMSSite](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L733)
|
|
36
|
-
* [DotCMSTemplate](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L432)
|
|
37
|
-
* [DotCMSViewAs](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L598)
|
|
38
|
-
* [DotCMSVanityUrl](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L80)
|
|
39
|
-
* [DotCMSURLContentMap](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L41)
|
|
40
|
-
* [DotCMSLayout](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L622)
|
|
41
|
-
* [DotCMSPageContainerContentlets](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1139)
|
|
42
|
-
* [DotCMSPageResponse](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1175)
|
|
43
|
-
* [DotCMSComposedPageAsset](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1189)
|
|
44
|
-
* [DotCMSComposedContent](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1195)
|
|
45
|
-
* [DotCMSComposedPageResponse](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1199)
|
|
46
|
-
* [DotCMSClientPageGetResponse](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1208)
|
|
94
|
+
**Editor Events:**
|
|
47
95
|
|
|
48
|
-
|
|
96
|
+
| Type | Description |
|
|
97
|
+
|------|-------------|
|
|
98
|
+
| [UVEEventHandler](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L67) | Event handler functions |
|
|
99
|
+
| [UVEEventSubscriber](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L90) | Event subscription management |
|
|
100
|
+
| [UVEEventType](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L169) | Available event types |
|
|
101
|
+
| [UVEEventPayloadMap](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L199) | Event payload definitions |
|
|
49
102
|
|
|
50
|
-
|
|
103
|
+
**Inline Editing:**
|
|
51
104
|
|
|
52
|
-
|
|
53
|
-
|
|
105
|
+
| Type | Description |
|
|
106
|
+
|------|-------------|
|
|
107
|
+
| [DotCMSInlineEditingPayload](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/events/public.ts#L13) | Inline editing data |
|
|
108
|
+
| [DotCMSInlineEditingType](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/events/public.ts#L1) | Types of inline editing |
|
|
54
109
|
|
|
55
|
-
### Editor
|
|
110
|
+
### Block Editor
|
|
56
111
|
|
|
57
|
-
|
|
112
|
+
| Type | Description |
|
|
113
|
+
|------|-------------|
|
|
114
|
+
| [BlockEditorContent](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/components/block-editor-renderer/public.ts#L38) | Block editor content structure |
|
|
115
|
+
| [BlockEditorNode](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/components/block-editor-renderer/public.ts#L18) | Individual blocks/nodes |
|
|
116
|
+
| [BlockEditorMark](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/components/block-editor-renderer/public.ts#L7) | Text formatting marks |
|
|
58
117
|
|
|
59
|
-
|
|
60
|
-
* [UVEEventHandler](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L67)
|
|
61
|
-
* [UVEEventSubscriber](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L90)
|
|
118
|
+
### Client & HTTP
|
|
62
119
|
|
|
63
|
-
|
|
64
|
-
* [UVEUnsubscribeFunction](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L73)
|
|
65
|
-
* [UVEEventType](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/editor/public.ts#L169)
|
|
120
|
+
**HTTP Client:**
|
|
66
121
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
122
|
+
| Type | Description |
|
|
123
|
+
|------|-------------|
|
|
124
|
+
| [DotHttpClient](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L108) | HTTP client interface for custom implementations |
|
|
125
|
+
| [BaseHttpClient](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L196) | Abstract base class with error handling utilities |
|
|
70
126
|
|
|
71
|
-
|
|
127
|
+
**Client Configuration:**
|
|
72
128
|
|
|
73
|
-
|
|
129
|
+
| Type | Description |
|
|
130
|
+
|------|-------------|
|
|
131
|
+
| [DotCMSClientConfig](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L395) | Client configuration options |
|
|
132
|
+
| [DotRequestOptions](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L383) | HTTP request options |
|
|
133
|
+
| [DotCMSPageRequestParams](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L378) | Page request parameters |
|
|
134
|
+
| [DotCMSGraphQLParams](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L280) | GraphQL query parameters |
|
|
135
|
+
| [DotCMSNavigationRequestParams](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/nav/public.ts#L39) | Navigation request options |
|
|
74
136
|
|
|
75
|
-
|
|
137
|
+
### Error Handling
|
|
76
138
|
|
|
77
|
-
|
|
139
|
+
**Base Error Types:**
|
|
78
140
|
|
|
79
|
-
|
|
141
|
+
| Type | Description |
|
|
142
|
+
|------|-------------|
|
|
143
|
+
| [HttpErrorDetails](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L6) | HTTP error details interface |
|
|
144
|
+
| [DotHttpError](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/client/public.ts#L26) | Standardized HTTP error class |
|
|
80
145
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
146
|
+
**Domain-Specific Errors:**
|
|
147
|
+
|
|
148
|
+
| Type | Description |
|
|
149
|
+
|------|-------------|
|
|
150
|
+
| [DotErrorPage](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/page/public.ts#L1253) | Page API errors with GraphQL context |
|
|
151
|
+
| [DotErrorContent](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/content/public.ts#L7) | Content API specific error handling |
|
|
152
|
+
| [DotErrorNavigation](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/types/src/lib/nav/public.ts#L7) | Navigation API error handling |
|
|
153
|
+
|
|
154
|
+
## Type Usage
|
|
155
|
+
|
|
156
|
+
### Error Type Checking
|
|
157
|
+
|
|
158
|
+
```typescript
|
|
159
|
+
import {
|
|
160
|
+
DotHttpError,
|
|
161
|
+
DotErrorPage,
|
|
162
|
+
DotErrorContent,
|
|
163
|
+
DotErrorNavigation
|
|
164
|
+
} from '@dotcms/types';
|
|
165
|
+
|
|
166
|
+
// Type-safe error handling
|
|
167
|
+
if (error instanceof DotHttpError) {
|
|
168
|
+
// Access standardized HTTP error properties
|
|
169
|
+
console.error(`HTTP ${error.status}: ${error.statusText}`);
|
|
170
|
+
console.error('Response data:', error.data);
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
if (error instanceof DotErrorPage) {
|
|
174
|
+
// Page-specific error with GraphQL context
|
|
175
|
+
console.error('GraphQL query:', error.graphql?.query);
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
if (error instanceof DotErrorContent) {
|
|
179
|
+
// Content-specific error context
|
|
180
|
+
console.error(`${error.operation} failed for ${error.contentType}`);
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
> **Note**: For complete implementation examples and usage patterns, see the [@dotcms/client](../client/README.md) package documentation.
|
|
85
185
|
|
|
86
186
|
## About
|
|
87
187
|
|
|
@@ -92,5 +192,25 @@ This package is maintained as part of the [dotCMS core repository](https://githu
|
|
|
92
192
|
* dotcms
|
|
93
193
|
* typescript
|
|
94
194
|
* types
|
|
95
|
-
* cms
|
|
195
|
+
* cms
|
|
96
196
|
* content-management-system
|
|
197
|
+
|
|
198
|
+
## Changelog
|
|
199
|
+
|
|
200
|
+
### [1.1.1]
|
|
201
|
+
|
|
202
|
+
#### Added
|
|
203
|
+
- `DotHttpClient` interface for custom HTTP client implementations
|
|
204
|
+
- `BaseHttpClient` abstract class with built-in error handling utilities
|
|
205
|
+
- `DotHttpError` class for standardized HTTP error handling
|
|
206
|
+
- `DotErrorPage` class for page-specific errors with GraphQL query context
|
|
207
|
+
- `DotErrorContent` class for content API errors with operation details
|
|
208
|
+
- `DotErrorNavigation` class for navigation-specific error handling
|
|
209
|
+
- `DotGraphQLApiResponse` interface for GraphQL API responses
|
|
210
|
+
- `HttpErrorDetails` interface for HTTP error standardization
|
|
211
|
+
- All error classes include `toJSON()` methods for easy logging and serialization
|
|
212
|
+
|
|
213
|
+
#### Changed
|
|
214
|
+
- Renamed `RequestOptions` to `DotRequestOptions` for better naming consistency
|
|
215
|
+
- Renamed `DotCMSGraphQLPageResponse` to `DotGraphQLApiResponse` for clarity
|
|
216
|
+
- Enhanced `DotCMSClientConfig` to support custom `httpClient` implementations
|
package/index.cjs.js
CHANGED
|
@@ -122,5 +122,244 @@ exports.UVEEventType = void 0;
|
|
|
122
122
|
UVEEventType["CONTENTLET_HOVERED"] = "contentlet-hovered";
|
|
123
123
|
})(exports.UVEEventType || (exports.UVEEventType = {}));
|
|
124
124
|
|
|
125
|
+
/* eslint-disable @typescript-eslint/no-explicit-any */
|
|
126
|
+
/**
|
|
127
|
+
* Page API specific error class
|
|
128
|
+
* Wraps HTTP errors and adds page-specific context including GraphQL information
|
|
129
|
+
*/
|
|
130
|
+
class DotErrorPage extends Error {
|
|
131
|
+
constructor(message, httpError, graphql) {
|
|
132
|
+
super(message);
|
|
133
|
+
this.name = 'DotCMSPageError';
|
|
134
|
+
this.httpError = httpError;
|
|
135
|
+
this.graphql = graphql;
|
|
136
|
+
// Ensure proper prototype chain for instanceof checks
|
|
137
|
+
Object.setPrototypeOf(this, DotErrorPage.prototype);
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Serializes the error to a plain object for logging or transmission
|
|
141
|
+
*/
|
|
142
|
+
toJSON() {
|
|
143
|
+
return {
|
|
144
|
+
name: this.name,
|
|
145
|
+
message: this.message,
|
|
146
|
+
httpError: this.httpError?.toJSON(),
|
|
147
|
+
graphql: this.graphql,
|
|
148
|
+
stack: this.stack
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* Standardized HTTP error class for all HTTP client implementations
|
|
155
|
+
*/
|
|
156
|
+
class DotHttpError extends Error {
|
|
157
|
+
constructor(details) {
|
|
158
|
+
super(details.message);
|
|
159
|
+
this.name = 'DotHttpError';
|
|
160
|
+
this.status = details.status;
|
|
161
|
+
this.statusText = details.statusText;
|
|
162
|
+
this.data = details.data;
|
|
163
|
+
// Ensure proper prototype chain for instanceof checks
|
|
164
|
+
Object.setPrototypeOf(this, DotHttpError.prototype);
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Serializes the error to a plain object for logging or transmission
|
|
168
|
+
*/
|
|
169
|
+
toJSON() {
|
|
170
|
+
return {
|
|
171
|
+
name: this.name,
|
|
172
|
+
message: this.message,
|
|
173
|
+
status: this.status,
|
|
174
|
+
statusText: this.statusText,
|
|
175
|
+
data: this.data,
|
|
176
|
+
stack: this.stack
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* Abstract base class for HTTP client implementations.
|
|
182
|
+
* Provides common error handling utilities and enforces HttpError contract.
|
|
183
|
+
*
|
|
184
|
+
* @example
|
|
185
|
+
* ```typescript
|
|
186
|
+
* // Fetch API example
|
|
187
|
+
* export class FetchHttpClient extends BaseHttpClient {
|
|
188
|
+
* async request<T>(url: string, options?: DotRequestOptions): Promise<T> {
|
|
189
|
+
* try {
|
|
190
|
+
* const response = await fetch(url, options);
|
|
191
|
+
*
|
|
192
|
+
* if (!response.ok) {
|
|
193
|
+
* // Parse response body and headers
|
|
194
|
+
* let errorBody: string | unknown;
|
|
195
|
+
* try {
|
|
196
|
+
* const contentType = response.headers.get('content-type');
|
|
197
|
+
* if (contentType?.includes('application/json')) {
|
|
198
|
+
* errorBody = await response.json();
|
|
199
|
+
* } else {
|
|
200
|
+
* errorBody = await response.text();
|
|
201
|
+
* }
|
|
202
|
+
* } catch {
|
|
203
|
+
* errorBody = response.statusText;
|
|
204
|
+
* }
|
|
205
|
+
*
|
|
206
|
+
* const headers: Record<string, string> = {};
|
|
207
|
+
* response.headers.forEach((value, key) => {
|
|
208
|
+
* headers[key] = value;
|
|
209
|
+
* });
|
|
210
|
+
*
|
|
211
|
+
* throw this.createHttpError(
|
|
212
|
+
* response.status,
|
|
213
|
+
* response.statusText,
|
|
214
|
+
* headers,
|
|
215
|
+
* errorBody
|
|
216
|
+
* );
|
|
217
|
+
* }
|
|
218
|
+
*
|
|
219
|
+
* return response.json();
|
|
220
|
+
* } catch (error) {
|
|
221
|
+
* if (error instanceof TypeError) {
|
|
222
|
+
* throw this.createNetworkError(error);
|
|
223
|
+
* }
|
|
224
|
+
* throw error;
|
|
225
|
+
* }
|
|
226
|
+
* }
|
|
227
|
+
* }
|
|
228
|
+
*
|
|
229
|
+
* // Axios example
|
|
230
|
+
* export class AxiosHttpClient extends BaseHttpClient {
|
|
231
|
+
* async request<T>(url: string, options?: DotRequestOptions): Promise<T> {
|
|
232
|
+
* try {
|
|
233
|
+
* const response = await axios(url, options);
|
|
234
|
+
* return response.data;
|
|
235
|
+
* } catch (error) {
|
|
236
|
+
* if (axios.isAxiosError(error)) {
|
|
237
|
+
* throw this.createHttpError(
|
|
238
|
+
* error.response?.status || 0,
|
|
239
|
+
* error.response?.statusText || 'Network Error',
|
|
240
|
+
* error.response?.headers,
|
|
241
|
+
* error.response?.data
|
|
242
|
+
* );
|
|
243
|
+
* }
|
|
244
|
+
* throw this.createNetworkError(error);
|
|
245
|
+
* }
|
|
246
|
+
* }
|
|
247
|
+
* }
|
|
248
|
+
* ```
|
|
249
|
+
*/
|
|
250
|
+
class BaseHttpClient {
|
|
251
|
+
/**
|
|
252
|
+
* Creates a standardized HttpError from HTTP response details.
|
|
253
|
+
* Handles parsing of error response body automatically.
|
|
254
|
+
*
|
|
255
|
+
* @param status - HTTP status code
|
|
256
|
+
* @param statusText - HTTP status text
|
|
257
|
+
* @param headers - Response headers (optional)
|
|
258
|
+
* @param body - Response body (optional)
|
|
259
|
+
* @param customMessage - Optional custom error message
|
|
260
|
+
* @returns HttpError instance with parsed response data
|
|
261
|
+
*/
|
|
262
|
+
createHttpError(status, statusText, headers, body, customMessage) {
|
|
263
|
+
let errorData = body;
|
|
264
|
+
// If body is a string, try to parse as JSON
|
|
265
|
+
if (typeof body === 'string') {
|
|
266
|
+
try {
|
|
267
|
+
const contentType = headers?.['content-type'] || headers?.['Content-Type'];
|
|
268
|
+
if (contentType?.includes('application/json')) {
|
|
269
|
+
errorData = JSON.parse(body);
|
|
270
|
+
} else {
|
|
271
|
+
errorData = body;
|
|
272
|
+
}
|
|
273
|
+
} catch {
|
|
274
|
+
errorData = body;
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
return new DotHttpError({
|
|
278
|
+
status,
|
|
279
|
+
statusText,
|
|
280
|
+
message: customMessage || `HTTP ${status}: ${statusText}`,
|
|
281
|
+
data: errorData
|
|
282
|
+
});
|
|
283
|
+
}
|
|
284
|
+
/**
|
|
285
|
+
* Creates a standardized HttpError for network/connection errors.
|
|
286
|
+
*
|
|
287
|
+
* @param originalError - The original network error
|
|
288
|
+
* @returns HttpError instance representing a network error
|
|
289
|
+
*/
|
|
290
|
+
createNetworkError(originalError) {
|
|
291
|
+
return new DotHttpError({
|
|
292
|
+
status: 0,
|
|
293
|
+
// Network error status
|
|
294
|
+
statusText: 'Network Error',
|
|
295
|
+
message: `Network error: ${originalError.message}`,
|
|
296
|
+
data: originalError
|
|
297
|
+
});
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
/**
|
|
302
|
+
* Content API specific error class
|
|
303
|
+
* Wraps HTTP errors and adds content-specific context including query information
|
|
304
|
+
*/
|
|
305
|
+
class DotErrorContent extends Error {
|
|
306
|
+
constructor(message, contentType, operation, httpError, query) {
|
|
307
|
+
super(message);
|
|
308
|
+
this.name = 'DotCMSContentError';
|
|
309
|
+
this.contentType = contentType;
|
|
310
|
+
this.operation = operation;
|
|
311
|
+
this.httpError = httpError;
|
|
312
|
+
this.query = query;
|
|
313
|
+
// Ensure proper prototype chain for instanceof checks
|
|
314
|
+
Object.setPrototypeOf(this, DotErrorContent.prototype);
|
|
315
|
+
}
|
|
316
|
+
/**
|
|
317
|
+
* Serializes the error to a plain object for logging or transmission
|
|
318
|
+
*/
|
|
319
|
+
toJSON() {
|
|
320
|
+
return {
|
|
321
|
+
name: this.name,
|
|
322
|
+
message: this.message,
|
|
323
|
+
contentType: this.contentType,
|
|
324
|
+
operation: this.operation,
|
|
325
|
+
httpError: this.httpError?.toJSON(),
|
|
326
|
+
query: this.query,
|
|
327
|
+
stack: this.stack
|
|
328
|
+
};
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/**
|
|
333
|
+
* Navigation API specific error class
|
|
334
|
+
* Wraps HTTP errors and adds navigation-specific context
|
|
335
|
+
*/
|
|
336
|
+
class DotErrorNavigation extends Error {
|
|
337
|
+
constructor(message, path, httpError) {
|
|
338
|
+
super(message);
|
|
339
|
+
this.name = 'DotNavigationError';
|
|
340
|
+
this.path = path;
|
|
341
|
+
this.httpError = httpError;
|
|
342
|
+
// Ensure proper prototype chain for instanceof checks
|
|
343
|
+
Object.setPrototypeOf(this, DotErrorNavigation.prototype);
|
|
344
|
+
}
|
|
345
|
+
/**
|
|
346
|
+
* Serializes the error to a plain object for logging or transmission
|
|
347
|
+
*/
|
|
348
|
+
toJSON() {
|
|
349
|
+
return {
|
|
350
|
+
name: this.name,
|
|
351
|
+
message: this.message,
|
|
352
|
+
path: this.path,
|
|
353
|
+
httpError: this.httpError?.toJSON(),
|
|
354
|
+
stack: this.stack
|
|
355
|
+
};
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
exports.BaseHttpClient = BaseHttpClient;
|
|
125
360
|
exports.DEVELOPMENT_MODE = DEVELOPMENT_MODE;
|
|
361
|
+
exports.DotErrorContent = DotErrorContent;
|
|
362
|
+
exports.DotErrorNavigation = DotErrorNavigation;
|
|
363
|
+
exports.DotErrorPage = DotErrorPage;
|
|
364
|
+
exports.DotHttpError = DotHttpError;
|
|
126
365
|
exports.PRODUCTION_MODE = PRODUCTION_MODE;
|
package/index.esm.js
CHANGED
|
@@ -120,4 +120,238 @@ var UVEEventType;
|
|
|
120
120
|
UVEEventType["CONTENTLET_HOVERED"] = "contentlet-hovered";
|
|
121
121
|
})(UVEEventType || (UVEEventType = {}));
|
|
122
122
|
|
|
123
|
-
|
|
123
|
+
/* eslint-disable @typescript-eslint/no-explicit-any */
|
|
124
|
+
/**
|
|
125
|
+
* Page API specific error class
|
|
126
|
+
* Wraps HTTP errors and adds page-specific context including GraphQL information
|
|
127
|
+
*/
|
|
128
|
+
class DotErrorPage extends Error {
|
|
129
|
+
constructor(message, httpError, graphql) {
|
|
130
|
+
super(message);
|
|
131
|
+
this.name = 'DotCMSPageError';
|
|
132
|
+
this.httpError = httpError;
|
|
133
|
+
this.graphql = graphql;
|
|
134
|
+
// Ensure proper prototype chain for instanceof checks
|
|
135
|
+
Object.setPrototypeOf(this, DotErrorPage.prototype);
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* Serializes the error to a plain object for logging or transmission
|
|
139
|
+
*/
|
|
140
|
+
toJSON() {
|
|
141
|
+
return {
|
|
142
|
+
name: this.name,
|
|
143
|
+
message: this.message,
|
|
144
|
+
httpError: this.httpError?.toJSON(),
|
|
145
|
+
graphql: this.graphql,
|
|
146
|
+
stack: this.stack
|
|
147
|
+
};
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Standardized HTTP error class for all HTTP client implementations
|
|
153
|
+
*/
|
|
154
|
+
class DotHttpError extends Error {
|
|
155
|
+
constructor(details) {
|
|
156
|
+
super(details.message);
|
|
157
|
+
this.name = 'DotHttpError';
|
|
158
|
+
this.status = details.status;
|
|
159
|
+
this.statusText = details.statusText;
|
|
160
|
+
this.data = details.data;
|
|
161
|
+
// Ensure proper prototype chain for instanceof checks
|
|
162
|
+
Object.setPrototypeOf(this, DotHttpError.prototype);
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Serializes the error to a plain object for logging or transmission
|
|
166
|
+
*/
|
|
167
|
+
toJSON() {
|
|
168
|
+
return {
|
|
169
|
+
name: this.name,
|
|
170
|
+
message: this.message,
|
|
171
|
+
status: this.status,
|
|
172
|
+
statusText: this.statusText,
|
|
173
|
+
data: this.data,
|
|
174
|
+
stack: this.stack
|
|
175
|
+
};
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Abstract base class for HTTP client implementations.
|
|
180
|
+
* Provides common error handling utilities and enforces HttpError contract.
|
|
181
|
+
*
|
|
182
|
+
* @example
|
|
183
|
+
* ```typescript
|
|
184
|
+
* // Fetch API example
|
|
185
|
+
* export class FetchHttpClient extends BaseHttpClient {
|
|
186
|
+
* async request<T>(url: string, options?: DotRequestOptions): Promise<T> {
|
|
187
|
+
* try {
|
|
188
|
+
* const response = await fetch(url, options);
|
|
189
|
+
*
|
|
190
|
+
* if (!response.ok) {
|
|
191
|
+
* // Parse response body and headers
|
|
192
|
+
* let errorBody: string | unknown;
|
|
193
|
+
* try {
|
|
194
|
+
* const contentType = response.headers.get('content-type');
|
|
195
|
+
* if (contentType?.includes('application/json')) {
|
|
196
|
+
* errorBody = await response.json();
|
|
197
|
+
* } else {
|
|
198
|
+
* errorBody = await response.text();
|
|
199
|
+
* }
|
|
200
|
+
* } catch {
|
|
201
|
+
* errorBody = response.statusText;
|
|
202
|
+
* }
|
|
203
|
+
*
|
|
204
|
+
* const headers: Record<string, string> = {};
|
|
205
|
+
* response.headers.forEach((value, key) => {
|
|
206
|
+
* headers[key] = value;
|
|
207
|
+
* });
|
|
208
|
+
*
|
|
209
|
+
* throw this.createHttpError(
|
|
210
|
+
* response.status,
|
|
211
|
+
* response.statusText,
|
|
212
|
+
* headers,
|
|
213
|
+
* errorBody
|
|
214
|
+
* );
|
|
215
|
+
* }
|
|
216
|
+
*
|
|
217
|
+
* return response.json();
|
|
218
|
+
* } catch (error) {
|
|
219
|
+
* if (error instanceof TypeError) {
|
|
220
|
+
* throw this.createNetworkError(error);
|
|
221
|
+
* }
|
|
222
|
+
* throw error;
|
|
223
|
+
* }
|
|
224
|
+
* }
|
|
225
|
+
* }
|
|
226
|
+
*
|
|
227
|
+
* // Axios example
|
|
228
|
+
* export class AxiosHttpClient extends BaseHttpClient {
|
|
229
|
+
* async request<T>(url: string, options?: DotRequestOptions): Promise<T> {
|
|
230
|
+
* try {
|
|
231
|
+
* const response = await axios(url, options);
|
|
232
|
+
* return response.data;
|
|
233
|
+
* } catch (error) {
|
|
234
|
+
* if (axios.isAxiosError(error)) {
|
|
235
|
+
* throw this.createHttpError(
|
|
236
|
+
* error.response?.status || 0,
|
|
237
|
+
* error.response?.statusText || 'Network Error',
|
|
238
|
+
* error.response?.headers,
|
|
239
|
+
* error.response?.data
|
|
240
|
+
* );
|
|
241
|
+
* }
|
|
242
|
+
* throw this.createNetworkError(error);
|
|
243
|
+
* }
|
|
244
|
+
* }
|
|
245
|
+
* }
|
|
246
|
+
* ```
|
|
247
|
+
*/
|
|
248
|
+
class BaseHttpClient {
|
|
249
|
+
/**
|
|
250
|
+
* Creates a standardized HttpError from HTTP response details.
|
|
251
|
+
* Handles parsing of error response body automatically.
|
|
252
|
+
*
|
|
253
|
+
* @param status - HTTP status code
|
|
254
|
+
* @param statusText - HTTP status text
|
|
255
|
+
* @param headers - Response headers (optional)
|
|
256
|
+
* @param body - Response body (optional)
|
|
257
|
+
* @param customMessage - Optional custom error message
|
|
258
|
+
* @returns HttpError instance with parsed response data
|
|
259
|
+
*/
|
|
260
|
+
createHttpError(status, statusText, headers, body, customMessage) {
|
|
261
|
+
let errorData = body;
|
|
262
|
+
// If body is a string, try to parse as JSON
|
|
263
|
+
if (typeof body === 'string') {
|
|
264
|
+
try {
|
|
265
|
+
const contentType = headers?.['content-type'] || headers?.['Content-Type'];
|
|
266
|
+
if (contentType?.includes('application/json')) {
|
|
267
|
+
errorData = JSON.parse(body);
|
|
268
|
+
} else {
|
|
269
|
+
errorData = body;
|
|
270
|
+
}
|
|
271
|
+
} catch {
|
|
272
|
+
errorData = body;
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
return new DotHttpError({
|
|
276
|
+
status,
|
|
277
|
+
statusText,
|
|
278
|
+
message: customMessage || `HTTP ${status}: ${statusText}`,
|
|
279
|
+
data: errorData
|
|
280
|
+
});
|
|
281
|
+
}
|
|
282
|
+
/**
|
|
283
|
+
* Creates a standardized HttpError for network/connection errors.
|
|
284
|
+
*
|
|
285
|
+
* @param originalError - The original network error
|
|
286
|
+
* @returns HttpError instance representing a network error
|
|
287
|
+
*/
|
|
288
|
+
createNetworkError(originalError) {
|
|
289
|
+
return new DotHttpError({
|
|
290
|
+
status: 0,
|
|
291
|
+
// Network error status
|
|
292
|
+
statusText: 'Network Error',
|
|
293
|
+
message: `Network error: ${originalError.message}`,
|
|
294
|
+
data: originalError
|
|
295
|
+
});
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
/**
|
|
300
|
+
* Content API specific error class
|
|
301
|
+
* Wraps HTTP errors and adds content-specific context including query information
|
|
302
|
+
*/
|
|
303
|
+
class DotErrorContent extends Error {
|
|
304
|
+
constructor(message, contentType, operation, httpError, query) {
|
|
305
|
+
super(message);
|
|
306
|
+
this.name = 'DotCMSContentError';
|
|
307
|
+
this.contentType = contentType;
|
|
308
|
+
this.operation = operation;
|
|
309
|
+
this.httpError = httpError;
|
|
310
|
+
this.query = query;
|
|
311
|
+
// Ensure proper prototype chain for instanceof checks
|
|
312
|
+
Object.setPrototypeOf(this, DotErrorContent.prototype);
|
|
313
|
+
}
|
|
314
|
+
/**
|
|
315
|
+
* Serializes the error to a plain object for logging or transmission
|
|
316
|
+
*/
|
|
317
|
+
toJSON() {
|
|
318
|
+
return {
|
|
319
|
+
name: this.name,
|
|
320
|
+
message: this.message,
|
|
321
|
+
contentType: this.contentType,
|
|
322
|
+
operation: this.operation,
|
|
323
|
+
httpError: this.httpError?.toJSON(),
|
|
324
|
+
query: this.query,
|
|
325
|
+
stack: this.stack
|
|
326
|
+
};
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/**
|
|
331
|
+
* Navigation API specific error class
|
|
332
|
+
* Wraps HTTP errors and adds navigation-specific context
|
|
333
|
+
*/
|
|
334
|
+
class DotErrorNavigation extends Error {
|
|
335
|
+
constructor(message, path, httpError) {
|
|
336
|
+
super(message);
|
|
337
|
+
this.name = 'DotNavigationError';
|
|
338
|
+
this.path = path;
|
|
339
|
+
this.httpError = httpError;
|
|
340
|
+
// Ensure proper prototype chain for instanceof checks
|
|
341
|
+
Object.setPrototypeOf(this, DotErrorNavigation.prototype);
|
|
342
|
+
}
|
|
343
|
+
/**
|
|
344
|
+
* Serializes the error to a plain object for logging or transmission
|
|
345
|
+
*/
|
|
346
|
+
toJSON() {
|
|
347
|
+
return {
|
|
348
|
+
name: this.name,
|
|
349
|
+
message: this.message,
|
|
350
|
+
path: this.path,
|
|
351
|
+
httpError: this.httpError?.toJSON(),
|
|
352
|
+
stack: this.stack
|
|
353
|
+
};
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
export { BaseHttpClient, DEVELOPMENT_MODE, DotCMSUVEAction, DotErrorContent, DotErrorNavigation, DotErrorPage, DotHttpError, PRODUCTION_MODE, UVEEventType, UVE_MODE };
|
package/package.json
CHANGED
package/src/index.d.ts
CHANGED
|
@@ -1,4 +1,189 @@
|
|
|
1
1
|
import { UVE_MODE } from '../editor/public';
|
|
2
|
+
/**
|
|
3
|
+
* Standardized HTTP error details
|
|
4
|
+
*/
|
|
5
|
+
export interface HttpErrorDetails {
|
|
6
|
+
status: number;
|
|
7
|
+
statusText: string;
|
|
8
|
+
message: string;
|
|
9
|
+
data?: unknown;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Standardized HTTP error class for all HTTP client implementations
|
|
13
|
+
*/
|
|
14
|
+
export declare class DotHttpError extends Error implements HttpErrorDetails {
|
|
15
|
+
status: number;
|
|
16
|
+
statusText: string;
|
|
17
|
+
data?: unknown;
|
|
18
|
+
constructor(details: HttpErrorDetails);
|
|
19
|
+
/**
|
|
20
|
+
* Serializes the error to a plain object for logging or transmission
|
|
21
|
+
*/
|
|
22
|
+
toJSON(): {
|
|
23
|
+
name: string;
|
|
24
|
+
message: string;
|
|
25
|
+
status: number;
|
|
26
|
+
statusText: string;
|
|
27
|
+
data: unknown;
|
|
28
|
+
stack: string | undefined;
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Interface for HTTP client implementations.
|
|
33
|
+
* Allows the SDK to work with different HTTP libraries.
|
|
34
|
+
*
|
|
35
|
+
* @important IMPLEMENTATION REQUIREMENTS:
|
|
36
|
+
* - ALL implementations MUST throw HttpError instances for failed requests
|
|
37
|
+
* - NEVER throw generic Error or other error types
|
|
38
|
+
* - Include response status, statusText, and message in HttpError
|
|
39
|
+
* - Attempt to parse error response body and include in HttpError.data
|
|
40
|
+
* - Handle network errors by wrapping them in HttpError (use createNetworkError helper)
|
|
41
|
+
*
|
|
42
|
+
* @example
|
|
43
|
+
* ```typescript
|
|
44
|
+
* // CORRECT - Throws HttpError
|
|
45
|
+
* if (!response.ok) {
|
|
46
|
+
* throw new HttpError({
|
|
47
|
+
* status: response.status,
|
|
48
|
+
* statusText: response.statusText,
|
|
49
|
+
* message: `Request failed: ${response.status}`,
|
|
50
|
+
* data: await response.json()
|
|
51
|
+
* });
|
|
52
|
+
* }
|
|
53
|
+
*
|
|
54
|
+
* // WRONG - Throws generic Error
|
|
55
|
+
* if (!response.ok) {
|
|
56
|
+
* throw new Error(`HTTP ${response.status}`);
|
|
57
|
+
* }
|
|
58
|
+
* ```
|
|
59
|
+
*/
|
|
60
|
+
export interface DotHttpClient {
|
|
61
|
+
/**
|
|
62
|
+
* Makes an HTTP request.
|
|
63
|
+
*
|
|
64
|
+
* @template T - The expected response type
|
|
65
|
+
* @param url - The URL to request
|
|
66
|
+
* @param options - Request options (method, headers, body, etc.)
|
|
67
|
+
* @returns A promise that resolves with the response data
|
|
68
|
+
* @throws {DotHttpError} When the request fails (non-2xx status or network error)
|
|
69
|
+
*
|
|
70
|
+
* @important IMPLEMENTATION REQUIREMENTS:
|
|
71
|
+
* - MUST throw DotHttpError instances for failed requests, never generic Error objects
|
|
72
|
+
* - Include response status, statusText, and message in DotHttpError
|
|
73
|
+
* - Attempt to parse error response body and include in DotHttpError.data
|
|
74
|
+
* - Handle network errors by wrapping them in DotHttpError
|
|
75
|
+
* - Consumers expect DotHttpError with status, statusText, and data properties for proper error handling
|
|
76
|
+
*/
|
|
77
|
+
request<T = unknown>(url: string, options?: DotRequestOptions): Promise<T>;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Abstract base class for HTTP client implementations.
|
|
81
|
+
* Provides common error handling utilities and enforces HttpError contract.
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* ```typescript
|
|
85
|
+
* // Fetch API example
|
|
86
|
+
* export class FetchHttpClient extends BaseHttpClient {
|
|
87
|
+
* async request<T>(url: string, options?: DotRequestOptions): Promise<T> {
|
|
88
|
+
* try {
|
|
89
|
+
* const response = await fetch(url, options);
|
|
90
|
+
*
|
|
91
|
+
* if (!response.ok) {
|
|
92
|
+
* // Parse response body and headers
|
|
93
|
+
* let errorBody: string | unknown;
|
|
94
|
+
* try {
|
|
95
|
+
* const contentType = response.headers.get('content-type');
|
|
96
|
+
* if (contentType?.includes('application/json')) {
|
|
97
|
+
* errorBody = await response.json();
|
|
98
|
+
* } else {
|
|
99
|
+
* errorBody = await response.text();
|
|
100
|
+
* }
|
|
101
|
+
* } catch {
|
|
102
|
+
* errorBody = response.statusText;
|
|
103
|
+
* }
|
|
104
|
+
*
|
|
105
|
+
* const headers: Record<string, string> = {};
|
|
106
|
+
* response.headers.forEach((value, key) => {
|
|
107
|
+
* headers[key] = value;
|
|
108
|
+
* });
|
|
109
|
+
*
|
|
110
|
+
* throw this.createHttpError(
|
|
111
|
+
* response.status,
|
|
112
|
+
* response.statusText,
|
|
113
|
+
* headers,
|
|
114
|
+
* errorBody
|
|
115
|
+
* );
|
|
116
|
+
* }
|
|
117
|
+
*
|
|
118
|
+
* return response.json();
|
|
119
|
+
* } catch (error) {
|
|
120
|
+
* if (error instanceof TypeError) {
|
|
121
|
+
* throw this.createNetworkError(error);
|
|
122
|
+
* }
|
|
123
|
+
* throw error;
|
|
124
|
+
* }
|
|
125
|
+
* }
|
|
126
|
+
* }
|
|
127
|
+
*
|
|
128
|
+
* // Axios example
|
|
129
|
+
* export class AxiosHttpClient extends BaseHttpClient {
|
|
130
|
+
* async request<T>(url: string, options?: DotRequestOptions): Promise<T> {
|
|
131
|
+
* try {
|
|
132
|
+
* const response = await axios(url, options);
|
|
133
|
+
* return response.data;
|
|
134
|
+
* } catch (error) {
|
|
135
|
+
* if (axios.isAxiosError(error)) {
|
|
136
|
+
* throw this.createHttpError(
|
|
137
|
+
* error.response?.status || 0,
|
|
138
|
+
* error.response?.statusText || 'Network Error',
|
|
139
|
+
* error.response?.headers,
|
|
140
|
+
* error.response?.data
|
|
141
|
+
* );
|
|
142
|
+
* }
|
|
143
|
+
* throw this.createNetworkError(error);
|
|
144
|
+
* }
|
|
145
|
+
* }
|
|
146
|
+
* }
|
|
147
|
+
* ```
|
|
148
|
+
*/
|
|
149
|
+
export declare abstract class BaseHttpClient implements DotHttpClient {
|
|
150
|
+
/**
|
|
151
|
+
* Makes an HTTP request.
|
|
152
|
+
*
|
|
153
|
+
* @template T - The expected response type
|
|
154
|
+
* @param url - The URL to request
|
|
155
|
+
* @param options - Request options (method, headers, body, etc.)
|
|
156
|
+
* @returns A promise that resolves with the response data
|
|
157
|
+
* @throws {DotHttpError} When the request fails (non-2xx status or network error)
|
|
158
|
+
*
|
|
159
|
+
* @important IMPLEMENTATION REQUIREMENTS:
|
|
160
|
+
* - MUST throw DotHttpError instances for failed requests, never generic Error objects
|
|
161
|
+
* - Include response status, statusText, and message in DotHttpError
|
|
162
|
+
* - Attempt to parse error response body and include in DotHttpError.data
|
|
163
|
+
* - Handle network errors by wrapping them in DotHttpError using createNetworkError()
|
|
164
|
+
* - Use createHttpError() helper for HTTP response errors
|
|
165
|
+
*/
|
|
166
|
+
abstract request<T = unknown>(url: string, options?: DotRequestOptions): Promise<T>;
|
|
167
|
+
/**
|
|
168
|
+
* Creates a standardized HttpError from HTTP response details.
|
|
169
|
+
* Handles parsing of error response body automatically.
|
|
170
|
+
*
|
|
171
|
+
* @param status - HTTP status code
|
|
172
|
+
* @param statusText - HTTP status text
|
|
173
|
+
* @param headers - Response headers (optional)
|
|
174
|
+
* @param body - Response body (optional)
|
|
175
|
+
* @param customMessage - Optional custom error message
|
|
176
|
+
* @returns HttpError instance with parsed response data
|
|
177
|
+
*/
|
|
178
|
+
protected createHttpError(status: number, statusText: string, headers?: Record<string, string>, body?: string | unknown, customMessage?: string): DotHttpError;
|
|
179
|
+
/**
|
|
180
|
+
* Creates a standardized HttpError for network/connection errors.
|
|
181
|
+
*
|
|
182
|
+
* @param originalError - The original network error
|
|
183
|
+
* @returns HttpError instance representing a network error
|
|
184
|
+
*/
|
|
185
|
+
protected createNetworkError(originalError: Error): DotHttpError;
|
|
186
|
+
}
|
|
2
187
|
/**
|
|
3
188
|
* The GraphQL parameters for a page request.
|
|
4
189
|
* @public
|
|
@@ -75,9 +260,31 @@ export interface DotCMSPageRequestParams {
|
|
|
75
260
|
graphql?: DotCMSGraphQLParams;
|
|
76
261
|
}
|
|
77
262
|
/**
|
|
78
|
-
* Options for configuring
|
|
263
|
+
* Options for configuring HTTP requests in the DotCMS client.
|
|
264
|
+
*
|
|
265
|
+
* Extends the native `RequestInit` interface from the Fetch API, providing all standard
|
|
266
|
+
* fetch options including headers, credentials, cache settings, and more. This type is
|
|
267
|
+
* used throughout the DotCMS client for configuring HTTP requests consistently.
|
|
268
|
+
*
|
|
269
|
+
* @example
|
|
270
|
+
* ```typescript
|
|
271
|
+
* const options: DotRequestOptions = {
|
|
272
|
+
* method: 'POST',
|
|
273
|
+
* headers: {
|
|
274
|
+
* 'Content-Type': 'application/json',
|
|
275
|
+
* 'Authorization': 'Bearer your-token'
|
|
276
|
+
* },
|
|
277
|
+
* body: JSON.stringify({ name: 'John' }),
|
|
278
|
+
* credentials: 'include',
|
|
279
|
+
* cache: 'no-cache'
|
|
280
|
+
* };
|
|
281
|
+
*
|
|
282
|
+
* const result = await httpClient.request('/api/content', options);
|
|
283
|
+
* ```
|
|
284
|
+
*
|
|
285
|
+
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options RequestInit} - MDN documentation for RequestInit
|
|
79
286
|
*/
|
|
80
|
-
export type
|
|
287
|
+
export type DotRequestOptions = RequestInit;
|
|
81
288
|
/**
|
|
82
289
|
* Configuration options for the DotCMS client.
|
|
83
290
|
*/
|
|
@@ -101,25 +308,11 @@ export interface DotCMSClientConfig {
|
|
|
101
308
|
* Additional options for the fetch request.
|
|
102
309
|
* @example `{ headers: { 'Content-Type': 'application/json' } }`
|
|
103
310
|
*/
|
|
104
|
-
requestOptions?:
|
|
105
|
-
}
|
|
106
|
-
/**
|
|
107
|
-
* The parameters for the Navigation API.
|
|
108
|
-
* @public
|
|
109
|
-
*/
|
|
110
|
-
export interface DotCMSNavigationRequestParams {
|
|
311
|
+
requestOptions?: DotRequestOptions;
|
|
111
312
|
/**
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
* `
|
|
115
|
-
* `2` returns the element specified in the path, and if that element is a folder, returns all direct children of that folder.
|
|
116
|
-
* `3` returns all children and grandchildren of the element specified in the path.
|
|
117
|
-
*/
|
|
118
|
-
depth?: number;
|
|
119
|
-
/**
|
|
120
|
-
* The language ID of content to return.
|
|
121
|
-
* @example
|
|
122
|
-
* `1` (or unspecified) returns content in the default language of the site.
|
|
313
|
+
* Custom HTTP client implementation.
|
|
314
|
+
* If not provided, the default FetchHttpClient will be used.
|
|
315
|
+
* @example `{ httpClient: new AxiosHttpClient() }`
|
|
123
316
|
*/
|
|
124
|
-
|
|
317
|
+
httpClient?: DotHttpClient;
|
|
125
318
|
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { DotHttpError } from '../client/public';
|
|
2
|
+
/**
|
|
3
|
+
* Content API specific error class
|
|
4
|
+
* Wraps HTTP errors and adds content-specific context including query information
|
|
5
|
+
*/
|
|
6
|
+
export declare class DotErrorContent extends Error {
|
|
7
|
+
readonly httpError?: DotHttpError;
|
|
8
|
+
readonly contentType: string;
|
|
9
|
+
readonly operation: string;
|
|
10
|
+
readonly query?: string;
|
|
11
|
+
constructor(message: string, contentType: string, operation: string, httpError?: DotHttpError, query?: string);
|
|
12
|
+
/**
|
|
13
|
+
* Serializes the error to a plain object for logging or transmission
|
|
14
|
+
*/
|
|
15
|
+
toJSON(): {
|
|
16
|
+
name: string;
|
|
17
|
+
message: string;
|
|
18
|
+
contentType: string;
|
|
19
|
+
operation: string;
|
|
20
|
+
httpError: {
|
|
21
|
+
name: string;
|
|
22
|
+
message: string;
|
|
23
|
+
status: number;
|
|
24
|
+
statusText: string;
|
|
25
|
+
data: unknown;
|
|
26
|
+
stack: string | undefined;
|
|
27
|
+
} | undefined;
|
|
28
|
+
query: string | undefined;
|
|
29
|
+
stack: string | undefined;
|
|
30
|
+
};
|
|
31
|
+
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { DotHttpError } from '../client/public';
|
|
2
|
+
/**
|
|
3
|
+
* Navigation API specific error class
|
|
4
|
+
* Wraps HTTP errors and adds navigation-specific context
|
|
5
|
+
*/
|
|
6
|
+
export declare class DotErrorNavigation extends Error {
|
|
7
|
+
readonly httpError?: DotHttpError;
|
|
8
|
+
readonly path: string;
|
|
9
|
+
constructor(message: string, path: string, httpError?: DotHttpError);
|
|
10
|
+
/**
|
|
11
|
+
* Serializes the error to a plain object for logging or transmission
|
|
12
|
+
*/
|
|
13
|
+
toJSON(): {
|
|
14
|
+
name: string;
|
|
15
|
+
message: string;
|
|
16
|
+
path: string;
|
|
17
|
+
httpError: {
|
|
18
|
+
name: string;
|
|
19
|
+
message: string;
|
|
20
|
+
status: number;
|
|
21
|
+
statusText: string;
|
|
22
|
+
data: unknown;
|
|
23
|
+
stack: string | undefined;
|
|
24
|
+
} | undefined;
|
|
25
|
+
stack: string | undefined;
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* The parameters for the Navigation API.
|
|
30
|
+
* @public
|
|
31
|
+
*/
|
|
32
|
+
export interface DotCMSNavigationRequestParams {
|
|
33
|
+
/**
|
|
34
|
+
* The depth of the folder tree to return.
|
|
35
|
+
* @example
|
|
36
|
+
* `1` returns only the element specified in the path.
|
|
37
|
+
* `2` returns the element specified in the path, and if that element is a folder, returns all direct children of that folder.
|
|
38
|
+
* `3` returns all children and grandchildren of the element specified in the path.
|
|
39
|
+
*/
|
|
40
|
+
depth?: number;
|
|
41
|
+
/**
|
|
42
|
+
* The language ID of content to return.
|
|
43
|
+
* @example
|
|
44
|
+
* `1` (or unspecified) returns content in the default language of the site.
|
|
45
|
+
*/
|
|
46
|
+
languageId?: number;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Represents a navigation item in the DotCMS navigation structure
|
|
50
|
+
*
|
|
51
|
+
* @interface DotCMSNavigationItem
|
|
52
|
+
* @property {string} [code] - Optional unique code identifier for the navigation item
|
|
53
|
+
* @property {string} folder - The folder path where this navigation item is located
|
|
54
|
+
* @property {DotCMSNavigationItem[]} [children] - Optional array of child navigation items
|
|
55
|
+
* @property {string} host - The host/site this navigation item belongs to
|
|
56
|
+
* @property {number} languageId - The language ID for this navigation item
|
|
57
|
+
* @property {string} href - The URL/link that this navigation item points to
|
|
58
|
+
* @property {string} title - The display title of the navigation item
|
|
59
|
+
* @property {string} type - The type of navigation item
|
|
60
|
+
* @property {number} hash - Hash value for the navigation item
|
|
61
|
+
* @property {string} target - The target attribute for the link (e.g. "_blank", "_self")
|
|
62
|
+
* @property {number} order - The sort order position of this item in the navigation
|
|
63
|
+
*/
|
|
64
|
+
export interface DotCMSNavigationItem {
|
|
65
|
+
code?: string;
|
|
66
|
+
folder: string;
|
|
67
|
+
children?: DotCMSNavigationItem[];
|
|
68
|
+
host: string;
|
|
69
|
+
languageId: number;
|
|
70
|
+
href: string;
|
|
71
|
+
title: string;
|
|
72
|
+
type: string;
|
|
73
|
+
hash: number;
|
|
74
|
+
target: string;
|
|
75
|
+
order: number;
|
|
76
|
+
}
|
package/src/lib/page/public.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { DotHttpError } from '../client/public';
|
|
1
2
|
/**
|
|
2
3
|
* Represents a map of container identifiers to their container objects
|
|
3
4
|
*
|
|
@@ -365,35 +366,6 @@ export interface DotCMSBasicContentlet {
|
|
|
365
366
|
__icon__?: string;
|
|
366
367
|
_map?: Record<string, unknown>;
|
|
367
368
|
}
|
|
368
|
-
/**
|
|
369
|
-
* Represents a navigation item in the DotCMS navigation structure
|
|
370
|
-
*
|
|
371
|
-
* @interface DotCMSNavigationItem
|
|
372
|
-
* @property {string} [code] - Optional unique code identifier for the navigation item
|
|
373
|
-
* @property {string} folder - The folder path where this navigation item is located
|
|
374
|
-
* @property {DotCMSNavigationItem[]} [children] - Optional array of child navigation items
|
|
375
|
-
* @property {string} host - The host/site this navigation item belongs to
|
|
376
|
-
* @property {number} languageId - The language ID for this navigation item
|
|
377
|
-
* @property {string} href - The URL/link that this navigation item points to
|
|
378
|
-
* @property {string} title - The display title of the navigation item
|
|
379
|
-
* @property {string} type - The type of navigation item
|
|
380
|
-
* @property {number} hash - Hash value for the navigation item
|
|
381
|
-
* @property {string} target - The target attribute for the link (e.g. "_blank", "_self")
|
|
382
|
-
* @property {number} order - The sort order position of this item in the navigation
|
|
383
|
-
*/
|
|
384
|
-
export interface DotCMSNavigationItem {
|
|
385
|
-
code?: string;
|
|
386
|
-
folder: string;
|
|
387
|
-
children?: DotCMSNavigationItem[];
|
|
388
|
-
host: string;
|
|
389
|
-
languageId: number;
|
|
390
|
-
href: string;
|
|
391
|
-
title: string;
|
|
392
|
-
type: string;
|
|
393
|
-
hash: number;
|
|
394
|
-
target: string;
|
|
395
|
-
order: number;
|
|
396
|
-
}
|
|
397
369
|
/**
|
|
398
370
|
* Represents a template in DotCMS that defines the layout and structure of pages
|
|
399
371
|
*
|
|
@@ -1143,6 +1115,16 @@ export interface DotCMSPageContainerContentlets {
|
|
|
1143
1115
|
uuid: string;
|
|
1144
1116
|
contentlets: DotCMSBasicContentlet[];
|
|
1145
1117
|
}
|
|
1118
|
+
/**
|
|
1119
|
+
* dotCMS's GraphQL API response with a page and content query
|
|
1120
|
+
*/
|
|
1121
|
+
export interface DotGraphQLApiResponse {
|
|
1122
|
+
data: {
|
|
1123
|
+
page: DotCMSGraphQLPage;
|
|
1124
|
+
content?: Record<string, unknown>;
|
|
1125
|
+
};
|
|
1126
|
+
errors?: DotCMSGraphQLError[];
|
|
1127
|
+
}
|
|
1146
1128
|
/**
|
|
1147
1129
|
* Represents a GraphQL error
|
|
1148
1130
|
* @interface DotCMSGraphQLError
|
|
@@ -1157,18 +1139,6 @@ export interface DotCMSGraphQLError {
|
|
|
1157
1139
|
classification: string;
|
|
1158
1140
|
};
|
|
1159
1141
|
}
|
|
1160
|
-
/**
|
|
1161
|
-
* Represents the complete response from a page query from the GraphQL API
|
|
1162
|
-
*/
|
|
1163
|
-
export interface DotCMSGraphQLPageResponse {
|
|
1164
|
-
page: DotCMSGraphQLPage;
|
|
1165
|
-
content?: Record<string, unknown> | unknown;
|
|
1166
|
-
errors?: DotCMSGraphQLError;
|
|
1167
|
-
graphql: {
|
|
1168
|
-
query: string;
|
|
1169
|
-
variables: Record<string, unknown>;
|
|
1170
|
-
};
|
|
1171
|
-
}
|
|
1172
1142
|
/**
|
|
1173
1143
|
* Represents the complete response from a page query
|
|
1174
1144
|
*/
|
|
@@ -1189,4 +1159,39 @@ export type DotCMSComposedPageResponse<T extends DotCMSExtendedPageResponse> = O
|
|
|
1189
1159
|
content?: DotCMSComposedContent<T>;
|
|
1190
1160
|
};
|
|
1191
1161
|
export type DotCMSClientPageGetResponse<T extends DotCMSExtendedPageResponse> = Promise<DotCMSComposedPageResponse<T>>;
|
|
1162
|
+
/**
|
|
1163
|
+
* Page API specific error class
|
|
1164
|
+
* Wraps HTTP errors and adds page-specific context including GraphQL information
|
|
1165
|
+
*/
|
|
1166
|
+
export declare class DotErrorPage extends Error {
|
|
1167
|
+
readonly httpError?: DotHttpError;
|
|
1168
|
+
readonly graphql?: {
|
|
1169
|
+
query: string;
|
|
1170
|
+
variables: Record<string, unknown>;
|
|
1171
|
+
};
|
|
1172
|
+
constructor(message: string, httpError?: DotHttpError, graphql?: {
|
|
1173
|
+
query: string;
|
|
1174
|
+
variables: Record<string, unknown>;
|
|
1175
|
+
});
|
|
1176
|
+
/**
|
|
1177
|
+
* Serializes the error to a plain object for logging or transmission
|
|
1178
|
+
*/
|
|
1179
|
+
toJSON(): {
|
|
1180
|
+
name: string;
|
|
1181
|
+
message: string;
|
|
1182
|
+
httpError: {
|
|
1183
|
+
name: string;
|
|
1184
|
+
message: string;
|
|
1185
|
+
status: number;
|
|
1186
|
+
statusText: string;
|
|
1187
|
+
data: unknown;
|
|
1188
|
+
stack: string | undefined;
|
|
1189
|
+
} | undefined;
|
|
1190
|
+
graphql: {
|
|
1191
|
+
query: string;
|
|
1192
|
+
variables: Record<string, unknown>;
|
|
1193
|
+
} | undefined;
|
|
1194
|
+
stack: string | undefined;
|
|
1195
|
+
};
|
|
1196
|
+
}
|
|
1192
1197
|
export {};
|