@kontent-ai/core-sdk 10.0.0-0

package/lib/helpers/enum.helper.ts

@@ -0,0 +1,63 @@
+export class EnumHelper {
+
+    getAllNames(T: any): any[] {
+        const enumNames: any[] = [];
+
+        for (const key in T) {
+            if (T.hasOwnProperty(key)) {
+                enumNames.push(key);
+            }
+        }
+
+        return enumNames;
+    }
+
+    getAllValues(T: any): any[] {
+        const allEnumValues: any[] = Object.keys(T).map(key => T[key]);
+
+        return allEnumValues;
+    }
+
+    getEnumFromValue<T>(T: any, value: string | number): T | undefined {
+        try {
+            if (!value) {
+                return undefined;
+            }
+
+            // we can map back from index number directly
+            if (this.isNumeric(value)) {
+                return <T>T[value];
+            }
+
+            // for strings, we need to compare each value separately
+            const allEnumValues = this.getAllValues(T);
+
+            const result = allEnumValues.find(m => m.toLowerCase() === value.toString().toLowerCase());
+
+            if (!result) {
+                return undefined;
+            }
+
+            return result as T;
+        } catch (err) {
+            return undefined;
+        }
+    }
+
+    getEnumFromName<T>(T: any, name: string): T | undefined {
+        const allNames = this.getAllNames(T);
+
+        for (const enumName of allNames) {
+            if (enumName.toLowerCase() === name.toLowerCase()) {
+                return T[enumName];
+            }
+        }
+        return undefined;
+    }
+
+    private isNumeric(value: any): boolean {
+        return !isNaN(parseFloat(value)) && isFinite(value);
+      }
+}
+
+export const enumHelper = new EnumHelper();

package/lib/helpers/header.helper.ts

@@ -0,0 +1,23 @@
+import { ISDKInfo } from '../models';
+
+import { IHeader } from '../http/http.models';
+
+export class HeaderHelper {
+
+    /**
+    * Header name for SDK usage
+    */
+    private readonly sdkVersionHeader: string = 'X-KC-SDKID';
+
+    /**
+    * Header identifying SDK type & version for internal purposes of Kontent.ai
+    */
+    getSdkIdHeader(info: ISDKInfo): IHeader {
+        return {
+            header: this.sdkVersionHeader,
+            value: `${info.host};${info.name};${info.version}`
+        };
+    }
+}
+
+export const headerHelper = new HeaderHelper();

package/lib/helpers/headers-helper.ts

@@ -0,0 +1,15 @@
+import { AxiosResponse } from 'axios';
+import { IHeader } from '../http/http.models';
+
+export function extractHeadersFromAxiosResponse(response: AxiosResponse): IHeader[] {
+    const headers: IHeader[] = [];
+
+    for (const headerKey of Object.keys(response.headers)) {
+        headers.push({
+            header: headerKey,
+            value: response.headers[headerKey]
+        });
+    }
+
+    return headers;
+}

package/lib/helpers/index.ts

@@ -0,0 +1,5 @@
+export * from './url.helper';
+export * from './header.helper';
+export * from './enum.helper';
+export * from './retry-helper';
+export * from './headers-helper';

package/lib/helpers/retry-helper.ts

