@dotcms/client 1.0.0 → 1.0.1

package/src/lib/client/navigation/navigation-api.ts

@@ -0,0 +1,62 @@
+import {
+    DotCMSClientConfig,
+    DotCMSNavigationRequestParams,
+    RequestOptions,
+    DotCMSNavigationItem
+} from '@dotcms/types';
+
+export class NavigationClient {
+    private requestOptions: RequestOptions;
+
+    private BASE_URL: string;
+
+    constructor(config: DotCMSClientConfig, requestOptions: RequestOptions) {
+        this.requestOptions = requestOptions;
+        this.BASE_URL = `${config?.dotcmsUrl}/api/v1/nav`;
+    }
+
+    /**
+     * Retrieves information about the dotCMS file and folder tree.
+     * @param {NavigationApiOptions} options - The options for the Navigation API call. Defaults to `{ depth: 0, path: '/', languageId: 1 }`.
+     * @returns {Promise<DotCMSNavigationItem[]>} - A Promise that resolves to the response from the DotCMS API.
+     * @throws {Error} - Throws an error if the options are not valid.
+     */
+    async get(
+        path: string,
+        params?: DotCMSNavigationRequestParams
+    ): Promise<DotCMSNavigationItem[]> {
+        if (!path) {
+            throw new Error("The 'path' parameter is required for the Navigation API");
+        }
+
+        const navParams = params ? this.mapToBackendParams(params) : {};
+        const urlParams = new URLSearchParams(navParams).toString();
+
+        const parsedPath = path.replace(/^\/+/, '/').replace(/\/+$/, '/');
+        const url = `${this.BASE_URL}${parsedPath}${urlParams ? `?${urlParams}` : ''}`;
+
+        const response = await fetch(url, this.requestOptions);
+
+        if (!response.ok) {
+            throw new Error(
+                `Failed to fetch navigation data: ${response.statusText} - ${response.status}`
+            );
+        }
+
+        return response.json().then((data) => data.entity);
+    }
+
+    private mapToBackendParams(params: DotCMSNavigationRequestParams): Record<string, string> {
+        const backendParams: Record<string, string> = {};
+
+        if (params.depth) {
+            backendParams['depth'] = String(params.depth);
+        }
+
+        if (params.languageId) {
+            backendParams['language_id'] = String(params.languageId);
+        }
+
+        return backendParams;
+    }
+}

package/src/lib/client/page/page-api.spec.ts

