@dotcms/client 0.0.1-alpha.37 → 0.0.1-alpha.39

package/src/lib/client/content/shared/types.ts

@@ -0,0 +1,155 @@
+import { Equals } from '../../../query-builder/lucene-syntax';
+import { QueryBuilder } from '../../../query-builder/sdk-query-builder';
+
+/**
+ * Model to sort by fields.
+ */
+export type SortBy = {
+    /**
+     * The field to sort by.
+     */
+    field: string;
+    /**
+     * The order of sorting: 'asc' for ascending, 'desc' for descending.
+     */
+    order: 'asc' | 'desc';
+};
+
+/**
+ * Callback to build a query.
+ *
+ * @callback BuildQuery
+ * @param {QueryBuilder} qb - The query builder instance.
+ * @returns {Equals} The built query.
+ */
+export type BuildQuery = (qb: QueryBuilder) => Equals;
+
+/**
+ * Main fields of a Contentlet (Inherited from the Content Type).
+ */
+export interface ContentTypeMainFields {
+    hostName: string;
+    modDate: string;
+    publishDate: string;
+    title: string;
+    baseType: string;
+    inode: string;
+    archived: boolean;
+    ownerName: string;
+    host: string;
+    working: boolean;
+    locked: boolean;
+    stInode: string;
+    contentType: string;
+    live: boolean;
+    owner: string;
+    identifier: string;
+    publishUserName: string;
+    publishUser: string;
+    languageId: number;
+    creationDate: string;
+    url: string;
+    titleImage: string;
+    modUserName: string;
+    hasLiveVersion: boolean;
+    folder: string;
+    hasTitleImage: boolean;
+    sortOrder: number;
+    modUser: string;
+    __icon__: string;
+    contentTypeIcon: string;
+    variant: string;
+}
+
+/**
+ * The contentlet has the main fields and the custom fields of the content type.
+ *
+ * @template T - The custom fields of the content type.
+ */
+export type Contentlet<T> = T & ContentTypeMainFields;
+
+/**
+ * Callback for a fulfilled promise.
+ *
+ * @template T - The type of the response.
+ * @callback OnFullfilled
+ * @param {GetCollectionResponse<T>} value - The response value.
+ * @returns {GetCollectionResponse<T> | PromiseLike<GetCollectionResponse<T>> | void} The processed response or a promise.
+ */
+export type OnFullfilled<T> =
+    | ((
+          value: GetCollectionResponse<T>
+      ) => GetCollectionResponse<T> | PromiseLike<GetCollectionResponse<T>> | void)
+    | undefined
+    | null;
+
+/**
+ * Callback for a rejected promise.
+ *
+ * @callback OnRejected
+ * @param {GetCollectionError} error - The error object.
+ * @returns {GetCollectionError | PromiseLike<GetCollectionError> | void} The processed error or a promise.
+ */
+export type OnRejected =
+    | ((error: GetCollectionError) => GetCollectionError | PromiseLike<GetCollectionError> | void)
+    | undefined
+    | null;
+
+/**
+ * Response of the get collection method.
+ *
+ * @template T - The type of the contentlet.
+ */
+export interface GetCollectionResponse<T> {
+    /**
+     * The list of contentlets.
+     */
+    contentlets: Contentlet<T>[];
+    /**
+     * The current page number.
+     */
+    page: number;
+    /**
+     * The size of the page.
+     */
+    size: number;
+    /**
+     * The total number of contentlets.
+     */
+    total: number;
+    /**
+     * The fields by which the contentlets are sorted.
+     */
+    sortedBy?: SortBy[];
+}
+
+/**
+ * Raw response of the get collection method.
+ *
+ * @template T - The type of the contentlet.
+ */
+export interface GetCollectionRawResponse<T> {
+    entity: {
+        jsonObjectView: {
+            /**
+             * The list of contentlets.
+             */
+            contentlets: Contentlet<T>[];
+        };
+        /**
+         * The size of the results.
+         */
+        resultsSize: number;
+    };
+}
+
+/**
+ * Error object for the get collection method.
+ */
+export interface GetCollectionError {
+    /**
+     * The status code of the error.
+     */
+    status: number;
+    [key: string]: unknown;
+}

package/src/lib/client/content/shared/utils.ts

