@croct/sdk 0.11.0-alpha → 0.11.0-alpha.2

package/src/context.ts

@@ -0,0 +1,137 @@
+import {Token, TokenStore, CachedTokenStore, ReplicatedTokenStore, InMemoryTokenStore} from './token';
+import {Tab, UrlSanitizer} from './tab';
+import {uuid4} from './uuid';
+import {EventDispatcher} from './eventManager';
+import {SdkEventMap} from './sdkEvents';
+import {LocalStorageCache} from './cache';
+
+export type TokenScope = 'isolated' | 'global' | 'contextual';
+
+export type Configuration = {
+    tokenScope: TokenScope,
+    urlSanitizer?: UrlSanitizer,
+    eventDispatcher: ContextEventDispatcher,
+    cache: {
+        tabId: LocalStorageCache,
+        tabToken: LocalStorageCache,
+        browserToken: LocalStorageCache,
+    },
+};
+
+type ContextEventDispatcher = EventDispatcher<Pick<SdkEventMap, 'tokenChanged'>>;
+
+function tokenEquals(left: Token|null, right: Token|null): boolean {
+    return left === right || (left !== null && right !== null && left.toString() === right.toString());
+}
+
+export class Context {
+    private readonly tab: Tab;
+
+    private readonly tokenStore: TokenStore;
+
+    private readonly eventDispatcher: ContextEventDispatcher;
+
+    private lastToken: Token|null;
+
+    private constructor(tab: Tab, tokenStore: TokenStore, eventDispatcher: ContextEventDispatcher) {
+        this.tab = tab;
+        this.tokenStore = tokenStore;
+        this.eventDispatcher = eventDispatcher;
+        this.lastToken = tokenStore.getToken();
+        this.syncToken = this.syncToken.bind(this);
+    }
+
+    public static load({cache, tokenScope, eventDispatcher, urlSanitizer}: Configuration): Context {
+        let tabId: string | null = cache.tabId.get();
+        let newTab = false;
+
+        if (tabId === null) {
+            tabId = uuid4(true);
+            newTab = true;
+        }
+
+        const tab = new Tab(tabId, newTab, urlSanitizer);
+
+        cache.tabId.clear();
+
+        tab.addListener('unload', () => cache.tabId.put(tab.id));
+
+        switch (tokenScope) {
+            case 'isolated':
+                return new Context(tab, new InMemoryTokenStore(), eventDispatcher);
+
+            case 'global': {
+                const context = new Context(tab, new CachedTokenStore(cache.browserToken), eventDispatcher);
+
+                cache.browserToken.addListener(context.syncToken);
+
+                return context;
+            }
+
+            case 'contextual': {
+                const primaryStorage = new CachedTokenStore(cache.tabToken);
+                const secondaryStorage = new CachedTokenStore(cache.browserToken);
+
+                if (tab.isNew) {
+                    primaryStorage.setToken(secondaryStorage.getToken());
+                }
+
+                tab.addListener('visibilityChange', event => {
+                    if (event.detail.visible) {
+                        secondaryStorage.setToken(primaryStorage.getToken());
+                    }
+                });
+
+                return new Context(tab, new ReplicatedTokenStore(primaryStorage, secondaryStorage), eventDispatcher);
+            }
+        }
+    }
+
+    public getTab(): Tab {
+        return this.tab;
+    }
+
+    public isAnonymous(): boolean {
+        const token = this.getToken();
+
+        return token == null || token.isAnonymous();
+    }
+
+    public getUser(): string | null {
+        const token = this.getToken();
+
+        return token == null ? null : token.getSubject();
+    }
+
+    public getToken(): Token | null {
+        return this.tokenStore.getToken();
+    }
+
+    public setToken(token: Token | null): void {
+        const oldToken = this.lastToken;
+
+        this.lastToken = token;
+        this.tokenStore.setToken(token);
+
+        if (!tokenEquals(oldToken, token)) {
+            this.eventDispatcher.dispatch('tokenChanged', {
+                oldToken: oldToken,
+                newToken: token,
+            });
+        }
+    }
+
+    private syncToken(): void {
+        const newToken = this.tokenStore.getToken();
+        const oldToken = this.lastToken;
+
+        if (!tokenEquals(oldToken, newToken)) {
+            this.lastToken = newToken;
+
+            this.eventDispatcher.dispatch('tokenChanged', {
+                oldToken: oldToken,
+                newToken: newToken,
+            });
+        }
+    }
+}

package/src/error.ts

