@dotcms/client 1.0.1 → 1.0.2

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

@@ -0,0 +1,95 @@
+import { DotCMSClientConfig, DotCMSComposedPageResponse, DotCMSExtendedPageResponse, DotCMSPageResponse, DotCMSPageRequestParams, RequestOptions } from '@dotcms/types';
+/**
+ * Client for interacting with the DotCMS Page API.
+ * Provides methods to retrieve and manipulate pages.
+ */
+export declare class PageClient {
+    /**
+     * Request options including authorization headers.
+     * @private
+     */
+    private requestOptions;
+    /**
+     * Site ID for page requests.
+     * @private
+     */
+    private siteId;
+    /**
+     * DotCMS URL for page requests.
+     * @private
+     */
+    private dotcmsUrl;
+    /**
+     * 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);
+    /**
+     * 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
+     *                      }
+     *                  `
+     *              ]
+     *          }
+     *      });
+     * ```
+     */
+    get<T extends DotCMSExtendedPageResponse = DotCMSPageResponse>(url: string, options?: DotCMSPageRequestParams): Promise<DotCMSComposedPageResponse<T>>;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * 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 declare const buildPageQuery: ({ page, fragments, additionalQueries }: {
+    page?: string;
+    fragments?: string[];
+    additionalQueries?: string;
+}) => string;
+/**
+ * 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 declare function buildQuery(queryData: Record<string, string>): string;
+/**
+ * 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 declare function mapResponseData(responseData: Record<string, string>, keys: string[]): 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 declare function fetchGraphQL({ baseURL, body, headers }: {
+    baseURL: string;
+    body: string;
+    headers: Record<string, string>;
+}): Promise<any>;

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

@@ -0,0 +1,13 @@
+import { DotCMSGraphQLPageResponse, DotCMSPageAsset } 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 declare const graphqlToPageEntity: (graphQLPageResponse: DotCMSGraphQLPageResponse) => DotCMSPageAsset | null;

package/.eslintrc.json

@@ -1,18 +0,0 @@
-{
-    "extends": ["../../../.eslintrc.base.json"],
-    "ignorePatterns": ["!**/*"],
-    "overrides": [
-        {
-            "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
-            "rules": {}
-        },
-        {
-            "files": ["*.ts", "*.tsx"],
-            "rules": {}
-        },
-        {
-            "files": ["*.js", "*.jsx"],
-            "rules": {}
-        }
-    ]
-}

package/jest.config.ts

@@ -1,15 +0,0 @@
-/* eslint-disable */
-export default {
-    displayName: 'sdk-client',
-    preset: '../../../jest.preset.js',
-    transform: {
-        '^.+\\.[tj]s$': [
-            'ts-jest',
-            {
-                tsconfig: '<rootDir>/tsconfig.spec.json'
-            }
-        ]
-    },
-    moduleFileExtensions: ['ts', 'js', 'html'],
-    coverageDirectory: '../../../coverage/libs/sdk/client'
-};

package/project.json

@@ -1,73 +0,0 @@
-{
-    "name": "sdk-client",
-    "$schema": "../../../node_modules/nx/schemas/project-schema.json",
-    "sourceRoot": "libs/sdk/client/src",
-    "projectType": "library",
-    "targets": {
-        "build": {
-            "executor": "@nx/rollup:rollup",
-            "outputs": ["{options.outputPath}"],
-            "options": {
-                "format": ["esm", "cjs"],
-                "compiler": "tsc",
-                "additionalEntryPoints": ["libs/sdk/client/src/internal.ts"],
-                "generateExportsField": true,
-                "outputPath": "dist/libs/sdk/client",
-                "assets": [{ "input": "libs/sdk/client", "output": ".", "glob": "*.md" }],
-                "main": "libs/sdk/client/src/index.ts",
-                "tsConfig": "libs/sdk/client/tsconfig.lib.json"
-            }
-        },
-        "build:js": {
-            "executor": "@nx/esbuild:esbuild",
-            "outputs": ["{options.outputPath}"],
-            "options": {
-                "outputPath": "../dotCMS/src/main/webapp/html/js/editor-js",
-                "outputFileName": "sdk-editor",
-                "format": ["esm"],
-                "tsConfig": "libs/sdk/client/tsconfig.lib.json",
-                "project": "libs/sdk/client/package.json",
-                "entryFile": "libs/sdk/client/src/lib/deprecated/editor/sdk-editor-vtl.ts",
-                "external": ["react/jsx-runtime"],
-                "rollupConfig": "@nrwl/react/plugins/bundle-rollup",
-                "compiler": "tsc",
-                "extractCss": false,
-                "minify": true
-            }
-        },
-        "publish": {
-            "executor": "nx:run-commands",
-            "options": {
-                "command": "node tools/scripts/publish.mjs sdk-client {args.ver} {args.tag}"
-            },
-            "dependsOn": ["build"]
-        },
-        "nx-release-publish": {
-            "options": {
-                "packageRoot": "dist/libs/sdk/client"
-            }
-        },
-        "lint": {
-            "executor": "@nx/eslint:lint",
-            "outputs": ["{options.outputFile}"],
-            "options": {
-                "lintFilePatterns": ["libs/sdk/client/**/*.ts"]
-            }
-        },
-        "test": {
-            "executor": "@nrwl/jest:jest",
-            "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
-            "options": {
-                "jestConfig": "libs/sdk/client/jest.config.ts",
-                "passWithNoTests": true
-            },
-            "configurations": {
-                "ci": {
-                    "ci": true,
-                    "codeCoverage": true
-                }
-            }
-        }
-    },
-    "tags": []
-}

