@tryfinch/react-connect 3.15.1 → 4.1.0

package/src/index.ts

@@ -1,7 +1,5 @@
 import { useEffect, useRef } from 'react';
 
-type HasKey<T, K extends PropertyKey> = T extends Record<K, unknown> ? T : never;
-
 export type SuccessEvent = {
   code: string;
   state?: string;
@@ -9,50 +7,36 @@ export type SuccessEvent = {
 };
 
 type ErrorType = 'validation_error' | 'employer_connection_error';
-
 export type ErrorEvent = {
   errorMessage: string;
   errorType?: ErrorType;
 };
 
-export type Sandbox =
-  | 'finch' /** This is to enable the new Finch (simulated) Sandbox */
-  | 'provider' /** This is to enable the new Provider Sandbox */
-  | boolean /** This is the old sandbox flag retained for backwards compatibility */;
+type ApiConfig = {
+  connectUrl: string;
+};
 
-type BaseConnectOptions = {
-  state: string | null;
+export type ConnectInitializeArgs = {
   onSuccess: (e: SuccessEvent) => void;
   onError: (e: ErrorEvent) => void;
   onClose: () => void;
-  zIndex: number;
-  apiConfig?: {
-    connectUrl: string;
-    redirectUrl: string;
-  };
+  apiConfig?: ApiConfig;
 };
 
-type ConnectOptionsWithSessionId = BaseConnectOptions & {
-  // Use this option if you have a Finch Connect sessionID from the IDP redirect flow
+export type ConnectLaunchArgs = {
   sessionId: string;
-  // Allow for overriding products for the session
-  products?: string[];
+  state?: string;
+  zIndex?: number;
 };
 
-type ConnectOptionsWithClientId = BaseConnectOptions & {
-  category: string | null;
+export type ConnectPreviewLaunchArgs = {
   clientId: string;
-  manual: boolean;
-  payrollProvider: string | null;
   products: string[];
-  clientName?: string;
-  connectionId?: string;
-  sandbox: Sandbox;
 };
 
-export type ConnectOptions = ConnectOptionsWithSessionId | ConnectOptionsWithClientId;
+type OpenFn = (args: ConnectLaunchArgs) => void;
 
-type OpenFn = (overrides?: Partial<ConnectOptions>) => void;
+type OpenPreviewFn = (args: ConnectPreviewLaunchArgs) => void;
 
 const POST_MESSAGE_NAME = 'finch-auth-message-v2' as const;
 
@@ -78,95 +62,69 @@ interface FinchConnectPostMessage {
 }
 
 const BASE_FINCH_CONNECT_URI = 'https://connect.tryfinch.com';
-const DEFAULT_FINCH_REDIRECT_URI = 'https://tryfinch.com';
 
 const FINCH_CONNECT_IFRAME_ID = 'finch-connect-iframe';
 
-const constructAuthUrl = (connectOptions: ConnectOptions) => {
-  const { state, apiConfig } = connectOptions;
+const appendBaseParams = (url: URL) => {
+  url.searchParams.append('app_type', 'spa');
+  // The host URL of the SDK. This is used to store the referrer for postMessage purposes
+  url.searchParams.append('sdk_host_url', window.location.origin);
+  url.searchParams.append('mode', 'employer');
+  // replace with actual SDK version by rollup
+  url.searchParams.append('sdk_version', 'react-SDK_VERSION');
+};
 
+export const constructAuthUrl = ({
+  sessionId,
+  state,
+  apiConfig,
+}: {
+  sessionId: string;
+  state?: string;
+  apiConfig?: ApiConfig;
+}) => {
   const CONNECT_URL = apiConfig?.connectUrl || BASE_FINCH_CONNECT_URI;
-  const REDIRECT_URL = apiConfig?.redirectUrl || DEFAULT_FINCH_REDIRECT_URI;
 
   const authUrl = new URL(`${CONNECT_URL}/authorize`);
 
-  if ('sessionId' in connectOptions) {
-    const { sessionId, products } = connectOptions;
-    authUrl.searchParams.append('session', sessionId);
-    if (products) authUrl.searchParams.append('products', products.join(' '));
-  } else {
-    const {
-      clientId,
-      payrollProvider,
-      category,
-      products,
-      manual,
-      sandbox,
-      clientName,
-      connectionId,
-    } = connectOptions;
-
-    if (clientId) authUrl.searchParams.append('client_id', clientId);
-    if (payrollProvider) authUrl.searchParams.append('payroll_provider', payrollProvider);
-    if (category) authUrl.searchParams.append('category', category);
-    if (clientName) authUrl.searchParams.append('client_name', clientName);
-    if (connectionId) authUrl.searchParams.append('connection_id', connectionId);
-    authUrl.searchParams.append('products', (products ?? []).join(' '));
-    if (manual) authUrl.searchParams.append('manual', String(manual));
-    if (sandbox) authUrl.searchParams.append('sandbox', String(sandbox));
-  }
-
-  authUrl.searchParams.append('app_type', 'spa');
-  authUrl.searchParams.append('redirect_uri', REDIRECT_URL);
-  /** The host URL of the SDK. This is used to store the referrer for postMessage purposes */
-  authUrl.searchParams.append('sdk_host_url', window.location.origin);
-  authUrl.searchParams.append('mode', 'employer');
+  authUrl.searchParams.append('session', sessionId);
   if (state) authUrl.searchParams.append('state', state);
-  // replace with actual SDK version by rollup
-  authUrl.searchParams.append('sdk_version', 'react-SDK_VERSION');
+
+  appendBaseParams(authUrl);
 
   return authUrl.href;
 };
 
-const noop = () => {
-  // intentionally empty
-};
+export const constructPreviewUrl = ({
+  clientId,
+  products,
+  apiConfig,
+}: {
+  clientId: string;
+  products: string[];
+  apiConfig?: ApiConfig;
+}) => {
+  const CONNECT_URL = apiConfig?.connectUrl || BASE_FINCH_CONNECT_URI;
 
-const BASE_DEFAULTS = {
-  onSuccess: noop,
-  onError: noop,
-  onClose: noop,
-  state: null,
-  zIndex: 999,
-};
+  const previewUrl = new URL(`${CONNECT_URL}/authorize`);
 
-const DEFAULT_OPTIONS_WITH_CLIENT_ID: HasKey<ConnectOptions, 'clientId'> = {
-  ...BASE_DEFAULTS,
-  clientId: '',
-  category: null,
-  manual: false,
-  payrollProvider: null,
-  products: [],
-  clientName: undefined,
-  sandbox: false,
-};
+  previewUrl.searchParams.append('preview', 'true');
+  previewUrl.searchParams.append('client_id', clientId);
+  previewUrl.searchParams.append('products', (products ?? []).join(' '));
+  // This will be replaced by a universally allowed redirect URI in the backend
+  // We won't ever redirect to anything in preview mode, so we just need a value to pass validation
+  previewUrl.searchParams.append('redirect_uri', 'https://www.tryfinch.com');
+
+  appendBaseParams(previewUrl);
 
-const DEFAULT_OPTIONS_WITH_SESSION_ID: HasKey<ConnectOptions, 'sessionId'> = {
-  ...BASE_DEFAULTS,
-  sessionId: '',
+  return previewUrl.href;
 };
 
 let isUseFinchConnectInitialized = false;
 
-export const useFinchConnect = (options: Partial<ConnectOptions>): { open: OpenFn } => {
-  if (!('sessionId' in options) && !('clientId' in options)) {
-    throw new Error('must specify either sessionId or clientId in options for useFinchConnect');
-  }
-
-  if ('sessionId' in options && 'clientId' in options) {
-    throw new Error('cannot specify both sessionId and clientId in options for useFinchConnect');
-  }
-
+export const useFinchConnect = (
+  initializeArgs: ConnectInitializeArgs
+): { open: OpenFn; openPreview: OpenPreviewFn } => {
   const isHookMounted = useRef(false);
 
   useEffect(() => {
@@ -183,24 +141,20 @@ export const useFinchConnect = (options: Partial<ConnectOptions>): { open: OpenF
     }
   }, []);
 
-  const combinedOptions: ConnectOptions =
-    'sessionId' in options
-      ? { ...DEFAULT_OPTIONS_WITH_SESSION_ID, ...options }
-      : { ...DEFAULT_OPTIONS_WITH_CLIENT_ID, ...options };
-
-  const open: OpenFn = (overrides) => {
-    const openOptions: ConnectOptions = {
-      ...combinedOptions,
-      ...overrides,
-    };
-
+  const createAndAttachIFrame = ({
+    src,
+    zIndexOverride,
+  }: {
+    src: string;
+    zIndexOverride?: number;
+  }) => {
     if (!document.getElementById(FINCH_CONNECT_IFRAME_ID)) {
       const iframe = document.createElement('iframe');
-      iframe.src = constructAuthUrl(openOptions);
+      iframe.src = src;
       iframe.frameBorder = '0';
       iframe.id = FINCH_CONNECT_IFRAME_ID;
       iframe.style.position = 'fixed';
-      iframe.style.zIndex = openOptions.zIndex.toString();
+      iframe.style.zIndex = zIndexOverride?.toString() || '999';
       iframe.style.height = '100%';
       iframe.style.width = '100%';
       iframe.style.top = '0';
@@ -212,6 +166,31 @@ export const useFinchConnect = (options: Partial<ConnectOptions>): { open: OpenF
     }
   };
 
+  const open: OpenFn = (launchArgs) => {
+    const iframeSrc = constructAuthUrl({
+      sessionId: launchArgs.sessionId,
+      state: launchArgs.state,
+      apiConfig: initializeArgs.apiConfig,
+    });
+
+    createAndAttachIFrame({
+      src: iframeSrc,
+      zIndexOverride: launchArgs.zIndex,
+    });
+  };
+
+  const openPreview: OpenPreviewFn = (launchArgs) => {
+    const iframeSrc = constructPreviewUrl({
+      clientId: launchArgs.clientId,
+      products: launchArgs.products,
+      apiConfig: initializeArgs.apiConfig,
+    });
+
+    createAndAttachIFrame({
+      src: iframeSrc,
+    });
+  };
+
   const close = () => {
     const frameToRemove = document.getElementById(FINCH_CONNECT_IFRAME_ID);
     if (frameToRemove) {
@@ -222,7 +201,7 @@ export const useFinchConnect = (options: Partial<ConnectOptions>): { open: OpenF
 
   useEffect(() => {
     function handleFinchAuth(event: FinchConnectPostMessage) {
-      const CONNECT_URL = combinedOptions.apiConfig?.connectUrl || BASE_FINCH_CONNECT_URI;
+      const CONNECT_URL = initializeArgs.apiConfig?.connectUrl || BASE_FINCH_CONNECT_URI;
 
       if (!event.data) return;
       if (event.data.name !== POST_MESSAGE_NAME) return;
@@ -232,18 +211,18 @@ export const useFinchConnect = (options: Partial<ConnectOptions>): { open: OpenF
 
       switch (event.data.kind) {
         case 'closed':
-          combinedOptions.onClose();
+          initializeArgs.onClose();
           break;
         case 'error':
           if (event.data.error?.shouldClose) close();
 
-          combinedOptions.onError({
+          initializeArgs.onError({
             errorMessage: event.data.error?.message,
             errorType: event.data.error?.type,
           });
           break;
         case 'success':
-          combinedOptions.onSuccess({
+          initializeArgs.onSuccess({
             code: event.data.code,
             state: event.data.state,
             idpRedirectUri: event.data.idpRedirectUri,
@@ -251,7 +230,7 @@ export const useFinchConnect = (options: Partial<ConnectOptions>): { open: OpenF
           break;
         default: {
           // This case should never happen, if it does it should be reported to us
-          combinedOptions.onError({
+          initializeArgs.onError({
             errorMessage: `Report to developers@tryfinch.com: unable to handle window.postMessage for:  ${JSON.stringify(
               event.data
             )}`,
@@ -265,9 +244,10 @@ export const useFinchConnect = (options: Partial<ConnectOptions>): { open: OpenF
       window.removeEventListener('message', handleFinchAuth);
       isUseFinchConnectInitialized = false;
     };
-  }, [combinedOptions.onClose, combinedOptions.onError, combinedOptions.onSuccess]);
+  }, [initializeArgs.onClose, initializeArgs.onError, initializeArgs.onSuccess]);
 
   return {
     open,
+    openPreview,
   };
 };