@@ -0,0 +1,31 @@
+function extractMessage(error: unknown): string {
+    if (error instanceof Error) {
+        return error.message;
+    }
+
+    if (typeof error === 'string' && error !== '') {
+        return error;
+    }
+
+    return 'unknown error';
+}
+
+export function formatMessage(error: unknown): string {
+    const message = extractMessage(error);
+
+    if (message.length === 0) {
+        return message;
+    }
+
+    return message.charAt(0).toUpperCase() + message.slice(1);
+}
+
+export function formatCause(error: unknown): string {
+    const message = formatMessage(error);
+
+    if (message.length === 0) {
+        return message;
+    }
+
+    return message.charAt(0).toLowerCase() + message.slice(1);
+}

package/src/evaluator.ts

@@ -0,0 +1,251 @@
+import {JsonObject, JsonValue} from '@croct/json';
+import {Token} from './token';
+import {EVALUATION_ENDPOINT_URL, MAX_QUERY_LENGTH} from './constants';
+import {formatMessage} from './error';
+import {getLength, getLocation, Location} from './sourceLocation';
+
+export type Campaign = {
+    name?: string,
+    source?: string,
+    medium?: string,
+    term?: string,
+    content?: string,
+};
+
+export type Page = {
+    url: string,
+    title?: string,
+    referrer?: string,
+};
+
+export type EvaluationContext = {
+    timeZone?: string,
+    campaign?: Campaign,
+    page?: Page,
+    attributes?: JsonObject,
+};
+
+type AllowedFetchOptions = Exclude<keyof RequestInit, 'method' | 'body' | 'headers' | 'signal'>;
+
+type ExtraFetchOptions<T extends keyof RequestInit = AllowedFetchOptions> = Pick<RequestInit, T>
+    & {[key in Exclude<keyof RequestInit, T>]?: never}
+    & Record<string, any>;
+
+export type EvaluationOptions = {
+    clientId?: string,
+    clientIp?: string,
+    userAgent?: string,
+    userToken?: Token|string,
+    timeout?: number,
+    context?: EvaluationContext,
+    extra?: ExtraFetchOptions,
+};
+
+export enum EvaluationErrorType {
+    TIMEOUT = 'https://croct.help/api/evaluation#timeout',
+    UNEXPECTED_ERROR = 'https://croct.help/api/evaluation#unexpected-error',
+    INVALID_QUERY = 'https://croct.help/api/evaluation#invalid-query',
+    TOO_COMPLEX_QUERY = 'https://croct.help/api/evaluation#too-complex-query',
+    EVALUATION_FAILED = 'https://croct.help/api/evaluation#evaluation-failed',
+    UNALLOWED_RESULT = 'https://croct.help/api/evaluation#unallowed-result',
+    UNSERIALIZABLE_RESULT = 'https://croct.help/api/evaluation#unserializable-result',
+}
+
+export type ErrorResponse = {
+    type: EvaluationErrorType,
+    title: string,
+    status: number,
+    detail?: string,
+};
+
+export class EvaluationError<T extends ErrorResponse = ErrorResponse> extends Error {
+    public readonly response: T;
+
+    public constructor(response: T) {
+        super(response.title);
+
+        this.response = response;
+
+        Object.setPrototypeOf(this, EvaluationError.prototype);
+    }
+}
+
+type QueryErrorDetail = {
+    cause: string,
+    location: Location,
+};
+
+export type QueryErrorResponse = ErrorResponse & {
+    errors: QueryErrorDetail[],
+};
+
+export class QueryError extends EvaluationError<QueryErrorResponse> {
+    public constructor(response: QueryErrorResponse) {
+        super(response);
+
+        Object.setPrototypeOf(this, QueryError.prototype);
+    }
+}
+
+export type Configuration = {
+    appId?: string,
+    apiKey?: string,
+    endpointUrl?: string,
+};
+
+export class Evaluator {
+    public static readonly MAX_QUERY_LENGTH = MAX_QUERY_LENGTH;
+
+    private readonly configuration: Configuration;
+
+    private readonly endpoint: string;
+
+    public constructor(configuration: Configuration) {
+        if ((configuration.appId === undefined) === (configuration.apiKey === undefined)) {
+            throw new Error('Either the application ID or the API key must be provided.');
+        }
+
+        const {endpointUrl, apiKey} = configuration;
+
+        // eslint-disable-next-line prefer-template -- Better readability
+        this.endpoint = (endpointUrl ?? EVALUATION_ENDPOINT_URL).replace(/\/+$/, '')
+            + (apiKey === undefined ? '/client' : '/external')
+            + '/web/evaluate';
+
+        this.configuration = configuration;
+    }
+
+    public evaluate(query: string, options: EvaluationOptions = {}): Promise<JsonValue> {
+        const length = getLength(query);
+
+        if (length > Evaluator.MAX_QUERY_LENGTH) {
+            const response: QueryErrorResponse = {
+                title: 'The query is too complex.',
+                status: 422, // Unprocessable Entity
+                type: EvaluationErrorType.TOO_COMPLEX_QUERY,
+                detail: `The query must be at most ${Evaluator.MAX_QUERY_LENGTH} characters long, `
+                    + `but it is ${length} characters long.`,
+                errors: [{
+                    cause: 'The query is longer than expected.',
+                    location: getLocation(query, 0, Math.max(length - 1, 0)),
+                }],
+            };
+
+            return Promise.reject(new QueryError(response));
+        }
+
+        const body: JsonObject = {
+            query: query,
+        };
+
+        if (options.context !== undefined) {
+            body.context = options.context;
+        }
+
+        return new Promise((resolve, reject) => {
+            const abortController = new AbortController();
+
+            if (options.timeout !== undefined) {
+                setTimeout(
+                    () => {
+                        const response: ErrorResponse = {
+                            title: 'Maximum evaluation timeout reached before evaluation could complete.',
+                            type: EvaluationErrorType.TIMEOUT,
+                            detail: `The evaluation took more than ${options.timeout}ms to complete.`,
+                            status: 408, // Request Timeout
+                        };
+
+                        abortController.abort();
+
+                        reject(new EvaluationError(response));
+                    },
+                    options.timeout,
+                );
+            }
+
+            const promise = this.fetch(body, abortController.signal, options);
+
+            promise.then(
+                response => response.json()
+                    .then(data => {
+                        if (response.ok) {
+                            return resolve(data);
+                        }
+
+                        const errorResponse: ErrorResponse = data;
+
+                        switch (errorResponse.type) {
+                            case EvaluationErrorType.INVALID_QUERY:
+                            case EvaluationErrorType.EVALUATION_FAILED:
+                            case EvaluationErrorType.TOO_COMPLEX_QUERY:
+                                reject(new QueryError(errorResponse as QueryErrorResponse));
+
+                                break;
+
+                            default:
+                                reject(new EvaluationError(errorResponse));
+
+                                break;
+                        }
+                    }),
+            )
+                .catch(
+                    error => {
+                        if (!abortController.signal.aborted) {
+                            reject(
+                                new EvaluationError({
+                                    title: formatMessage(error),
+                                    type: EvaluationErrorType.UNEXPECTED_ERROR,
+                                    detail: 'Please try again or contact Croct support if the error persists.',
+                                    status: 500, // Internal Server Error
+                                }),
+                            );
+                        }
+                    },
+                );
+        });
+    }
+
+    private fetch(body: JsonObject, signal: AbortSignal, options: EvaluationOptions): Promise<Response> {
+        const {appId, apiKey} = this.configuration;
+        const {clientId, clientIp, userAgent, userToken} = options;
+
+        const headers = new Headers();
+
+        if (apiKey !== undefined) {
+            headers.set('X-Api-Key', apiKey);
+        } else if (appId !== undefined) {
+            headers.set('X-App-Id', appId);
+        }
+
+        if (clientId !== undefined) {
+            headers.set('X-Client-Id', clientId);
+        }
+
+        if (clientIp !== undefined) {
+            headers.set('X-Client-Ip', clientIp);
+        }
+
+        if (userToken !== undefined) {
+            headers.set('X-Token', userToken.toString());
+        }
+
+        if (userAgent !== undefined) {
+            headers.set('User-Agent', userAgent);
+        }
+
+        return fetch(this.endpoint, {
+            credentials: 'omit',
+            ...options.extra,
+            method: 'POST',
+            headers: headers,
+            signal: signal,
+            body: JSON.stringify(body),
+        });
+    }
+
+    public toJSON(): never {
+        // Prevent sensitive configuration from being serialized
+        throw new Error('Unserializable value.');
+    }
+}

