@empathyco/x-components/types/src/x-installer/x-installer.d.ts

Empathy X Components

import type { Plugin } from 'vue';
import type { XPluginOptions } from '../plugins/x-plugin.types';
import type { WireMetadata, XEventsTypes } from '../wiring/index';
import type { XBus } from '../x-bus';
import type { NormalisedSnippetConfig, SnippetConfig, XAPI } from './api/api.types';
import type { InitWrapper, InstallXOptions } from './types';
declare global {
    interface Window {
        InterfaceX?: XAPI;
        initX?: (() => SnippetConfig) | SnippetConfig;
    }
}
/**
 * The purpose of this class is to offer a quick way to initialize the XComponents in a setup
 * project. It allows to receive all the options in {@link InstallXOptions} which is an extension
 * of {@link XPluginOptions} with all the options for the plugin and some options more.
 *
 * This class does multiple things:
 * 1. Install the {@link XPlugin} with the {@link XPluginOptions}.
 * 2. Creates the public {@link XAPI} and add it to global window.
 * 3. Creates the Vue Application for the customer project.
 *
 * The steps 2 & 3 are optional and depends on the options passed in {@link InstallXOptions}.
 *
 * @example The way to use this class is the next:
 *    1. Create the installer passing in the {@link InstallXOptions}. This only save the options:
 *
 * ```
 *        const installer = new XInstaller(installXOptions)
 * ```
 *
 *    2. Initialize passing the {@link SnippetConfig}. This installs the plugin and creates the App.
 *       There are 3 different ways to do this:
 *
 *        2.1 Using the created installer:
 *
 * ```
 *            installer.init(snippetConfig)
 * ```
 *
 *        2.2 If the API option is enabled (`createAPI` is `true` in {@link InstallXOptions}, or
 *            is not present as the default value is `true`) then this init step can be done with
 *            the Public API:
 *
 * ```
 *            window.InterfaceX.init(snippetConfig)
 * ```
 *
 *        2.3 When the script of the project build is loaded it searches for a global `initX`
 *            variable that the customer must have in their website. This variable can be a
 *            function that returns the {@link SnippetConfig} or an object that contains the
 *            {@link SnippetConfig} itself:
 *
 * ```
 *            window.initX = function() {
 *                 return {
 *                   instance,
 *                   env,
 *                   scope,
 *                   lang,
 *                   uiLang,
 *                   currency,
 *                   consent,
 *                   documentDirection
 *                 };
 *              };
 * ```
 *
 * ```
 *            window.initX = {
 *                 instance,
 *                 env,
 *                 scope,
 *                 lang,
 *                 uiLang,
 *                 currency,
 *                 consent,
 *                 documentDirection
 *               };
 * ```
 *
 * @public
 */
