@extrahorizon/javascript-sdk 8.2.0-test

package/build/types/http/types.d.ts

@@ -0,0 +1,331 @@
+import { AxiosError, AxiosInstance, AxiosInterceptorManager, AxiosPromise, AxiosRequestConfig, AxiosResponse } from 'axios';
+export declare type HttpResponse<T = any> = AxiosResponse<T> & {
+    config: HttpRequestConfig;
+};
+export declare type HttpRequestConfig = AxiosRequestConfig & {
+    interceptors?: {
+        skipCamelizeResponseData?: boolean;
+        skipTransformResponseData?: boolean;
+        skipTransformKeysResponseData?: boolean;
+    };
+    retry?: {
+        tries: number;
+        retryTimeInMs: number;
+        current: number;
+        retryCondition: (error: HttpResponseError) => boolean;
+    };
+    normalizeCustomData?: boolean;
+    customKeys?: string[];
+    /**
+     * Overrides values provided in {@Link customKeys}
+     */
+    customRequestKeys?: string[];
+    /**
+     * Overrides values provided in {@Link customKeys}
+     */
+    customResponseKeys?: string[];
+};
+export declare type HttpResponseError = AxiosError & {
+    config: HttpRequestConfig;
+};
+export interface HttpInstance {
+    (config: AxiosRequestConfig): AxiosPromise;
+    (url: string, config?: AxiosRequestConfig): AxiosPromise;
+    normalizeCustomData?: boolean;
+    defaults: AxiosInstance['defaults'];
+    interceptors: {
+        request: AxiosInterceptorManager<AxiosRequestConfig>;
+        response: AxiosInterceptorManager<AxiosResponse>;
+    };
+    getUri(config?: HttpRequestConfig): string;
+    request<T = any, R = AxiosResponse<T>>(config: HttpRequestConfig): Promise<R>;
+    get<T = any, R = AxiosResponse<T>>(url: string, config?: HttpRequestConfig): Promise<R>;
+    delete<T = any, R = AxiosResponse<T>>(url: string, config?: HttpRequestConfig): Promise<R>;
+    head<T = any, R = AxiosResponse<T>>(url: string, config?: HttpRequestConfig): Promise<R>;
+    options<T = any, R = AxiosResponse<T>>(url: string, config?: HttpRequestConfig): Promise<R>;
+    post<T = any, R = AxiosResponse<T>>(url: string, data?: any, config?: HttpRequestConfig): Promise<R>;
+    put<T = any, R = AxiosResponse<T>>(url: string, data?: any, config?: HttpRequestConfig): Promise<R>;
+    patch<T = any, R = AxiosResponse<T>>(url: string, data?: any, config?: HttpRequestConfig): Promise<R>;
+}
+export interface TokenDataOauth2 {
+    tokenType: string;
+    accessToken: string;
+    expiresIn: number;
+    refreshToken: string;
+    applicationId: string;
+    userId: string;
+    creationTimestamp: Date;
+}
+export interface TokenDataOauth1 {
+    id?: string;
+    key: string;
+    secret: string;
+    token?: string;
+    tokenSecret?: string;
+    applicationId?: string;
+    userId?: string;
+    updateTimestamp?: Date;
+    creationTimestamp?: Date;
+}
+export interface OidcAuthenticationUrlRequest {
+    /** The state parameter to be included in the authentication URL */
+    state?: string;
+}
+export interface OidcAuthenticationUrl {
+    /** The authentication URL the user should be directed to */
+    authenticationUrl: string;
+}
+export interface OidcAuthenticateRequest {
+    /** The authorizationCode received from the provider via the redirect after the user authenticated with the provider */
+    authorizationCode: string;
+}
+export interface OAuth2HttpClient extends HttpInstance {
+    extraAuthMethods: {
+        /**
+         * Use OAuth2 Authorization Code Grant flow with callback
+         * @example
+         * await exh.auth.authenticate({
+         *  code: '',
+         * });
+         * @throws {InvalidRequestError}
+         * @throws {InvalidGrantError}
+         * @throws {UnsupportedGrantTypeError}
+         * @throws {MfaRequiredError}
+         * @throws {InvalidClientError}
+         */
+        authenticate(oauth: {
+            code: string;
+        }): Promise<TokenDataOauth2>;
+        /**
+         * Use OAuth2 Password Grant flow
+         * @example
+         * await exh.auth.authenticate({
+         *  password: '',
+         *  username: '',
+         * });
+         * @throws {InvalidRequestError}
+         * @throws {InvalidGrantError}
+         * @throws {UnsupportedGrantTypeError}
+         * @throws {MfaRequiredError}
+         * @throws {InvalidClientError}
+         */
+        authenticate(oauth: {
+            username: string;
+            password: string;
+        }): Promise<TokenDataOauth2>;
+        /**
+         * Use OAuth2 Refresh Token Grant flow
+         * @example
+         * await exh.auth.authenticate({
+         *  refreshToken: '',
+         * });
+         * @throws {InvalidRequestError}
+         * @throws {InvalidGrantError}
+         * @throws {UnsupportedGrantTypeError}
+         * @throws {MfaRequiredError}
+         * @throws {InvalidClientError}
+         */
+        authenticate(oauth: {
+            refreshToken: string;
+        }): Promise<TokenDataOauth2>;
+        /**
+         *  Confirm MFA method with token, methodId and code
+         *  @example
+         *  try {
+         *    await exh.auth.authenticate({
+         *      username: '',
+         *      password: '',
+         *    });
+         *  } catch (error) {
+         *    if (error instanceof MfaRequiredError) {
+         *      const { mfa } = error;
+         *
+         *      // Your logic to request which method the user want to use in case of multiple methods
+         *      const methodId = mfa.methods[0].id;
+         *
+         *      await exh.auth.confirmMfa({
+         *        token: mfa.token,
+         *        methodId,
+         *        code: '', // code from ie. Google Authenticator
+         *      });
+         *    }
+         *  }
+         */
+        confirmMfa(data: MfaConfig): Promise<TokenDataOauth2>;
+        /**
+         * ## Generate an OIDC authentication URL
+         * You can use this endpoint to generate a fully configured OIDC authentication URL.
+         * You can use the authentication URL to redirect the user to the specified OIDC provider to initiate the authentication process.
+         *
+         * Once the user is authenticated, the OIDC provider will redirect the user to the configured `redirectUri` with an authorization code.
+         * The authorization code can then be used to login (see `auth.authenticateWithOidc()`).
+         *
+         * A state parameter can be added to the URL.
+         * Supply the `state` property to this function and the state parameter will be included in the URL.
+         * If supplied, the provider will add the same state parameter and value again to the URL when redirecting the user is back to your application (the configured `redirectUri`).
+         * This can (and should) be used to protect against Cross-Site Request Forgery (CSRF) attacks.
+         *
+         * A `nonce` parameter is automatically added and will be validated during the authorization code exchange by ExH.
+         *
+         * #### Example URL
+         * An example of a fully configured authentication URL: (new lines added for readability)
+         * ```txt
+         * https://accounts.google.com/o/oauth2/auth
+         *   ?response_type=code
+         *   &client_id=123456789-abcdefghijklw.apps.googleusercontent.com
+         *   &scope=openid%20email%20profile
+         *   &redirect_uri=https%3A%2F%2Fapi.dev.yourapp.com%2Fcallback
+         *   &nonce=608c038a830f40d7fe028a3f05c85b84f9040d37
+         * ```
+         *
+         * #### Function details
+         * @param providerName The name of the OIDC provider to generate an authentication URL for
+         * @param data {@link OidcAuthenticationUrlRequest}
+         *
+         * @returns An object containing the authentication URL
+         *
+         * @throws {@link IllegalStateError} When targeting a disabled provider. A provider must be enabled to allow users to use this endpoint.
+         */
+        generateOidcAuthenticationUrl(providerName: string, data?: OidcAuthenticationUrlRequest): Promise<OidcAuthenticationUrl>;
+        /**
+         * ## Authenticate a user with OIDC
+         * You can use this method to authenticate a user after obtaining a authorization code from an OIDC provider.
+         * The authorization code is obtained when an OIDC provider redirects a user back to your application after a successful authentication.
+         * The authorization code may be URL encoded, so make sure the authorization code is in the correct format before providing it here.
+         * See `auth.generateOidcAuthenticationUrl()` to initiate the authentication process.
+         *
+         * Like the `auth.authenticate()` method, the SDK uses the returned access token and refresh token to authenticate successive requests.
+         *
+         * All (successful and failed) login attempts are logged. See `auth.oidc.getLoginAttempts()`.
+         *
+         * #### Function details
+         * @param providerName The name of the OIDC provider to login with
+         * @param data {@link OidcAuthenticateRequest}
+         *
+         * @returns The OAuth2 tokens generated for the user.
+         *
+         * @throws {@link IllegalStateError} When targeting a disabled provider. A provider must be enabled to allow users to use this endpoint.
+         * @throws {@link OAuth2MissingClientCredentialsError} When no client credentials are specified or, for a confidential application, the `clientSecret` is missing.
+         * @throws {@link OidcProviderResponseError} When the provider is incorrectly configured or the provider gave us an unexpected response. Please check the provider configuration.
+         * @throws {@link OidcInvalidAuthorizationCodeError} When the provided `authorizationCode` is not accepted or recognized by the provider.
+         * @throws {@link EmailUsedError} When a new ExH account is being created for the user trying to login with an email address which is already in use by an existing ExH account.
+         * @throws {@link OAuth2ClientIdError} When the supplied `clientId` could not be found.
+         * @throws {@link OAuth2ClientSecretError} When the supplied `clientSecret` is incorrect.
+         * @throws {@link OidcIdTokenError} When we understood the response of the provider but the id token returned is invalid.
+         */
+        authenticateWithOidc(providerName: string, data: OidcAuthenticateRequest): Promise<TokenDataOauth2>;
+        /**
+         *  Logout
+         *  @returns {boolean} Success
+         *  @example
+         *  try {
+         *    await exh.auth.authenticate({
+         *      username: '',
+         *      password: '',
+         *    });
+         *    exh.auth.logout();
+         *  } catch (error) {
+         *    console.log(error)
+         *  }
+         */
+        logout(): boolean;
+    };
+    userId: Promise<string | undefined>;
+}
+export interface OAuth1HttpClient extends HttpInstance {
+    extraAuthMethods: {
+        /**
+         * Use OAuth1 Token authentication
+         * @example
+         * await exh.auth.authenticate({
+         *  token: '',
+         *  tokenSecret: '',
+         * });
+         * @throws {ApplicationNotAuthenticatedError}
+         * @throws {AuthenticationError}
+         * @throws {LoginTimeoutError}
+         * @throws {LoginFreezeError}
+         * @throws {TooManyFailedAttemptsError}
+         * @throws {MfaRequiredError}
+         */
+        authenticate(oauth: {
+            token: string;
+            tokenSecret: string;
+            skipTokenCheck?: boolean;
+        }): Promise<TokenDataOauth1>;
+        /**
+         * Use OAuth1 Password authentication
+         * @example
+         * await exh.auth.authenticate({
+         *  email: '',
+         *  password: '',
+         * });
+         * @throws {ApplicationNotAuthenticatedError}
+         * @throws {AuthenticationError}
+         * @throws {LoginTimeoutError}
+         * @throws {LoginFreezeError}
+         * @throws {TooManyFailedAttemptsError}
+         * @throws {MfaRequiredError}
+         */
+        authenticate(oauth: {
+            email: string;
+            password: string;
+        }): Promise<TokenDataOauth1>;
+        /**
+         *  Confirm MFA method with token, methodId and code
+         *  @example
+         *  try {
+         *    await exh.auth.authenticate({
+         *      email: '',
+         *      password: '',
+         *    });
+         *  } catch (error) {
+         *    if (error instanceof MfaRequiredError) {
+         *      const { mfa } = error;
+         *
+         *      // Your logic to request which method the user want to use in case of multiple methods
+         *      const methodId = mfa.methods[0].id;
+         *
+         *      await exh.auth.confirmMfa({
+         *        token: mfa.token,
+         *        methodId,
+         *        code: '', // code from ie. Google Authenticator
+         *      });
+         *    }
+         *  }
+         */
+        confirmMfa(data: MfaConfig): Promise<TokenDataOauth1>;
+        /**
+         *  Logout
+         *  @returns {boolean} Success
+         *  @example
+         *  try {
+         *    await exh.auth.authenticate({
+         *      email: '',
+         *      password: '',
+         *    });
+         *    exh.auth.logout();
+         *  } catch (error) {
+         *    console.log(error)
+         *  }
+         */
+        logout(): boolean;
+    };
+    userId: Promise<string | undefined>;
+}
+export interface ProxyInstance extends HttpInstance {
+    extraAuthMethods: {
+        /**
+         *  Logout
+         *  @returns {boolean} Success
+         */
+        logout(): Promise<boolean>;
+    };
+    userId: Promise<string | undefined>;
+}
+export declare type AuthHttpClient = OAuth1HttpClient | OAuth2HttpClient | ProxyInstance;
+export interface MfaConfig {
+    token: string;
+    methodId: string;
+    code: string;
+}

