@croct/plug 0.11.0-alpha → 0.11.0-alpha.3

package/src/plug.ts

@@ -0,0 +1,470 @@
+import {Logger} from '@croct/sdk/logging';
+import {SessionFacade} from '@croct/sdk/facade/sessionFacade';
+import {UserFacade} from '@croct/sdk/facade/userFacade';
+import {TrackerFacade} from '@croct/sdk/facade/trackerFacade';
+import {EvaluationOptions, EvaluatorFacade} from '@croct/sdk/facade/evaluatorFacade';
+import {Configuration as SdkFacadeConfiguration, SdkFacade} from '@croct/sdk/facade/sdkFacade';
+import {formatCause} from '@croct/sdk/error';
+import {describe} from '@croct/sdk/validation';
+import {Optional} from '@croct/sdk/utilityTypes';
+import {Token} from '@croct/sdk/token';
+import {
+    ExternalTrackingEvent as ExternalEvent,
+    ExternalTrackingEventPayload as ExternalEventPayload,
+    ExternalTrackingEventType as ExternalEventType,
+} from '@croct/sdk/trackingEvents';
+import {VERSION} from '@croct/sdk';
+import {FetchOptions as BaseFetchOptions} from '@croct/sdk/facade/contentFetcherFacade';
+import {Plugin, PluginArguments, PluginFactory} from './plugin';
+import {CDN_URL} from './constants';
+import {factory as playgroundPluginFactory} from './playground';
+import {factory as previewPluginFactory} from './preview';
+import {EapFeatures} from './eap';
+import {VersionedSlotId, SlotContent} from './slot';
+import {JsonValue, JsonObject} from './sdk/json';
+
+export interface PluginConfigurations {
+    [key: string]: any;
+}
+
+export type Configuration = Optional<SdkFacadeConfiguration, 'appId'> & {
+    plugins?: PluginConfigurations,
+};
+
+export type FetchOptions = Omit<BaseFetchOptions, 'version'>;
+
+export type FetchResponse<I extends VersionedSlotId, C extends JsonObject = JsonObject> = {
+    content: SlotContent<I, C>,
+};
+
+/**
+ * @internal
+ */
+export type LegacyFetchResponse<I extends VersionedSlotId, C extends JsonObject = JsonObject> = FetchResponse<I, C> & {
+    /**
+     * @deprecated Use `content` instead.
+     */
+    payload: SlotContent<I, C>,
+};
+
+export interface Plug extends EapFeatures {
+    readonly tracker: TrackerFacade;
+    readonly user: UserFacade;
+    readonly session: SessionFacade;
+    readonly initialized: boolean;
+    readonly flushed: Promise<this>;
+    readonly plugged: Promise<this>;
+
+    plug(configuration: Configuration): void;
+
+    isAnonymous(): boolean;
+
+    getUserId(): string | null;
+
+    identify(userId: string): void;
+
+    anonymize(): void;
+
+    setToken(token: string): void;
+
+    unsetToken(): void;
+
+    track<T extends ExternalEventType>(type: T, payload: ExternalEventPayload<T>): Promise<ExternalEvent<T>>;
+
+    evaluate<T extends JsonValue>(expression: string, options?: EvaluationOptions): Promise<T>;
+
+    fetch<P extends JsonObject, I extends VersionedSlotId>(
+        slotId: I,
+        options?: FetchOptions
+    ): Promise<LegacyFetchResponse<I, P>>;
+
+    unplug(): Promise<void>;
+}
+
+const PLUGIN_NAMESPACE = 'Plugin';
+
+function detectAppId(): string | null {
+    const script = window.document.querySelector(`script[src^='${CDN_URL}']`);
+
+    if (!(script instanceof HTMLScriptElement)) {
+        return null;
+    }
+
+    return (new URL(script.src)).searchParams.get('appId');
+}
+
+export class GlobalPlug implements Plug {
+    private pluginFactories: {[key: string]: PluginFactory} = {
+        playground: playgroundPluginFactory,
+        preview: previewPluginFactory,
+    };
+
+    private instance?: SdkFacade;
+
+    private plugins: {[key: string]: Plugin} = {};
+
+    private initialize: {(): void};
+
+    private ready: Promise<void>;
+
+    public constructor() {
+        this.ready = new Promise(resolve => {
+            this.initialize = resolve;
+        });
+    }
+
+    public extend(name: string, plugin: PluginFactory): void {
+        if (this.pluginFactories[name] !== undefined) {
+            throw new Error(`Another plugin is already registered with name "${name}".`);
+        }
+
+        this.pluginFactories[name] = plugin;
+    }
+
+    public plug(configuration: Configuration = {}): void {
+        if (this.instance !== undefined) {
+            const logger = this.instance.getLogger();
+
+            logger.info('Croct is already plugged in.');
+
+            return;
+        }
+
+        const detectedAppId = detectAppId();
+        const configuredAppId = configuration.appId ?? null;
+
+        if (detectedAppId !== null && configuredAppId !== null && detectedAppId !== configuredAppId) {
+            throw new Error(
+                'The specified app ID and the auto-detected app ID are conflicting. '
+                + 'There is no need to specify an app ID when using an application-specific tag. '
+                + 'Please try again omitting the "appId" option.',
+            );
+        }
+
+        const appId = detectedAppId ?? configuredAppId;
+
+        if (appId === null) {
+            throw new Error(
+                'The app ID must be specified when it cannot be auto-detected. '
+                + 'Please try again specifying the "appId" option.',
+            );
+        }
+
+        const {plugins, test, ...sdkConfiguration} = configuration;
+
+        const sdk = SdkFacade.init({
+            ...sdkConfiguration,
+            appId: appId,
+            test: test ?? (typeof process === 'object' && (
+                process.env?.CROCT_TEST_MODE !== undefined
+                    ? process.env.CROCT_TEST_MODE === 'true'
+                    : process.env?.NODE_ENV === 'test'
+            )),
+        });
+
+        this.instance = sdk;
+
+        const logger = this.instance.getLogger();
+
+        if (detectedAppId === configuredAppId) {
+            logger.warn(
+                'It is strongly recommended omitting the "appId" option when using '
+                + 'the application-specific tag as it is detected automatically.',
+            );
+        }
+
+        const pending: Array<Promise<void>> = [];
+
+        const defaultEnabledPlugins = Object.fromEntries(
+            Object.keys(this.pluginFactories)
+                .map(name => [name, true]),
+        );
+
+        for (const [name, options] of Object.entries({...defaultEnabledPlugins, ...plugins})) {
+            logger.debug(`Initializing plugin "${name}"...`);
+
+            const factory = this.pluginFactories[name];
+
+            if (factory === undefined) {
+                logger.error(`Plugin "${name}" is not registered.`);
+
+                continue;
+            }
+
+            if (typeof options !== 'boolean' && (options === null || typeof options !== 'object')) {
+                logger.error(
+                    `Invalid options for plugin "${name}", `
+                    + `expected either boolean or object but got ${describe(options)}`,
+                );
+
+                continue;
+            }
+
+            if (options === false) {
+                logger.warn(`Plugin "${name}" is declared but not enabled`);
+
+                continue;
+            }
+
+            const args: PluginArguments = {
+                options: options === true ? {} : options,
+                sdk: {
+                    version: VERSION,
+                    appId: appId,
+                    tracker: sdk.tracker,
+                    evaluator: sdk.evaluator,
+                    user: sdk.user,
+                    session: sdk.session,
+                    tab: sdk.context.getTab(),
+                    userTokenStore: {
+                        getToken: sdk.getToken.bind(sdk),
+                        setToken: sdk.setToken.bind(sdk),
+                    },
+                    previewTokenStore: sdk.previewTokenStore,
+                    cidAssigner: sdk.cidAssigner,
+                    eventManager: sdk.eventManager,
+                    getLogger: (...namespace: string[]): Logger => sdk.getLogger(PLUGIN_NAMESPACE, name, ...namespace),
+                    getTabStorage: (...namespace: string[]): Storage => (
+                        sdk.getTabStorage(PLUGIN_NAMESPACE, name, ...namespace)
+                    ),
+                    getBrowserStorage: (...namespace: string[]): Storage => (
+                        sdk.getBrowserStorage(PLUGIN_NAMESPACE, name, ...namespace)
+                    ),
+                },
+            };
+
+            let plugin;
+
+            try {
+                plugin = factory(args);
+            } catch (error) {
+                logger.error(`Failed to initialize plugin "${name}": ${formatCause(error)}`);
+
+                continue;
+            }
+
+            logger.debug(`Plugin "${name}" initialized`);
+
+            if (typeof plugin !== 'object') {
+                continue;
+            }
+
+            this.plugins[name] = plugin;
+
+            const promise = plugin.enable();
+
+            if (!(promise instanceof Promise)) {
+                logger.debug(`Plugin "${name}" enabled`);
+
+                continue;
+            }
+
+            pending.push(
+                promise.then(() => logger.debug(`Plugin "${name}" enabled`))
+                    .catch(error => logger.error(`Failed to enable plugin "${name}": ${formatCause(error)}`)),
+            );
+        }
+
+        const initializeEap = window.croctEap?.initialize;
+
+        if (typeof initializeEap === 'function') {
+            initializeEap.call(this);
+        }
+
+        Promise.all(pending)
+            .then(() => {
+                this.initialize();
+
+                logger.debug('Initialization complete');
+            });
+    }
+
+    public get initialized(): boolean {
+        return this.instance !== undefined;
+    }
+
+    public get plugged(): Promise<this> {
+        return this.ready.then(() => this);
+    }
+
+    public get flushed(): Promise<this> {
+        return this.tracker
+            .flushed
+            .then(() => this);
+    }
+
+    private get sdk(): SdkFacade {
+        if (this.instance === undefined) {
+            throw new Error('Croct is not plugged in.');
+        }
+
+        return this.instance;
+    }
+
+    public get tracker(): TrackerFacade {
+        return this.sdk.tracker;
+    }
+
+    public get evaluator(): EvaluatorFacade {
+        return this.sdk.evaluator;
+    }
+
+    public get user(): UserFacade {
+        return this.sdk.user;
+    }
+
+    public get session(): SessionFacade {
+        return this.sdk.session;
+    }
+
+    public isAnonymous(): boolean {
+        return this.sdk
+            .context
+            .isAnonymous();
+    }
+
+    public getUserId(): string | null {
+        return this.sdk
+            .context
+            .getUser();
+    }
+
+    public identify(userId: string): void {
+        if (typeof userId !== 'string') {
+            throw new Error('The user ID must be a string. Read more on https://croct.help/plug-js/id-conversion');
+        }
+
+        this.sdk.identify(userId);
+    }
+
+    public anonymize(): void {
+        this.sdk.anonymize();
+    }
+
+    public setToken(token: string): void {
+        this.sdk.setToken(Token.parse(token));
+    }
+
+    public unsetToken(): void {
+        this.sdk.unsetToken();
+    }
+
+    public track<T extends ExternalEventType>(type: T, payload: ExternalEventPayload<T>): Promise<ExternalEvent<T>> {
+        return this.sdk
+            .tracker
+            .track(type, payload);
+    }
+
+    public evaluate<T extends JsonValue>(expression: string, options: EvaluationOptions = {}): Promise<T> {
+        return this.sdk
+            .evaluator
+            .evaluate(expression, options) as Promise<T>;
+    }
+
+    public test(expression: string, options: EvaluationOptions = {}): Promise<boolean> {
+        return this.evaluate(expression, options)
+            .then(result => result === true);
+    }
+
+    public get fetch(): Plug['fetch'] {
+        return this.eap(
+            'fetch',
+            <C extends JsonObject, I extends VersionedSlotId = VersionedSlotId>(
+                slotId: I,
+                options: FetchOptions = {},
+            ): Promise<LegacyFetchResponse<I, C>> => {
+                const [id, version] = slotId.split('@') as [string, `${number}` | 'latest' | undefined];
+                const logger = this.sdk.getLogger();
+
+                return this.sdk
+                    .contentFetcher
+                    .fetch<SlotContent<I, C>>(id, {
+                        ...options,
+                        version: version === 'latest' ? undefined : version,
+                    })
+                    .then(
+                        response => ({
+                            get payload(): SlotContent<I, C> {
+                                logger.warn(
+                                    'Accessing the "payload" property of the fetch response is deprecated'
+                                    + ' and will be removed in a future version. Use the "content" property instead.',
+                                );
+
+                                return response.content;
+                            },
+                            content: response.content,
+                        }),
+                    );
+            },
+        );
+    }
+
+    public async unplug(): Promise<void> {
+        if (this.instance === undefined) {
+            return;
+        }
+
+        const {instance, plugins} = this;
+
+        const logger = this.sdk.getLogger();
+        const pending: Array<Promise<void>> = [];
+
+        for (const [pluginName, controller] of Object.entries(plugins)) {
+            if (typeof controller.disable !== 'function') {
+                continue;
+            }
+
+            logger.debug(`Disabling plugin "${pluginName}"...`);
+
+            const promise = controller.disable();
+
+            if (!(promise instanceof Promise)) {
+                logger.debug(`Plugin "${pluginName}" disabled`);
+
+                continue;
+            }
+
+            pending.push(
+                promise.then(() => logger.debug(`Plugin "${pluginName}" disabled`))
+                    .catch(error => logger.error(`Failed to disable "${pluginName}": ${formatCause(error)}`)),
+            );
+        }
+
+        // Reset
+        delete this.instance;
+
+        this.plugins = {};
+        this.ready = new Promise(resolve => {
+            this.initialize = resolve;
+        });
+
+        await Promise.all(pending);
+
+        try {
+            await instance.close();
+        } finally {
+            logger.info('🔌 Croct has been unplugged.');
+        }
+    }
+
+    private eap<T extends keyof EapFeatures>(feature: T, api: EapFeatures[T]): EapFeatures[T] {
+        const eap = window.croctEap;
+        const method: EapFeatures[T] | undefined = typeof eap === 'object' ? eap[feature] : undefined;
+
+        if (typeof method !== 'function') {
+            return api;
+        }
+
+        return method.bind(
+            new Proxy(this, {
+                get: (plug, property): any => {
+                    if (property === feature) {
+                        return api;
+                    }
+
+                    return plug[property as keyof GlobalPlug];
+                },
+            }),
+        );
+    }
+}

