@croct/sdk 0.16.1 → 0.17.0

package/src/container.ts

@@ -20,13 +20,12 @@ import {
     RetryChannel,
     GuaranteedChannel,
     EncodedChannel,
-    BeaconSocketChannel,
-    SocketChannel,
     SandboxChannel,
 } from './channel';
 import {ContentFetcher} from './contentFetcher';
 import {CookieCache, CookieCacheConfiguration} from './cache/cookieCache';
 import {FilteredLogger} from './logging/filteredLogger';
+import {HttpBeaconChannel} from './channel/httpBeaconChannel';
 
 export type DependencyResolver<T> = (container: Container) => T;
 
@@ -51,9 +50,13 @@ export type Configuration = {
     },
     eventMetadata?: {[key: string]: string},
     eventProcessor?: DependencyResolver<TrackingEventProcessor>,
+    defaultFetchTimeout?: number,
+    defaultPreferredLocale?: string,
 };
 
 export class Container {
+    public static readonly DEFAULT_FETCH_TIMEOUT = 5_000; // 5 seconds
+
     private readonly configuration: Configuration;
 
     private context?: Context;
@@ -99,6 +102,7 @@ export class Container {
             appId: this.configuration.appId,
             baseEndpointUrl: this.configuration.evaluationBaseEndpointUrl,
             logger: this.getLogger('Evaluator'),
+            defaultTimeout: this.configuration.defaultFetchTimeout ?? Container.DEFAULT_FETCH_TIMEOUT,
         });
     }
 
@@ -115,6 +119,8 @@ export class Container {
             appId: this.configuration.appId,
             baseEndpointUrl: this.configuration.contentBaseEndpointUrl,
             logger: this.getLogger('ContentFetcher'),
+            defaultTimeout: this.configuration.defaultFetchTimeout ?? Container.DEFAULT_FETCH_TIMEOUT,
+            defaultPreferredLocale: this.configuration.defaultPreferredLocale,
         });
     }
 