@@ -0,0 +1,28 @@
+import { CONTENT_TYPE_MAIN_FIELDS } from './const';
+
+/**
+ * @description
+ * Sanitizes the query for the given content type.
+ * It replaces the fields that are not content type fields with the correct format.
+ * Example: +field: -> +contentTypeVar.field:
+ *
+ * @example
+ *
+ * ```ts
+ * const query = '+field: value';
+ * const contentType = 'contentTypeVar';
+ * const sanitizedQuery = sanitizeQueryForContentType(query, contentType); // Output: '+contentTypeVar.field: value'
+ * ```
+ *
+ * @export
+ * @param {string} query - The query string to be sanitized.
+ * @param {string} contentType - The content type to be used for formatting the fields.
+ * @returns {string} The sanitized query string.
+ */
+export function sanitizeQueryForContentType(query: string, contentType: string): string {
+    return query.replace(/\+([^+:]*?):/g, (original, field) => {
+        return !CONTENT_TYPE_MAIN_FIELDS.includes(field) // Fields that are not content type fields
+            ? `+${contentType}.${field}:` // Should have this format: +contentTypeVar.field:
+            : original; // Return the field if it is a content type field
+    });
+}

package/src/lib/client/models/index.ts

@@ -0,0 +1,19 @@
+/**
+ * A record of HTTP status codes and their corresponding error messages.
+ *
+ * @type {Record<number, string>}
+ * @property {string} 401 - Unauthorized. Check the token and try again.
+ * @property {string} 403 - Forbidden. Check the permissions and try again.
+ * @property {string} 404 - Not Found. Check the URL and try again.
+ * @property {string} 500 - Internal Server Error. Try again later.
+ * @property {string} 502 - Bad Gateway. Try again later.
+ * @property {string} 503 - Service Unavailable. Try again later.
+ */
+export const ErrorMessages: Record<number, string> = {
+    401: 'Unauthorized. Check the token and try again.',
+    403: 'Forbidden. Check the permissions and try again.',
+    404: 'Not Found. Check the URL and try again.',
+    500: 'Internal Server Error. Try again later.',
+    502: 'Bad Gateway. Try again later.',
+    503: 'Service Unavailable. Try again later.'
+};

package/src/lib/client/models/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Represents a listener for DotcmsClientListener.
+ *
+ * @typedef {Object} DotcmsClientListener
+ * @property {string} action - The action that triggers the event.
+ * @property {string} event - The name of the event.
+ * @property {function(...args: any[]): void} callback - The callback function to handle the event.
+ */
+export type DotcmsClientListener = {
+    action: string;
+    event: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    callback: (...args: any[]) => void;
+};

package/src/lib/client/sdk-js-client.spec.ts

