@dotcms/client 1.0.0 → 1.0.1

package/src/lib/client/page/utils.ts

@@ -0,0 +1,291 @@
+import { consola } from 'consola';
+
+import { ErrorMessages } from '../models';
+
+const DEFAULT_PAGE_CONTENTLETS_CONTENT = `
+          publishDate
+          inode
+          identifier
+          archived
+          urlMap
+          urlMap
+          locked
+          contentType
+          creationDate
+          modDate
+          title
+          baseType
+          working
+          live
+          publishUser {
+            firstName
+            lastName
+          }
+          owner {
+            lastName
+          }
+          conLanguage {
+            language
+            languageCode
+          }
+          modUser {
+            firstName
+            lastName
+          }
+`;
+
+/**
+ * Builds a GraphQL query for retrieving page content from DotCMS.
+ *
+ * @param {string} pageQuery - Custom fragment fields to include in the ClientPage fragment
+ * @param {string} additionalQueries - Additional GraphQL queries to include in the main query
+ * @returns {string} Complete GraphQL query string for page content
+ */
+export const buildPageQuery = ({
+    page,
+    fragments,
+    additionalQueries
+}: {
+    page?: string;
+    fragments?: string[];
+    additionalQueries?: string;
+}) => {
+    if (!page) {
+        consola.warn(
+            "[DotCMS Client]: No page query was found, so we're loading all content using _map. This might slow things down. For better performance, we recommend adding a specific query in the page attribute."
+        );
+    }
+
+    return `
+  fragment DotCMSPage on DotPage {
+    publishDate
+    type
+    httpsRequired
+    inode
+    path
+    identifier
+    hasTitleImage
+    sortOrder
+    extension
+    canRead
+    pageURI
+    canEdit
+    archived
+    friendlyName
+    workingInode
+    url
+    pageURI
+    hasLiveVersion
+    deleted
+    pageUrl
+    shortyWorking
+    mimeType
+    locked
+    stInode
+    contentType
+    creationDate
+    liveInode
+    name
+    shortyLive
+    modDate
+    title
+    baseType
+    working
+    canLock
+    live
+    isContentlet
+    statusIcons
+    canEdit
+    canLock
+    canRead
+    canEdit
+    canLock
+    canRead
+    runningExperimentId
+    urlContentMap {
+      _map
+    }
+    host {
+      identifier
+      hostName
+     	googleMap
+      archived
+      contentType
+    }
+    vanityUrl {
+      action
+      forwardTo
+      uri
+    }
+    conLanguage {
+      id
+      language
+      languageCode
+    }
+    template {
+      drawed
+      anonymous
+      theme
+      identifier
+    }
+    containers {
+      path
+      identifier
+      maxContentlets
+      containerStructures {
+        id
+        code
+        structureId
+        containerId
+        contentTypeVar
+        containerInode
+      }
+      containerContentlets {
+        uuid
+        contentlets {
+          ${page ? DEFAULT_PAGE_CONTENTLETS_CONTENT : '_map'}
+        }
+      }
+    }
+    layout {
+      header
+      footer
+      body {
+        rows {
+          styleClass
+          columns {
+            leftOffset
+            styleClass
+            width
+            left
+            containers {
+              identifier
+              uuid
+            }
+          }
+        }
+      }
+    }
+    viewAs {
+      visitor {
+        persona {
+          modDate
+          inode
+          name
+          identifier
+          keyTag
+          photo {
+            versionPath
+          }
+        }
+      }
+      persona {
+        modDate
+        inode
+        name
+        identifier
+        keyTag
+        photo {
+         versionPath
+        }
+      }
+      language {
+        id
+        languageCode
+        countryCode
+        language
+        country
+      }
+    }
+  }
+
+  ${page ? ` fragment ClientPage on DotPage { ${page} } ` : ''}
+
+  ${fragments ? fragments.join('\n\n') : ''}
+
+  query PageContent($url: String!, $languageId: String, $mode: String, $personaId: String, $fireRules: Boolean, $publishDate: String, $siteId: String, $variantName: String) {
+    page: page(url: $url, languageId: $languageId, pageMode: $mode, persona: $personaId, fireRules: $fireRules, publishDate: $publishDate, site: $siteId, variantName: $variantName) {
+      ...DotCMSPage
+      ${page ? '...ClientPage' : ''}
+    }
+
+    ${additionalQueries}
+  }
+  `;
+};
+
+/**
+ * Converts a record of query strings into a single GraphQL query string.
+ *
+ * @param {Record<string, string>} queryData - Object containing named query strings
+ * @returns {string} Combined query string or empty string if no queryData provided
+ */
+export function buildQuery(queryData: Record<string, string>): string {
+    if (!queryData) return '';
+
+    return Object.entries(queryData)
+        .map(([key, query]) => `${key}: ${query}`)
+        .join(' ');
+}
+
+/**
+ * Filters response data to include only specified keys.
+ *
+ * @param {Record<string, string>} responseData - Original response data object
+ * @param {string[]} keys - Array of keys to extract from the response data
+ * @returns {Record<string, string>} New object containing only the specified keys
+ */
+export function mapResponseData(
+    responseData: Record<string, string>,
+    keys: string[]
+): Record<string, string> {
+    return keys.reduce(
+        (accumulator, key) => {
+            if (responseData[key] !== undefined) {
+                accumulator[key] = responseData[key];
+            }
+
+            return accumulator;
+        },
+        {} as Record<string, string>
+    );
+}
+
+/**
+ * Executes a GraphQL query against the DotCMS API.
+ *
+ * @param {Object} options - Options for the fetch request
+ * @param {string} options.body - GraphQL query string
+ * @param {Record<string, string>} options.headers - HTTP headers for the request
+ * @returns {Promise<any>} Parsed JSON response from the GraphQL API
+ * @throws {Error} If the HTTP response is not successful
+ */
+export async function fetchGraphQL({
+    baseURL,
+    body,
+    headers
+}: {
+    baseURL: string;
+    body: string;
+    headers: Record<string, string>;
+}) {
+    const url = new URL(baseURL);
+    url.pathname = '/api/v1/graphql';
+
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        body,
+        headers
+    });
+
+    if (!response.ok) {
+        const error = {
+            status: response.status,
+            message: ErrorMessages[response.status] || response.statusText
+        };
+
+        throw error;
+    }
+
+    return await response.json();
+}

