@ckeditor/ckeditor5-cloud-services 0.0.0-internal-20241017.0

package/src/cloudservices.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module cloud-services/cloudservices
+ */
+import { ContextPlugin } from 'ckeditor5/src/core.js';
+import CloudServicesCore from './cloudservicescore.js';
+import type { CloudServicesConfig, TokenUrl } from './cloudservicesconfig.js';
+import type { InitializedToken } from './token/token.js';
+/**
+ * Plugin introducing the integration between CKEditor 5 and CKEditor Cloud Services .
+ *
+ * It initializes the token provider based on
+ * the {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig `config.cloudService`}.
+ */
+export default class CloudServices extends ContextPlugin implements CloudServicesConfig {
+    /**
+     * The authentication token URL for CKEditor Cloud Services or a callback to the token value promise. See the
+     * {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl} for more details.
+     */
+    readonly tokenUrl?: TokenUrl;
+    /**
+     * The URL to which the files should be uploaded.
+     */
+    readonly uploadUrl?: string;
+    /**
+     * The URL for web socket communication, used by the `RealTimeCollaborativeEditing` plugin. Every customer (organization in the CKEditor
+     * Ecosystem dashboard) has their own, unique URLs to communicate with CKEditor Cloud Services. The URL can be found in the
+     * CKEditor Ecosystem customer dashboard.
+     *
+     * Note: Unlike most plugins, `RealTimeCollaborativeEditing` is not included in any CKEditor 5 build and needs to be installed manually.
+     * Check [Collaboration overview](https://ckeditor.com/docs/ckeditor5/latest/features/collaboration/overview.html) for more details.
+     */
+    readonly webSocketUrl?: string;
+    /**
+     * An optional parameter used for integration with CKEditor Cloud Services when uploading the editor build to cloud services.
+     *
+     * Whenever the editor build or the configuration changes, this parameter should be set to a new, unique value to differentiate
+     * the new bundle (build + configuration) from the old ones.
+     */
+    readonly bundleVersion?: string;
+    /**
+     * Other plugins use this token for the authorization process. It handles token requesting and refreshing.
+     * Its value is `null` when {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl} is not provided.
+     *
+     * @readonly
+     */
+    token: InitializedToken | null;
+    /**
+     * A map of token object instances keyed by the token URLs.
+     */
+    private readonly _tokens;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CloudServices";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof CloudServicesCore];
+    /**
+     * @inheritDoc
+     */
+    init(): Promise<void>;
+    /**
+     * Registers an additional authentication token URL for CKEditor Cloud Services or a callback to the token value promise. See the
+     * {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl} for more details.
+     *
+     * @param tokenUrl The authentication token URL for CKEditor Cloud Services or a callback to the token value promise.
+     */
+    registerTokenUrl(tokenUrl: TokenUrl): Promise<InitializedToken>;
+    /**
+     * Returns an authentication token provider previously registered by {@link #registerTokenUrl}.
+     *
+     * @param tokenUrl The authentication token URL for CKEditor Cloud Services or a callback to the token value promise.
+     */
+    getTokenFor(tokenUrl: TokenUrl): InitializedToken;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+}

package/src/cloudservices.js

@@ -0,0 +1,109 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module cloud-services/cloudservices
+ */
+import { ContextPlugin } from 'ckeditor5/src/core.js';
+import { CKEditorError } from 'ckeditor5/src/utils.js';
+import CloudServicesCore from './cloudservicescore.js';
+/**
+ * Plugin introducing the integration between CKEditor 5 and CKEditor Cloud Services .
+ *
+ * It initializes the token provider based on
+ * the {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig `config.cloudService`}.
+ */
+export default class CloudServices extends ContextPlugin {
+    constructor() {
+        super(...arguments);
+        /**
+         * Other plugins use this token for the authorization process. It handles token requesting and refreshing.
+         * Its value is `null` when {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl} is not provided.
+         *
+         * @readonly
+         */
+        this.token = null;
+        /**
+         * A map of token object instances keyed by the token URLs.
+         */
+        this._tokens = new Map();
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'CloudServices';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [CloudServicesCore];
+    }
+    /**
+     * @inheritDoc
+     */
+    async init() {
+        const config = this.context.config;
+        const options = config.get('cloudServices') || {};
+        for (const [key, value] of Object.entries(options)) {
+            this[key] = value;
+        }
+        if (!this.tokenUrl) {
+            this.token = null;
+            return;
+        }
+        const cloudServicesCore = this.context.plugins.get('CloudServicesCore');
+        this.token = await cloudServicesCore.createToken(this.tokenUrl).init();
+        this._tokens.set(this.tokenUrl, this.token);
+    }
+    /**
+     * Registers an additional authentication token URL for CKEditor Cloud Services or a callback to the token value promise. See the
+     * {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl} for more details.
+     *
+     * @param tokenUrl The authentication token URL for CKEditor Cloud Services or a callback to the token value promise.
+     */
+    async registerTokenUrl(tokenUrl) {
+        // Reuse the token instance in case of multiple features using the same token URL.
+        if (this._tokens.has(tokenUrl)) {
+            return this.getTokenFor(tokenUrl);
+        }
+        const cloudServicesCore = this.context.plugins.get('CloudServicesCore');
+        const token = await cloudServicesCore.createToken(tokenUrl).init();
+        this._tokens.set(tokenUrl, token);
+        return token;
+    }
+    /**
+     * Returns an authentication token provider previously registered by {@link #registerTokenUrl}.
+     *
+     * @param tokenUrl The authentication token URL for CKEditor Cloud Services or a callback to the token value promise.
+     */
+    getTokenFor(tokenUrl) {
+        const token = this._tokens.get(tokenUrl);
+        if (!token) {
+            /**
+             * The provided `tokenUrl` was not registered by {@link module:cloud-services/cloudservices~CloudServices#registerTokenUrl}.
+             *
+             * @error cloudservices-token-not-registered
+             */
+            throw new CKEditorError('cloudservices-token-not-registered', this);
+        }
+        return token;
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        for (const token of this._tokens.values()) {
+            token.destroy();
+        }
+    }
+}

