@useparagon/connect 1.0.0

package/src/ConnectSDK.tsx

@@ -0,0 +1,1065 @@
+import jwtDecode from 'jwt-decode';
+
+import { VisibleConnectAction } from './types/action';
+import ActionCatalogConfigs from './helpers/actionCatalog';
+import { IPersona, PersonaMeta } from './entities/persona.interface';
+import {
+  CredentialStatus,
+  IConnectCredential,
+} from './entities/connectCredential.interface';
+import { ICredential } from './entities/credential.interface';
+import {
+  IConnectIntegrationWithCredentialInfo,
+  IIntegrationMetadata,
+  getIntegrationTypeName,
+  isCustomIntegrationTypeName,
+} from './entities/integration.interface'
+import { IConnectSDKProject } from './entities/project.interface';
+import { Action, overrideActionAlias } from './types/action';
+import {
+  AuthenticatedConnectUser,
+  IConnectUser,
+  INFER_CONTENT_TYPE_FROM_CONNECT_OPTIONS,
+  ModalConfig,
+} from './types/connect';
+import { ConnectAddOn } from './types/stripe';
+import { getAssetUrl } from './utils/connect';
+import { hash } from './utils/crypto';
+import { isValidUrl, sanitizeUrl } from './utils/http';
+import { CacheThrottle } from './utils/throttle';
+
+import { Props as ConnectModalProps } from './types/connectModal';
+import { IConnectUserContext } from './helpers/ConnectUserContext';
+import { shouldShowPreAuthInputs, startOAuthFlow } from './helpers/oauth';
+import SDKEventEmitter from './SDKEventEmitter';
+import { ConnectSdkEnvironments } from './server.types';
+import {
+  AuthenticateOptions,
+  ConnectParams,
+  ConnectUser,
+  DocumentLoadingState,
+  EventInfo,
+  FunctionPropertyNames,
+  IConnectSDK,
+  InstallOptions,
+  IntegrationInstallEvent,
+  SDKFunctionErrorMessage,
+  SDKFunctionInvocationMessage,
+  SDKFunctionResponseMessage,
+  SDKReceivedMessage,
+  SDK_EVENT,
+  TriggerWorkflowRequest,
+  UIUpdateMessage,
+  UnwrapPromise,
+  UserProvidedIntegrationConfig,
+} from './types/sdk';
+
+const PARAGON_ROOT_IFRAME_ID = 'paragon-connect-frame';
+const PARAGON_ROOT_IFRAME_CONTAINER_ID = `${PARAGON_ROOT_IFRAME_ID}-container`;
+const PARAGON_STATE_STORAGE_KEY = 'paragon-connect-user-state';
+export const PARAGON_OVERFLOW_EMPTY_VALUE = 'PARAGON_OVERFLOW_EMPTY_VALUE';
+
+export default class ConnectSDK extends SDKEventEmitter implements IConnectSDK {
+  root: HTMLIFrameElement | undefined;
+  private rootLoaded: boolean = false;
+  private projectId: string | undefined;
+  private modalState: ConnectModalProps = {
+    integration: null,
+    onClose: this.onClose.bind(this),
+    overlayStyle: { overflow: 'auto' },
+    onOpen: this.onOpen.bind(this),
+    apiInstallationOptions: {
+      isApiInstallation: false,
+      showPortalAfterInstall: false,
+    },
+  };
+  private userState: ConnectUser = {
+    authenticated: false,
+  };
+  private loadedConfigs: { [type: string]: ModalConfig } = {};
+  private loadedIntegrations: { [type: string]: IConnectIntegrationWithCredentialInfo } = {};
+  private endUserIntegrationConfig: { [type: string]: UserProvidedIntegrationConfig } = {};
+  private environments: ConnectSdkEnvironments;
+  private project: IConnectSDKProject;
+
+  /**
+   * map b/w integration key name to integration metadata
+   */
+  private metadata: Record<string, IIntegrationMetadata> = {};
+
+  /**
+   * cache service
+   */
+  private cachedApiResponse: CacheThrottle = new CacheThrottle({ ttl: 1000 * 5 });
+
+  /**
+   * in order to not call multiple same GET request at same time
+   * we are storing {key -> promise} map
+   */
+  private keyToRequestPromiseMap: Record<string, Promise<unknown>> = {};
+
+  /**
+   * this will store the original overflow style of body
+   * we are using PARAGON_OVERFLOW_EMPTY_VALUE as default
+   * so that we will be able to know whether style is added in body or not
+   */
+  private originalBodyOverflow: string | null = PARAGON_OVERFLOW_EMPTY_VALUE;
+
+  constructor(environments?: ConnectSdkEnvironments) {
+    super();
+
+    const assetURL: string = getAssetUrl({
+      CDN_PUBLIC_URL: process.env.CDN_PUBLIC_URL || '',
+      DASHBOARD_PUBLIC_URL: process.env.DASHBOARD_PUBLIC_URL || '',
+      NODE_ENV: process.env.NODE_ENV || '',
+      PLATFORM_ENV: process.env.PLATFORM_ENV || '',
+      VERSION: process.env.VERSION || '',
+    });
+    this.environments = {
+      CDN_PUBLIC_URL: assetURL,
+      CONNECT_PUBLIC_URL: process.env.CONNECT_PUBLIC_URL as string,
+      DASHBOARD_PUBLIC_URL: process.env.DASHBOARD_PUBLIC_URL as string,
+      NODE_ENV: process.env.NODE_ENV as string,
+      PASSPORT_PUBLIC_URL: process.env.PASSPORT_PUBLIC_URL as string,
+      PLATFORM_ENV: process.env.PLATFORM_ENV as string,
+      VERSION: process.env.VERSION as string,
+      ZEUS_PUBLIC_URL: process.env.ZEUS_PUBLIC_URL as string,
+      ...environments,
+    };
+
+    if (!this.environments.CONNECT_PUBLIC_URL) {
+      throw new Error('Paragon SDK error! No `CONNECT_PUBLIC_URL` configured.');
+    } else if (!this.environments.DASHBOARD_PUBLIC_URL) {
+      throw new Error('Paragon SDK error! No `DASHBOARD_PUBLIC_URL` configured.');
+    } else if (!this.environments.PASSPORT_PUBLIC_URL) {
+      throw new Error('Paragon SDK error! No `PASSPORT_PUBLIC_URL` configured.');
+    } else if (!this.environments.ZEUS_PUBLIC_URL) {
+      throw new Error('Paragon SDK error! No `ZEUS_PUBLIC_URL` configured.');
+    }
+
+    this.loadState();
+
+    window.addEventListener('message', this.eventMessageHandler.bind(this));
+
+    if (window.document.readyState === DocumentLoadingState.LOADING) {
+      // still loading, wait for the event
+      window.document.addEventListener('DOMContentLoaded', () => {
+        this.createReactRoot();
+      });
+    } else {
+      // DOM is ready!
+      this.createReactRoot();
+    }
+  }
+
+  /**
+   * post message handler
+   * @param event
+   */
+  private async eventMessageHandler(event: MessageEvent): Promise<void> {
+    switch (event.data.type) {
+      case 'oauth_success_callback':
+        await this._oauthCallback(event.data.credential);
+        break;
+      case 'oauth_error_callback':
+        await this._oauthErrorCallback(event.data.error);
+        break;
+      default:
+        await this.functionInvocationHandler(event);
+    }
+  }
+
+  private async functionInvocationHandler<T extends FunctionPropertyNames<ConnectSDK>>(
+    event: MessageEvent,
+  ): Promise<void> {
+    if ((event.data as SDKReceivedMessage).messageType !== 'SDK_FUNCTION_INVOCATION') {
+      return;
+    }
+    const { type, id, parameters } = event.data as SDKFunctionInvocationMessage<T>;
+    let reply: SDKFunctionResponseMessage<T> | SDKFunctionErrorMessage | undefined;
+
+    try {
+      // @ts-ignore The spread isn't recognized here as valid args
+      const result = (await this[type](...parameters)) as UnwrapPromise<ReturnType<ConnectSDK[T]>>;
+      reply = { messageType: 'SDK_FUNCTION_RESPONSE', id, type, result };
+    } catch (err) {
+      reply = { messageType: 'SDK_FUNCTION_ERROR', error: true, message: err.message, id };
+    }
+
+    (event.source as Window).postMessage(reply, this.environments.CONNECT_PUBLIC_URL);
+  }
+
+  private createReactRoot(): void {
+    this.root = document.createElement('iframe');
+    this.root.onload = () => {
+      this.rootLoaded = true;
+      // when root is loaded then render component
+      this.render();
+    };
+
+    const isAtRoot: boolean = document.querySelector(`#${PARAGON_ROOT_IFRAME_CONTAINER_ID}`)
+      ? true
+      : false;
+    this.root.id = PARAGON_ROOT_IFRAME_ID;
+    this.root.src = `${this.environments.CONNECT_PUBLIC_URL}/ui${
+      this.projectId ? `?projectId=${this.projectId}` : ''
+    }`;
+    this.root.style.position = isAtRoot ? 'absolute' : 'fixed';
+    this.root.style.top = '0';
+    this.root.style.left = '0';
+    this.root.style.width = isAtRoot ? '100%' : '100vw';
+    this.root.style.height = isAtRoot ? '100%' : '100vh';
+    this.root.style.zIndex = '2147483647';
+    this.root.style.display = 'none';
+
+    (document.querySelector(`#${PARAGON_ROOT_IFRAME_CONTAINER_ID}`) || document.body)?.appendChild(
+      this.root,
+    );
+  }
+
+  private validateAction(action: Action, validateIsEnabled: boolean = false): boolean {
+    if (!Object.values(Action).includes(action) && !isCustomIntegrationTypeName(action)) {
+      throw new Error(
+        `"${action}" is not a valid integration type. The integrations you have configured for this Paragon project are:
+
+${Object.keys(this.loadedConfigs)
+  .map((validAction: string) => `- "${validAction}"`)
+  .join('\n')}
+`,
+      );
+    }
+
+    if (!this.loadedConfigs[action]) {
+      throw new Error(
+        `paragon.connect() was called with "${action}", but you do not have this integration set up in your Paragon project yet.
+
+${Object.keys(this.loadedConfigs)
+  .map((validAction: string) => `- "${validAction}"`)
+  .join('\n')}`,
+      );
+    }
+
+    if (!this.loadedIntegrations[action]?.isActive) {
+      throw new Error(
+        `paragon.connect() was called with "${action}", but this integration is not active in your Paragon project yet.`,
+      );
+    }
+
+    if (validateIsEnabled && this.userState.authenticated) {
+      return Boolean(this.userState.integrations[action]?.enabled);
+    }
+
+    return true;
+  }
+
+  private async bootstrapSDKState(userMeta?: PersonaMeta): Promise<void> {
+    if (!this.projectId || !this.userState.authenticated) {
+      return;
+    }
+
+    this.project = (await this.sendConnectRequest<IConnectSDKProject>(
+      `/sdk/projects/${this.projectId}`,
+      {
+        headers: {
+          'X-Paragon-Cache-Metadata': '1',
+          ...(userMeta
+            ? {
+                'X-Paragon-User-Metadata': JSON.stringify(userMeta),
+              }
+            : {}),
+        },
+      },
+      false,
+    )) as IConnectSDKProject;
+
+    await this.updateLocalState();
+  }
+
+  setModalState(statePartial: Partial<ConnectModalProps>): void {
+    this.modalState = {
+      config: undefined,
+      ...this.modalState,
+      ...statePartial,
+    };
+    this.render();
+  }
+
+  /**
+   * Loads previous SDK state saved in localStorage.
+   *
+   * **Warning:** This favors stored to current state. This should typically be called in
+   * unauthenticated contexts, as a fallback.
+   */
+  private loadState(): void {
+    if (typeof window !== 'undefined') {
+      try {
+        const localState: {
+          userState: Record<string, unknown> | undefined;
+          projectId: string | undefined;
+        } = window.localStorage.getItem(PARAGON_STATE_STORAGE_KEY)
+          ? JSON.parse(window.localStorage.getItem(PARAGON_STATE_STORAGE_KEY) as string)
+          : {};
+
+        if (localState.projectId) {
+          this.projectId = localState.projectId;
+        }
+        if (localState.userState) {
+          const { userState } = localState;
+          if ('authenticated' in userState && userState.authenticated && 'token' in userState) {
+            this.updateAuthenticatedUser(userState);
+            // Refresh user state automatically, if available
+            this.bootstrapSDKState().catch(() => {
+              // PARA-3267
+              this.clearState();
+            });
+          } else {
+            throw new Error(
+              'Malformatted or unauthenticated user was persisted into localStorage. Refusing to load.',
+            );
+          }
+        }
+      } catch {
+        this.clearState();
+      }
+    }
+  }
+
+  /**
+   * Saves the current SDK state into localStorage, if available.
+   */
+  private saveState(): void {
+    if (typeof window !== 'undefined' && this.userState.authenticated) {
+      window.localStorage.setItem(
+        PARAGON_STATE_STORAGE_KEY,
+        JSON.stringify({ projectId: this.projectId, userState: this.userState }),
+      );
+    }
+  }
+
+  /**
+   * Clears the current SDK state from localStorage, if available.
+   */
+  private clearState(): void {
+    if (typeof window !== 'undefined') {
+      window.localStorage.removeItem(PARAGON_STATE_STORAGE_KEY);
+    }
+  }
+
+  private render(): void {
+    if (this.root && this.rootLoaded) {
+      const { onClose, onOpen, ...modalState } = this.modalState;
+      const update: UIUpdateMessage = {
+        messageType: 'UI_UPDATE',
+        nextContext: {
+          user: this.userState,
+          projectId: this.projectId,
+          environments: this.environments,
+          project: this.project,
+          endUserIntegrationConfig: this.modalState.integration
+            ? this.endUserIntegrationConfig[this.modalState.integration.type]
+            : undefined,
+        },
+        nextModalState: modalState,
+      };
+
+      if (!this.root.contentWindow) {
+        throw new Error('Browser not supported');
+      }
+      this.root.contentWindow.postMessage(update, this.environments.CONNECT_PUBLIC_URL);
+    }
+  }
+
+  /**
+   * this will update container style
+   * @param param0
+   * @returns
+   */
+  updateContainerStyle({ isModalShown }: { isModalShown: boolean }) {
+    if (!this.root) {
+      return;
+    }
+    if (isModalShown) {
+      this.root.style.display = 'block';
+    } else {
+      this.root.style.display = 'none';
+    }
+  }
+
+  /**
+   * Authenticate your end user into the Paragon Connect SDK.
+   *
+   * @param projectId Your Paragon project ID.
+   * @param token A JWT signed by your App Server. The JWT should include a user ID and a
+   * session expiration time.
+   */
+  async authenticate(
+    projectId: string,
+    token: string,
+    options?: AuthenticateOptions,
+  ): Promise<void> {
+    if (!projectId || !token) {
+      throw new Error('projectId or token not specified to paragon.authenticate()');
+    }
+    let decodedJwt: { sub?: string; id?: string } = {};
+    try {
+      decodedJwt = jwtDecode<typeof decodedJwt>(token);
+    } catch (err) {
+      throw new Error('A well-formed JWT was not provided to paragon.authenticate()');
+    }
+
+    this.projectId = projectId;
+    this.userState = {
+      authenticated: true,
+      token,
+      userId: (decodedJwt.sub || decodedJwt.id) as string,
+      integrations: {},
+      meta: options?.metadata ?? {},
+    };
+    try {
+      await this.bootstrapSDKState(options?.metadata);
+    } catch (err) {
+      console.warn('paragon.authenticate() could not login user', err);
+      this.logout();
+      throw new Error(`Failed to authenticate user with Paragon: ${err.message}`);
+    }
+    this.render();
+  }
+
+  /**
+   * Get the Paragon authentication and integration state of your end user.
+   */
+  getUser(): ConnectUser {
+    return Object.fromEntries(
+      Object.entries(this.userState).filter(([key]: [string, unknown]) => key !== 'token'),
+    ) as ConnectUser;
+  }
+
+  updateAuthenticatedUser(statePartial: Partial<AuthenticatedConnectUser>): void {
+    if (this.userState.authenticated) {
+      this.userState = { ...this.userState, ...statePartial };
+    } else if (statePartial.authenticated) {
+      this.userState = statePartial as AuthenticatedConnectUser;
+    }
+    this.render();
+  }
+
+  /**
+   * Logout the currently authenticated end user from the Paragon SDK.
+   */
+  logout(): void {
+    this.userState = { authenticated: false };
+    this.clearState();
+    this.render();
+  }
+
+  /**
+   * Display the Paragon Connect modal
+   */
+  async connect(
+    action: Action,
+    params: ConnectParams = { showPortalAfterInstall: true, isApiInstallation: false },
+  ): Promise<void> {
+    const { mapObjectFields, overrideRedirectUrl, ...callbacks } = params;
+
+    return new Promise((resolve: () => void, reject: (err: Error) => void) => {
+      this.subscribeToIntegration(action, {
+        ...callbacks,
+        onInstall: (event: IntegrationInstallEvent, user: AuthenticatedConnectUser) => {
+          resolve();
+          callbacks?.onInstall
+            ? callbacks.onInstall(event, user)
+            : callbacks?.onSuccess?.(event, user);
+        },
+        onError: (err: Error) => {
+          reject(err);
+          callbacks?.onError?.(err);
+        },
+      });
+
+      try {
+        if (
+          mapObjectFields &&
+          !this.project.accessibleFeatures.includes(ConnectAddOn.DynamicFieldMapper)
+        ) {
+          throw new Error(
+            `Dynamic Field Mapping is available on our Enterprise plan. Contact sales@useparagon.com to learn more or upgrade.`,
+          );
+        }
+
+        this.validateAction(action);
+
+        if (overrideRedirectUrl && !isValidUrl(overrideRedirectUrl)) {
+          throw new Error(`${overrideRedirectUrl} is not valid url.`);
+        }
+        this.endUserIntegrationConfig[action] = {
+          mapObjectFields,
+          overrideRedirectUrl: overrideRedirectUrl ? sanitizeUrl(overrideRedirectUrl) : undefined,
+        };
+        const integration: IConnectIntegrationWithCredentialInfo = Object.values(
+          this.loadedIntegrations,
+        ).find(
+          (integration: IConnectIntegrationWithCredentialInfo) =>
+            getIntegrationTypeName(integration) === action,
+        ) as IConnectIntegrationWithCredentialInfo;
+
+        /**
+         * in chrome getting issue for asynchronous popup opening
+         * see PARA-1505
+         */
+        if (params.isApiInstallation && !shouldShowPreAuthInputs(integration)) {
+          void startOAuthFlow({
+            context: {
+              user: this.userState,
+              projectId: this.projectId,
+              environments: this.environments,
+              endUserIntegrationConfig: this.modalState.integration
+                ? this.endUserIntegrationConfig[this.modalState.integration.type]
+                : undefined,
+            } as IConnectUserContext,
+            integration,
+          });
+        }
+
+        this.setModalState({
+          integration,
+          config: this.loadedConfigs[action],
+          apiInstallationOptions: {
+            isApiInstallation: params.isApiInstallation,
+            showPortalAfterInstall: params.showPortalAfterInstall,
+          },
+        });
+      } catch (err) {
+        this.emitError(err, action);
+      }
+    });
+  }
+
+  async _oauthCallback(credential: ICredential, credentialId?: string): Promise<void> {
+    const { integration } = this.modalState;
+    if (!integration) {
+      return;
+    }
+    const type = getIntegrationTypeName(integration) as string;
+    try {
+      const user = this.userState as AuthenticatedConnectUser;
+      const requestURI = credentialId
+        ? `/sdk/credentials/${credentialId}/complete-setup`
+        : `/sdk/credentials`;
+      const oauthResponse = await this.sendConnectRequest<IConnectCredential>(requestURI, {
+        method: 'POST',
+        body: JSON.stringify({
+          integrationId: integration.id,
+          config: {},
+          payload: credential,
+        }),
+      });
+
+      if (!oauthResponse) {
+        throw new Error('Unable to save oauth credentials');
+      }
+
+      const { id, config, providerId, status, providerData } = oauthResponse;
+      this.updateAuthenticatedUser({
+        integrations: {
+          ...user.integrations,
+          [type]: {
+            ...user.integrations[type],
+            ...config,
+            credentialStatus: status,
+            enabled: status === CredentialStatus.VALID,
+            credentialId: id,
+            providerId,
+            providerData,
+          },
+        },
+      });
+
+      if (status === CredentialStatus.VALID) {
+        this.triggerSDKEvent({
+          type: SDK_EVENT.ON_INTEGRATION_INSTALL,
+          integrationId: integration.id,
+          integrationType: type,
+        });
+      }
+    } catch (err) {
+      this.emitError(err, type);
+      await this._oauthErrorCallback(err.message);
+    }
+  }
+
+  // tslint:disable-next-line: function-name
+  async _oauthErrorCallback(errorMessage: string | object): Promise<void> {
+    let message: string | object = errorMessage;
+    //also log error in console
+    console.error('Failed to connect account to Paragon over OAuth', message);
+
+    if (typeof message === 'object') {
+      message = JSON.stringify(message);
+    }
+    // currently alerting generic error or error message for oauth failure
+    // TODO: to make generic oauth error modal to show errormessage property
+    window.alert(`Something went wrong connecting your account. Please try again or ${message}`);
+  }
+
+  /**
+   * Send a Connect API request. Automatically handles authorization and errors.
+   *
+   * @param path The path of the request, including the leading slash, i.e. `/sdk/actions`
+   * @param init Options for the request, excluding headers (automatically added).
+   * @param prefixWithProjectPath Defaults to true. Prepends /projects/${this.projectId}` to the
+   * path.
+   */
+  async sendConnectRequest<TResponse>(
+    path: string,
+    init?: RequestInit & { cacheResult?: boolean },
+    prefixWithProjectPath: boolean = true,
+  ): Promise<TResponse | undefined> {
+    if (!this.userState.authenticated || !this.projectId) {
+      throw new Error(
+        `Connect SDK attempted to make an API request, but no user was authenticated.
+Call paragon.authenticate(<projectId>, <user token>) before using the SDK.`,
+      );
+    }
+    const url: string = `${this.environments.ZEUS_PUBLIC_URL}${
+      prefixWithProjectPath ? `/projects/${this.projectId}` : ''
+    }${path}`;
+
+    const cacheKey: string = hash(JSON.stringify({ url, payload: { ...init } }));
+    const cachedResult = await this.cachedApiResponse.get(cacheKey, true);
+    if (init?.cacheResult && cachedResult) {
+      return cachedResult;
+    }
+
+    const shouldCacheRequest: boolean = Boolean(!init || init.method === 'GET' || init.cacheResult);
+
+    if (shouldCacheRequest && typeof this.keyToRequestPromiseMap[cacheKey] === 'object') {
+      return this.keyToRequestPromiseMap[cacheKey] as Promise<TResponse | undefined>;
+    }
+
+    const accessToken: string = this.userState.token;
+
+    const onGoingRequest: Promise<TResponse | undefined> = new Promise((resolve, reject) => {
+      (async () => {
+        try {
+          const result = await this.sendRequest<TResponse>(
+            url,
+            {
+              ...init,
+              headers: {
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                ...init?.headers,
+                Authorization: `Bearer ${accessToken}`,
+              },
+            },
+            shouldCacheRequest ? cacheKey : undefined,
+          );
+          resolve(result);
+        } catch (err) {
+          reject(err);
+        }
+      })();
+    });
+
+    if (shouldCacheRequest) {
+      this.keyToRequestPromiseMap[cacheKey] = onGoingRequest;
+    }
+    return onGoingRequest;
+  }
+
+  private async sendRequest<TResponse>(
+    url: string,
+    init: RequestInit,
+    cacheKey?: string,
+  ): Promise<TResponse | undefined> {
+    let response: Response | undefined;
+    let responseBody: TResponse | undefined;
+    let responseError: Error | undefined;
+    try {
+      response = await fetch(url, init);
+    } catch (error) {
+      responseError = error;
+    }
+
+    if ((response && !response.ok) || responseError) {
+      const requestReturnedAuthorizationError: boolean =
+        response?.status === 401 || response?.status === 403;
+      if (!url.includes('proxy') && requestReturnedAuthorizationError) {
+        this.logout();
+      }
+
+      const errorMessage: string = (await response?.text()) || (responseError?.message as string);
+
+      if (cacheKey) {
+        await this.cachedApiResponse.del(cacheKey);
+        delete this.keyToRequestPromiseMap[cacheKey];
+      }
+      throw new Error(errorMessage);
+    }
+
+    try {
+      responseBody = await response?.json();
+    } catch {
+      responseBody = undefined;
+    }
+
+    if (cacheKey) {
+      await this.cachedApiResponse.set(cacheKey, responseBody);
+      delete this.keyToRequestPromiseMap[cacheKey];
+    }
+
+    return responseBody;
+  }
+
+  async sendProxyRequest<TResponse>(
+    action: VisibleConnectAction,
+    path: string,
+    init: {
+      method: RequestInit['method'];
+      body: RequestInit['body'] | object;
+      headers: RequestInit['headers'];
+    },
+  ): Promise<TResponse | undefined> {
+    let baseProxyPath: string = `/sdk/proxy/${action}`;
+    if (isCustomIntegrationTypeName(action)) {
+      baseProxyPath = `/sdk/proxy/custom/${
+        Object.values(this.loadedIntegrations).find(
+          (integration: IConnectIntegrationWithCredentialInfo) => {
+            if (integration.customIntegration) {
+              return integration.customIntegration.slug === action;
+            }
+            return false;
+          },
+        )?.id
+      }`;
+    }
+    const pathWithLeadingSlash: string = path.startsWith('/') ? path : `/${path}`;
+    const response = await this.sendConnectRequest<{ output: TResponse }>(
+      `${baseProxyPath}${pathWithLeadingSlash}`,
+      {
+        method: init.method,
+        body: typeof init.body === 'object' ? JSON.stringify(init.body) : init.body,
+        headers: {
+          'Content-Type': INFER_CONTENT_TYPE_FROM_CONNECT_OPTIONS,
+          ...init.headers,
+        },
+      },
+    );
+    return response?.output;
+  }
+
+  async event(name: string, payload: Record<string, unknown>): Promise<void> {
+    await this.sendConnectRequest(
+      `/v2/projects/${this.projectId}/sdk/events/trigger`,
+      {
+        method: 'POST',
+        body: JSON.stringify({
+          name,
+          payload,
+        }),
+      },
+      false,
+    );
+  }
+
+  /**
+   * @summary this will be called to close the modal
+   */
+  onClose(): void {
+    const { integration, apiInstallationOptions } = this.modalState;
+
+    if (!integration) {
+      // This might happen if the "X" button is closed, because `onClose` will fire twice. We
+      // ignore it if this is the case.
+      return;
+    }
+    this.triggerSDKEvent({
+      type: SDK_EVENT.ON_PORTAL_CLOSE,
+      integrationId: integration.id,
+      integrationType: getIntegrationTypeName(integration) as string,
+    });
+
+    if (this.originalBodyOverflow !== PARAGON_OVERFLOW_EMPTY_VALUE) {
+      window.document.body.style.overflow = this.originalBodyOverflow as string;
+      this.originalBodyOverflow = PARAGON_OVERFLOW_EMPTY_VALUE;
+    }
+
+    // Not clearing integration state as its required in oauth_callback
+    if (!apiInstallationOptions?.isApiInstallation) {
+      this.setModalState({ integration: null });
+    }
+  }
+
+  /**
+   * @summary this will be called when modal will be visible
+   */
+  onOpen(): void {
+    const { integration } = this.modalState;
+    if (!integration) {
+      return;
+    }
+    this.triggerSDKEvent({
+      type: SDK_EVENT.ON_PORTAL_OPEN,
+      integrationId: integration.id,
+      integrationType: getIntegrationTypeName(integration) as string,
+    });
+
+    if (this.root && this.originalBodyOverflow === PARAGON_OVERFLOW_EMPTY_VALUE) {
+      const boundingRect = this.root.getBoundingClientRect();
+      // If the Connect Portal is bigger than the window
+      if (window.innerHeight <= boundingRect.height && window.innerWidth <= boundingRect.width) {
+        this.originalBodyOverflow = window.document.body.style.overflow;
+        window.document.body.style.overflow = 'hidden';
+      }
+    }
+  }
+
+  /**
+   * this is shared in ConnectUserContext
+   * so that event can be trigger from components
+   * @param eventInfo
+   */
+  triggerSDKEvent(eventInfo: EventInfo): void {
+    this.triggerEvent(eventInfo, this.userState as AuthenticatedConnectUser);
+  }
+
+  /**
+   * get single or all metadata info for integrations
+   * @param integrationKeyName
+   * @returns
+   */
+  getIntegrationMetadata(
+    integrationKeyName?: string,
+  ): IIntegrationMetadata | IIntegrationMetadata[] {
+    if (!integrationKeyName) {
+      return Object.values(this.metadata);
+    } else if (!this.metadata[integrationKeyName]) {
+      throw new Error(`${integrationKeyName} is not a valid integration name`);
+    }
+
+    return this.metadata[integrationKeyName];
+  }
+
+  /**
+   * trigger connect endpoint trigger workflow
+   * @param workflowId
+   * @param payload
+   */
+  triggerWorkflow(
+    workflowId: string,
+    { body = {}, query = {}, headers = {} }: TriggerWorkflowRequest = {
+      body: {},
+      headers: {},
+      query: {},
+    },
+  ): Promise<object | undefined> {
+    if (!workflowId) {
+      throw new Error('workflowId is required.');
+    }
+
+    const queryString: string = new URLSearchParams(query).toString();
+
+    return this.sendConnectRequest<object>(
+      `/sdk/triggers/${workflowId}?${queryString}`,
+      {
+        method: 'POST',
+        body: JSON.stringify(body),
+        headers,
+      },
+      true,
+    );
+  }
+
+  /**
+   * for programmatically installing an integration
+   */
+  installIntegration(
+    action: Action,
+    params: Omit<InstallOptions, 'isApiInstallation'> = { showPortalAfterInstall: false },
+  ): Promise<void> {
+    if (!this.userState.authenticated) {
+      throw new Error(
+        `User not authenticated, Call paragon.authenticate(<projectId>, <user token>) before using the SDK.`,
+      );
+    }
+    this.ensureHeadlessIsSupported();
+
+    const isAlreadyEnabled = this.validateAction(action, true);
+    if (isAlreadyEnabled) {
+      throw new Error(`Integration "${action}" is already installed.`);
+    }
+
+    // as we have added integration dependency in ConnectModal useEffect to trigger enableIntegration
+    // so this reset is needed incase previous one fails
+    this.setModalState({ integration: null });
+
+    return this.connect(action, { ...params, isApiInstallation: true });
+  }
+
+  /**
+   * gates headless feature to pro and enterprise users
+   */
+  ensureHeadlessIsSupported(): void {
+    if (!this.project.accessibleFeatures.includes(ConnectAddOn.HeadlessConnectPortal)) {
+      throw new Error(
+        'Headless Connect Portal is available on our Pro plan and above. Contact sales@useparagon.com to learn more or upgrade.',
+      );
+    }
+  }
+
+  async uninstallIntegration(action: Action): Promise<void> {
+    if (!this.userState.authenticated) {
+      throw new Error(
+        `User not authenticated, Call paragon.authenticate(<projectId>, <user token>) before using the SDK.`,
+      );
+    }
+    this.ensureHeadlessIsSupported();
+    if (!this.validateAction(action, true)) {
+      throw new Error(`Integration "${action}" is not installed.`);
+    }
+
+    const integrationId = this.loadedIntegrations[action].id;
+    await this.sendConnectRequest(`/sdk/integrations/${integrationId}`, {
+      method: 'DELETE',
+    });
+
+    this.updateAuthenticatedUser({
+      integrations: {
+        ...this.userState.integrations,
+        [action]: { enabled: false, configuredWorkflows: {} },
+      },
+    });
+
+    this.saveState();
+
+    this.triggerSDKEvent({
+      type: SDK_EVENT.ON_INTEGRATION_UNINSTALL,
+      integrationId,
+      integrationType: action,
+    });
+  }
+
+  async disableWorkflow(workflowId: string): Promise<void> {
+    if (!this.userState.authenticated) {
+      throw new Error(
+        `User not authenticated, Call paragon.authenticate(<projectId>, <user token>) before using the SDK.`,
+      );
+    }
+
+    if (!this.isWorkflowEnabled(workflowId)) {
+      throw new Error(`Workflow ${workflowId} cannot be disabled for this user.`);
+    }
+
+    await this.sendConnectRequest<IConnectCredential>(`/sdk/workflows/${workflowId}`, {
+      method: 'DELETE',
+    });
+
+    await this.updateLocalState();
+  }
+
+  private async updateLocalState(): Promise<void> {
+    const [userData, integrations] = await Promise.all([
+      this.fetchUserData(),
+      this.fetchIntegrations(),
+    ]);
+
+    this.updateAuthenticatedUser({ integrations: userData.integrations, meta: userData.meta });
+    this.updateIntegrations(integrations);
+    this.saveState();
+  }
+
+  /**
+   * also returns false if unable to find workflow in configured workflow property of any integration
+   */
+  private isWorkflowEnabled(workflowId: string): boolean {
+    const result = Object.values((this.userState as AuthenticatedConnectUser).integrations).find(
+      (integration) => integration?.configuredWorkflows?.[workflowId]?.enabled,
+    );
+
+    return result === undefined ? false : true;
+  }
+
+  /**
+   * gets the user data from api `/sdk/me`
+   */
+  private async fetchUserData(): Promise<IConnectUser> {
+    const userData = await this.sendConnectRequest<IConnectUser>('/sdk/me');
+    if (!userData) {
+      throw new Error('Unable to get user Data');
+    } else {
+      return userData;
+    }
+  }
+
+  /**
+   * Gets the integrations from api `/sdk/integrations`
+   * Required this another request for integrations, as `/sdk/me` provides only minimal data for integrations
+   * we also need integration config and other credentials info which is not included in `sdk/me`
+   */
+  private async fetchIntegrations(): Promise<IConnectIntegrationWithCredentialInfo[]> {
+    const integrations = await this.sendConnectRequest<IConnectIntegrationWithCredentialInfo[]>(
+      '/sdk/integrations',
+    );
+
+    if (!integrations) {
+      throw new Error('Unable to fetch integrations');
+    }
+
+    return integrations;
+  }
+
+  /**
+   * Updates internal state where integration information may be used.
+   */
+  private updateIntegrations(integrations: IConnectIntegrationWithCredentialInfo[]): void {
+    integrations.forEach((integration: IConnectIntegrationWithCredentialInfo) => {
+      if (integration.configs.length) {
+        try {
+          const type = getIntegrationTypeName(integration) as string;
+
+          // update loaded configs
+          this.loadedConfigs[type] = integration.configs[0].values;
+
+          // update loaded integrations
+          this.loadedIntegrations[type] = integration;
+
+          // update integration metadata
+          if (Boolean(integration.isActive)) {
+            this.metadata[type] = {
+              type,
+              name:
+                integration.customIntegration?.name ?? ActionCatalogConfigs[integration.type].name,
+              brandColor:
+                integration.configs[0].values.accentColor ??
+                ActionCatalogConfigs[integration.type].brandColor,
+              icon:
+                integration.customIntegration?.icon ??
+                `${this.environments.CDN_PUBLIC_URL}/integrations/${
+                  overrideActionAlias[integration.type] || integration.type
+                }.svg`,
+            };
+          }
+
+          // update modal state (if being used)
+          if (this.modalState.integration?.id === integration.id) {
+            this.setModalState({ integration });
+          }
+        } catch (err) {
+          console.warn(err);
+        }
+      }
+    });
+  }
+
+  async setUserMetadata(meta: PersonaMeta): Promise<AuthenticatedConnectUser> {
+    await this.sendConnectRequest<IPersona>('/sdk/me', {
+      method: 'PATCH',
+      body: JSON.stringify({ meta }),
+    });
+
+    await this.updateLocalState();
+    this.render();
+
+    return this.userState as AuthenticatedConnectUser;
+  }
+}