@@ -0,0 +1,359 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+jest.mock('consola');
+
+import * as consola from 'consola';
+
+import {
+    DotCMSClientConfig,
+    DotCMSPageRequestParams,
+    RequestOptions,
+    DotCMSGraphQLPageResponse,
+    DotCMSPageResponse
+} from '@dotcms/types';
+
+import { PageClient } from './page-api';
+import * as utils from './utils';
+
+import { graphqlToPageEntity } from '../../utils';
+
+describe('PageClient', () => {
+    const mockFetchGraphQL = jest.fn();
+
+    const validConfig: DotCMSClientConfig = {
+        dotcmsUrl: 'https://demo.dotcms.com',
+        authToken: 'test-token',
+        siteId: 'test-site'
+    };
+
+    const requestOptions: RequestOptions = {
+        headers: {
+            Authorization: 'Bearer test-token'
+        }
+    };
+
+    const mockGraphQLResponse = {
+        data: {
+            page: {
+                title: 'GraphQL Page',
+                url: '/graphql-page'
+            },
+            testContent: {
+                items: [{ title: 'Content Item' }]
+            },
+            testNav: {
+                items: [{ label: 'Nav Item', url: '/nav' }]
+            }
+        },
+        errors: null
+    };
+
+    beforeEach(() => {
+        mockFetchGraphQL.mockReset();
+        global.console.error = jest.fn(); // Mock console.error to prevent actual errors from being logged in the console when running tests
+
+        jest.spyOn(utils, 'fetchGraphQL').mockImplementation(mockFetchGraphQL);
+        mockFetchGraphQL.mockResolvedValue(mockGraphQLResponse);
+
+        jest.spyOn(utils, 'buildPageQuery').mockReturnValue('mock-page-query');
+        jest.spyOn(utils, 'buildQuery').mockReturnValue('mock-query');
+        jest.spyOn(utils, 'mapResponseData').mockImplementation((data, keys) => {
+            const result: Record<string, any> = {};
+
+            keys.forEach((key) => {
+                result[key] = data[`test${key.charAt(0).toUpperCase() + key.slice(1)}`];
+            });
+
+            return result;
+        });
+    });
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    describe('GraphQL API', () => {
+        it('should fetch page using GraphQL when query option is provided', async () => {
+            const pageClient = new PageClient(validConfig, requestOptions);
+
+            const graphQLOptions: DotCMSPageRequestParams = {
+                graphql: {
+                    page: `containers {
+      containerContentlets {
+        contentlets {
+         ... on Banner {
+            title
+          }
+        }
+      }
+    }`,
+                    content: { content: 'query Content { items { title } }' }
+                },
+                languageId: '1',
+                mode: 'LIVE'
+            };
+
+            const result = await pageClient.get('/graphql-page', graphQLOptions);
+
+            expect(utils.buildPageQuery).toHaveBeenCalled();
+            expect(utils.buildQuery).toHaveBeenCalledTimes(1);
+            expect(utils.fetchGraphQL).toHaveBeenCalledWith({
+                body: expect.any(String),
+                headers: requestOptions.headers,
+                baseURL: 'https://demo.dotcms.com'
+            });
+
+            expect(result).toEqual({
+                pageAsset: graphqlToPageEntity(
+                    mockGraphQLResponse.data as unknown as DotCMSGraphQLPageResponse
+                ),
+                content: { content: mockGraphQLResponse.data.testContent },
+                graphql: {
+                    query: expect.any(String),
+                    variables: expect.any(Object)
+                },
+                vanityUrl: undefined,
+                runningExperimentId: undefined
+            });
+        });
+
+        it('should print graphql errors ', async () => {
+            const consolaSpy = jest.spyOn(consola, 'error');
+            const pageClient = new PageClient(validConfig, requestOptions);
+            const graphQLOptions = {
+                graphql: {
+                    page: `containers {
+                        containerContentlets {
+                            contentlets {
+                                ... on Banner {
+                                    title
+                                }
+                            }
+                        }
+                    }`,
+                    content: { content: 'query Content { items { title } }' }
+                }
+            };
+
+            mockFetchGraphQL.mockResolvedValue({
+                data: {
+                    page: {
+                        title: 'GraphQL Page'
+                    }
+                },
+                errors: [{ message: 'Some internal server error' }]
+            });
+
+            await pageClient.get('/graphql-page', graphQLOptions);
+
+            expect(consolaSpy).toHaveBeenCalledWith(
+                '[DotCMS GraphQL Error]: ',
+                'Some internal server error'
+            );
+        });
+
+        it('should return an error if the page is not found', async () => {
+            const pageClient = new PageClient(validConfig, requestOptions);
+            const graphQLOptions = {
+                graphql: {
+                    page: `containers {
+                        containerContentlets {
+                            contentlets {
+                                ... on Banner {
+                                    title
+                                }
+                            }
+                        }
+                    }`,
+                    content: { content: 'query Content { items { title } }' }
+                }
+            };
+
+            mockFetchGraphQL.mockResolvedValue({
+                data: {
+                    page: null
+                },
+                errors: [{ message: 'No page data found' }]
+            });
+
+            try {
+                await pageClient.get('/graphql-page', graphQLOptions);
+            } catch (response: unknown) {
+                const responseData = response as DotCMSPageResponse;
+
+                expect(responseData.error?.message).toBe('No page data found');
+            }
+        });
+
+        it('should add leading slash to url if it does not have it', async () => {
+            const pageClient = new PageClient(validConfig, requestOptions);
+            const graphQLOptions = {
+                graphql: {
+                    page: `containers {
+                        containerContentlets {
+                            contentlets {
+                                ... on Banner {
+                                    title
+                                }
+                            }
+                        }
+                    }`,
+                    content: { content: 'query Content { items { title } }' }
+                }
+            };
+
+            // No leading slash
+            const result = await pageClient.get('graphql-page', graphQLOptions as any);
+
+            expect(result).toEqual({
+                pageAsset: graphqlToPageEntity(
+                    mockGraphQLResponse.data as unknown as DotCMSGraphQLPageResponse
+                ),
+                content: { content: mockGraphQLResponse.data.testContent },
+                graphql: {
+                    query: expect.any(String),
+                    variables: expect.objectContaining({
+                        url: '/graphql-page'
+                    })
+                },
+                vanityUrl: undefined,
+                runningExperimentId: undefined
+            });
+        });
+
+        it('should pass correct variables to GraphQL query', async () => {
+            const pageClient = new PageClient(validConfig, requestOptions);
+            const graphQLOptions = {
+                graphql: {
+                    page: `containers {
+      containerContentlets {
+        contentlets {
+         ... on Banner {
+            title
+          }
+        }
+      }
+    }`,
+                    content: { content: 'query Content { items { title } }' }
+                },
+                languageId: '2',
+                mode: 'PREVIEW_MODE'
+            };
+
+            await pageClient.get('/custom-page', graphQLOptions as any);
+
+            const requestBody = JSON.parse(mockFetchGraphQL.mock.calls[0][0].body);
+            expect(requestBody.variables).toEqual({
+                url: '/custom-page',
+                mode: 'PREVIEW_MODE',
+                languageId: '2',
+                fireRules: false,
+                siteId: 'test-site'
+            });
+        });
+
+        it('should handle GraphQL errors', async () => {
+            mockFetchGraphQL.mockRejectedValue(new Error('GraphQL error'));
+
+            const pageClient = new PageClient(validConfig, requestOptions);
+            const graphQLOptions = {
+                graphql: {
+                    page: `containers {
+      containerContentlets {
+        contentlets {
+         ... on Banner {
+            title
+          }
+        }
+      }
+    }`,
+                    content: { content: 'query Content { items { title } }' }
+                }
+            };
+            try {
+                await pageClient.get('/page', graphQLOptions);
+            } catch (error: any) {
+                expect(error.message).toBe('Failed to retrieve page data');
+            }
+        });
+
+        it('should throw errors from GraphQL', async () => {
+            mockFetchGraphQL.mockResolvedValue({
+                errors: [{ message: 'GraphQL error' }]
+            });
+
+            const pageClient = new PageClient(validConfig, requestOptions);
+            const graphQLOptions = {
+                graphql: {
+                    page: `containers {
+      containerContentlets {
+        contentlets {
+         ... on Banner {
+            title
+          }
+        }`,
+                    content: { content: 'query Content { items { title } }' }
+                }
+            };
+            try {
+                await pageClient.get('/page', graphQLOptions);
+            } catch (error: any) {
+                expect(error.message).toBe('Failed to retrieve page data');
+            }
+        });
+
+        it('should use default values for languageId and mode if not provided', async () => {
+            const pageClient = new PageClient(validConfig, requestOptions);
+            const graphQLOptions = {
+                graphql: {
+                    page: `containers {
+      containerContentlets {
+        contentlets {
+         ... on Banner {
+            title
+          }
+        }`,
+                    content: { content: 'query Content { items { title } }' }
+                }
+            };
+            await pageClient.get('/default-page', graphQLOptions);
+
+            const requestBody = JSON.parse(mockFetchGraphQL.mock.calls[0][0].body);
+            expect(requestBody.variables).toEqual({
+                url: '/default-page',
+                mode: 'LIVE',
+                languageId: '1',
+                fireRules: false,
+                siteId: 'test-site'
+            });
+        });
+
+        it('should fetch using graphQL even if there is no graphql option', async () => {
+            const pageClient = new PageClient(validConfig, requestOptions);
+
+            await pageClient.get('/why-obi-wan-had-the-high-ground');
+
+            expect(mockFetchGraphQL).toHaveBeenCalled();
+            expect(utils.buildPageQuery).toHaveBeenCalled();
+            expect(utils.buildQuery).toHaveBeenCalledTimes(1);
+            expect(utils.fetchGraphQL).toHaveBeenCalledWith({
+                body: expect.stringContaining('"url":"/why-obi-wan-had-the-high-ground"'),
+                headers: requestOptions.headers,
+                baseURL: 'https://demo.dotcms.com'
+            });
+        });
+    });
+
+    describe('Client initialization', () => {
+        it('should use siteId from config when not provided in params', async () => {
+            const pageClient = new PageClient(validConfig, requestOptions);
+
+            await pageClient.get('/test-page');
+
+            expect(mockFetchGraphQL).toHaveBeenCalledWith({
+                baseURL: 'https://demo.dotcms.com',
+                body: expect.stringContaining('"siteId":"test-site"'),
+                headers: requestOptions.headers
+            });
+        });
+    });
+});