package/src/cloudservicesconfig.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module cloud-services/cloudservicesconfig
+ */
+/**
+ * Endpoint address to download the token or a callback that provides the token.
+ */
+export type TokenUrl = string | (() => Promise<string>);
+/**
+ * The configuration for all plugins using CKEditor Cloud Services.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( document.querySelector( '#editor' ), {
+ * 		cloudServices: {
+ * 			tokenUrl: 'https://example.com/cs-token-endpoint',
+ * 			uploadUrl: 'https://your-organization-id.cke-cs.com/easyimage/upload/'
+ * 		}
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ */
+export interface CloudServicesConfig {
+    /**
+     * A token URL or a token request function.
+     *
+     * As a string, it should be a URL to the security token endpoint in your application.
+     * The role of this endpoint is to securely authorize
+     * the end users of your application to use [CKEditor Cloud Services](https://ckeditor.com/ckeditor-cloud-services) only
+     * if they should have access e.g. to upload files with {@glink features/file-management/ckbox CKBox} or to use the
+     * {@glink @cs guides/collaboration/quick-start Collaboration} service.
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( document.querySelector( '#editor' ), {
+     * 		cloudServices: {
+     * 			tokenUrl: 'https://example.com/cs-token-endpoint',
+     * 			...
+     * 		}
+     * 	} )
+     * 	.then( ... )
+     * 	.catch( ... );
+     * ```
+     *
+     * As a function, it should provide a promise to the token value,
+     * so you can highly customize the token and provide your token URL endpoint.
+     * By using this approach you can set your own headers for the request.
+     *
+     * ```ts
+     * ClassicEditor
+     * 	.create( document.querySelector( '#editor' ), {
+     * 		cloudServices: {
+     * 			tokenUrl: () => new Promise( ( resolve, reject ) => {
+     * 				const xhr = new XMLHttpRequest();
+     *
+     * 				xhr.open( 'GET', 'https://example.com/cs-token-endpoint' );
+     *
+     * 				xhr.addEventListener( 'load', () => {
+     * 					const statusCode = xhr.status;
+     * 					const xhrResponse = xhr.response;
+     *
+     * 					if ( statusCode < 200 || statusCode > 299 ) {
+     * 						return reject( new Error( 'Cannot download new token!' ) );
+     * 					}
+     *
+     * 					return resolve( xhrResponse );
+     * 				} );
+     *
+     * 				xhr.addEventListener( 'error', () => reject( new Error( 'Network Error' ) ) );
+     * 				xhr.addEventListener( 'abort', () => reject( new Error( 'Abort' ) ) );
+     *
+     * 				xhr.setRequestHeader( customHeader, customValue );
+     *
+     * 				xhr.send();
+     * 			} ),
+     * 			...
+     * 		}
+     * 	} )
+     * ```
+     *
+     * If the request to the token endpoint fails, the editor will call the token request function every 5 seconds in attempt
+     * to refresh the token.
+     *
+     * You can find more information about token endpoints in the
+     * {@glink @cs guides/easy-image/quick-start##configuration Cloud Services - Quick start}
+     * and {@glink @cs developer-resources/security/token-endpoint Cloud Services - Token endpoint} documentation.
+     *
+     * Without a properly working token endpoint (token URL) CKEditor plugins will not be able to connect to CKEditor Cloud Services.
+     */
+    tokenUrl?: TokenUrl;
+    /**
+     * The endpoint URL for [CKEditor Cloud Services](https://ckeditor.com/ckeditor-cloud-services) uploads.
+     * This option must be set for Easy Image to work correctly.
+     *
+     * The upload URL is unique for each customer and can be found in the
+     * [CKEditor Ecosystem customer dashboard](https://dashboard.ckeditor.com) after subscribing to the Easy Image service.
+     * To learn how to start using Easy Image, check the {@glink @cs guides/easy-image/quick-start Easy Image - Quick start} documentation.
+     *
+     * Note: Make sure to also set the {@link module:cloud-services/cloudservicesconfig~CloudServicesConfig#tokenUrl} configuration option.
+     */
+    uploadUrl?: string;
+    /**
+     * The URL for web socket communication, used by the `RealTimeCollaborativeEditing` plugin. Every customer (organization in the CKEditor
+     * Ecosystem dashboard) has their own, unique URLs to communicate with CKEditor Cloud Services. The URL can be found in the
+     * CKEditor Ecosystem customer dashboard.
+     *
+     * Note: Unlike most plugins, `RealTimeCollaborativeEditing` is not included in any CKEditor 5 build and needs to be installed manually.
+     * Check [Collaboration overview](https://ckeditor.com/docs/ckeditor5/latest/features/collaboration/overview.html) for more details.
+     */
+    webSocketUrl?: string;
+    /**
+     * An optional parameter used for integration with CKEditor Cloud Services when uploading the editor build to cloud services.
+     *
+     * Whenever the editor build or the configuration changes, this parameter should be set to a new, unique value to differentiate
+     * the new bundle (build + configuration) from the old ones.
+     */
+    bundleVersion?: string;
+}