package/src/lib/utils/graphql/transforms.spec.ts

@@ -0,0 +1,250 @@
+import { DotCMSGraphQLPageResponse } from '@dotcms/types';
+
+import { graphqlToPageEntity } from './transforms';
+
+const GRAPHQL_RESPONSE_MOCK = {
+    page: {
+        title: 'test2',
+        url: '/test2',
+        seodescription: null,
+        containers: [
+            {
+                path: '//demo.dotcms.com/application/containers/default/',
+                identifier: '69b3d24d-7e80-4be6-b04a-d352d16493ee',
+                containerStructures: [
+                    {
+                        id: '77ec7720-bad8-431c-a0a3-6443fe87af73'
+                    },
+                    {
+                        id: '1e5372c4-9fff-4793-ad8a-a52558d0d395'
+                    },
+                    {
+                        id: '461b6fad-04a8-49ba-b75b-6634799bc289'
+                    },
+                    {
+                        id: '57b4a9de-4765-4c57-8a05-2a0a317ec546'
+                    },
+                    {
+                        id: '342a83bf-040a-45a2-a4bc-defb0f1bf4eb'
+                    },
+                    {
+                        id: '91a955a0-5c97-4fc3-91dd-f894e2f3dc54'
+                    },
+                    {
+                        id: '71ded7c9deb5b05452824bb42b9aa9d5'
+                    },
+                    {
+                        id: '86a06a2e-ba40-43d4-a3ad-3a870d43bfc1'
+                    },
+                    {
+                        id: '7673e601-26d4-4dbc-b6ad-7028599df656'
+                    },
+                    {
+                        id: '313498a4-5b57-4d9e-8d32-ef2d30f9e867'
+                    }
+                ],
+                containerContentlets: [
+                    {
+                        uuid: 'uuid-1562770692396',
+                        contentlets: [
+                            {
+                                identifier: 'd9444fa005a10d555318d8b014e474d4'
+                            }
+                        ]
+                    }
+                ]
+            }
+        ],
+        host: {
+            hostName: 'demo.dotcms.com'
+        },
+        layout: {
+            title: 'default-template'
+        },
+        template: {
+            identifier: '31f4c794-c769-4929-9d5d-7c383408c65c'
+        },
+        urlContentMap: {
+            _map: {
+                identifier: '31f4c794-c769-4929-9d5d-7c383408c74d'
+            }
+        },
+        viewAs: {
+            mode: 'LIVE'
+        },
+        runningExperimentId: '123',
+        vanityUrl: {
+            action: 200,
+            uri: '/test2',
+            forwardTo: '/test2'
+        }
+    }
+};
+
+const MOCK_PAGE_ENTITY = {
+    containers: {
+        '//demo.dotcms.com/application/containers/default/': {
+            container: {
+                identifier: '69b3d24d-7e80-4be6-b04a-d352d16493ee',
+                path: '//demo.dotcms.com/application/containers/default/'
+            },
+            containerStructures: [
+                {
+                    id: '77ec7720-bad8-431c-a0a3-6443fe87af73'
+                },
+                {
+                    id: '1e5372c4-9fff-4793-ad8a-a52558d0d395'
+                },
+                {
+                    id: '461b6fad-04a8-49ba-b75b-6634799bc289'
+                },
+                {
+                    id: '57b4a9de-4765-4c57-8a05-2a0a317ec546'
+                },
+                {
+                    id: '342a83bf-040a-45a2-a4bc-defb0f1bf4eb'
+                },
+                {
+                    id: '91a955a0-5c97-4fc3-91dd-f894e2f3dc54'
+                },
+                {
+                    id: '71ded7c9deb5b05452824bb42b9aa9d5'
+                },
+                {
+                    id: '86a06a2e-ba40-43d4-a3ad-3a870d43bfc1'
+                },
+                {
+                    id: '7673e601-26d4-4dbc-b6ad-7028599df656'
+                },
+                {
+                    id: '313498a4-5b57-4d9e-8d32-ef2d30f9e867'
+                }
+            ],
+            contentlets: {
+                'uuid-1562770692396': [
+                    {
+                        identifier: 'd9444fa005a10d555318d8b014e474d4'
+                    }
+                ]
+            }
+        }
+    },
+    layout: {
+        title: 'default-template'
+    },
+    page: {
+        seodescription: null,
+        title: 'test2',
+        url: '/test2'
+    },
+    urlContentMap: {
+        identifier: '31f4c794-c769-4929-9d5d-7c383408c74d'
+    },
+    template: {
+        identifier: '31f4c794-c769-4929-9d5d-7c383408c65c'
+    },
+    viewAs: {
+        mode: 'LIVE'
+    },
+    site: {
+        hostName: 'demo.dotcms.com'
+    },
+    vanityUrl: {
+        action: 200,
+        uri: '/test2',
+        forwardTo: '/test2'
+    },
+    runningExperimentId: '123'
+};
+
+describe('GraphQL Parser', () => {
+    it('should return the correct page entity', () => {
+        const pageEntity = graphqlToPageEntity(
+            GRAPHQL_RESPONSE_MOCK as unknown as DotCMSGraphQLPageResponse
+        );
+
+        expect(pageEntity).toEqual(MOCK_PAGE_ENTITY);
+    });
+
+    it('should transform _map properties correctly', () => {
+        const graphqlResponse = {
+            page: {
+                title: 'map-test',
+                url: '/map-test',
+                _map: {
+                    customField: 'custom value'
+                },
+                urlContentMap: {
+                    _map: {
+                        mapField: 'map value',
+                        identifier: 'test-id',
+                        someNestedField: {
+                            nestedField: 'nested value'
+                        }
+                    }
+                },
+                containers: [
+                    {
+                        path: '//test/container/',
+                        identifier: 'test-container-id',
+                        containerContentlets: [
+                            {
+                                uuid: 'test-uuid',
+                                contentlets: [
+                                    {
+                                        _map: {
+                                            identifier: 'test-contentlet-id',
+                                            contentletField: 'contentlet value'
+                                        }
+                                    }
+                                ]
+                            }
+                        ]
+                    }
+                ]
+            }
+        };
+
+        const expectedResult = {
+            page: {
+                title: 'map-test',
+                url: '/map-test',
+                customField: 'custom value'
+            },
+            urlContentMap: {
+                identifier: 'test-id',
+                mapField: 'map value',
+                someNestedField: {
+                    nestedField: 'nested value'
+                }
+            },
+            containers: {
+                '//test/container/': {
+                    container: {
+                        path: '//test/container/',
+                        identifier: 'test-container-id'
+                    },
+                    containerStructures: undefined,
+                    contentlets: {
+                        'test-uuid': [
+                            {
+                                identifier: 'test-contentlet-id',
+                                contentletField: 'contentlet value'
+                            }
+                        ]
+                    }
+                }
+            }
+        };
+
+        const pageEntity = graphqlToPageEntity(
+            graphqlResponse as unknown as DotCMSGraphQLPageResponse
+        );
+
+        expect(pageEntity?.page).toEqual(expectedResult.page);
+        expect(pageEntity?.urlContentMap).toEqual(expectedResult.urlContentMap);
+        expect(pageEntity?.containers['//test/container/'].contentlets['test-uuid'][0]).toEqual(
+            expectedResult.containers['//test/container/'].contentlets['test-uuid'][0]
+        );
+    });
+});