package/src/eventManager.ts

@@ -0,0 +1,53 @@
+export interface EventListener<T> {
+    (event: T): void;
+}
+
+export type EventMap = Record<string, Record<string, any>>;
+
+export interface EventDispatcher<TEvents extends EventMap> {
+    dispatch<T extends keyof TEvents>(eventName: T, event: TEvents[T]): void;
+}
+
+export interface EventSubscriber<TEvents extends EventMap> {
+    addListener<T extends keyof TEvents>(eventName: T, listener: EventListener<TEvents[T]>): void;
+
+    removeListener<T extends keyof TEvents>(eventName: T, listener: EventListener<TEvents[T]>): void;
+}
+
+export interface EventManager<DEvents extends EventMap, SEvents extends EventMap = DEvents>
+    extends EventDispatcher<DEvents>, EventSubscriber<SEvents> {
+}
+
+export class SynchronousEventManager<TEvents extends EventMap> implements EventManager<TEvents> {
+    private readonly listeners: {[type in keyof TEvents]?: Array<EventListener<TEvents[type]>>} = {};
+
+    public addListener<T extends keyof TEvents>(type: T, listener: EventListener<TEvents[T]>): void {
+        const listeners: Array<EventListener<TEvents[T]>> = this.listeners[type] ?? [];
+
+        listeners.push(listener);
+
+        this.listeners[type] = listeners;
+    }
+
+    public removeListener<T extends keyof TEvents>(eventName: T, listener: EventListener<TEvents[T]>): void {
+        const listeners = this.listeners[eventName];
+
+        if (listeners === undefined) {
+            return;
+        }
+
+        const index = listeners.indexOf(listener);
+
+        if (index >= 0) {
+            listeners.splice(index, 1);
+        }
+    }
+
+    public dispatch<T extends keyof TEvents>(eventName: T, event: TEvents[T]): void {
+        const listeners = this.listeners[eventName];
+
+        if (listeners !== undefined) {
+            listeners.forEach(listener => listener(event));
+        }
+    }
+}