@@ -0,0 +1,204 @@
+import { AxiosError } from 'axios';
+
+import { extractHeadersFromAxiosResponse } from './headers-helper';
+import { IHeader, IRetryStrategyOptions } from '../http/http.models';
+
+export class RetryHelper {
+    public readonly requestCancelledMessagePrefix: string = 'Request cancelled';
+    public readonly retryAfterHeaderName: string = 'Retry-After';
+    public readonly defaultRetryStatusCodes: number[] = [408, 429, 500, 502, 503, 504];
+    public readonly defaultRetryStrategy = {
+        addJitter: true,
+        deltaBackoffMs: 1000, // 1 sec
+        maxAttempts: 5,
+        canRetryError: (error: any) => this.canRetryErrorDefault(error)
+    };
+
+    getRetryErrorResult(data: {
+        retryAttempt: number;
+        error: any;
+        retryStrategy: IRetryStrategyOptions;
+    }): {
+        retryInMs: number;
+        canRetry: boolean;
+        maxRetries: number;
+    } {
+        if (data.error && data.error.message) {
+            if ((<string>data.error.message).startsWith(this.requestCancelledMessagePrefix)) {
+                // request was cancelled by user, do not retry it
+                return {
+                    canRetry: false,
+                    retryInMs: 0,
+                    maxRetries: 0
+                };
+            }
+        }
+
+        const canRetryError: boolean = data.retryStrategy.canRetryError
+            ? data.retryStrategy.canRetryError(data.error)
+            : this.defaultRetryStrategy.canRetryError(data.error);
+
+        if (!canRetryError) {
+            // request cannot be retried
+            return {
+                canRetry: false,
+                retryInMs: 0,
+                maxRetries: 0
+            };
+        }
+
+        const maxRetries: number = (data.retryStrategy.maxAttempts ?? this.defaultRetryStrategy.maxAttempts);
+
+        const maxRetriesReached: boolean =
+            data.retryAttempt >= maxRetries;
+
+        if (maxRetriesReached) {
+            // request cannot be retried anymore due to maximum attempts
+            return {
+                canRetry: false,
+                retryInMs: 0,
+                maxRetries: maxRetries
+            };
+        }
+        // get wait time
+        const retryResult: number | undefined = this.tryGetRetryAfterInMsFromError(data.error);
+
+        if (retryResult) {
+            // retry after header was provided
+            return {
+                canRetry: true,
+                retryInMs: retryResult,
+                maxRetries: maxRetries
+            };
+        }
+
+        // wait time was not provided in header
+        const waitTimeMs = this.getNextWaitTimeMs(
+            data.retryStrategy.addJitter ?? this.defaultRetryStrategy.addJitter,
+            data.retryStrategy.deltaBackoffMs ?? this.defaultRetryStrategy.deltaBackoffMs,
+            data.retryAttempt
+        );
+
+        return {
+            canRetry: true,
+            retryInMs: waitTimeMs,
+            maxRetries: maxRetries
+        };
+    }
+
+    getRetryStrategyFromStrategyOptions(retryOptions?: IRetryStrategyOptions): IRetryStrategyOptions {
+        if (!retryOptions) {
+            return this.defaultRetryStrategy;
+        }
+
+        return retryOptions;
+    }
+
+    canRetryInTime(
+        startTime: Date,
+        maxCumulativeWaitTimeMs: number
+    ): {
+        canRetry: boolean;
+        differenceInMs: number;
+    } {
+        const start = startTime.getTime();
+        const now = new Date().getTime();
+
+        const differenceInMs = now - start;
+
+        return {
+            canRetry: differenceInMs < maxCumulativeWaitTimeMs,
+            differenceInMs: differenceInMs
+        };
+    }
+
+    private getNextWaitTimeMs(addJitter: boolean, deltaBackoffMs: number, retryAttempts: number): number {
+        if (!addJitter) {
+            return deltaBackoffMs * Math.pow(2, retryAttempts);
+        }
+
+        const from: number = 0.8 * deltaBackoffMs;
+        const to: number = 1.2 * deltaBackoffMs * Math.pow(2, retryAttempts);
+
+        return this.randomNumberFromInterval(from, to);
+    }
+
+    private canRetryErrorDefault(error: any): boolean {
+        const axiosError = this.tryGetAxiosError(error);
+
+        if (!axiosError) {
+            // by default non-axios errors are not retried
+            return false;
+        }
+
+        const statusCode: number = this.getStatusCodeFromError(error);
+        const canRetryStatusCode: boolean = this.canRetryStatusCode(statusCode, this.defaultRetryStatusCodes);
+
+        if (canRetryStatusCode) {
+            return true;
+        }
+
+        return false;
+    }
+
+    private tryGetRetryAfterInMsFromError(error: any): number | undefined {
+        const axiosError = this.tryGetAxiosError(error);
+
+        if (!axiosError || !axiosError.response) {
+            return undefined;
+        }
+
+        const headers: IHeader[] = extractHeadersFromAxiosResponse(axiosError.response);
+
+        const retryValueHeader = headers.find(
+            (m) => m.header.toLowerCase() === this.retryAfterHeaderName.toLowerCase()
+        );
+        if (!retryValueHeader) {
+            return undefined;
+        }
+
+        const retryInSeconds = +retryValueHeader.value;
+
+        return retryInSeconds * 1000;
+    }
+
+    private canRetryStatusCode(statusCode: number, useRetryForResponseCodes: number[]): boolean {
+        return useRetryForResponseCodes.includes(statusCode);
+    }
+
+    private getStatusCodeFromError(error: any): number {
+        const axiosError = this.tryGetAxiosError(error);
+
+        if (!axiosError || !axiosError.response) {
+            return 0;
+        }
+
+        return axiosError.response.status;
+    }
+
+    private tryGetAxiosError(error: any): AxiosError | undefined {
+        if (!error) {
+            return undefined;
+        }
+
+        if (error.isAxiosError) {
+            return error as AxiosError;
+        }
+
+        const originalError = error.originalError;
+        if (originalError && originalError.isAxiosError) {
+            return originalError as AxiosError;
+        }
+
+        return undefined;
+    }
+
+    /**
+     * min and max included
+     */
+    private randomNumberFromInterval(min: number, max: number): number {
+        return Math.floor(Math.random() * (max - min + 1) + min);
+    }
+}
+
+export const retryHelper = new RetryHelper();