package/src/lib/client/client.spec.ts

@@ -1,147 +0,0 @@
-import { DotCMSClientConfig, RequestOptions } from '@dotcms/types';
-
-import { createDotCMSClient } from './client';
-import { Content } from './content/content-api';
-import { NavigationClient } from './navigation/navigation-api';
-import { PageClient } from './page/page-api';
-
-// Mock the dependencies
-jest.mock('./content/content-api');
-jest.mock('./navigation/navigation-api');
-jest.mock('./page/page-api');
-
-describe('DotCMSClient', () => {
-    const originalTypeError = global.TypeError;
-    const mockTypeError = jest.fn().mockImplementation((...args) => new originalTypeError(...args));
-    const validConfig: DotCMSClientConfig = {
-        dotcmsUrl: 'https://demo.dotcms.com',
-        authToken: 'test-token',
-        siteId: 'test-site',
-        requestOptions: {
-            headers: {
-                'Content-Type': 'application/json'
-            }
-        }
-    };
-
-    beforeEach(() => {
-        jest.clearAllMocks();
-        global.TypeError = mockTypeError as unknown as ErrorConstructor;
-    });
-
-    afterAll(() => {
-        global.TypeError = originalTypeError;
-    });
-
-    it('should initialize sub-clients with correct parameters', () => {
-        createDotCMSClient(validConfig);
-
-        const expectedRequestOptions: RequestOptions = {
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: 'Bearer test-token'
-            }
-        };
-
-        expect(PageClient).toHaveBeenCalledWith(
-            expect.objectContaining({
-                dotcmsUrl: 'https://demo.dotcms.com',
-                authToken: 'test-token',
-                siteId: 'test-site'
-            }),
-            expectedRequestOptions
-        );
-
-        expect(Content).toHaveBeenCalledWith(expectedRequestOptions, 'https://demo.dotcms.com');
-
-        expect(NavigationClient).toHaveBeenCalledWith(
-            expect.objectContaining({
-                dotcmsUrl: 'https://demo.dotcms.com',
-                authToken: 'test-token',
-                siteId: 'test-site'
-            }),
-            expectedRequestOptions
-        );
-    });
-
-    it('should add authorization header to request options', () => {
-        const configWithoutHeaders: DotCMSClientConfig = {
-            dotcmsUrl: 'https://demo.dotcms.com',
-            authToken: 'test-token'
-        };
-
-        createDotCMSClient(configWithoutHeaders);
-
-        expect(PageClient).toHaveBeenCalledWith(
-            expect.anything(),
-            expect.objectContaining({
-                headers: {
-                    Authorization: 'Bearer test-token'
-                }
-            })
-        );
-    });
-
-    it('should preserve existing headers when adding authorization', () => {
-        createDotCMSClient(validConfig);
-
-        expect(PageClient).toHaveBeenCalledWith(
-            expect.anything(),
-            expect.objectContaining({
-                headers: {
-                    'Content-Type': 'application/json',
-                    Authorization: 'Bearer test-token'
-                }
-            })
-        );
-    });
-
-    describe('validation and normalization', () => {
-        it('should throw TypeError when dotcmsUrl is invalid', () => {
-            const invalidConfig = {
-                ...validConfig,
-                dotcmsUrl: 'invalid-url'
-            };
-
-            try {
-                createDotCMSClient(invalidConfig);
-                fail('Expected TypeError to be thrown');
-            } catch (error) {
-                // This is expected, verify the error
-            }
-
-            expect(mockTypeError).toHaveBeenCalledWith(
-                "Invalid configuration - 'dotcmsUrl' must be a valid URL"
-            );
-        });
-
-        it('should throw TypeError when authToken is missing', () => {
-            const invalidConfig = {
-                ...validConfig,
-                authToken: ''
-            };
-
-            try {
-                createDotCMSClient(invalidConfig);
-                fail('Expected TypeError to be thrown');
-            } catch (error) {
-                // This is expected, verify the error
-            }
-
-            expect(mockTypeError).toHaveBeenCalledWith(
-                "Invalid configuration - 'authToken' is required"
-            );
-        });
-
-        it('should extract origin from dotcmsUrl', () => {
-            const configWithPath = {
-                ...validConfig,
-                dotcmsUrl: 'https://demo.dotcms.com/some/path'
-            };
-
-            createDotCMSClient(configWithPath);
-
-            expect(Content).toHaveBeenCalledWith(expect.anything(), 'https://demo.dotcms.com');
-        });
-    });
-});