package/src/facade/contentFetcherFacade.ts

@@ -0,0 +1,69 @@
+import {JsonObject} from '@croct/json';
+import {formatCause} from '../error';
+import {ContentFetcher, FetchResponse} from '../contentFetcher';
+import {ContextFactory} from './evaluatorFacade';
+import {fetchOptionsSchema as optionsSchema} from '../schema';
+import {TokenProvider} from '../token';
+import {CidAssigner} from '../cid';
+
+export type FetchOptions = {
+    version?: `${number}`|number,
+    preferredLocale?: string,
+    timeout?: number,
+    attributes?: JsonObject,
+};
+
+function validate(options: unknown): asserts options is FetchOptions {
+    try {
+        optionsSchema.validate(options);
+    } catch (violation) {
+        throw new Error(`Invalid options: ${formatCause(violation)}`);
+    }
+}
+
+export type Configuration = {
+    contentFetcher: ContentFetcher,
+    contextFactory: ContextFactory,
+    previewTokenProvider: TokenProvider,
+    userTokenProvider: TokenProvider,
+    cidAssigner: CidAssigner,
+};
+
+export class ContentFetcherFacade {
+    private readonly fetcher: ContentFetcher;
+
+    private readonly contextFactory: ContextFactory;
+
+    private readonly previewTokenProvider: TokenProvider;
+
+    private readonly userTokenProvider: TokenProvider;
+
+    private readonly cidAssigner: CidAssigner;
+
+    public constructor(configuration: Configuration) {
+        this.fetcher = configuration.contentFetcher;
+        this.previewTokenProvider = configuration.previewTokenProvider;
+        this.userTokenProvider = configuration.userTokenProvider;
+        this.cidAssigner = configuration.cidAssigner;
+        this.contextFactory = configuration.contextFactory;
+    }
+
+    public async fetch<P extends JsonObject>(slotId: string, options: FetchOptions = {}): Promise<FetchResponse<P>> {
+        if (typeof slotId !== 'string' || slotId.length === 0) {
+            throw new Error('The slot ID must be a non-empty string.');
+        }
+
+        validate(options);
+
+        return this.fetcher.fetch(slotId, {
+            static: false,
+            clientId: await this.cidAssigner.assignCid(),
+            userToken: this.userTokenProvider.getToken() ?? undefined,
+            previewToken: this.previewTokenProvider.getToken() ?? undefined,
+            version: options.version,
+            preferredLocale: options.preferredLocale,
+            context: this.contextFactory.createContext(options.attributes),
+            timeout: options.timeout,
+        });
+    }
+}

package/src/facade/evaluatorFacade.ts