package/src/lib/client/page/page-api.ts

@@ -0,0 +1,197 @@
+import consola from 'consola';
+
+import {
+    DotCMSClientConfig,
+    DotCMSComposedPageResponse,
+    DotCMSExtendedPageResponse,
+    DotCMSPageResponse,
+    DotCMSPageRequestParams,
+    RequestOptions
+} from '@dotcms/types';
+
+import { buildPageQuery, buildQuery, fetchGraphQL, mapResponseData } from './utils';
+
+import { graphqlToPageEntity } from '../../utils';
+
+/**
+ * Client for interacting with the DotCMS Page API.
+ * Provides methods to retrieve and manipulate pages.
+ */
+export class PageClient {
+    /**
+     * Request options including authorization headers.
+     * @private
+     */
+    private requestOptions: RequestOptions;
+
+    /**
+     * Site ID for page requests.
+     * @private
+     */
+    private siteId: string;
+
+    /**
+     * DotCMS URL for page requests.
+     * @private
+     */
+    private dotcmsUrl: string;
+
+    /**
+     * Creates a new PageClient instance.
+     *
+     * @param {DotCMSClientConfig} config - Configuration options for the DotCMS client
+     * @param {RequestOptions} requestOptions - Options for fetch requests including authorization headers
+     * @example
+     * ```typescript
+     * const pageClient = new PageClient(
+     *   {
+     *     dotcmsUrl: 'https://demo.dotcms.com',
+     *     authToken: 'your-auth-token',
+     *     siteId: 'demo.dotcms.com'
+     *   },
+     *   {
+     *     headers: {
+     *       Authorization: 'Bearer your-auth-token'
+     *     }
+     *   }
+     * );
+     * ```
+     */
+    constructor(config: DotCMSClientConfig, requestOptions: RequestOptions) {
+        this.requestOptions = requestOptions;
+        this.siteId = config.siteId || '';
+        this.dotcmsUrl = config.dotcmsUrl;
+    }
+
+    /**
+     * Retrieves a page from DotCMS using GraphQL.
+     *
+     * @param {string} url - The URL of the page to retrieve
+     * @param {DotCMSPageRequestParams} [options] - Options for the request
+     * @template T - The type of the page and content, defaults to DotCMSBasicPage and Record<string, unknown> | unknown
+     * @returns {Promise<DotCMSComposedPageResponse<T>>} A Promise that resolves to the page data
+     *
+     * @example Using GraphQL
+     * ```typescript
+     * const page = await pageClient.get<{ page: MyPageWithBanners; content: { blogPosts: { blogTitle: string } } }>(
+     *     '/index',
+     *     {
+     *         languageId: '1',
+     *         mode: 'LIVE',
+     *         graphql: {
+     *             page: `
+     *              containers {
+     *                  containerContentlets {
+     *                      contentlets {
+     *                          ... on 	Banner {
+     *                              ...bannerFragment
+     *                          }
+     *                      }
+     *                  }
+     *              `,
+     *              content: {
+     *                  blogPosts: `
+     *                      BlogCollection(limit: 3) {
+     *                          ...blogFragment
+     *                      }
+     *                  `,
+     *              },
+     *              fragments: [
+     *                  `
+     *                      fragment bannerFragment on Banner {
+     *                          caption
+     *                      }
+     *                  `,
+     *                  `
+     *                      fragment blogFragment on Blog {
+     *                          title
+     *                          urlTitle
+     *                      }
+     *                  `
+     *              ]
+     *          }
+     *      });
+     * ```
+     */
+    async get<T extends DotCMSExtendedPageResponse = DotCMSPageResponse>(
+        url: string,
+        options?: DotCMSPageRequestParams
+    ): Promise<DotCMSComposedPageResponse<T>> {
+        const {
+            languageId = '1',
+            mode = 'LIVE',
+            siteId = this.siteId,
+            fireRules = false,
+            personaId,
+            publishDate,
+            variantName,
+            graphql = {}
+        } = options || {};
+        const { page, content = {}, variables, fragments } = graphql;
+
+        const contentQuery = buildQuery(content);
+        const completeQuery = buildPageQuery({
+            page,
+            fragments,
+            additionalQueries: contentQuery
+        });
+
+        const requestVariables: Record<string, unknown> = {
+            // The url is expected to have a leading slash to comply on VanityURL Matching, some frameworks like Angular will not add the leading slash
+            url: url.startsWith('/') ? url : `/${url}`,
+            mode,
+            languageId,
+            personaId,
+            fireRules,
+            publishDate,
+            siteId,
+            variantName,
+            ...variables
+        };
+
+        const requestHeaders = this.requestOptions.headers as Record<string, string>;
+        const requestBody = JSON.stringify({ query: completeQuery, variables: requestVariables });
+
+        try {
+            const { data, errors } = await fetchGraphQL({
+                baseURL: this.dotcmsUrl,
+                body: requestBody,
+                headers: requestHeaders
+            });
+
+            if (errors) {
+                errors.forEach((error: { message: string }) => {
+                    consola.error('[DotCMS GraphQL Error]: ', error.message);
+                });
+            }
+
+            const pageResponse = graphqlToPageEntity(data);
+
+            if (!pageResponse) {
+                throw new Error('No page data found');
+            }
+
+            const contentResponse = mapResponseData(data, Object.keys(content));
+
+            return {
+                pageAsset: pageResponse,
+                content: contentResponse,
+                graphql: {
+                    query: completeQuery,
+                    variables: requestVariables
+                }
+            };
+        } catch (error) {
+            const errorMessage = {
+                error,
+                message: 'Failed to retrieve page data',
+                graphql: {
+                    query: completeQuery,
+                    variables: requestVariables
+                }
+            };
+
+            throw errorMessage;
+        }
+    }
+}