@quiltt/react 4.3.0 → 4.3.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @quiltt/react
 
+## 4.3.2
+
+### Patch Changes
+
+- [#372](https://github.com/quiltt/quiltt-js/pull/372) [`c022ebe`](https://github.com/quiltt/quiltt-js/commit/c022ebed0c82404a1bdbf5abbaf6e60b49f2d07a) Thanks [@sirwolfgang](https://github.com/sirwolfgang)! - Hardened React SDK against unstable prop references by implementing ref-based callback wrappers and deep equality checks, eliminating unnecessary re-renders, event handler churn, and API calls without requiring customers to use useCallback.
+
+- Updated dependencies [[`c022ebe`](https://github.com/quiltt/quiltt-js/commit/c022ebed0c82404a1bdbf5abbaf6e60b49f2d07a)]:
+  - @quiltt/core@4.3.2
+
+## 4.3.1
+
+### Patch Changes
+
+- [#366](https://github.com/quiltt/quiltt-js/pull/366) [`dc376b5`](https://github.com/quiltt/quiltt-js/commit/dc376b52dd824d7867ca74677bbfd5c54eff5cdc) Thanks [@sirwolfgang](https://github.com/sirwolfgang)! - Warn if useQuilttConnector is unmounted while in use
+- [#365](https://github.com/quiltt/quiltt-js/pull/365) [`5f6b8af`](https://github.com/quiltt/quiltt-js/commit/5f6b8af153086c77bb2227d43ae7023fb0c47985) Thanks [@rubendinho](https://github.com/rubendinho)! - Standardize SDK agent tracking header to `Quiltt-SDK-Agent` and add support for custom Apollo Links injection
+
+- Updated dependencies [[`dc376b5`](https://github.com/quiltt/quiltt-js/commit/dc376b52dd824d7867ca74677bbfd5c54eff5cdc)]:
+  - @quiltt/core@4.3.1
+
 ## 4.3.0
 
 ### Minor Changes

package/dist/{QuilttAuthProvider-12s-DNnAmo8E.js → QuilttAuthProvider-12s-D-Wr7LUT.js}

@@ -7,7 +7,7 @@ import './useSession-12s-7GOn4sUn.js';
 import 'use-debounce';
 import { jsx } from 'react/jsx-runtime';
 import { ApolloProvider } from '@apollo/client/react/context/ApolloProvider.js';
-import { u as useQuilttSession } from './useQuilttSession-12s-QlPCR8A-.js';
+import { u as useQuilttSession } from './useQuilttSession-12s-CwVw-aOM.js';
 
 const useAuthenticateSession = (auth, setSession)=>{
     const authenticateSession = useCallback(async (payload, callbacks)=>{
@@ -133,8 +133,9 @@ const useRevokeSession = (auth, session, setSession)=>{
     }
     if (obj1 instanceof Set && obj2 instanceof Set) {
         if (obj1.size !== obj2.size) return false;
+        const arr2 = Array.from(obj2);
         for (const item of obj1){
-            if (!Array.from(obj2).some((value)=>isDeepEqual(item, value))) return false;
+            if (!arr2.some((value)=>isDeepEqual(item, value))) return false;
         }
         return true;
     }
@@ -158,16 +159,25 @@ const useRevokeSession = (auth, session, setSession)=>{
  * it into trusted storage. While this process is happening, the component is put
  * into a loading state and the children are not rendered to prevent race conditions
  * from triggering within the transitionary state.
- */ const QuilttAuthProvider = ({ token, children })=>{
+ */ const QuilttAuthProvider = ({ graphqlClient, token, children })=>{
     const { session, importSession } = useQuilttSession();
     const previousSessionRef = useRef(session);
-    // @todo: extract into a provider so it can accessed by child components
-    const graphQLClient = useMemo(()=>new QuilttClient({
+    const previousTokenRef = useRef();
+    // Memoize the client to avoid unnecessary re-renders
+    const apolloClient = useMemo(()=>graphqlClient || new QuilttClient({
             cache: new InMemoryCache()
-        }), []);
-    // Import passed in token
+        }), [
+        graphqlClient
+    ]);
+    // Import passed in token (only if value has changed)
     useEffect(()=>{
-        if (token) importSession(token);
+        if (token && token !== previousTokenRef.current) {
+            importSession(token);
+            previousTokenRef.current = token;
+        } else if (!token) {
+            // Reset ref when token becomes undefined to allow re-import of same token later
+            previousTokenRef.current = undefined;
+        }
     }, [
         token,
         importSession
@@ -175,15 +185,15 @@ const useRevokeSession = (auth, session, setSession)=>{
     // Reset Client Store when session changes (using deep comparison)
     useEffect(()=>{
         if (!isDeepEqual(session, previousSessionRef.current)) {
-            graphQLClient.resetStore();
+            apolloClient.resetStore();
             previousSessionRef.current = session;
         }
     }, [
         session,
-        graphQLClient
+        apolloClient
     ]);
     return /*#__PURE__*/ jsx(ApolloProvider, {
-        client: graphQLClient,
+        client: apolloClient,
         children: children
     });
 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ConnectorSDKCallbacks, Maybe, QuilttJWT, PasscodePayload, UnprocessableData, AuthAPI, UsernamePayload, ConnectorSDKConnectorOptions, InstitutionsData } from '@quiltt/core';
+import { ConnectorSDKCallbacks, Maybe, QuilttJWT, PasscodePayload, UnprocessableData, AuthAPI, UsernamePayload, ConnectorSDKConnectorOptions, InstitutionsData, QuilttClient } from '@quiltt/core';
 export * from '@quiltt/core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { JSX, ComponentType, ElementType, PropsWithChildren, MouseEvent, RefObject, useEffect, Dispatch, SetStateAction, FC } from 'react';
@@ -159,7 +159,9 @@ declare const useQuilttSettings: () => {
 declare const useStorage: <T>(key: string, initialState?: Maybe<T>) => [Maybe<T> | undefined, Dispatch<SetStateAction<Maybe<T> | undefined>>];
 
 type QuilttAuthProviderProps = PropsWithChildren & {
-    /** The Session token obtained from the server */
+    /** A custom QuilttClient instance to use instead of the default */
+    graphqlClient?: QuilttClient;
+    /** The Quiltt Session token obtained from the server */
     token?: string;
 };
 /**
@@ -170,19 +172,14 @@ type QuilttAuthProviderProps = PropsWithChildren & {
  */
 declare const QuilttAuthProvider: FC<QuilttAuthProviderProps>;
 
-type QuilttProviderProps = PropsWithChildren & {
-    /** The client ID for the client-side Auth API */
-    clientId?: string;
-    /** The Session token obtained from the server */
-    token?: string;
-};
-declare const QuilttProvider: FC<QuilttProviderProps>;
-
 type QuilttSettingsProviderProps = PropsWithChildren & {
-    /** The Client ID to use for the client-side Auth API */
+    /** The Client ID to use for the passwordless Auth API */
     clientId?: string;
 };
 declare const QuilttSettingsProvider: FC<QuilttSettingsProviderProps>;
 
+type QuilttProviderProps = QuilttSettingsProviderProps & QuilttAuthProviderProps;
+declare const QuilttProvider: FC<QuilttProviderProps>;
+
 export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useAuthenticateSession, useEventListener, useIdentifySession, useImportSession, useIsomorphicLayoutEffect, useQuilttClient, useQuilttConnector, useQuilttInstitutions, useQuilttSession, useQuilttSettings, useRevokeSession, useSession, useStorage };
-export type { AuthenticateSession, IdentifySession, ImportSession, RevokeSession, SetSession, UseQuilttInstitutions, UseQuilttSession };
+export type { AuthenticateSession, IdentifySession, ImportSession, QuilttAuthProviderProps, QuilttSettingsProviderProps, RevokeSession, SetSession, UseQuilttInstitutions, UseQuilttSession };

package/dist/index.js

@@ -1,14 +1,14 @@
 export * from '@quiltt/core';
 import { jsx } from 'react/jsx-runtime';
 import { useRef, useEffect } from 'react';
-import { u as useQuilttConnector } from './useQuilttConnector-12s-BaTUXD56.js';
-import { i as isDeepEqual, Q as QuilttAuthProvider } from './QuilttAuthProvider-12s-DNnAmo8E.js';
-export { b as useAuthenticateSession, a as useIdentifySession, u as useImportSession, c as useRevokeSession } from './QuilttAuthProvider-12s-DNnAmo8E.js';
+import { u as useQuilttConnector } from './useQuilttConnector-12s-BJljrsWT.js';
+import { i as isDeepEqual, Q as QuilttAuthProvider } from './QuilttAuthProvider-12s-D-Wr7LUT.js';
+export { b as useAuthenticateSession, a as useIdentifySession, u as useImportSession, c as useRevokeSession } from './QuilttAuthProvider-12s-D-Wr7LUT.js';
 export { u as useEventListener } from './useEventListener-12s-D_-6QIXa.js';
 export { u as useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect-12s-DeTHOKz1.js';
 export { u as useQuilttClient } from './useQuilttClient-12s-CAAUait1.js';
-export { u as useQuilttInstitutions } from './useQuilttInstitutions-12s-Djd5k9Ae.js';
-export { u as useQuilttSession } from './useQuilttSession-12s-QlPCR8A-.js';
+export { u as useQuilttInstitutions } from './useQuilttInstitutions-12s-PJd2C3BF.js';
+export { u as useQuilttSession } from './useQuilttSession-12s-CwVw-aOM.js';
 export { u as useQuilttSettings } from './useQuilttSettings-12s--rCJoNHD.js';
 export { u as useSession } from './useSession-12s-7GOn4sUn.js';
 export { u as useStorage } from './useStorage-12s-DHcq3Kuh.js';
@@ -78,9 +78,11 @@ import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmO
         // 1. Pre-open validation
         // 2. Preventing opening via event.preventDefault()
         // 3. Setting up state before connector opens
-        if (onClick) onClick(event);
-        // Then open the Quiltt connector
-        open();
+        onClick?.(event);
+        // Only open if event wasn't prevented
+        if (!event.defaultPrevented) {
+            open();
+        }
     };
     // Generate key for forced remounting if enabled, but respect user-provided key
     const buttonKey = props.key ?? (forceRemountOnConnectionChange ? `${connectorId}-${connectionId || 'no-connection'}` : undefined);
@@ -159,11 +161,12 @@ import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmO
     }, containerKey);
 };
 
-const QuilttProvider = ({ clientId, token, children })=>{
+const QuilttProvider = ({ clientId, graphqlClient, token, children })=>{
     return /*#__PURE__*/ jsx(QuilttSettingsProvider, {
         clientId: clientId,
         children: /*#__PURE__*/ jsx(QuilttAuthProvider, {
             token: token,
+            graphqlClient: graphqlClient,
             children: children
         })
     });

package/dist/useQuilttConnector-12s-BJljrsWT.js

@@ -0,0 +1,173 @@
+'use client';
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { cdnBase } from '@quiltt/core';
+import { u as useQuilttSession } from './useQuilttSession-12s-CwVw-aOM.js';
+import { u as useScript } from './useScript-12s-JCgaTW9n.js';
+import { i as isDeepEqual } from './QuilttAuthProvider-12s-D-Wr7LUT.js';
+
+var version = "4.3.2";
+
+const useQuilttConnector = (connectorId, options)=>{
+    const status = useScript(`${cdnBase}/v1/connector.js?agent=react-${version}`, {
+        nonce: options?.nonce
+    });
+    // This ensures we're not destructuring `session` before the script has loaded
+    const useQuilttSessionReturn = useQuilttSession();
+    const session = useQuilttSessionReturn?.session || null;
+    const [connector, setConnector] = useState();
+    const [isOpening, setIsOpening] = useState(false);
+    // Keep track of the previous connectionId to detect changes
+    const prevConnectionIdRef = useRef(options?.connectionId);
+    const prevConnectorIdRef = useRef(connectorId);
+    const prevInstitutionRef = useRef(options?.institution);
+    const connectorCreatedRef = useRef(false);
+    // Track whether the connector is currently open
+    const isConnectorOpenRef = useRef(false);
+    // Store callbacks in refs to maintain stable references
+    const callbacksRef = useRef(options || {});
+    useEffect(()=>{
+        callbacksRef.current = options || {};
+    });
+    // Set Session
+    // biome-ignore lint/correctness/useExhaustiveDependencies: trigger effects when script status changes too
+    useEffect(()=>{
+        if (typeof Quiltt === 'undefined') return;
+        Quiltt.authenticate(session?.token);
+    }, [
+        status,
+        session?.token
+    ]);
+    // Set Connector
+    // biome-ignore lint/correctness/useExhaustiveDependencies: trigger effects when script status changes too
+    useEffect(()=>{
+        if (typeof Quiltt === 'undefined' || !connectorId) return;
+        const currentConnectionId = options?.connectionId;
+        const currentInstitution = options?.institution;
+        // Check for changes - use deep equality for institution object
+        const connectionIdChanged = prevConnectionIdRef.current !== currentConnectionId;
+        const connectorIdChanged = prevConnectorIdRef.current !== connectorId;
+        const institutionChanged = !isDeepEqual(prevInstitutionRef.current, currentInstitution);
+        const hasChanges = connectionIdChanged || connectorIdChanged || institutionChanged || !connectorCreatedRef.current;
+        // Update if there are changes, regardless of what the changes are
+        if (hasChanges) {
+            if (currentConnectionId) {
+                // Always use reconnect when connectionId is available
+                setConnector(Quiltt.reconnect(connectorId, {
+                    connectionId: currentConnectionId
+                }));
+            } else {
+                // Use connect for new connections without connectionId
+                setConnector(Quiltt.connect(connectorId, {
+                    institution: currentInstitution
+                }));
+            }
+            // Update refs
+            connectorCreatedRef.current = true;
+            prevConnectionIdRef.current = currentConnectionId;
+            prevConnectorIdRef.current = connectorId;
+            prevInstitutionRef.current = currentInstitution;
+        }
+    }, [
+        connectorId,
+        options?.connectionId,
+        options?.institution,
+        status
+    ]);
+    // Internal handlers to track connector state (stable references)
+    const handleOpen = useCallback((metadata)=>{
+        isConnectorOpenRef.current = true;
+        callbacksRef.current?.onOpen?.(metadata);
+    }, []);
+    const handleExit = useCallback((type, metadata)=>{
+        isConnectorOpenRef.current = false;
+        callbacksRef.current?.onExit?.(type, metadata);
+    }, []);
+    // Create stable wrapper functions for callbacks
+    const stableOnEvent = useCallback((type, metadata)=>{
+        callbacksRef.current?.onEvent?.(type, metadata);
+    }, []);
+    const stableOnLoad = useCallback((metadata)=>{
+        callbacksRef.current?.onLoad?.(metadata);
+    }, []);
+    const stableOnExitSuccess = useCallback((metadata)=>{
+        callbacksRef.current?.onExitSuccess?.(metadata);
+    }, []);
+    const stableOnExitAbort = useCallback((metadata)=>{
+        callbacksRef.current?.onExitAbort?.(metadata);
+    }, []);
+    const stableOnExitError = useCallback((metadata)=>{
+        callbacksRef.current?.onExitError?.(metadata);
+    }, []);
+    // Register event handlers (only re-runs when connector changes)
+    useEffect(()=>{
+        if (!connector) return;
+        // Capture which handlers we're registering to ensure proper cleanup
+        const registered = {
+            onEvent: callbacksRef.current?.onEvent ? stableOnEvent : null,
+            onOpen: callbacksRef.current?.onOpen ? handleOpen : null,
+            onLoad: callbacksRef.current?.onLoad ? stableOnLoad : null,
+            onExit: callbacksRef.current?.onExit ? handleExit : null,
+            onExitSuccess: callbacksRef.current?.onExitSuccess ? stableOnExitSuccess : null,
+            onExitAbort: callbacksRef.current?.onExitAbort ? stableOnExitAbort : null,
+            onExitError: callbacksRef.current?.onExitError ? stableOnExitError : null
+        };
+        if (registered.onEvent) connector.onEvent(registered.onEvent);
+        if (registered.onOpen) connector.onOpen(registered.onOpen);
+        if (registered.onLoad) connector.onLoad(registered.onLoad);
+        if (registered.onExit) connector.onExit(registered.onExit);
+        if (registered.onExitSuccess) connector.onExitSuccess(registered.onExitSuccess);
+        if (registered.onExitAbort) connector.onExitAbort(registered.onExitAbort);
+        if (registered.onExitError) connector.onExitError(registered.onExitError);
+        return ()=>{
+            if (registered.onEvent) connector.offEvent(registered.onEvent);
+            if (registered.onOpen) connector.offOpen(registered.onOpen);
+            if (registered.onLoad) connector.offLoad(registered.onLoad);
+            if (registered.onExit) connector.offExit(registered.onExit);
+            if (registered.onExitSuccess) connector.offExitSuccess(registered.onExitSuccess);
+            if (registered.onExitAbort) connector.offExitAbort(registered.onExitAbort);
+            if (registered.onExitError) connector.offExitError(registered.onExitError);
+        };
+    }, [
+        connector,
+        stableOnEvent,
+        handleOpen,
+        stableOnLoad,
+        handleExit,
+        stableOnExitSuccess,
+        stableOnExitAbort,
+        stableOnExitError
+    ]);
+    // This is used to hide any potential race conditions from usage; allowing
+    // interaction before the script may have loaded.
+    useEffect(()=>{
+        if (connector && isOpening) {
+            setIsOpening(false);
+            connector.open();
+        }
+    }, [
+        connector,
+        isOpening
+    ]);
+    // Cleanup effect - runs when the hook is torn down
+    useEffect(()=>{
+        return ()=>{
+            if (isConnectorOpenRef.current) {
+                console.error('[Quiltt] useQuilttConnector: Component unmounted while Connector is still open. ' + 'This may lead to memory leaks or unexpected behavior. ' + 'Ensure the Connector is properly closed before component unmount.');
+            }
+        };
+    }, []);
+    const open = useCallback(()=>{
+        if (connectorId) {
+            setIsOpening(true);
+        } else {
+            throw new Error('Must provide `connectorId` to `open` Quiltt Connector with Method Call');
+        }
+    }, [
+        connectorId
+    ]);
+    return {
+        open
+    };
+};
+
+export { useQuilttConnector as u, version as v };

package/dist/{useQuilttInstitutions-12s-Djd5k9Ae.js → useQuilttInstitutions-12s-PJd2C3BF.js}

@@ -1,8 +1,8 @@
 'use client';
-import { useMemo, useState, useCallback, useEffect } from 'react';
+import { useMemo, useState, useRef, useEffect, useCallback } from 'react';
 import { InstitutionsAPI } from '@quiltt/core';
 import { useDebounce } from 'use-debounce';
-import { v as version } from './useQuilttConnector-12s-BaTUXD56.js';
+import { v as version } from './useQuilttConnector-12s-BJljrsWT.js';
 import { u as useSession } from './useSession-12s-7GOn4sUn.js';
 
 const useQuilttInstitutions = (connectorId, onErrorCallback)=>{
@@ -27,6 +27,11 @@ const useQuilttInstitutions = (connectorId, onErrorCallback)=>{
     const [searchTerm] = useDebounce(searchTermInput, 350);
     const [searchResults, setSearchResults] = useState([]);
     const [isSearching, setIsSearching] = useState(false);
+    // Store callback in ref to maintain stable reference
+    const onErrorCallbackRef = useRef(onErrorCallback);
+    useEffect(()=>{
+        onErrorCallbackRef.current = onErrorCallback;
+    });
     /**
    * Start Search
    * This function is used to initiate a search for institutions based on the provided term with
@@ -43,10 +48,8 @@ const useQuilttInstitutions = (connectorId, onErrorCallback)=>{
     const handleError = useCallback((message)=>{
         const errorMessage = message || 'Unknown error occurred while searching institutions';
         console.error('Quiltt Institutions Search Error:', errorMessage);
-        if (onErrorCallback) onErrorCallback(errorMessage);
-    }, [
-        onErrorCallback
-    ]);
+        if (onErrorCallbackRef.current) onErrorCallbackRef.current(errorMessage);
+    }, []);
     /**
    * Run Search
    * This effect will run when the searchTerm changes and is at least 2 characters long.
@@ -66,7 +69,7 @@ const useQuilttInstitutions = (connectorId, onErrorCallback)=>{
             }
         }).catch((error)=>{
             if (!abortController.signal.aborted) {
-                handleError(error.message);
+                handleError(error?.message);
                 setIsSearching(false);
             }
         });

package/dist/{useQuilttSession-12s-QlPCR8A-.js → useQuilttSession-12s-CwVw-aOM.js}

@@ -1,7 +1,7 @@
 'use client';
 import { useCallback } from 'react';
 import { AuthAPI } from '@quiltt/core';
-import { u as useImportSession, a as useIdentifySession, b as useAuthenticateSession, c as useRevokeSession } from './QuilttAuthProvider-12s-DNnAmo8E.js';
+import { u as useImportSession, a as useIdentifySession, b as useAuthenticateSession, c as useRevokeSession } from './QuilttAuthProvider-12s-D-Wr7LUT.js';
 import { u as useQuilttSettings } from './useQuilttSettings-12s--rCJoNHD.js';
 import { u as useSession } from './useSession-12s-7GOn4sUn.js';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quiltt/react",
-  "version": "4.3.0",
+  "version": "4.3.2",
   "description": "React Components and Hooks for Quiltt Connector",
   "keywords": [
     "quiltt",
@@ -36,7 +36,7 @@
   "dependencies": {
     "@apollo/client": "^3.14.0",
     "use-debounce": "^10.0.4",
-    "@quiltt/core": "4.3.0"
+    "@quiltt/core": "4.3.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.4",

package/src/components/QuilttButton.tsx

@@ -127,10 +127,12 @@ export const QuilttButton = <T extends ElementType = 'button'>({
     // 1. Pre-open validation
     // 2. Preventing opening via event.preventDefault()
     // 3. Setting up state before connector opens
-    if (onClick) onClick(event)
+    onClick?.(event)
 
-    // Then open the Quiltt connector
-    open()
+    // Only open if event wasn't prevented
+    if (!event.defaultPrevented) {
+      open()
+    }
   }
 
   // Generate key for forced remounting if enabled, but respect user-provided key

package/src/hooks/useQuilttConnector.ts

@@ -11,6 +11,7 @@ import { cdnBase } from '@quiltt/core'
 
 import { useQuilttSession } from '@/hooks/useQuilttSession'
 import { useScript } from '@/hooks/useScript'
+import { isDeepEqual } from '@/utils/isDeepEqual'
 import { version } from '@/version'
 
 declare const Quiltt: ConnectorSDK
@@ -33,8 +34,18 @@ export const useQuilttConnector = (
   // Keep track of the previous connectionId to detect changes
   const prevConnectionIdRef = useRef<string | undefined>(options?.connectionId)
   const prevConnectorIdRef = useRef<string | undefined>(connectorId)
+  const prevInstitutionRef = useRef<string | undefined>(options?.institution)
   const connectorCreatedRef = useRef<boolean>(false)
 
+  // Track whether the connector is currently open
+  const isConnectorOpenRef = useRef<boolean>(false)
+
+  // Store callbacks in refs to maintain stable references
+  const callbacksRef = useRef<ConnectorSDKConnectorOptions>(options || {})
+  useEffect(() => {
+    callbacksRef.current = options || {}
+  })
+
   // Set Session
   // biome-ignore lint/correctness/useExhaustiveDependencies: trigger effects when script status changes too
   useEffect(() => {
@@ -51,10 +62,15 @@ export const useQuilttConnector = (
     const currentConnectionId = options?.connectionId
     const currentInstitution = options?.institution
 
-    // Check for changes
+    // Check for changes - use deep equality for institution object
     const connectionIdChanged = prevConnectionIdRef.current !== currentConnectionId
     const connectorIdChanged = prevConnectorIdRef.current !== connectorId
-    const hasChanges = connectionIdChanged || connectorIdChanged || !connectorCreatedRef.current
+    const institutionChanged = !isDeepEqual(prevInstitutionRef.current, currentInstitution)
+    const hasChanges =
+      connectionIdChanged ||
+      connectorIdChanged ||
+      institutionChanged ||
+      !connectorCreatedRef.current
 
     // Update if there are changes, regardless of what the changes are
     if (hasChanges) {
@@ -70,49 +86,83 @@ export const useQuilttConnector = (
       connectorCreatedRef.current = true
       prevConnectionIdRef.current = currentConnectionId
       prevConnectorIdRef.current = connectorId
+      prevInstitutionRef.current = currentInstitution
     }
   }, [connectorId, options?.connectionId, options?.institution, status])
 
-  // Register event handlers
+  // Internal handlers to track connector state (stable references)
+  const handleOpen = useCallback((metadata: any) => {
+    isConnectorOpenRef.current = true
+    callbacksRef.current?.onOpen?.(metadata)
+  }, [])
+
+  const handleExit = useCallback((type: any, metadata: any) => {
+    isConnectorOpenRef.current = false
+    callbacksRef.current?.onExit?.(type, metadata)
+  }, [])
+
+  // Create stable wrapper functions for callbacks
+  const stableOnEvent = useCallback((type: any, metadata: any) => {
+    callbacksRef.current?.onEvent?.(type, metadata)
+  }, [])
+
+  const stableOnLoad = useCallback((metadata: any) => {
+    callbacksRef.current?.onLoad?.(metadata)
+  }, [])
+
+  const stableOnExitSuccess = useCallback((metadata: any) => {
+    callbacksRef.current?.onExitSuccess?.(metadata)
+  }, [])
+
+  const stableOnExitAbort = useCallback((metadata: any) => {
+    callbacksRef.current?.onExitAbort?.(metadata)
+  }, [])
+
+  const stableOnExitError = useCallback((metadata: any) => {
+    callbacksRef.current?.onExitError?.(metadata)
+  }, [])
+
+  // Register event handlers (only re-runs when connector changes)
   useEffect(() => {
     if (!connector) return
 
-    const handlers = {
-      onEvent: options?.onEvent,
-      onOpen: options?.onOpen,
-      onLoad: options?.onLoad,
-      onExit: options?.onExit,
-      onExitSuccess: options?.onExitSuccess,
-      onExitAbort: options?.onExitAbort,
-      onExitError: options?.onExitError,
+    // Capture which handlers we're registering to ensure proper cleanup
+    const registered = {
+      onEvent: callbacksRef.current?.onEvent ? stableOnEvent : null,
+      onOpen: callbacksRef.current?.onOpen ? handleOpen : null,
+      onLoad: callbacksRef.current?.onLoad ? stableOnLoad : null,
+      onExit: callbacksRef.current?.onExit ? handleExit : null,
+      onExitSuccess: callbacksRef.current?.onExitSuccess ? stableOnExitSuccess : null,
+      onExitAbort: callbacksRef.current?.onExitAbort ? stableOnExitAbort : null,
+      onExitError: callbacksRef.current?.onExitError ? stableOnExitError : null,
     }
 
-    if (handlers.onEvent) connector.onEvent(handlers.onEvent)
-    if (handlers.onOpen) connector.onOpen(handlers.onOpen)
-    if (handlers.onLoad) connector.onLoad(handlers.onLoad)
-    if (handlers.onExit) connector.onExit(handlers.onExit)
-    if (handlers.onExitSuccess) connector.onExitSuccess(handlers.onExitSuccess)
-    if (handlers.onExitAbort) connector.onExitAbort(handlers.onExitAbort)
-    if (handlers.onExitError) connector.onExitError(handlers.onExitError)
+    if (registered.onEvent) connector.onEvent(registered.onEvent)
+    if (registered.onOpen) connector.onOpen(registered.onOpen)
+    if (registered.onLoad) connector.onLoad(registered.onLoad)
+    if (registered.onExit) connector.onExit(registered.onExit)
+    if (registered.onExitSuccess) connector.onExitSuccess(registered.onExitSuccess)
+    if (registered.onExitAbort) connector.onExitAbort(registered.onExitAbort)
+    if (registered.onExitError) connector.onExitError(registered.onExitError)
 
     return () => {
-      if (handlers.onEvent) connector.offEvent(handlers.onEvent)
-      if (handlers.onOpen) connector.offOpen(handlers.onOpen)
-      if (handlers.onLoad) connector.offLoad(handlers.onLoad)
-      if (handlers.onExit) connector.offExit(handlers.onExit)
-      if (handlers.onExitSuccess) connector.offExitSuccess(handlers.onExitSuccess)
-      if (handlers.onExitAbort) connector.offExitAbort(handlers.onExitAbort)
-      if (handlers.onExitError) connector.offExitError(handlers.onExitError)
+      if (registered.onEvent) connector.offEvent(registered.onEvent)
+      if (registered.onOpen) connector.offOpen(registered.onOpen)
+      if (registered.onLoad) connector.offLoad(registered.onLoad)
+      if (registered.onExit) connector.offExit(registered.onExit)
+      if (registered.onExitSuccess) connector.offExitSuccess(registered.onExitSuccess)
+      if (registered.onExitAbort) connector.offExitAbort(registered.onExitAbort)
+      if (registered.onExitError) connector.offExitError(registered.onExitError)
     }
   }, [
     connector,
-    options?.onEvent,
-    options?.onOpen,
-    options?.onLoad,
-    options?.onExit,
-    options?.onExitSuccess,
-    options?.onExitAbort,
-    options?.onExitError,
+    stableOnEvent,
+    handleOpen,
+    stableOnLoad,
+    handleExit,
+    stableOnExitSuccess,
+    stableOnExitAbort,
+    stableOnExitError,
   ])
 
   // This is used to hide any potential race conditions from usage; allowing
@@ -124,6 +174,19 @@ export const useQuilttConnector = (
     }
   }, [connector, isOpening])
 
+  // Cleanup effect - runs when the hook is torn down
+  useEffect(() => {
+    return () => {
+      if (isConnectorOpenRef.current) {
+        console.error(
+          '[Quiltt] useQuilttConnector: Component unmounted while Connector is still open. ' +
+            'This may lead to memory leaks or unexpected behavior. ' +
+            'Ensure the Connector is properly closed before component unmount.'
+        )
+      }
+    }
+  }, [])
+
   const open = useCallback(() => {
     if (connectorId) {
       setIsOpening(true)

package/src/hooks/useQuilttInstitutions.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
 import type { ErrorData, InstitutionsData } from '@quiltt/core'
 import { InstitutionsAPI } from '@quiltt/core'
@@ -53,6 +53,12 @@ export const useQuilttInstitutions: UseQuilttInstitutions = (connectorId, onErro
 
   const [isSearching, setIsSearching] = useState(false)
 
+  // Store callback in ref to maintain stable reference
+  const onErrorCallbackRef = useRef(onErrorCallback)
+  useEffect(() => {
+    onErrorCallbackRef.current = onErrorCallback
+  })
+
   /**
    * Start Search
    * This function is used to initiate a search for institutions based on the provided term with
@@ -69,15 +75,12 @@ export const useQuilttInstitutions: UseQuilttInstitutions = (connectorId, onErro
     setSearchTermInput(term)
   }, [])
 
-  const handleError = useCallback(
-    (message: string) => {
-      const errorMessage = message || 'Unknown error occurred while searching institutions'
+  const handleError = useCallback((message: string) => {
+    const errorMessage = message || 'Unknown error occurred while searching institutions'
 
-      console.error('Quiltt Institutions Search Error:', errorMessage)
-      if (onErrorCallback) onErrorCallback(errorMessage)
-    },
-    [onErrorCallback]
-  )
+    console.error('Quiltt Institutions Search Error:', errorMessage)
+    if (onErrorCallbackRef.current) onErrorCallbackRef.current(errorMessage)
+  }, [])
 
   /**
    * Run Search
@@ -104,7 +107,7 @@ export const useQuilttInstitutions: UseQuilttInstitutions = (connectorId, onErro
       })
       .catch((error) => {
         if (!abortController.signal.aborted) {
-          handleError(error.message)
+          handleError(error?.message)
           setIsSearching(false)
         }
       })

package/src/providers/QuilttAuthProvider.tsx

@@ -9,8 +9,10 @@ import { InMemoryCache, QuilttClient } from '@quiltt/core'
 import { useQuilttSession } from '@/hooks'
 import { isDeepEqual } from '@/utils'
 
-type QuilttAuthProviderProps = PropsWithChildren & {
-  /** The Session token obtained from the server */
+export type QuilttAuthProviderProps = PropsWithChildren & {
+  /** A custom QuilttClient instance to use instead of the default */
+  graphqlClient?: QuilttClient
+  /** The Quiltt Session token obtained from the server */
   token?: string
 }
 
@@ -20,33 +22,45 @@ type QuilttAuthProviderProps = PropsWithChildren & {
  * into a loading state and the children are not rendered to prevent race conditions
  * from triggering within the transitionary state.
  */
-export const QuilttAuthProvider: FC<QuilttAuthProviderProps> = ({ token, children }) => {
+export const QuilttAuthProvider: FC<QuilttAuthProviderProps> = ({
+  graphqlClient,
+  token,
+  children,
+}) => {
   const { session, importSession } = useQuilttSession()
   const previousSessionRef = useRef(session)
+  const previousTokenRef = useRef<string | undefined>()
 
-  // @todo: extract into a provider so it can accessed by child components
-  const graphQLClient = useMemo(
+  // Memoize the client to avoid unnecessary re-renders
+  const apolloClient = useMemo(
     () =>
+      graphqlClient ||
       new QuilttClient({
         cache: new InMemoryCache(),
       }),
-    []
+    [graphqlClient]
   )
 
-  // Import passed in token
+  // Import passed in token (only if value has changed)
   useEffect(() => {
-    if (token) importSession(token)
+    if (token && token !== previousTokenRef.current) {
+      importSession(token)
+      previousTokenRef.current = token
+    } else if (!token) {
+      // Reset ref when token becomes undefined to allow re-import of same token later
+      previousTokenRef.current = undefined
+    }
   }, [token, importSession])
 
   // Reset Client Store when session changes (using deep comparison)
   useEffect(() => {
     if (!isDeepEqual(session, previousSessionRef.current)) {
-      graphQLClient.resetStore()
+      apolloClient.resetStore()
       previousSessionRef.current = session
     }
-  }, [session, graphQLClient])
+  }, [session, apolloClient])
 
-  return <ApolloProvider client={graphQLClient}>{children}</ApolloProvider>
+  return <ApolloProvider client={apolloClient}>{children}</ApolloProvider>
 }
 
 export default QuilttAuthProvider

package/src/providers/QuilttProvider.tsx

@@ -1,19 +1,23 @@
-import type { FC, PropsWithChildren } from 'react'
+import type { FC } from 'react'
 
+import type { QuilttAuthProviderProps } from './QuilttAuthProvider'
 import { QuilttAuthProvider } from './QuilttAuthProvider'
+import type { QuilttSettingsProviderProps } from './QuilttSettingsProvider'
 import { QuilttSettingsProvider } from './QuilttSettingsProvider'
 
-type QuilttProviderProps = PropsWithChildren & {
-  /** The client ID for the client-side Auth API */
-  clientId?: string
-  /** The Session token obtained from the server */
-  token?: string
-}
+type QuilttProviderProps = QuilttSettingsProviderProps & QuilttAuthProviderProps
 
-export const QuilttProvider: FC<QuilttProviderProps> = ({ clientId, token, children }) => {
+export const QuilttProvider: FC<QuilttProviderProps> = ({
+  clientId,
+  graphqlClient,
+  token,
+  children,
+}) => {
   return (
     <QuilttSettingsProvider clientId={clientId}>
-      <QuilttAuthProvider token={token}>{children}</QuilttAuthProvider>
+      <QuilttAuthProvider token={token} graphqlClient={graphqlClient}>
+        {children}
+      </QuilttAuthProvider>
     </QuilttSettingsProvider>
   )
 }

package/src/providers/QuilttSettingsProvider.tsx

@@ -5,8 +5,8 @@ import { useState } from 'react'
 
 import { QuilttSettings } from '@/contexts/QuilttSettings'
 
-type QuilttSettingsProviderProps = PropsWithChildren & {
-  /** The Client ID to use for the client-side Auth API */
+export type QuilttSettingsProviderProps = PropsWithChildren & {
+  /** The Client ID to use for the passwordless Auth API */
   clientId?: string
 }
 

package/src/utils/isDeepEqual.ts

@@ -31,8 +31,9 @@ export const isDeepEqual = (obj1: unknown, obj2: unknown): boolean => {
   }
   if (obj1 instanceof Set && obj2 instanceof Set) {
     if (obj1.size !== obj2.size) return false
+    const arr2 = Array.from(obj2)
     for (const item of obj1) {
-      if (!Array.from(obj2).some((value) => isDeepEqual(item, value))) return false
+      if (!arr2.some((value) => isDeepEqual(item, value))) return false
     }
     return true
   }

package/dist/useQuilttConnector-12s-BaTUXD56.js

@@ -1,128 +0,0 @@
-'use client';
-import { useState, useRef, useEffect, useCallback } from 'react';
-import { cdnBase } from '@quiltt/core';
-import { u as useQuilttSession } from './useQuilttSession-12s-QlPCR8A-.js';
-import { u as useScript } from './useScript-12s-JCgaTW9n.js';
-
-var version = "4.3.0";
-
-const useQuilttConnector = (connectorId, options)=>{
-    const status = useScript(`${cdnBase}/v1/connector.js?agent=react-${version}`, {
-        nonce: options?.nonce
-    });
-    // This ensures we're not destructuring `session` before the script has loaded
-    const useQuilttSessionReturn = useQuilttSession();
-    const session = useQuilttSessionReturn?.session || null;
-    const [connector, setConnector] = useState();
-    const [isOpening, setIsOpening] = useState(false);
-    // Keep track of the previous connectionId to detect changes
-    const prevConnectionIdRef = useRef(options?.connectionId);
-    const prevConnectorIdRef = useRef(connectorId);
-    const connectorCreatedRef = useRef(false);
-    // Set Session
-    // biome-ignore lint/correctness/useExhaustiveDependencies: trigger effects when script status changes too
-    useEffect(()=>{
-        if (typeof Quiltt === 'undefined') return;
-        Quiltt.authenticate(session?.token);
-    }, [
-        status,
-        session?.token
-    ]);
-    // Set Connector
-    // biome-ignore lint/correctness/useExhaustiveDependencies: trigger effects when script status changes too
-    useEffect(()=>{
-        if (typeof Quiltt === 'undefined' || !connectorId) return;
-        const currentConnectionId = options?.connectionId;
-        const currentInstitution = options?.institution;
-        // Check for changes
-        const connectionIdChanged = prevConnectionIdRef.current !== currentConnectionId;
-        const connectorIdChanged = prevConnectorIdRef.current !== connectorId;
-        const hasChanges = connectionIdChanged || connectorIdChanged || !connectorCreatedRef.current;
-        // Update if there are changes, regardless of what the changes are
-        if (hasChanges) {
-            if (currentConnectionId) {
-                // Always use reconnect when connectionId is available
-                setConnector(Quiltt.reconnect(connectorId, {
-                    connectionId: currentConnectionId
-                }));
-            } else {
-                // Use connect for new connections without connectionId
-                setConnector(Quiltt.connect(connectorId, {
-                    institution: currentInstitution
-                }));
-            }
-            // Update refs
-            connectorCreatedRef.current = true;
-            prevConnectionIdRef.current = currentConnectionId;
-            prevConnectorIdRef.current = connectorId;
-        }
-    }, [
-        connectorId,
-        options?.connectionId,
-        options?.institution,
-        status
-    ]);
-    // Register event handlers
-    useEffect(()=>{
-        if (!connector) return;
-        const handlers = {
-            onEvent: options?.onEvent,
-            onOpen: options?.onOpen,
-            onLoad: options?.onLoad,
-            onExit: options?.onExit,
-            onExitSuccess: options?.onExitSuccess,
-            onExitAbort: options?.onExitAbort,
-            onExitError: options?.onExitError
-        };
-        if (handlers.onEvent) connector.onEvent(handlers.onEvent);
-        if (handlers.onOpen) connector.onOpen(handlers.onOpen);
-        if (handlers.onLoad) connector.onLoad(handlers.onLoad);
-        if (handlers.onExit) connector.onExit(handlers.onExit);
-        if (handlers.onExitSuccess) connector.onExitSuccess(handlers.onExitSuccess);
-        if (handlers.onExitAbort) connector.onExitAbort(handlers.onExitAbort);
-        if (handlers.onExitError) connector.onExitError(handlers.onExitError);
-        return ()=>{
-            if (handlers.onEvent) connector.offEvent(handlers.onEvent);
-            if (handlers.onOpen) connector.offOpen(handlers.onOpen);
-            if (handlers.onLoad) connector.offLoad(handlers.onLoad);
-            if (handlers.onExit) connector.offExit(handlers.onExit);
-            if (handlers.onExitSuccess) connector.offExitSuccess(handlers.onExitSuccess);
-            if (handlers.onExitAbort) connector.offExitAbort(handlers.onExitAbort);
-            if (handlers.onExitError) connector.offExitError(handlers.onExitError);
-        };
-    }, [
-        connector,
-        options?.onEvent,
-        options?.onOpen,
-        options?.onLoad,
-        options?.onExit,
-        options?.onExitSuccess,
-        options?.onExitAbort,
-        options?.onExitError
-    ]);
-    // This is used to hide any potential race conditions from usage; allowing
-    // interaction before the script may have loaded.
-    useEffect(()=>{
-        if (connector && isOpening) {
-            setIsOpening(false);
-            connector.open();
-        }
-    }, [
-        connector,
-        isOpening
-    ]);
-    const open = useCallback(()=>{
-        if (connectorId) {
-            setIsOpening(true);
-        } else {
-            throw new Error('Must provide `connectorId` to `open` Quiltt Connector with Method Call');
-        }
-    }, [
-        connectorId
-    ]);
-    return {
-        open
-    };
-};
-
-export { useQuilttConnector as u, version as v };