package/src/lib/utils/graphql/transforms.ts

@@ -0,0 +1,128 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+    DotCMSBasicContentlet,
+    DotCMSGraphQLPageContainer,
+    DotCMSGraphQLPageResponse,
+    DotCMSPageAssetContainers,
+    DotCMSPageContainerContentlets,
+    DotCMSPage,
+    DotCMSPageAsset,
+    DotCMSContainer
+} from '@dotcms/types';
+
+/**
+ * Transforms a GraphQL Page response to a Page Entity.
+ *
+ * @param {GraphQLPageResponse} graphQLPageResponse - The GraphQL Page response object.
+ * @returns {object|null} The transformed Page Entity or null if the page is not present.
+ *
+ * @example
+ * ```ts
+ * const pageEntity = graphqlToPageEntity(graphQLPageResponse);
+ * ```
+ */
+export const graphqlToPageEntity = (
+    graphQLPageResponse: DotCMSGraphQLPageResponse
+): DotCMSPageAsset | null => {
+    const { page } = graphQLPageResponse;
+
+    // If there is no page, return null
+    if (!page) {
+        return null;
+    }
+
+    const {
+        layout,
+        template,
+        containers,
+        urlContentMap,
+        viewAs,
+        host,
+        vanityUrl,
+        runningExperimentId,
+        _map,
+        ...pageAsset
+    } = page;
+    const data = (_map || {}) as Record<string, unknown>;
+
+    const typedPageAsset = pageAsset as unknown as DotCMSPage;
+
+    // To prevent type errors, we cast the urlContentMap to an object
+    const urlContentMapObject = urlContentMap;
+
+    // Extract the _map data from the urlContentMap object
+    const urlContentMapData = urlContentMapObject?.['_map'];
+
+    return {
+        layout,
+        template,
+        viewAs,
+        vanityUrl,
+        runningExperimentId,
+        site: host,
+        urlContentMap: urlContentMapData,
+        containers: parseContainers(containers as []),
+        page: {
+            ...data,
+            ...typedPageAsset
+        }
+    };
+};
+
+/**
+ * Parses the containers from the GraphQL response.
+ *
+ * @param {DotCMSGraphQLPageContainer[]} [containers=[]] - The containers array from the GraphQL response.
+ * @returns {DotCMSPageAssetContainers} The parsed containers.
+ */
+const parseContainers = (
+    containers: DotCMSGraphQLPageContainer[] = []
+): DotCMSPageAssetContainers => {
+    return containers.reduce(
+        (acc: DotCMSPageAssetContainers, container: DotCMSGraphQLPageContainer) => {
+            const { path, identifier, containerStructures, containerContentlets, ...rest } =
+                container;
+
+            const key = (path || identifier) as string;
+
+            acc[key] = {
+                containerStructures,
+                container: {
+                    path,
+                    identifier,
+                    ...rest
+                } as DotCMSContainer,
+                contentlets: parseContentletsToUuidMap(containerContentlets as [])
+            };
+
+            return acc;
+        },
+        {}
+    );
+};
+
+/**
+ * Parses the contentlets from the GraphQL response.
+ *
+ * @param {Array<Record<string, unknown>>} containerContentlets - The contentlets array from the GraphQL response.
+ * @returns {Record<string, Array<Record<string, unknown>>>} The parsed contentlets mapped by UUID.
+ */
+const parseContentletsToUuidMap = (containerContentlets: DotCMSPageContainerContentlets[] = []) => {
+    return containerContentlets.reduce(
+        (acc, containerContentlet) => {
+            const { uuid, contentlets } = containerContentlet;
+
+            // TODO: This is a temporary solution, we need to find a better way to handle this.
+            acc[uuid] = contentlets.map(({ _map = {}, ...rest }) => {
+                return {
+                    ...(_map as Record<string, unknown>),
+                    ...rest
+                };
+            });
+
+            return acc;
+        },
+        {} as Record<string, DotCMSBasicContentlet[]>
+    );
+};

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+    "extends": "../../../tsconfig.base.json",
+    "compilerOptions": {
+        "module": "ESNext",
+        "forceConsistentCasingInFileNames": true,
+        "strict": true,
+        "noImplicitOverride": true,
+        "noPropertyAccessFromIndexSignature": true,
+        "noImplicitReturns": true,
+        "noFallthroughCasesInSwitch": true
+    },
+    "files": [],
+    "include": [],
+    "references": [
+        {
+            "path": "./tsconfig.lib.json"
+        },
+        {
+            "path": "./tsconfig.spec.json"
+        }
+    ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,13 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "../../../dist/out-tsc",
+        "declaration": true,
+        "types": [""],
+        "target": "es2020",
+        "module": "es2020",
+        "moduleResolution": "node"
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,9 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "../../../dist/out-tsc",
+        "module": "commonjs",
+        "types": ["jest", "node"]
+    },
+    "include": ["jest.config.ts", "src/**/*.test.ts", "src/**/*.spec.ts", "src/**/*.d.ts"]
+}