package/lib/helpers/url.helper.ts

@@ -0,0 +1,26 @@
+import { IQueryParameter } from '../models';
+
+export class UrlHelper {
+
+    /**
+   * Adds query parameters to given url
+   * @param url Url to which options will be added
+   * @param options Query parameters to add
+   */
+    addOptionsToUrl(url: string, options?: IQueryParameter[]): string {
+        if (options) {
+            options.forEach(filter => {
+                if (url.indexOf('?') > -1) {
+                    url += '&';
+                } else {
+                    url += '?';
+                }
+
+                url += filter.getParam();
+            });
+        }
+        return url;
+    }
+}
+
+export const urlHelper = new UrlHelper();

package/lib/http/http.debugger.ts

@@ -0,0 +1,21 @@
+export class HttpDebugger {
+    /*
+    Called when http request is started
+    */
+    debugStartHttpRequest(): void {
+    }
+
+    /*
+    Called when http request is resolved
+    */
+    debugSuccessHttpRequest(): void {
+    }
+
+    /*
+    Called when http request is being retried
+    */
+    debugRetryHttpRequest(): void {
+    }
+}
+
+export const httpDebugger = new HttpDebugger();

package/lib/http/http.functions.ts

@@ -0,0 +1,312 @@
+import axios, { AxiosInstance, Canceler, CancelToken } from 'axios';
+import { extractHeadersFromAxiosResponse } from '../helpers/headers-helper';
+
+import { httpDebugger } from './http.debugger';
+import {
+    IHttpCancelRequestToken,
+    IHeader,
+    IHttpDeleteQueryCall,
+    IHttpGetQueryCall,
+    IHttpPatchQueryCall,
+    IHttpPostQueryCall,
+    IHttpPutQueryCall,
+    IHttpQueryOptions,
+    IResponse,
+    IRetryStrategyOptions
+} from './http.models';
+import { retryHelper } from '../helpers/retry-helper';
+
+export interface IHttpFunctionsConfig {
+    logErrorsToConsole: boolean;
+}
+
+export async function getWithRetryAsync<TRawData>(
+    instance: AxiosInstance,
+    call: IHttpGetQueryCall,
+    functionsConfig: IHttpFunctionsConfig,
+    options?: IHttpQueryOptions<CancelToken>
+): Promise<IResponse<TRawData>> {
+    const retryStrategyOptions = options?.retryStrategy ?? retryHelper.defaultRetryStrategy;
+
+    return await runWithRetryAsync<TRawData>({
+        retryAttempt: 0,
+        url: call.url,
+        retryStrategy: retryStrategyOptions,
+        functionsConfig: functionsConfig,
+        call: async (retryAttempt) => {
+            httpDebugger.debugStartHttpRequest();
+
+            const axiosResponse = await instance.get<TRawData>(call.url, {
+                headers: getHeadersJson(options?.headers ?? [], false),
+                responseType: options?.responseType,
+                cancelToken: options?.cancelToken?.token
+            });
+
+            const response: IResponse<TRawData> = {
+                data: axiosResponse.data,
+                rawResponse: axiosResponse,
+                headers: extractHeadersFromAxiosResponse(axiosResponse),
+                status: axiosResponse.status,
+                retryStrategy: {
+                    options: retryStrategyOptions,
+                    retryAttempts: retryAttempt
+                }
+            };
+
+            httpDebugger.debugSuccessHttpRequest();
+            return response;
+        }
+    });
+}
+
+export async function postWithRetryAsync<TRawData>(
+    instance: AxiosInstance,
+    call: IHttpPostQueryCall,
+    functionsConfig: IHttpFunctionsConfig,
+    options?: IHttpQueryOptions<CancelToken>
+): Promise<IResponse<TRawData>> {
+    const retryStrategyOptions = options?.retryStrategy ?? retryHelper.defaultRetryStrategy;
+
+    return await runWithRetryAsync<TRawData>({
+        retryAttempt: 0,
+        url: call.url,
+        retryStrategy: retryStrategyOptions,
+        functionsConfig: functionsConfig,
+        call: async (retryAttempt) => {
+            httpDebugger.debugStartHttpRequest();
+
+            const axiosResponse = await instance.post<TRawData>(call.url, call.body, {
+                headers: getHeadersJson(options?.headers ?? [], false),
+                responseType: options?.responseType,
+                // required for uploading large files
+                // https://github.com/axios/axios/issues/1362
+                maxContentLength: 'Infinity' as any,
+                maxBodyLength: 'Infinity' as any,
+                cancelToken: options?.cancelToken?.token
+            });
+
+            const response: IResponse<TRawData> = {
+                data: axiosResponse.data,
+                rawResponse: axiosResponse,
+                headers: extractHeadersFromAxiosResponse(axiosResponse),
+                status: axiosResponse.status,
+                retryStrategy: {
+                    options: retryStrategyOptions,
+                    retryAttempts: retryAttempt
+                }
+            };
+
+            httpDebugger.debugSuccessHttpRequest();
+            return response;
+        }
+    });
+}
+
+export async function putWithRetryAsync<TRawData>(
+    instance: AxiosInstance,
+    call: IHttpPutQueryCall,
+    functionsConfig: IHttpFunctionsConfig,
+    options?: IHttpQueryOptions<CancelToken>
+): Promise<IResponse<TRawData>> {
+    const retryStrategyOptions = options?.retryStrategy ?? retryHelper.defaultRetryStrategy;
+
+    return await runWithRetryAsync<TRawData>({
+        retryAttempt: 0,
+        url: call.url,
+        retryStrategy: retryStrategyOptions,
+        functionsConfig: functionsConfig,
+        call: async (retryAttempt) => {
+            httpDebugger.debugStartHttpRequest();
+
+            const axiosResponse = await instance.put<TRawData>(call.url, call.body, {
+                headers: getHeadersJson(options?.headers ?? [], false),
+                responseType: options?.responseType,
+                // required for uploading large files
+                // https://github.com/axios/axios/issues/1362
+                maxContentLength: 'Infinity' as any,
+                maxBodyLength: 'Infinity' as any,
+                cancelToken: options?.cancelToken?.token
+            });
+
+            const response: IResponse<TRawData> = {
+                data: axiosResponse.data,
+                rawResponse: axiosResponse,
+                headers: extractHeadersFromAxiosResponse(axiosResponse),
+                status: axiosResponse.status,
+                retryStrategy: {
+                    options: retryStrategyOptions,
+                    retryAttempts: retryAttempt
+                }
+            };
+
+            httpDebugger.debugSuccessHttpRequest();
+            return response;
+        }
+    });
+}
+
+export async function patchWithRetryAsync<TRawData>(
+    instance: AxiosInstance,
+    call: IHttpPatchQueryCall,
+    functionsConfig: IHttpFunctionsConfig,
+    options?: IHttpQueryOptions<CancelToken>
+): Promise<IResponse<TRawData>> {
+    const retryStrategyOptions = options?.retryStrategy ?? retryHelper.defaultRetryStrategy;
+
+    return await runWithRetryAsync<TRawData>({
+        retryAttempt: 0,
+        url: call.url,
+        retryStrategy: retryStrategyOptions,
+        functionsConfig: functionsConfig,
+        call: async (retryAttempt) => {
+            httpDebugger.debugStartHttpRequest();
+
+            const axiosResponse = await instance.patch<TRawData>(call.url, call.body, {
+                headers: getHeadersJson(options?.headers ?? [], false),
+                responseType: options?.responseType,
+                // required for uploading large files
+                // https://github.com/axios/axios/issues/1362
+                maxContentLength: 'Infinity' as any,
+                maxBodyLength: 'Infinity' as any,
+                cancelToken: options?.cancelToken?.token
+            });
+
+            const response: IResponse<TRawData> = {
+                data: axiosResponse.data,
+                rawResponse: axiosResponse,
+                headers: extractHeadersFromAxiosResponse(axiosResponse),
+                status: axiosResponse.status,
+                retryStrategy: {
+                    options: retryStrategyOptions,
+                    retryAttempts: retryAttempt
+                }
+            };
+
+            httpDebugger.debugSuccessHttpRequest();
+            return response;
+        }
+    });
+}
+
+export async function deleteWithRetryAsync<TRawData>(
+    instance: AxiosInstance,
+    call: IHttpDeleteQueryCall,
+    functionsConfig: IHttpFunctionsConfig,
+    options?: IHttpQueryOptions<CancelToken>
+): Promise<IResponse<TRawData>> {
+    const retryStrategyOptions = options?.retryStrategy ?? retryHelper.defaultRetryStrategy;
+
+    return await runWithRetryAsync<TRawData>({
+        retryAttempt: 0,
+        url: call.url,
+        retryStrategy: retryStrategyOptions,
+        functionsConfig: functionsConfig,
+        call: async (retryAttempt) => {
+            httpDebugger.debugStartHttpRequest();
+
+            const axiosResponse = await instance.delete<TRawData>(call.url, {
+                headers: getHeadersJson(options?.headers ?? [], false),
+                responseType: options?.responseType,
+                // required for uploading large files
+                // https://github.com/axios/axios/issues/1362
+                maxContentLength: 'Infinity' as any,
+                maxBodyLength: 'Infinity' as any,
+                cancelToken: options?.cancelToken?.token
+            });
+
+            const response: IResponse<TRawData> = {
+                data: axiosResponse.data,
+                rawResponse: axiosResponse,
+                headers: extractHeadersFromAxiosResponse(axiosResponse),
+                status: axiosResponse.status,
+                retryStrategy: {
+                    options: retryStrategyOptions,
+                    retryAttempts: retryAttempt
+                }
+            };
+
+            httpDebugger.debugSuccessHttpRequest();
+            return response;
+        }
+    });
+}
+
+export function createCancelToken(): IHttpCancelRequestToken<CancelToken> {
+    let canceler: Canceler;
+
+    const token = new axios.CancelToken((c) => {
+        // An executor function receives a cancel function as a parameter
+        canceler = c;
+    });
+
+    return {
+        cancel: (cancelMessage) =>
+            canceler(`${retryHelper.requestCancelledMessagePrefix}: ${cancelMessage ?? 'User cancel'}`),
+        token: token
+    };
+}
+
+async function runWithRetryAsync<TRawData>(data: {
+    url: string;
+    retryAttempt: number;
+    call: (retryAttempt: number) => Promise<IResponse<TRawData>>;
+    retryStrategy: IRetryStrategyOptions;
+    functionsConfig: IHttpFunctionsConfig;
+}): Promise<IResponse<TRawData>> {
+    try {
+        return await data.call(data.retryAttempt);
+    } catch (error) {
+        const retryResult = retryHelper.getRetryErrorResult({
+            error: error,
+            retryAttempt: data.retryAttempt,
+            retryStrategy: data.retryStrategy
+        });
+
+        if (retryResult.canRetry) {
+            httpDebugger.debugRetryHttpRequest();
+
+            // wait time before retrying
+            await new Promise((resolve) => setTimeout(resolve, retryResult.retryInMs));
+
+            // retry request
+            console.warn(
+                `Retry attempt '${data.retryAttempt + 1}' from a maximum of '${
+                    retryResult.maxRetries
+                }' retries. Request url: '${data.url}'`
+            );
+
+            return await runWithRetryAsync({
+                call: data.call,
+                retryStrategy: data.retryStrategy,
+                retryAttempt: data.retryAttempt + 1,
+                url: data.url,
+                functionsConfig: data.functionsConfig
+            });
+        }
+
+        if (data.functionsConfig.logErrorsToConsole) {
+            console.error(`Executing '${data.url}' failed. Request was retried '${data.retryAttempt}' times. `, error);
+        }
+
+        throw error;
+    }
+}
+
+function getHeadersJson(headers: IHeader[], addContentTypeHeader: boolean): { [header: string]: string } {
+    const headerJson: { [header: string]: string } = {};
+
+    headers.forEach((header) => {
+        headerJson[header.header] = header.value;
+    });
+
+    if (addContentTypeHeader) {
+        // add default content type header if not present
+        const contentTypeHeader = headers.find((m) => m.header.toLowerCase() === 'Content-Type'.toLowerCase());
+
+        if (!contentTypeHeader) {
+            headerJson['Content-Type'] = 'application/json';
+        }
+    }
+
+    return headerJson;
+}