@croct/sdk 0.16.2 → 0.17.1

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.',
+                            title: `Content could not be loaded in time for slot '${slotId}'.`,
                             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(`Content for slot '${slotId}' 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) {
@@ -264,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,18 +131,20 @@ export class Evaluator {
         this.configuration = {
             appId: configuration.appId,
             apiKey: apiKey,
+            defaultTimeout: configuration.defaultTimeout,
         };
     }
 
     public evaluate(query: string, options: EvaluationOptions = {}): Promise<JsonValue> {
         const length = getLength(query);
+        const reference = query.length > 20 ? `${query.slice(0, 20)}...` : 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, `
+                detail: `The query "${reference}" must be at most ${Evaluator.MAX_QUERY_LENGTH} characters long, `
                     + `but it is ${length} characters long.`,
                 errors: [{
                     cause: 'The query is longer than expected.',
@@ -154,98 +155,101 @@ 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.',
+                            title: `Evaluation could not be completed in time for query "${reference}".`,
                             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(
+                        `Evaluation of the query "${reference}" 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',
@@ -292,6 +296,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;
+      }
+  }
+}

package/src/queue/persistentQueue.ts

@@ -1,8 +1,6 @@
 import {Queue} from './queue';
 
 export class PersistentQueue<T> implements Queue<T> {
-    private cache: T[];
-
     private readonly storage: Storage;
 
     private readonly key: string;
@@ -17,7 +15,7 @@ export class PersistentQueue<T> implements Queue<T> {
     }
 
     public getCapacity(): number {
-        return Infinity;
+        return Number.MAX_SAFE_INTEGER;
     }
 
     public isEmpty(): boolean {
@@ -29,9 +27,7 @@ export class PersistentQueue<T> implements Queue<T> {
     }
 
     public push(value: T): void {
-        this.queue.push(value);
-
-        this.flush();
+        this.save([...this.queue, value]);
     }
 
     public peek(): T | null {
@@ -45,30 +41,19 @@ export class PersistentQueue<T> implements Queue<T> {
     }
 
     public shift(): T {
-        const value = this.queue.shift();
+        const queue = [...this.queue];
+        const value = queue.shift();
 
         if (value === undefined) {
             throw new Error('The queue is empty.');
         }
 
-        this.flush();
+        this.save(queue);
 
         return value;
     }
 
-    private get queue(): T[] {
-        if (this.cache === undefined) {
-            this.cache = this.load();
-        }
-
-        return this.cache;
-    }
-
-    private flush(): void {
-        this.storage.setItem(this.key, JSON.stringify(this.cache ?? []));
-    }
-
-    private load(): T[] {
+    private get queue(): readonly T[] {
         const data = this.storage.getItem(this.key);
 
         if (data === null) {
@@ -77,8 +62,12 @@ export class PersistentQueue<T> implements Queue<T> {
 
         try {
             return JSON.parse(data);
-        } catch (error) {
+        } catch {
             return [];
         }
     }
+
+    private save(data: T[]): void {
+        this.storage.setItem(this.key, JSON.stringify(data));
+    }
 }

package/src/schema/eventSchemas.ts

@@ -114,22 +114,6 @@ export const eventOccurred = new ObjectType({
             minLength: 1,
             maxLength: 50,
         }),
-        testId: new StringType({
-            minLength: 1,
-            maxLength: 50,
-        }),
-        groupId: new StringType({
-            minLength: 1,
-            maxLength: 50,
-        }),
-        personalizationId: new StringType({
-            minLength: 1,
-            maxLength: 50,
-        }),
-        audience: new StringType({
-            minLength: 1,
-            maxLength: 50,
-        }),
         details: new ObjectType({
             additionalProperties: new UnionType(
                 new NullType(),

package/src/schema/sdkFacadeSchemas.ts

@@ -1,4 +1,12 @@
-import {ObjectType, StringType, BooleanType, UnionType, NullType, FunctionType} from '../validation';
+import {
+    ObjectType,
+    StringType,
+    BooleanType,
+    UnionType,
+    NullType,
+    FunctionType,
+    NumberType,
+} from '../validation';
 import {tokenScopeSchema} from './contextSchemas';
 import {cookieOptionsSchema, eventMetadataSchema} from './sdkSchemas';
 import {loggerSchema} from './loggerSchema';
@@ -45,7 +53,11 @@ export const sdkFacadeConfigurationSchema = new ObjectType({
                 previewToken: cookieOptionsSchema,
             },
         }),
-        preferredLocale: new StringType({
+        defaultFetchTimeout: new NumberType({
+            integer: true,
+            minimum: 1,
+        }),
+        defaultPreferredLocale: new StringType({
             pattern: /^[a-z]{2,3}([-_][a-z]{2,3})?$/i,
         }),
     },

package/src/schema/sdkSchemas.ts

@@ -71,5 +71,12 @@ export const sdkConfigurationSchema = new ObjectType({
         urlSanitizer: new FunctionType(),
         eventMetadata: eventMetadataSchema,
         eventProcessor: new FunctionType(),
+        defaultFetchTimeout: new NumberType({
+            integer: true,
+            minimum: 1,
+        }),
+        defaultPreferredLocale: new StringType({
+            pattern: /^[a-z]{2,3}([-_][a-z]{2,3})?$/i,
+        }),
     },
 });