package/src/plugin.ts

@@ -0,0 +1,39 @@
+import {TokenStore} from './sdk/token';
+import {EvaluatorFacade} from './sdk/evaluation';
+import {TrackerFacade} from './sdk/tracking';
+import {Tab, Logger, SdkEventManager, SessionFacade, UserFacade, CidAssigner} from './sdk';
+
+export interface PluginSdk {
+    readonly version: string;
+    readonly appId: string;
+    readonly tracker: TrackerFacade;
+    readonly evaluator: EvaluatorFacade;
+    readonly user: UserFacade;
+    readonly session: SessionFacade;
+    readonly tab: Tab;
+    readonly userTokenStore: TokenStore;
+    readonly previewTokenStore: TokenStore;
+    readonly cidAssigner: CidAssigner;
+    readonly eventManager: SdkEventManager;
+
+    getLogger(...namespace: string[]): Logger;
+
+    getTabStorage(...namespace: string[]): Storage;
+
+    getBrowserStorage(...namespace: string[]): Storage;
+}
+
+export interface PluginArguments<T = any> {
+    options: T;
+    sdk: PluginSdk;
+}
+
+export interface PluginFactory<T = any> {
+    (args: PluginArguments<T>): Plugin;
+}
+
+export interface Plugin {
+    enable(): Promise<void>|void;
+
+    disable?(): Promise<void>|void;
+}