export declare class XInstaller {
    protected readonly options: InstallXOptions;
    private app;
    private api?;
    /**
     * The configuration coming from the snippet {@link SnippetConfig}.
     *
     * @internal
     */
    protected snippetConfig?: NormalisedSnippetConfig;
    /**
     * Receives the {@link InstallXOptions} and merges it with the default fallback options. Also
     * creates the public {@link XAPI}.
     *
     * @remarks Auto initializes the Vue application if window.initX is defined as a function or
     * object specifying the {@link SnippetConfig | snippet config}.
     *
     *
     * @param options - The {@link InstallXOptions}.
     *
     * @public
     */
    constructor(options: InstallXOptions);
    /**
     * Creates the public {@link XAPI} using the `api` option from {@link InstallXOptions}. If this
     * `api` option is not passed, then a default {@link BaseXAPI} is created. To disable the API
     * creation the value `false` must be passed in the `api` option.
     *
     * @internal
     */
    protected createAPI(): void;
    /**
     * Retrieves the {@link SnippetConfig | snippet config} it is defined in the window.initX.
     *
     * @returns The snippet config if it is defined or undefined otherwise.
     *
     * @internal
     */
    private retrieveSnippetConfig;
    /**
     * Receives the {@link SnippetConfig | snippet config} or retrieves it from window.initX and
     * installs the plugin and initializes the Vue application.
     *
     * @param snippetConfig - The {@link SnippetConfig} that receives from snippet integration.
     *
     * @returns If {@link SnippetConfig | snippet config} is passed or configured in window.initX,
     * returns an object with the {@link XAPI}, the XBus, the {@link XPlugin}
     * and the Vue application instance. Else, a rejected promise is returned.
     *
     * @public
     */
    init(snippetConfig: SnippetConfig): Promise<InitWrapper>;
    init(): Promise<InitWrapper | void>;
    /**
     * Creates the {@link XPluginOptions} object.
     *
     * @returns The {@link XPluginOptions} object.
     *
     * @internal
     */
    protected getPluginOptions(): XPluginOptions;
    /**
     * This method returns the bus instance to be used in the {@link XPlugin} and in the {@link XAPI}.
     * It returns the `bus` parameter in the {@link InstallXOptions} or if not provided, then
     * creates a new instance of {@link @empathyco/x-bus#XPriorityBus | bus}.
     *
     * @returns XBus - The bus instance.
     *
     * @internal
     */
    protected createBus(): XBus<XEventsTypes, WireMetadata>;
    /**
     * Creates and install the Vue Plugin. If `plugin` parameter is passed in the
     * {@link InstallXOptions}, then it is used. If not, then a new instance of {@link XPlugin} is
     * created and installed.
     *
     * @param pluginOptions - The {@link XPluginOptions} to passed as parameter to the install method
     * of the plugin.
     * @param bus - The XBus to be used to create the XPlugin.
     *
     * @returns Plugin<XPluginOption> - The plugin instance.
     * @internal
     */
    protected installPlugin(pluginOptions: XPluginOptions, bus: XBus<XEventsTypes, WireMetadata>): Plugin<XPluginOptions>;
    /**
     * Runs the installExtraPlugins callback defined in the {@link InstallXOptions}
     * to allow the user to install more plugins to the App.
     *
     * @param bus - The events bus used in the application.
     * @returns An empty promise.
     * @internal
     */
    protected installExtraPlugins(bus: XBus<XEventsTypes, WireMetadata>): Promise<void>;
    /**
     * In the case that the `rootComponent` parameter is present in the {@link InstallXOptions},
     * then a new Vue application is created using that component as root.
     *
     * @internal
     */
    protected createApp(): void;
    protected normaliseSnippetConfig(snippetConfig: SnippetConfig): NormalisedSnippetConfig;
    protected normaliseSnippetConfig(snippetConfig: Partial<SnippetConfig>): Partial<SnippetConfig>;
    /**
     * It returns the HTML element to mount the Vue Application. If the `domElement` parameter in
     * the {@link InstallXOptions} is an Element or an element selector, then this will be used.
     * The `domElement` can also be a function with the {@link SnippetConfig} as parameter which
     * returns an Element or element selector to use.
     * If it is not present, a new <div> Element is created and appended to the body.
     *
     * @param domElement - {@link InstallXOptions.domElement} Element, ShadowRoot, string or function
     * used to mount the Vue Application.
     *
     * @returns The Element or ShadowRoot to use as mounting target for the Vue Application.
     * @internal
     */
    protected getMountingTarget(domElement?: InstallXOptions['domElement']): Element | ShadowRoot;
    /**
     * It updates all the provided properties from the current snippet config.
     *
     * @param newSnippetConfig - All the properties to be updated in the {@link SnippetConfig}.
     *
     * @internal
     */
    protected updateSnippetConfig(newSnippetConfig: Partial<SnippetConfig>): void;
    /**
     * Getter for the snippet config object.
     *
     * @returns The {@link NormalisedSnippetConfig | snippetConfig} object.
     *
     * @public
     */
    protected getSnippetConfig(): NormalisedSnippetConfig;
}
//# sourceMappingURL=x-installer.d.ts.map