@@ -226,23 +232,18 @@ export class Container {
         const queuedChannel = new QueuedChannel(
             new RetryChannel({
                 channel: new GuaranteedChannel({
-                    channel: new BeaconSocketChannel({
-                        trackerEndpointUrl: `${trackerEndpointUrl}/${appId}`,
-                        tokenParameter: 'token',
-                        loggerFactory: this.getLogger.bind(this),
-                        logger: channelLogger,
-                        channelFactory: (url, logger): SocketChannel<any, any> => (
-                            new SocketChannel({url: url, logger: logger})
-                        ),
+                    channel: new HttpBeaconChannel({
+                        appId: appId,
+                        endpointUrl: trackerEndpointUrl,
                         cidAssigner: this.getCidAssigner(),
-                        cidParameter: 'clientId',
+                        logger: channelLogger,
                     }),
                     stamper: new TimeStamper(),
                     ackTimeout: 10000,
                     logger: channelLogger,
                 }),
                 retryPolicy: new BackoffPolicy({
-                    minRetryDelay: 1000, // 1 second
+                    minRetryDelay: 3000, // 3 seconds
                     maxRetryDelay: 60 * 1000, // 60 seconds
                     backoffFactor: 1.5, // 1.5 ^ attempt
                     backoffJitter: 1, // add randomness
@@ -300,12 +301,9 @@ export class Container {
     }
 
     private createBeaconQueue(): MonitoredQueue<string> {
-        const context = this.getContext();
-        const tab = context.getTab();
-
         return new MonitoredQueue<string>(
             new CapacityRestrictedQueue(
-                new PersistentQueue(this.getGlobalTabStorage('queue'), tab.id),
+                new PersistentQueue(this.getGlobalTabStorage('queue')),
                 this.configuration.beaconQueueSize,
             ),
             this.getLogger('BeaconQueue'),
@@ -349,9 +347,9 @@ export class Container {
     }
 
     private resolveStorageNamespace(namespace: string, ...subnamespace: string[]): string {
-        return `croct[${this.configuration
-            .appId
-            .toLowerCase()}].${[namespace].concat(subnamespace).join('.')}`;
+        const {appId} = this.configuration;
+
+        return `croct[${appId.toLowerCase()}].${[namespace].concat(subnamespace).join('.')}`;
     }
 
     private getLocalStorage(): Storage {

package/src/contentFetcher.ts

@@ -5,6 +5,7 @@ import {BASE_ENDPOINT_URL, CLIENT_LIBRARY} from './constants';
 import {formatMessage} from './error';
 import {Logger, NullLogger} from './logging';
 import type {ApiKey} from './apiKey';
+import {Help} from './help';
 
 export type ErrorResponse = {
     type: string,
@@ -54,10 +55,6 @@ export type DynamicContentOptions = BasicOptions & {
     clientId?: string,
     clientIp?: string,
     clientAgent?: string,
-    /**
-     * @deprecated Use `clientAgent` instead. This option will be removed in future releases.
-     */
-    userAgent?: string,
     userToken?: Token|string,
     previewToken?: Token|string,
     context?: EvaluationContext,
@@ -80,11 +77,15 @@ export type Configuration = {
     apiKey?: string|ApiKey,
     baseEndpointUrl?: string,
     logger?: Logger,
+    defaultTimeout?: number,
+    defaultPreferredLocale?: string,
 };
 
 type InternalConfiguration = {
     appId?: string,
     apiKey?: string,
+    defaultTimeout?: number,
+    defaultPreferredLocale?: string,
 };
 
 export class ContentFetcher {
@@ -117,6 +118,8 @@ export class ContentFetcher {
         this.configuration = {
             appId: configuration.appId,
             apiKey: apiKey,
+            defaultTimeout: configuration.defaultTimeout,
+            defaultPreferredLocale: configuration.defaultPreferredLocale,
         };
     }
 
@@ -127,34 +130,44 @@ export class ContentFetcher {
 
         return new Promise((resolve, reject) => {
             const abortController = new AbortController();
+            const timeout = options.timeout ?? this.configuration.defaultTimeout;
 
-            if (options.timeout !== undefined) {
+            if (timeout !== undefined) {
                 setTimeout(
                     () => {
                         const response: ErrorResponse = {
                             title: 'Maximum timeout reached before content could be loaded.',
                             type: ContentErrorType.TIMEOUT,
-                            detail: `The content took more than ${options.timeout}ms to load.`,
+                            detail: `The content took more than ${timeout}ms to load.`,
                             status: 408, // Request Timeout
                         };
 
                         abortController.abort();
 
+                        this.logHelp(response.status);
+
                         reject(new ContentError(response));
                     },
-                    options.timeout,
+                    timeout,
                 );
             }
 
             this.load(slotId, abortController.signal, options)
-                .then(
-                    response => response.json()
+                .then(response => {
+                    const region = response.headers.get('X-Croct-Region');
+                    const timing = response.headers.get('X-Croct-Timing');
+
+                    this.logger.debug(`Request processed by region ${region} in ${timing}`);
+
+                    return response.json()
                         .then(body => {
                             if (response.ok) {
-                                resolve(body);
-                            } else {
-                                reject(new ContentError(body));
+                                return resolve(body);
                             }
+
+                            this.logHelp(response.status);
+
+                            reject(new ContentError(body));
                         })
                         .catch(error => {
                             if (!response.ok) {
@@ -162,8 +175,8 @@ export class ContentFetcher {
                             }
 
                             throw error;
-                        }),
-                )
+                        });
+                })
                 .catch(error => {
                     if (!abortController.signal.aborted) {
                         reject(
@@ -204,22 +217,15 @@ export class ContentFetcher {
             payload.version = `${options.version}`;
         }
 
-        if (options.preferredLocale !== undefined) {
-            payload.preferredLocale = options.preferredLocale;
+        const preferredLocale = options.preferredLocale ?? this.configuration.defaultPreferredLocale;
+
+        if (preferredLocale !== undefined) {
+            payload.preferredLocale = preferredLocale;
         }
 
         const dynamic = ContentFetcher.isDynamicContent(options);
 
         if (dynamic) {
-            if (options.userAgent !== undefined) {
-                this.logger.warn(
-                    'The `userAgent` option is deprecated and '
-                    + 'will be removed in future releases. '
-                    + 'Please update the part of your code calling the `fetch` method '
-                    + 'to use the `clientAgent` option instead.',
-                );
-            }
-
             if (options.clientId !== undefined) {
                 headers['X-Client-Id'] = options.clientId;
             }
@@ -232,10 +238,8 @@ export class ContentFetcher {
                 headers['X-Token'] = options.userToken.toString();
             }
 
-            const clientAgent = options.clientAgent ?? options.userAgent;
-
-            if (clientAgent !== undefined) {
-                headers['X-Client-Agent'] = clientAgent;
+            if (options.clientAgent !== undefined) {
+                headers['X-Client-Agent'] = options.clientAgent;
             }
 
             if (options.context !== undefined) {
@@ -248,6 +252,13 @@ export class ContentFetcher {
         }
 
         return fetch(dynamic ? this.dynamicEndpoint : this.staticEndpoint, {
+            // Set the request mode to 'cors' when running in the browser.
+            // By default, the request mode is computed based on the referrer policy
+            // and response-tainting rules applied to the script that ultimately
+            // initiated the fetch, make this prone to errors due to unrelated
+            // configurations on the page.
+            // https://fetch.spec.whatwg.org/#origin-header
+            mode: typeof window === 'undefined' ? undefined : 'cors',
             credentials: 'omit',
             ...options.extra,
             method: 'POST',
@@ -257,6 +268,14 @@ export class ContentFetcher {
         });
     }
 
+    private logHelp(statusCode: number): void {
+        const help = Help.forStatusCode(statusCode);
+
+        if (help !== undefined) {
+            this.logger.error(help);
+        }
+    }
+
     private static isDynamicContent(options: FetchOptions): options is DynamicContentOptions {
         return options.static !== true;
     }

package/src/evaluator.ts

@@ -5,6 +5,7 @@ import {formatMessage} from './error';
 import {getLength, getLocation, Location} from './sourceLocation';
 import {Logger, NullLogger} from './logging';
 import type {ApiKey} from './apiKey';
+import {Help} from './help';
 
 export type Campaign = {
     name?: string,
@@ -37,10 +38,6 @@ export type EvaluationOptions = {
     clientId?: string,
     clientIp?: string,
     clientAgent?: string,
-    /**
-     * @deprecated Use `clientAgent` instead. This option will be removed in future releases.
-     */
-    userAgent?: string,
     userToken?: Token|string,
     timeout?: number,
     context?: EvaluationContext,
@@ -98,11 +95,13 @@ export type Configuration = {
     apiKey?: string|ApiKey,
     baseEndpointUrl?: string,
     logger?: Logger,
+    defaultTimeout?: number,
 };
 
 type InternalConfiguration = {
     appId?: string,
     apiKey?: string,
+    defaultTimeout?: number,
 };
 
 export class Evaluator {
@@ -132,6 +131,7 @@ export class Evaluator {
         this.configuration = {
             appId: configuration.appId,
             apiKey: apiKey,
+            defaultTimeout: configuration.defaultTimeout,
         };
     }
 
@@ -154,98 +154,99 @@ export class Evaluator {
             return Promise.reject(new QueryError(response));
         }
 
-        const body: JsonObject = {
+        const payload: JsonObject = {
             query: query,
         };
 
         if (options.context !== undefined) {
-            body.context = options.context;
+            payload.context = options.context;
         }
 
         return new Promise((resolve, reject) => {
             const abortController = new AbortController();
+            const timeout = options.timeout ?? this.configuration.defaultTimeout;
 
-            if (options.timeout !== undefined) {
+            if (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.`,
+                            detail: `The evaluation took more than ${timeout}ms to complete.`,
                             status: 408, // Request Timeout
                         };
 
                         abortController.abort();
 
+                        this.logHelp(response.status);
+
                         reject(new EvaluationError(response));
                     },
-                    options.timeout,
+                    timeout,
                 );
             }
 
-            const promise = this.fetch(body, abortController.signal, options);
+            const promise = this.fetch(payload, 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 (!response.ok) {
-                            throw new Error(`Error ${response.status} - ${response.statusText}`);
-                        }
-
-                        throw error;
-                    }),
-            )
-                .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
-                                }),
-                            );
-                        }
-                    },
-                );
+                response => {
+                    const region = response.headers.get('X-Croct-Region');
+                    const timing = response.headers.get('X-Croct-Timing');
+
+                    this.logger.debug(`Request processed by region ${region} in ${timing}`);
+
+                    return response.json()
+                        .then(body => {
+                            if (response.ok) {
+                                return resolve(body);
+                            }
+
+                            this.logHelp(response.status);
+
+                            const problem: ErrorResponse = body;
+
+                            switch (problem.type) {
+                                case EvaluationErrorType.INVALID_QUERY:
+                                case EvaluationErrorType.EVALUATION_FAILED:
+                                case EvaluationErrorType.TOO_COMPLEX_QUERY:
+                                    reject(new QueryError(problem as QueryErrorResponse));
+
+                                    break;
+
+                                default:
+                                    reject(new EvaluationError(problem));
+
+                                    break;
+                            }
+                        })
+                        .catch(error => {
+                            if (!response.ok) {
+                                throw new Error(`Error ${response.status} - ${response.statusText}`);
+                            }
+
+                            throw error;
+                        });
+                },
+            ).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, userToken} = options;
-        const clientAgent = options.clientAgent ?? options.userAgent;
-
-        if (options.userAgent !== undefined) {
-            this.logger.warn(
-                'The `userAgent` option is deprecated and '
-                + 'will be removed in future releases. '
-                + 'Please update the part of your code calling the `evaluate` method '
-                + 'to use the `clientAgent` option instead.',
-            );
-        }
+        const {clientId, clientIp, userToken, clientAgent} = options;
 
         const headers: Record<string, string> = {
             'Content-Type': 'application/json',
@@ -276,6 +277,13 @@ export class Evaluator {
         }
 
         return fetch(this.endpoint, {
+            // Set the request mode to 'cors' when running in the browser.
+            // By default, the request mode is computed based on the referrer policy
+            // and response-tainting rules applied to the script that ultimately
+            // initiated the fetch, make this prone to errors due to unrelated
+            // configurations on the page.
+            // https://fetch.spec.whatwg.org/#origin-header
+            mode: typeof window === 'undefined' ? undefined : 'cors',
             credentials: 'omit',
             ...options.extra,
             method: 'POST',
@@ -285,6 +293,14 @@ export class Evaluator {
         });
     }
 
+    private logHelp(statusCode: number): void {
+        const help = Help.forStatusCode(statusCode);
+
+        if (help !== undefined) {
+            this.logger.error(help);
+        }
+    }
+
     public toJSON(): never {
         // Prevent sensitive configuration from being serialized
         throw new Error('Unserializable value.');

package/src/facade/contentFetcherFacade.ts

@@ -21,11 +21,7 @@ function validate(options: unknown): asserts options is FetchOptions {
     }
 }
 
-type Options = {
-    preferredLocale?: string,
-};
-
-export type Configuration = Options & {
+export type Configuration = {
     contentFetcher: ContentFetcher,
     contextFactory: ContextFactory,
     previewTokenProvider: TokenProvider,
@@ -44,17 +40,12 @@ export class ContentFetcherFacade {
 
     private readonly cidAssigner: CidAssigner;
 
-    private readonly options: Options;
-
     public constructor(configuration: Configuration) {
         this.fetcher = configuration.contentFetcher;
         this.previewTokenProvider = configuration.previewTokenProvider;
         this.userTokenProvider = configuration.userTokenProvider;
         this.cidAssigner = configuration.cidAssigner;
         this.contextFactory = configuration.contextFactory;
-        this.options = {
-            preferredLocale: configuration.preferredLocale,
-        };
     }
 
     public async fetch<P extends JsonObject>(slotId: string, options: FetchOptions = {}): Promise<FetchResponse<P>> {
@@ -72,7 +63,7 @@ export class ContentFetcherFacade {
             version: options.version,
             context: this.contextFactory.createContext(options.attributes),
             timeout: options.timeout,
-            preferredLocale: options.preferredLocale ?? this.options.preferredLocale,
+            preferredLocale: options.preferredLocale,
         });
     }
 }

package/src/facade/sdkFacade.ts

@@ -17,11 +17,7 @@ import {ContentFetcherFacade} from './contentFetcherFacade';
 import {CookieCacheConfiguration} from '../cache/cookieCache';
 import {EventSubjectProcessor} from '../eventSubjectProcessor';
 
-type Options = {
-    preferredLocale?: string,
-};
-
-export type Configuration = Options & {
+export type Configuration = {
     appId: string,
     tokenScope?: TokenScope,
     debug?: boolean,
@@ -41,6 +37,8 @@ export type Configuration = Options & {
         userToken?: CookieCacheConfiguration,
         previewToken?: CookieCacheConfiguration,
     },
+    defaultFetchTimeout?: number,
+    defaultPreferredLocale?: string,
 };
 
 function validateConfiguration(configuration: unknown): asserts configuration is Configuration {
@@ -64,17 +62,14 @@ export class SdkFacade {
 
     private contentFetcherFacade?: ContentFetcherFacade;
 
-    private readonly options: Options;
-
-    private constructor(sdk: Sdk, options: Options = {}) {
+    private constructor(sdk: Sdk) {
         this.sdk = sdk;
-        this.options = options;
     }
 
     public static init(configuration: Configuration): SdkFacade {
         validateConfiguration(configuration);
 
-        const {track = true, userId, token, preferredLocale, ...containerConfiguration} = configuration;
+        const {track = true, userId, token, ...containerConfiguration} = configuration;
 
         if (userId !== undefined && token !== undefined) {
             throw new Error('Either the user ID or token can be specified, but not both.');
@@ -89,9 +84,6 @@ export class SdkFacade {
                 disableCidMirroring: containerConfiguration.disableCidMirroring ?? false,
                 eventProcessor: container => new EventSubjectProcessor(container.getLogger('EventSubjectProcessor')),
             }),
-            {
-                preferredLocale: preferredLocale,
-            },
         );
 
         if (userId !== undefined) {
@@ -184,7 +176,6 @@ export class SdkFacade {
                 cidAssigner: this.sdk.cidAssigner,
                 previewTokenProvider: this.sdk.previewTokenStore,
                 userTokenProvider: this.sdk.userTokenStore,
-                preferredLocale: this.options.preferredLocale,
             });
         }
 

package/src/help.ts

@@ -0,0 +1,24 @@
+export namespace Help {
+  export function forStatusCode(statusCode: number): string|undefined {
+      switch (statusCode) {
+          case 401:
+              return 'The request was not authorized, most likely due to invalid credentials. '
+                  + 'For help, see https://croct.help/sdk/js/invalid-credentials';
+
+          case 403:
+              return 'The origin of the request is not allowed in your application settings. '
+                  + 'For help, see https://croct.help/sdk/js/cors';
+
+          case 408:
+              return 'The request timed out. '
+                    + 'For help, see https://croct.help/sdk/js/timeout';
+
+          case 423:
+              return 'The application has exceeded the monthly active users (MAU) quota. '
+                  + 'For help, see https://croct.help/sdk/js/mau-exceeded';
+
+          default:
+              return undefined;
+      }
+  }
+}