package/src/cloudservicesconfig.js

@@ -0,0 +1,5 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+export {};

package/src/cloudservicescore.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module cloud-services/cloudservicescore
+ */
+import { ContextPlugin } from 'ckeditor5/src/core.js';
+import type { TokenUrl } from './cloudservicesconfig.js';
+import Token, { type InitializedToken, type TokenOptions } from './token/token.js';
+import UploadGateway from './uploadgateway/uploadgateway.js';
+/**
+ * The `CloudServicesCore` plugin exposes the base API for communication with CKEditor Cloud Services.
+ */
+export default class CloudServicesCore extends ContextPlugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "CloudServicesCore";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * Creates the {@link module:cloud-services/token/token~Token} instance.
+     *
+     * @param tokenUrlOrRefreshToken Endpoint address to download the token or a callback that provides the token. If the
+     * value is a function it has to match the {@link module:cloud-services/token/token~Token#refreshToken} interface.
+     * @param options.initValue Initial value of the token.
+     * @param options.autoRefresh Specifies whether to start the refresh automatically.
+     */
+    createToken(tokenUrlOrRefreshToken: TokenUrl, options?: TokenOptions): Token;
+    /**
+     * Creates the {@link module:cloud-services/uploadgateway/uploadgateway~UploadGateway} instance.
+     *
+     * @param token Token used for authentication.
+     * @param apiAddress API address.
+     */
+    createUploadGateway(token: InitializedToken, apiAddress: string): UploadGateway;
+}

package/src/cloudservicescore.js