@@ -0,0 +1,152 @@
+import {JsonObject, JsonValue} from '@croct/json';
+import {Evaluator, Campaign, EvaluationContext, Page} from '../evaluator';
+import {Tab} from '../tab';
+import {evaluationOptionsSchema as optionsSchema} from '../schema';
+import {formatCause} from '../error';
+import {TokenProvider} from '../token';
+import {CidAssigner} from '../cid';
+
+export type EvaluationOptions = {
+    timeout?: number,
+    attributes?: JsonObject,
+};
+
+function validate(options: unknown): asserts options is EvaluationOptions {
+    try {
+        optionsSchema.validate(options);
+    } catch (violation) {
+        throw new Error(`Invalid options: ${formatCause(violation)}`);
+    }
+}
+
+export interface ContextFactory {
+    createContext(attributes?: JsonObject): EvaluationContext;
+}
+
+export type Configuration = {
+    evaluator: Evaluator,
+    contextFactory: ContextFactory,
+    userTokenProvider: TokenProvider,
+    cidAssigner: CidAssigner,
+};
+
+export class EvaluatorFacade {
+    private readonly evaluator: Evaluator;
+
+    private readonly contextFactory: ContextFactory;
+
+    private readonly tokenProvider: TokenProvider;
+
+    private readonly cidAssigner: CidAssigner;
+
+    public constructor(configuration: Configuration) {
+        this.evaluator = configuration.evaluator;
+        this.contextFactory = configuration.contextFactory;
+        this.tokenProvider = configuration.userTokenProvider;
+        this.cidAssigner = configuration.cidAssigner;
+    }
+
+    public async evaluate(query: string, options: EvaluationOptions = {}): Promise<JsonValue> {
+        if (typeof query !== 'string' || query.length === 0) {
+            throw new Error('The query must be a non-empty string.');
+        }
+
+        validate(options);
+
+        return this.evaluator.evaluate(query, {
+            clientId: await this.cidAssigner.assignCid(),
+            userToken: this.tokenProvider.getToken() ?? undefined,
+            timeout: options.timeout,
+            context: this.contextFactory.createContext(options.attributes),
+        });
+    }
+}
+
+export class MinimalContextFactory implements ContextFactory {
+    public createContext(attributes?: JsonObject): EvaluationContext {
+        if (attributes === undefined) {
+            return {};
+        }
+
+        return {attributes: attributes};
+    }
+}
+
+export class TabContextFactory implements ContextFactory {
+    private readonly tab: Tab;
+
+    public constructor(tab: Tab) {
+        this.tab = tab;
+    }
+
+    public createContext(attributes?: JsonObject): EvaluationContext {
+        const url = new URL(this.tab.url);
+        const context: EvaluationContext = {};
+
+        const page: Page = {
+            title: this.tab.title,
+            url: url.toString(),
+        };
+
+        const {referrer} = this.tab;
+
+        if (referrer.length > 0) {
+            page.referrer = referrer;
+        }
+
+        context.page = page;
+
+        const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone ?? null;
+
+        if (timeZone !== null) {
+            context.timeZone = timeZone;
+        }
+
+        const campaign = TabContextFactory.createCampaign(url);
+
+        if (Object.keys(campaign).length > 0) {
+            context.campaign = campaign;
+        }
+
+        if (attributes !== undefined && Object.keys(attributes).length > 0) {
+            context.attributes = attributes;
+        }
+
+        return context;
+    }
+
+    private static createCampaign(url: URL): Campaign {
+        const campaign: Campaign = {};
+
+        for (const [parameter, value] of url.searchParams.entries()) {
+            switch (parameter.toLowerCase()) {
+                case 'utm_campaign':
+                    campaign.name = value;
+
+                    break;
+
+                case 'utm_source':
+                    campaign.source = value;
+
+                    break;
+
+                case 'utm_term':
+                    campaign.term = value;
+
+                    break;
+
+                case 'utm_medium':
+                    campaign.medium = value;
+
+                    break;
+
+                case 'utm_content':
+                    campaign.content = value;
+
+                    break;
+            }
+        }
+
+        return campaign;
+    }
+}

package/src/facade/index.ts

@@ -0,0 +1,7 @@
+export {EvaluatorFacade, ContextFactory, MinimalContextFactory, TabContextFactory} from './evaluatorFacade';
+export {SdkFacade} from './sdkFacade';
+export {SessionFacade} from './sessionFacade';
+export {SessionPatch} from './sessionPatch';
+export {TrackerFacade} from './trackerFacade';
+export {UserFacade} from './userFacade';
+export {UserPatch} from './userPatch';