package/build/types/http/utils.d.ts

@@ -0,0 +1,21 @@
+export declare function mapObjIndexed(fn: any, object: any): Record<string, unknown>;
+export declare const recursiveMap: (fn: any, obj: any, ignoreKeys?: any[], skipData?: boolean) => any;
+/**
+ * Recursively renames keys in an object using a provided function.
+ * @param fn A function that takes a string (key) and returns a string (new key).
+ * @param obj The object to rename they keys in.
+ * @param ignoreKeys An array of keys to ignore during the renaming process.
+ * @returns An object with keys renamed according to the provided function.
+ */
+export declare function recursiveRenameKeys(fn: {
+    (arg: string): string;
+}, obj: any, ignoreKeys?: string[]): any;
+export declare function camelize(string: string): string;
+export declare function decamelize(string: string): string;
+export declare function camelizeKeys(object: Record<string, unknown>, ignoreKeys?: string[]): Record<string, unknown>;
+export declare function decamelizeKeys(object: Record<string, unknown>, ignoreKeys?: string[]): Record<string, unknown>;
+/**
+ * Composes a `User-Agent` like header value which looks something like
+ * `'Node/14.4.0 SDK/3.0.0'`.
+ */
+export declare function composeUserAgent(packageVersion: string): string;

package/build/types/index.d.ts