package/src/lib/client/client.ts

@@ -1,125 +0,0 @@
-import { consola } from 'consola';
-
-import { DotCMSClientConfig, RequestOptions } from '@dotcms/types';
-
-import { Content } from './content/content-api';
-import { NavigationClient } from './navigation/navigation-api';
-import { PageClient } from './page/page-api';
-
-/**
- * Parses a string into a URL object.
- *
- * @param url - The URL string to parse
- * @returns A URL object if parsing is successful, undefined otherwise
- */
-function parseURL(url: string): URL | undefined {
-    try {
-        return new URL(url);
-    } catch {
-        consola.error('[DotCMS Client]: Invalid URL:', url);
-
-        return undefined;
-    }
-}
-
-/**
- * Default configuration for the DotCMS client.
- */
-const defaultConfig: DotCMSClientConfig = {
-    dotcmsUrl: '',
-    authToken: '',
-    requestOptions: {}
-};
-
-/**
- * Client for interacting with the DotCMS REST API.
- * Provides access to content, page, and navigation functionality.
- */
-class DotCMSClient {
-    private config: DotCMSClientConfig;
-    private requestOptions!: RequestOptions;
-
-    /**
-     * Client for content-related operations.
-     */
-    content: Content;
-
-    /**
-     * Client for page-related operations.
-     */
-    page: PageClient;
-
-    /**
-     * Client for navigation-related operations.
-     */
-    nav: NavigationClient;
-
-    /**
-     * Creates a new DotCMS client instance.
-     *
-     * @param config - Configuration options for the client
-     * @throws Warning if dotcmsUrl is invalid or authToken is missing
-     */
-    constructor(config: DotCMSClientConfig = defaultConfig) {
-        this.config = config;
-        this.requestOptions = this.createAuthenticatedRequestOptions(this.config);
-
-        // Initialize clients
-        this.page = new PageClient(this.config, this.requestOptions);
-        this.nav = new NavigationClient(this.config, this.requestOptions);
-        this.content = new Content(this.requestOptions, this.config.dotcmsUrl);
-    }
-
-    /**
-     * Creates request options with authentication headers.
-     *
-     * @param config - The client configuration
-     * @returns Request options with authorization headers
-     */
-    private createAuthenticatedRequestOptions(config: DotCMSClientConfig): RequestOptions {
-        return {
-            ...config.requestOptions,
-            headers: {
-                ...config.requestOptions?.headers,
-                Authorization: `Bearer ${config.authToken}`
-            }
-        };
-    }
-}
-
-/**
- * Creates and returns a new DotCMS client instance.
- *
- * @param config - Configuration options for the client
- * @returns A configured DotCMS client instance
- * @example
- * ```typescript
- * const client = dotCMSCreateClient({
- *   dotcmsUrl: 'https://demo.dotcms.com',
- *   authToken: 'your-auth-token'
- * });
- *
- * // Use the client to fetch content
- * const pages = await client.page.get('/about-us');
- * ```
- */
-export const createDotCMSClient = (clientConfig: DotCMSClientConfig): DotCMSClient => {
-    const { dotcmsUrl, authToken } = clientConfig || {};
-    const instanceUrl = parseURL(dotcmsUrl)?.origin;
-
-    if (!instanceUrl) {
-        throw new TypeError("Invalid configuration - 'dotcmsUrl' must be a valid URL");
-    }
-
-    if (!authToken) {
-        throw new TypeError("Invalid configuration - 'authToken' is required");
-    }
-
-    const config = {
-        ...clientConfig,
-        authToken,
-        dotcmsUrl: instanceUrl
-    };
-
-    return new DotCMSClient(config);
-};