@@ -0,0 +1,47 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module cloud-services/cloudservicescore
+ */
+import { ContextPlugin } from 'ckeditor5/src/core.js';
+import Token from './token/token.js';
+import UploadGateway from './uploadgateway/uploadgateway.js';
+/**
+ * The `CloudServicesCore` plugin exposes the base API for communication with CKEditor Cloud Services.
+ */
+export default class CloudServicesCore extends ContextPlugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'CloudServicesCore';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * Creates the {@link module:cloud-services/token/token~Token} instance.
+     *
+     * @param tokenUrlOrRefreshToken Endpoint address to download the token or a callback that provides the token. If the
+     * value is a function it has to match the {@link module:cloud-services/token/token~Token#refreshToken} interface.
+     * @param options.initValue Initial value of the token.
+     * @param options.autoRefresh Specifies whether to start the refresh automatically.
+     */
+    createToken(tokenUrlOrRefreshToken, options) {
+        return new Token(tokenUrlOrRefreshToken, options);
+    }
+    /**
+     * Creates the {@link module:cloud-services/uploadgateway/uploadgateway~UploadGateway} instance.
+     *
+     * @param token Token used for authentication.
+     * @param apiAddress API address.
+     */
+    createUploadGateway(token, apiAddress) {
+        return new UploadGateway(token, apiAddress);
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module cloud-services
+ */
+export { default as CloudServices } from './cloudservices.js';
+export { default as CloudServicesCore } from './cloudservicescore.js';
+export type { TokenUrl, CloudServicesConfig } from './cloudservicesconfig.js';
+export type { default as Token, InitializedToken } from './token/token.js';
+export type { default as UploadGateway } from './uploadgateway/uploadgateway.js';
+export type { default as FileUploader } from './uploadgateway/fileuploader.js';
+import './augmentation.js';

package/src/index.js

@@ -0,0 +1,10 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module cloud-services
+ */
+export { default as CloudServices } from './cloudservices.js';
+export { default as CloudServicesCore } from './cloudservicescore.js';
+import './augmentation.js';

package/src/token/token.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type { TokenUrl } from '../cloudservicesconfig.js';
+declare const Token_base: {
+    new (): import("ckeditor5/src/utils.js").Observable;
+    prototype: import("ckeditor5/src/utils.js").Observable;
+};
+/**
+ * The class representing the token used for communication with CKEditor Cloud Services.
+ * The value of the token is retrieved from the specified URL and refreshed every 1 hour by default.
+ * If the token retrieval fails, the token will automatically retry in 5 seconds intervals.
+ */
+export default class Token extends /* #__PURE__ */ Token_base {
+    /**
+     * Value of the token.
+     * The value of the token is undefined if `initValue` is not provided or `init` method was not called.
+     * `create` method creates token with initialized value from url.
+     *
+     * @see module:cloud-services/token/token~InitializedToken
+     * @observable
+     * @readonly
+     */
+    value: string | undefined;
+    /**
+     * Base refreshing function.
+     */
+    private _refresh;
+    /**
+     * Cached token options.
+     */
+    private _options;
+    /**
+     * `setTimeout()` id for a token refresh when {@link module:cloud-services/token/token~TokenOptions auto refresh} is enabled.
+     */
+    private _tokenRefreshTimeout?;
+    /**
+     * Creates `Token` instance.
+     * Method `init` should be called after using the constructor or use `create` method instead.
+     *
+     * @param tokenUrlOrRefreshToken Endpoint address to download the token or a callback that provides the token. If the
+     * value is a function it has to match the {@link module:cloud-services/token/token~Token#refreshToken} interface.
+     */
+    constructor(tokenUrlOrRefreshToken: TokenUrl, options?: TokenOptions);
+    /**
+     * Initializes the token.
+     */
+    init(): Promise<InitializedToken>;
+    /**
+     * Refresh token method. Useful in a method form as it can be overridden in tests.
+     *
+     * This method will be invoked periodically based on the token expiry date after first call to keep the token up-to-date
+     * (requires {@link module:cloud-services/token/token~TokenOptions auto refresh option} to be set).
+     *
+     * If the token refresh fails, the method will retry in 5 seconds intervals until success or the token gets
+     * {@link #destroy destroyed}.
+     */
+    refreshToken(): Promise<InitializedToken>;
+    /**
+     * Destroys token instance. Stops refreshing.
+     */
+    destroy(): void;
+    /**
+     * Checks whether the provided token follows the JSON Web Tokens (JWT) format.
+     *
+     * @param tokenValue The token to validate.
+     */
+    private _validateTokenValue;
+    /**
+     * Registers a refresh token timeout for the time taken from token.
+     */
+    private _registerRefreshTokenTimeout;
+    /**
+     * Returns token refresh timeout time calculated from expire time in the token payload.
+     *
+     * If the token parse fails or the token payload doesn't contain, the default DEFAULT_TOKEN_REFRESH_TIMEOUT_TIME is returned.
+     */
+    private _getTokenRefreshTimeoutTime;
+    /**
+     * Creates a initialized {@link module:cloud-services/token/token~Token} instance.
+     *
+     * @param tokenUrlOrRefreshToken Endpoint address to download the token or a callback that provides the token. If the
+     * value is a function it has to match the {@link module:cloud-services/token/token~Token#refreshToken} interface.
+     */
+    static create(tokenUrlOrRefreshToken: TokenUrl, options?: TokenOptions): Promise<InitializedToken>;
+}
+/**
+ * A {@link ~Token} instance that has been initialized.
+ */
+export type InitializedToken = Token & {
+    value: string;
+};
+/**
+ * Options for creating tokens.
+ */
+export interface TokenOptions {
+    /**
+     * Initial value of the token.
+     */
+    initValue?: string;
+    /**
+     * Specifies whether to start the refresh automatically.
+     *
+     * @default true
+     */
+    autoRefresh?: boolean;
+}
+export {};