@@ -0,0 +1,483 @@
+/// <reference types="jest" />
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Content } from './content/content-api';
+import { ClientConfig, DotCmsClient } from './sdk-js-client';
+
+import * as dotcmsEditor from '../editor/sdk-editor';
+
+global.fetch = jest.fn();
+
+class TestDotCmsClient extends DotCmsClient {
+    /**
+     * Override the init method to test the static method
+     * Allows to test Singleton pattern with different configurations
+     *
+     * @param {*} config
+     * @return {*}
+     * @memberof TestDotCmsClient
+     */
+    static override init(config: ClientConfig) {
+        return (this.instance = new TestDotCmsClient(config));
+    }
+}
+
+// Utility function to mock fetch responses
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const mockFetchResponse = (body: any, ok = true, status = 200) => {
+    (fetch as jest.Mock).mockImplementationOnce(() =>
+        Promise.resolve({
+            ok,
+            status,
+            json: () => Promise.resolve(body)
+        })
+    );
+};
+
+describe('DotCmsClient', () => {
+    describe('with full configuration', () => {
+        let client: TestDotCmsClient;
+        let isInsideEditorSpy: jest.SpyInstance<boolean>;
+
+        beforeEach(() => {
+            (fetch as jest.Mock).mockClear();
+
+            client = TestDotCmsClient.init({
+                dotcmsUrl: 'http://localhost',
+                siteId: '123456',
+                authToken: 'ABC'
+            });
+
+            isInsideEditorSpy = jest.spyOn(dotcmsEditor, 'isInsideEditor');
+        });
+
+        describe('init', () => {
+            it('should initialize with valid configuration', () => {
+                const config = {
+                    dotcmsUrl: 'https://example.com',
+                    siteId: '123456',
+                    authToken: 'ABC'
+                };
+
+                const client = TestDotCmsClient.init(config);
+                expect(client).toBeDefined();
+            });
+
+            it('should throw error on missing dotcmsUrl', () => {
+                const config = {
+                    dotcmsUrl: '',
+                    siteId: '123456',
+                    authToken: 'ABC'
+                };
+
+                expect(() => {
+                    TestDotCmsClient.init(config);
+                }).toThrow("Invalid configuration - 'dotcmsUrl' is required");
+            });
+
+            it('should throw error if dotcmsUrl is not a valid URL', () => {
+                const config = {
+                    dotcmsUrl: '//example.com',
+                    siteId: '123456',
+                    authToken: 'ABC'
+                };
+
+                expect(() => {
+                    TestDotCmsClient.init(config);
+                }).toThrow("Invalid configuration - 'dotcmsUrl' must be a valid URL");
+            });
+
+            it('should throw error on missing authToken', () => {
+                const config = {
+                    dotcmsUrl: 'https://example.com',
+                    siteId: '123456',
+                    authToken: ''
+                };
+
+                expect(() => {
+                    TestDotCmsClient.init(config);
+                }).toThrow("Invalid configuration - 'authToken' is required");
+            });
+
+            it('should use a clean dotcmsUrl when passing an slash at the end', async () => {
+                const config = {
+                    dotcmsUrl: 'https://example.com/',
+                    siteId: '123456',
+                    authToken: 'ABC'
+                };
+
+                const mockResponse = { content: 'Page data' };
+                mockFetchResponse(mockResponse);
+
+                const client = TestDotCmsClient.init(config);
+
+                await client.page.get({ path: '/home' });
+
+                expect(fetch).toHaveBeenCalledWith(
+                    'https://example.com/api/v1/page/json/home?host_id=123456',
+                    {
+                        headers: { Authorization: 'Bearer ABC' }
+                    }
+                );
+            });
+
+            it('should use a clean dotcmsUrl when passing a route at the end', async () => {
+                const config = {
+                    dotcmsUrl: 'https://example.com/some/cool/route',
+                    siteId: '123456',
+                    authToken: 'ABC'
+                };
+
+                const mockResponse = { content: 'Page data' };
+                mockFetchResponse(mockResponse);
+
+                const client = TestDotCmsClient.init(config);
+
+                await client.page.get({ path: '/home' });
+
+                expect(fetch).toHaveBeenCalledWith(
+                    'https://example.com/api/v1/page/json/home?host_id=123456',
+                    {
+                        headers: { Authorization: 'Bearer ABC' }
+                    }
+                );
+            });
+
+            it('should use a clean dotcmsUrl when passing a port and an slash at the end', async () => {
+                const config = {
+                    dotcmsUrl: 'https://example.com:3434/cool/route',
+                    siteId: '123456',
+                    authToken: 'ABC'
+                };
+
+                const mockResponse = { content: 'Page data' };
+                mockFetchResponse(mockResponse);
+
+                const client = TestDotCmsClient.init(config);
+
+                await client.page.get({ path: '/home' });
+
+                expect(fetch).toHaveBeenCalledWith(
+                    'https://example.com:3434/api/v1/page/json/home?host_id=123456',
+                    {
+                        headers: { Authorization: 'Bearer ABC' }
+                    }
+                );
+            });
+
+            it('should use a clean dotcmsUrl when passing a port and an slash at the end', async () => {
+                const config = {
+                    dotcmsUrl: 'https://example.com:3434/',
+                    siteId: '123456',
+                    authToken: 'ABC'
+                };
+
+                const mockResponse = { content: 'Page data' };
+                mockFetchResponse(mockResponse);
+
+                const client = TestDotCmsClient.init(config);
+
+                await client.page.get({ path: '/home' });
+
+                expect(fetch).toHaveBeenCalledWith(
+                    'https://example.com:3434/api/v1/page/json/home?host_id=123456',
+                    {
+                        headers: { Authorization: 'Bearer ABC' }
+                    }
+                );
+            });
+        });
+
+        describe('page.get', () => {
+            it('should fetch page data successfully', async () => {
+                const mockResponse = { content: 'Page data' };
+                mockFetchResponse({ entity: mockResponse });
+
+                const data = await client.page.get({ path: '/home' });
+
+                expect(fetch).toHaveBeenCalledTimes(1);
+                expect(fetch).toHaveBeenCalledWith(
+                    'http://localhost/api/v1/page/json/home?host_id=123456',
+                    {
+                        headers: { Authorization: 'Bearer ABC' }
+                    }
+                );
+                expect(data).toEqual(mockResponse);
+            });
+
+            it('should throw an error if the path is not provided', async () => {
+                await expect(client.page.get({} as any)).rejects.toThrowError(
+                    `The 'path' parameter is required for the Page API`
+                );
+            });
+
+            it('should get the page for specified persona', () => {
+                const mockResponse = { content: 'Page data' };
+                mockFetchResponse(mockResponse);
+
+                client.page.get({ path: '/home', personaId: 'doe123' });
+
+                expect(fetch).toHaveBeenCalledWith(
+                    'http://localhost/api/v1/page/json/home?com.dotmarketing.persona.id=doe123&host_id=123456',
+                    {
+                        headers: { Authorization: 'Bearer ABC' }
+                    }
+                );
+            });
+
+            it('should get the page for specified siteId', () => {
+                const mockResponse = { content: 'Page data' };
+                mockFetchResponse(mockResponse);
+
+                client.page.get({ path: '/home', siteId: 'host-123' });
+
+                expect(fetch).toHaveBeenCalledWith(
+                    'http://localhost/api/v1/page/json/home?host_id=host-123',
+                    {
+                        headers: { Authorization: 'Bearer ABC' }
+                    }
+                );
+            });
+
+            it('should get the page for specified language', () => {
+                const mockResponse = { content: 'Page data' };
+                mockFetchResponse(mockResponse);
+
+                client.page.get({ path: '/home', language_id: 99 });
+
+                expect(fetch).toHaveBeenCalledWith(
+                    'http://localhost/api/v1/page/json/home?language_id=99&host_id=123456',
+                    {
+                        headers: { Authorization: 'Bearer ABC' }
+                    }
+                );
+            });
+
+            it('should manage error response', () => {
+                const mockResponse = {};
+                mockFetchResponse(mockResponse, false, 401);
+
+                expect(client.page.get({ path: '/home' })).rejects.toEqual({
+                    status: 401,
+                    message: 'Unauthorized. Check the token and try again.'
+                });
+            });
+        });
+
+        describe('editor.on', () => {
+            it('should listen to FETCH_PAGE_ASSET_FROM_UVE event', () => {
+                isInsideEditorSpy.mockReturnValue(true);
+
+                const callback = jest.fn();
+                client.editor.on('changes', callback);
+
+                const mockMessageEvent = {
+                    data: {
+                        name: 'SET_PAGE_DATA',
+                        payload: { some: 'test' }
+                    }
+                };
+
+                window.dispatchEvent(new MessageEvent('message', mockMessageEvent));
+
+                expect(callback).toHaveBeenCalledWith(mockMessageEvent.data.payload);
+            });
+
+            it('should do nothing if is outside editor', () => {
+                isInsideEditorSpy.mockReturnValue(false);
+
+                const callback = jest.fn();
+                client.editor.on('FETCH_PAGE_ASSET_FROM_UVE', callback);
+
+                const mockMessageEvent = {
+                    data: {
+                        name: 'SET_PAGE_DATA',
+                        payload: { some: 'test' }
+                    }
+                };
+
+                window.dispatchEvent(new MessageEvent('message', mockMessageEvent));
+
+                expect(callback).not.toHaveBeenCalled();
+            });
+        });
+
+        describe('editor.off', () => {
+            it('should remove a page event listener', () => {
+                isInsideEditorSpy.mockReturnValue(true);
+
+                const windowSpy = jest.spyOn(window, 'removeEventListener');
+                const callback = jest.fn();
+                client.editor.on('changes', callback);
+
+                client.editor.off('changes');
+
+                expect(windowSpy).toHaveBeenCalledWith('message', expect.anything());
+
+                const mockMessageEvent = {
+                    data: {
+                        name: 'SET_PAGE_DATA',
+                        payload: { some: 'test' }
+                    }
+                };
+
+                window.dispatchEvent(new MessageEvent('message', mockMessageEvent));
+
+                expect(callback).not.toHaveBeenCalled();
+            });
+        });
+
+        describe('content', () => {
+            it('should have an instance of the content API', () => {
+                expect(client.content instanceof Content).toBeTruthy();
+            });
+        });
+
+        describe('nav.get', () => {
+            it('should fetch navigation data successfully', async () => {
+                const mockResponse = { nav: 'Navigation data' };
+                mockFetchResponse(mockResponse);
+
+                const data = await client.nav.get({ path: '/', depth: 1 });
+
+                expect(fetch).toHaveBeenCalledTimes(1);
+                expect(fetch).toHaveBeenCalledWith('http://localhost/api/v1/nav/?depth=1', {
+                    headers: { Authorization: 'Bearer ABC' }
+                });
+                expect(data).toEqual(mockResponse);
+            });
+
+            it('should correctly handle the root path', async () => {
+                const mockResponse = { nav: 'Root nav data' };
+                mockFetchResponse(mockResponse);
+
+                const data = await client.nav.get({ path: '/' });
+
+                expect(fetch).toHaveBeenCalledWith('http://localhost/api/v1/nav/', {
+                    headers: { Authorization: 'Bearer ABC' }
+                });
+                expect(data).toEqual(mockResponse);
+            });
+
+            it('should throw an error if the path is not provided', async () => {
+                await expect(client.nav.get({} as any)).rejects.toThrowError(
+                    `The 'path' parameter is required for the Nav API`
+                );
+            });
+        });
+    });
+
+    describe('with minimal configuration', () => {
+        let client: DotCmsClient;
+
+        beforeEach(() => {
+            (fetch as jest.Mock).mockClear();
+
+            client = TestDotCmsClient.init({
+                dotcmsUrl: 'http://localhost',
+                authToken: 'ABC'
+            });
+        });
+
+        it('should get the page without siteId', () => {
+            const mockResponse = { content: 'Page data' };
+            mockFetchResponse(mockResponse);
+
+            client.page.get({ path: '/home' });
+
+            expect(fetch).toHaveBeenCalledWith('http://localhost/api/v1/page/json/home', {
+                headers: { Authorization: 'Bearer ABC' }
+            });
+        });
+    });
+
+    describe('with requestOptions', () => {
+        let client: DotCmsClient;
+
+        beforeEach(() => {
+            (fetch as jest.Mock).mockClear();
+
+            client = TestDotCmsClient.init({
+                dotcmsUrl: 'http://localhost',
+                siteId: '123456',
+                authToken: 'ABC',
+                requestOptions: {
+                    headers: {
+                        'X-My-Header': 'my-value'
+                    },
+                    cache: 'no-cache'
+                }
+            });
+        });
+
+        it('should fetch page data with extra headers and cache', async () => {
+            const mockResponse = { content: 'Page data' };
+            mockFetchResponse({ entity: mockResponse });
+
+            const data = await client.page.get({ path: '/home' });
+
+            expect(fetch).toHaveBeenCalledTimes(1);
+            expect(fetch).toHaveBeenCalledWith(
+                'http://localhost/api/v1/page/json/home?host_id=123456',
+                {
+                    headers: { Authorization: 'Bearer ABC', 'X-My-Header': 'my-value' },
+                    cache: 'no-cache'
+                }
+            );
+            expect(data).toEqual(mockResponse);
+        });
+
+        it('should fetch bav data with extra headers and cache', async () => {
+            const mockResponse = { content: 'Page data' };
+            mockFetchResponse(mockResponse);
+
+            const data = await client.nav.get();
+
+            expect(fetch).toHaveBeenCalledTimes(1);
+            expect(fetch).toHaveBeenCalledWith(
+                'http://localhost/api/v1/nav/?depth=0&languageId=1',
+                {
+                    headers: { Authorization: 'Bearer ABC', 'X-My-Header': 'my-value' },
+                    cache: 'no-cache'
+                }
+            );
+            expect(data).toEqual(mockResponse);
+        });
+    });
+
+    describe('Singleton pattern', () => {
+        it('should return the same instance and log a warning when calling init multiple times', () => {
+            const consoleWarnSpy = jest.spyOn(console, 'warn');
+            const expectedWarnMessage =
+                'DotCmsClient has already been initialized. Please use the instance to interact with the DotCMS API.';
+            const config = {
+                dotcmsUrl: 'https://example.com',
+                siteId: '123456',
+                authToken: 'ABC'
+            };
+
+            const config2 = {
+                dotcmsUrl: 'https://example.com',
+                siteId: '123456',
+                authToken: 'DEF'
+            };
+
+            const client1 = DotCmsClient.init(config);
+            const client2 = DotCmsClient.init(config2);
+
+            expect(client1).toBe(client2);
+            expect(consoleWarnSpy).toHaveBeenCalledWith(expectedWarnMessage);
+        });
+    });
+
+    describe('Properties', () => {
+        it('should return he current dotcmsUrl', () => {
+            TestDotCmsClient.init({
+                dotcmsUrl: 'http://localhost:8080',
+                siteId: '123456',
+                authToken: 'ABC'
+            });
+
+            expect(TestDotCmsClient.dotcmsUrl).toBe('http://localhost:8080');
+        });
+    });
+});