package/src/preview.ts

@@ -0,0 +1,187 @@
+import {formatCause} from '@croct/sdk/error';
+import {uuid4} from '@croct/sdk/uuid';
+import {Logger} from './sdk';
+import {Plugin, PluginFactory} from './plugin';
+import {Token, TokenStore} from './sdk/token';
+import {PREVIEW_WIDGET_ORIGIN, PREVIEW_WIDGET_URL} from './constants';
+
+const PREVIEW_PARAMETER = 'croct-preview';
+const PREVIEW_EXIT = 'exit';
+
+export type Configuration = {
+    tokenStore: TokenStore,
+    logger: Logger,
+};
+
+export class PreviewPlugin implements Plugin {
+    private static readonly PREVIEW_PARAMS = {
+        experienceName: 'experience',
+        experimentName: 'experiment',
+        audienceName: 'audience',
+        variantName: 'variant',
+    };
+
+    private readonly tokenStore: TokenStore;
+
+    private readonly logger: Logger;
+
+    private readonly widgetId = `croct-preview:${uuid4()}`;
+
+    public constructor(configuration: Configuration) {
+        this.tokenStore = configuration.tokenStore;
+        this.logger = configuration.logger;
+    }
+
+    public enable(): void {
+        const url = new URL(window.location.href);
+        const previewData = url.searchParams.get(PREVIEW_PARAMETER);
+
+        if (previewData !== null) {
+            this.updateToken(previewData);
+
+            this.updateUrl();
+
+            // Some frameworks (e.g. Next) may revert the URL change
+            // after the page is loaded, so ensure the token is removed
+            // from the URL after a short delay.
+            setTimeout(this.updateUrl, 500);
+        }
+
+        const token = this.tokenStore.getToken();
+
+        if (token !== null) {
+            this.insertWidget(this.getWidgetUrl(token));
+        }
+    }
+
+    public disable(): void {
+        document.getElementById(this.widgetId)?.remove();
+    }
+
+    private updateToken(data: string): void {
+        if (data === PREVIEW_EXIT) {
+            this.logger.debug('Exiting preview mode.');
+
+            this.tokenStore.setToken(null);
+
+            return;
+        }
+
+        try {
+            let token: Token|null = Token.parse(data);
+            const {exp} = token.getPayload();
+
+            if (exp !== undefined && exp <= Date.now() / 1000) {
+                this.logger.debug('Preview token expired.');
+
+                token = null;
+            }
+
+            this.tokenStore.setToken(token);
+        } catch (error) {
+            this.tokenStore.setToken(null);
+
+            this.logger.warn(`Invalid preview token: ${formatCause(error)}`);
+        }
+    }
+
+    private getWidgetUrl(token: Token): string {
+        const params = this.getWidgetParams(token);
+        let queryString = params.toString();
+
+        if (queryString !== '') {
+            queryString = `?${queryString}`;
+        }
+
+        return `${PREVIEW_WIDGET_URL}${queryString}`;
+    }
+
+    private getWidgetParams(token: Token): URLSearchParams {
+        const {metadata = {}} = token.getPayload();
+        const params = new URLSearchParams();
+
+        if (metadata === null || typeof metadata !== 'object' || Array.isArray(metadata)) {
+            return params;
+        }
+
+        for (const [key, param] of Object.entries(PreviewPlugin.PREVIEW_PARAMS)) {
+            const value = metadata[key];
+
+            if (typeof value === 'string') {
+                params.set(param, value);
+            }
+        }
+
+        return params;
+    }
+
+    private insertWidget(url: string): void {
+        const widget = this.createWidget(url);
+
+        window.addEventListener('message', event => {
+            if (event.origin !== PREVIEW_WIDGET_ORIGIN) {
+                return;
+            }
+
+            switch (event.data.type) {
+                case 'croct:preview:leave': {
+                    this.tokenStore.setToken(null);
+
+                    const exitUrl = new URL(window.location.href);
+
+                    exitUrl.searchParams.set(PREVIEW_PARAMETER, PREVIEW_EXIT);
+
+                    window.location.replace(exitUrl.toString());
+
+                    break;
+                }
+
+                case 'croct:preview:resize':
+                    widget.style.width = `${event.data.width}px`;
+                    widget.style.height = `${event.data.height}px`;
+
+                    break;
+            }
+        });
+
+        document.body.prepend(widget);
+    }
+
+    private updateUrl(): void {
+        const url = new URL(window.location.href);
+
+        if (url.searchParams.has(PREVIEW_PARAMETER)) {
+            url.searchParams.delete(PREVIEW_PARAMETER);
+
+            window.history.replaceState({}, '', url.toString());
+        }
+    }
+
+    private createWidget(url: string): HTMLIFrameElement {
+        const widget = document.createElement('iframe');
+
+        widget.setAttribute('id', this.widgetId);
+        widget.setAttribute('src', url);
+        widget.setAttribute('sandbox', 'allow-scripts allow-same-origin');
+
+        widget.style.position = 'fixed';
+        widget.style.width = '0px';
+        widget.style.height = '0px';
+        widget.style.right = '0';
+        widget.style.bottom = '0';
+        widget.style.border = '0';
+        widget.style.overflow = 'hidden';
+        widget.style.zIndex = '2147483647';
+
+        return widget;
+    }
+}
+
+export const factory: PluginFactory = (props): PreviewPlugin => {
+    const {sdk} = props;
+
+    return new PreviewPlugin({
+        tokenStore: props.sdk.previewTokenStore,
+        logger: sdk.getLogger(),
+    });
+};

package/src/sdk/evaluation.ts

@@ -0,0 +1,2 @@
+export {EvaluatorFacade, EvaluationOptions} from '@croct/sdk/facade/evaluatorFacade';
+export {EvaluationError, EvaluationErrorType, QueryError} from '@croct/sdk/evaluator';