@@ -0,0 +1,9 @@
+export { rqlBuilder, rqlParser, RQLString } from './rql';
+export * from './errors';
+export * from './types';
+export { recursiveMap } from './http/utils';
+export { parseGlobalPermissions } from './utils';
+export { findAllGeneric, findAllIterator } from './services/helpers';
+export { getMockSdkOAuth1, getMockSdkOAuth2, getMockSdkProxy, getMockSdkOAuth2 as getMockSdk, } from './mock';
+export { createClient, createOAuth1Client, createOAuth2Client, createProxyClient, Client, OAuth1Client, OAuth2Client, ProxyClient, } from './client';
+export { parseStoredCredentials, ExHCredentials, } from './parseStoredCredentials';

package/build/types/mock.d.ts

@@ -0,0 +1,43 @@
+import type { MockClientOAuth1, MockClientOAuth2, MockClientProxy } from './mockType';
+/**
+ * Returns a mocked version of the Proxy SDK. Requires a mocking function like `jest.fn`
+ * @param fn  mocking function
+ * @returns {MockClientProxy} mockSdk
+ * @example
+ * import { getMockSdkProxy } from "@extrahorizon/javascript-sdk";
+ * describe("mock SDK", () => {
+ *   const exh = getMockSdkProxy(jest.fn);
+ *   it("should be valid mock", async () => {
+ *     expect(exh.data).toBeDefined();
+ *   });
+ * });
+ */
+export declare const getMockSdkProxy: <MockFn>(fn: () => MockFn) => MockClientProxy<MockFn>;
+/**
+ * Returns a mocked version of the OAuth2 SDK. Requires a mocking function like `jest.fn`
+ * @param fn  mocking function
+ * @returns {MockClientOAuth2} mockSdk
+ * @example
+ * import { getMockSdkOAuth2 } from "@extrahorizon/javascript-sdk";
+ * describe("mock SDK", () => {
+ *   const exh = getMockSdkOAuth2(jest.fn);
+ *   it("should be valid mock", async () => {
+ *     expect(exh.data).toBeDefined();
+ *   });
+ * });
+ */
+export declare const getMockSdkOAuth2: <MockFn>(fn: () => MockFn) => MockClientOAuth2<MockFn>;
+/**
+ * Returns a mocked version of the OAuth1 SDK. Requires a mocking function like `jest.fn`
+ * @param fn  mocking function
+ * @returns {MockClientOAuth1} mockSdk
+ * @example
+ * import { getMockSdkOAuth1 } from "@extrahorizon/javascript-sdk";
+ * describe("mock SDK", () => {
+ *   const exh = getMockSdkOAuth1(jest.fn);
+ *   it("should be valid mock", async () => {
+ *     expect(exh.data).toBeDefined();
+ *   });
+ * });
+ */
+export declare const getMockSdkOAuth1: <MockFn>(fn: () => MockFn) => MockClientOAuth1<MockFn>;