@quiltt/react 4.3.3 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @quiltt/react
 
+## 4.5.0
+
+### Minor Changes
+
+- [#386](https://github.com/quiltt/quiltt-js/pull/386) [`0bf706c`](https://github.com/quiltt/quiltt-js/commit/0bf706ce2ad926304d6eac739ee58971736f913e) Thanks [@zubairaziz](https://github.com/zubairaziz)! - Update platform webview props
+
+### Patch Changes
+
+- [#380](https://github.com/quiltt/quiltt-js/pull/380) [`31cd190`](https://github.com/quiltt/quiltt-js/commit/31cd1902618ebc2314d42dd7aca81b3ab94068ea) Thanks [@sirwolfgang](https://github.com/sirwolfgang)! - Improve useQuilttResolvable error messaging
+
+- Updated dependencies [[`31cd190`](https://github.com/quiltt/quiltt-js/commit/31cd1902618ebc2314d42dd7aca81b3ab94068ea), [`0bf706c`](https://github.com/quiltt/quiltt-js/commit/0bf706ce2ad926304d6eac739ee58971736f913e)]:
+  - @quiltt/core@4.5.0
+
+## 4.4.0
+
+### Minor Changes
+
+- [#378](https://github.com/quiltt/quiltt-js/pull/378) [`0af4e66`](https://github.com/quiltt/quiltt-js/commit/0af4e6622d1542e0c0c02ac7e897e3e4f9219cbd) Thanks [@sirwolfgang](https://github.com/sirwolfgang)! - Add connector institution search and provider migration support.
+
+  ## New APIs
+
+  ### `useQuilttResolvable` Hook
+
+  Check if external provider institution IDs (e.g., Plaid) can be migrated to your connector.
+
+  ```typescript
+  import { useQuilttResolvable } from "@quiltt/react";
+  import { useEffect } from "react";
+
+  function ResolvableConnector({ plaidInstitutionId, children }) {
+    const { checkResolvable, isResolvable, isLoading } =
+      useQuilttResolvable("my-connector-id");
+
+    useEffect(() => {
+      checkResolvable({ plaid: plaidInstitutionId });
+    }, [plaidInstitutionId]);
+
+    if (isLoading) return <div>Checking...</div>;
+    if (!isResolvable) return null;
+
+    return <>{children}</>;
+  }
+
+  // Usage
+  <ResolvableConnector plaidInstitutionId="ins_3">
+    <QuilttButton connectorId="my-connector-id" />
+  </ResolvableConnector>;
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`0af4e66`](https://github.com/quiltt/quiltt-js/commit/0af4e6622d1542e0c0c02ac7e897e3e4f9219cbd)]:
+  - @quiltt/core@4.4.0
+
 ## 4.3.3
 
 ### Patch Changes

package/dist/{QuilttAuthProvider-12s-4hQ7iysR.js → QuilttAuthProvider-12s-BCpwSX-3.js}

@@ -5,9 +5,10 @@ import '@apollo/client/react/hooks/useApolloClient.js';
 import './QuilttSettings-12s-BK-0SQME.js';
 import './useSession-12s-7GOn4sUn.js';
 import 'use-debounce';
+import './QuilttProviderRender-12s-DtQtubjL.js';
 import { jsx } from 'react/jsx-runtime';
 import { ApolloProvider } from '@apollo/client/react/context/ApolloProvider.js';
-import { u as useQuilttSession } from './useQuilttSession-12s-BCq3OL9S.js';
+import { u as useQuilttSession } from './useQuilttSession-12s-D10t5Wfh.js';
 
 const useAuthenticateSession = (auth, setSession)=>{
     const authenticateSession = useCallback(async (payload, callbacks)=>{

package/dist/QuilttProviderRender-12s-DtQtubjL.js

@@ -0,0 +1,6 @@
+'use client';
+import { createContext } from 'react';
+
+const QuilttProviderRender = createContext({});
+
+export { QuilttProviderRender as Q };

package/dist/index.d.ts

@@ -125,6 +125,37 @@ type UseQuilttInstitutions = (connectorId: string, onErrorCallback?: (msg: strin
 };
 declare const useQuilttInstitutions: UseQuilttInstitutions;
 
+/**
+ * Internal hook that detects when a Quiltt SDK component may be rendered
+ * in the same component as QuilttProvider, which is an anti-pattern that
+ * can cause memory context issues and unexpected behavior.
+ *
+ * **Limitation**: Due to React context propagation, this will trigger for ALL
+ * descendants of QuilttProvider, not just direct children. This means it may
+ * produce false positives for valid nested component patterns. However, the
+ * primary use case (same-component rendering) is reliably detected.
+ *
+ * When the flag is set, this hook will emit a console error. This primarily
+ * helps catch the anti-pattern but may also flag valid nested structures.
+ *
+ * @param componentName - The name of the component calling this hook (for error messages)
+ */
+declare const useQuilttRenderGuard: (componentName: string) => void;
+
+type UseQuilttResolvable = (connectorId: string, onErrorCallback?: (msg: string) => void) => {
+    checkResolvable: (providerId: {
+        plaid?: string;
+        mock?: string;
+        mx?: string;
+        finicity?: string;
+        akoya?: string;
+    }) => Promise<boolean | null>;
+    isLoading: boolean;
+    isResolvable: boolean | null;
+    error: string | null;
+};
+declare const useQuilttResolvable: UseQuilttResolvable;
+
 type UseQuilttSession = (environmentId?: string) => {
     session: Maybe<QuilttJWT> | undefined;
     importSession: ImportSession;
@@ -182,5 +213,5 @@ 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, QuilttAuthProviderProps, QuilttSettingsProviderProps, RevokeSession, SetSession, UseQuilttInstitutions, UseQuilttSession };
+export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useAuthenticateSession, useEventListener, useIdentifySession, useImportSession, useIsomorphicLayoutEffect, useQuilttClient, useQuilttConnector, useQuilttInstitutions, useQuilttRenderGuard, useQuilttResolvable, useQuilttSession, useQuilttSettings, useRevokeSession, useSession, useStorage };
+export type { AuthenticateSession, IdentifySession, ImportSession, QuilttAuthProviderProps, QuilttSettingsProviderProps, RevokeSession, SetSession, UseQuilttInstitutions, UseQuilttResolvable, UseQuilttSession };

package/dist/index.js

@@ -1,17 +1,20 @@
 export * from '@quiltt/core';
 import { jsx } from 'react/jsx-runtime';
 import { useRef, useEffect } from 'react';
-import { u as useQuilttConnector } from './useQuilttConnector-12s-DTl-EiqV.js';
-import { i as isDeepEqual, Q as QuilttAuthProvider } from './QuilttAuthProvider-12s-4hQ7iysR.js';
-export { b as useAuthenticateSession, a as useIdentifySession, u as useImportSession, c as useRevokeSession } from './QuilttAuthProvider-12s-4hQ7iysR.js';
+import { u as useQuilttConnector } from './useQuilttConnector-12s-7jon0A8C.js';
+import { u as useQuilttRenderGuard } from './useQuilttRenderGuard-12s-BbUitnF1.js';
+import { i as isDeepEqual, Q as QuilttAuthProvider } from './QuilttAuthProvider-12s-BCpwSX-3.js';
+export { b as useAuthenticateSession, a as useIdentifySession, u as useImportSession, c as useRevokeSession } from './QuilttAuthProvider-12s-BCpwSX-3.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-Cg4OA77c.js';
-export { u as useQuilttSession } from './useQuilttSession-12s-BCq3OL9S.js';
+export { u as useQuilttInstitutions } from './useQuilttInstitutions-12s-Ca5smTKo.js';
+export { u as useQuilttResolvable } from './useQuilttResolvable-12s-CNvWZe0V.js';
+export { u as useQuilttSession } from './useQuilttSession-12s-D10t5Wfh.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';
+import { Q as QuilttProviderRender } from './QuilttProviderRender-12s-DtQtubjL.js';
 import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmOiZ.js';
 
 /**
@@ -21,6 +24,8 @@ import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmO
  * connector instance with the new connection details. If you need to force a
  * complete remount instead, set forceRemountOnConnectionChange to true.
  */ const QuilttButton = ({ as, connectorId, connectionId, institution, forceRemountOnConnectionChange = false, onEvent, onOpen, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, onClick, onHtmlLoad, children, ...props })=>{
+    // Check flag to warn about potential anti-pattern (may produce false positives for valid nested patterns)
+    useQuilttRenderGuard('QuilttButton');
     // Keep track of previous connectionId for change detection
     const prevConnectionIdRef = useRef(connectionId);
     const prevCallbacksRef = useRef({
@@ -103,6 +108,8 @@ import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmO
  * connector instance with the new connection details. If you need to force a
  * complete remount instead, set forceRemountOnConnectionChange to true.
  */ const QuilttContainer = ({ as, connectorId, connectionId, forceRemountOnConnectionChange = false, onEvent, onLoad, onExit, onExitSuccess, onExitAbort, onExitError, children, ...props })=>{
+    // Check flag to warn about potential anti-pattern (may produce false positives for valid nested patterns)
+    useQuilttRenderGuard('QuilttContainer');
     // Keep track of previous connectionId for change detection
     const prevConnectionIdRef = useRef(connectionId);
     const prevCallbacksRef = useRef({
@@ -162,14 +169,24 @@ import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-ZcmFmO
 };
 
 const QuilttProvider = ({ clientId, graphqlClient, token, children })=>{
-    return /*#__PURE__*/ jsx(QuilttSettingsProvider, {
-        clientId: clientId,
-        children: /*#__PURE__*/ jsx(QuilttAuthProvider, {
-            token: token,
-            graphqlClient: graphqlClient,
-            children: children
+    // Set a context flag that SDK components can check to warn about potential anti-patterns.
+    // LIMITATION: This flags ALL descendants due to React context propagation, not just same-component usage.
+    // Will produce false positives for valid patterns like: <QuilttProvider><MyPage /></QuilttProvider>
+    // where MyPage renders SDK components (which is correct usage).
+    // The flag-based approach is simple but imprecise - a proper solution would require render stack tracking.
+    return /*#__PURE__*/ jsx(QuilttProviderRender.Provider, {
+        value: {
+            isRenderingProvider: true
+        },
+        children: /*#__PURE__*/ jsx(QuilttSettingsProvider, {
+            clientId: clientId,
+            children: /*#__PURE__*/ jsx(QuilttAuthProvider, {
+                token: token,
+                graphqlClient: graphqlClient,
+                children: children
+            })
         })
     });
 };
 
-export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useQuilttConnector };
+export { QuilttAuthProvider, QuilttButton, QuilttContainer, QuilttProvider, QuilttSettingsProvider, useQuilttConnector, useQuilttRenderGuard };

package/dist/{useQuilttConnector-12s-DTl-EiqV.js → useQuilttConnector-12s-7jon0A8C.js}

@@ -1,11 +1,11 @@
 'use client';
 import { useState, useRef, useEffect, useCallback } from 'react';
 import { cdnBase } from '@quiltt/core';
-import { u as useQuilttSession } from './useQuilttSession-12s-BCq3OL9S.js';
+import { u as useQuilttSession } from './useQuilttSession-12s-D10t5Wfh.js';
 import { u as useScript } from './useScript-12s-JCgaTW9n.js';
-import { i as isDeepEqual } from './QuilttAuthProvider-12s-4hQ7iysR.js';
+import { i as isDeepEqual } from './QuilttAuthProvider-12s-BCpwSX-3.js';
 
-var version = "4.3.3";
+var version = "4.5.0";
 
 const useQuilttConnector = (connectorId, options)=>{
     const status = useScript(`${cdnBase}/v1/connector.js?agent=react-${version}`, {

package/dist/{useQuilttInstitutions-12s-Cg4OA77c.js → useQuilttInstitutions-12s-Ca5smTKo.js}

@@ -1,8 +1,8 @@
 'use client';
 import { useMemo, useState, useRef, useEffect, useCallback } from 'react';
-import { InstitutionsAPI } from '@quiltt/core';
+import { ConnectorsAPI } from '@quiltt/core';
 import { useDebounce } from 'use-debounce';
-import { v as version } from './useQuilttConnector-12s-DTl-EiqV.js';
+import { v as version } from './useQuilttConnector-12s-7jon0A8C.js';
 import { u as useSession } from './useSession-12s-7GOn4sUn.js';
 
 const useQuilttInstitutions = (connectorId, onErrorCallback)=>{
@@ -18,7 +18,7 @@ const useQuilttInstitutions = (connectorId, onErrorCallback)=>{
         typeof navigator !== 'undefined');
         return isReactNative ? `react-native-${version}` : `react-${version}`;
     }, []);
-    const institutionsAPI = useMemo(()=>new InstitutionsAPI(connectorId, agent), [
+    const connectorsAPI = useMemo(()=>new ConnectorsAPI(connectorId, agent), [
         connectorId,
         agent
     ]);
@@ -58,7 +58,7 @@ const useQuilttInstitutions = (connectorId, onErrorCallback)=>{
             return;
         }
         const abortController = new AbortController();
-        institutionsAPI.search(session?.token, connectorId, searchTerm, abortController.signal).then((response)=>{
+        connectorsAPI.searchInstitutions(session?.token, connectorId, searchTerm, abortController.signal).then((response)=>{
             if (!abortController.signal.aborted) {
                 if (response.status === 200) {
                     setSearchResults(response.data);
@@ -78,7 +78,7 @@ const useQuilttInstitutions = (connectorId, onErrorCallback)=>{
         session?.token,
         connectorId,
         searchTerm,
-        institutionsAPI,
+        connectorsAPI,
         handleError
     ]);
     return {

package/dist/useQuilttRenderGuard-12s-BbUitnF1.js

@@ -0,0 +1,37 @@
+'use client';
+import { useContext, useRef, useEffect } from 'react';
+import { Q as QuilttProviderRender } from './QuilttProviderRender-12s-DtQtubjL.js';
+
+/**
+ * Internal hook that detects when a Quiltt SDK component may be rendered
+ * in the same component as QuilttProvider, which is an anti-pattern that
+ * can cause memory context issues and unexpected behavior.
+ *
+ * **Limitation**: Due to React context propagation, this will trigger for ALL
+ * descendants of QuilttProvider, not just direct children. This means it may
+ * produce false positives for valid nested component patterns. However, the
+ * primary use case (same-component rendering) is reliably detected.
+ *
+ * When the flag is set, this hook will emit a console error. This primarily
+ * helps catch the anti-pattern but may also flag valid nested structures.
+ *
+ * @param componentName - The name of the component calling this hook (for error messages)
+ */ const useQuilttRenderGuard = (componentName)=>{
+    const { isRenderingProvider } = useContext(QuilttProviderRender);
+    const hasWarnedRef = useRef(false);
+    useEffect(()=>{
+        // Only run in development mode and warn once per component instance
+        // Support both Node.js (process.env) and Vite (import.meta.env) environments
+        const isProduction = process.env.NODE_ENV === 'production' || typeof import.meta !== 'undefined' && import.meta.env?.PROD;
+        if (isProduction) return;
+        if (isRenderingProvider && !hasWarnedRef.current) {
+            hasWarnedRef.current = true;
+            console.error(`[Quiltt] ⚠️  POTENTIAL ANTI-PATTERN: ${componentName} may be rendered in the same component as QuilttProvider.\n\n` + `NOTE: This check uses a simple flag and may produce false positives for valid nested patterns.\n` + `If ${componentName} is in a SEPARATE component from QuilttProvider, you can safely ignore this.\n\n` + `The ANTI-PATTERN we're trying to catch:\n` + `  • Rendering Provider and SDK components in the SAME function component\n` + `  • This causes memory context issues because they run at the same React execution layer\n` + `  • React cannot properly manage the context hierarchy in this case\n\n` + `RECOMMENDED PATTERN:\n` + `  • Move QuilttProvider to a parent component or layout\n` + `  • Render ${componentName} in a child component\n\n` + `Example:\n\n` + `  // ✅ CORRECT: Provider in parent, SDK component in child (separate components)\n` + `  function Providers({ children }) {\n` + `    return (\n` + `      <QuilttProvider token={token}>\n` + `        {children}\n` + `      </QuilttProvider>\n` + `    )\n` + `  }\n\n` + `  function MyFeature() {\n` + `    return <${componentName} connectorId="..." />\n` + `  }\n\n` + `  // ❌ ANTI-PATTERN: Both in SAME component\n` + `  function MyFeature() {\n` + `    return (\n` + `      <QuilttProvider token={token}>\n` + `        <${componentName} connectorId="..." />\n` + `      </QuilttProvider>\n` + `    )\n` + `  }\n\n` + `Learn more:\n` + `  • https://github.com/quiltt/quiltt-js/tree/main/packages/react#provider-usage\n` + `  • https://react.dev/reference/react/useContext#my-component-doesnt-see-the-value-from-my-provider`);
+        }
+    }, [
+        isRenderingProvider,
+        componentName
+    ]);
+};
+
+export { useQuilttRenderGuard as u };

package/dist/useQuilttResolvable-12s-CNvWZe0V.js

@@ -0,0 +1,86 @@
+'use client';
+import { useMemo, useState, useRef, useEffect, useCallback } from 'react';
+import { ConnectorsAPI } from '@quiltt/core';
+import { v as version } from './useQuilttConnector-12s-7jon0A8C.js';
+import { u as useSession } from './useSession-12s-7GOn4sUn.js';
+
+const useQuilttResolvable = (connectorId, onErrorCallback)=>{
+    const agent = useMemo(()=>{
+        // Try deprecated navigator.product first (still used in some RN versions)
+        if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+            return `react-native-${version}`;
+        }
+        // Detect React Native by its unique environment characteristics
+        const isReactNative = !!// Has window (unlike Node.js)
+        (typeof window !== 'undefined' && // No document in window (unlike browsers)
+        typeof window.document === 'undefined' && // Has navigator (unlike Node.js)
+        typeof navigator !== 'undefined');
+        return isReactNative ? `react-native-${version}` : `react-${version}`;
+    }, []);
+    const connectorsAPI = useMemo(()=>new ConnectorsAPI(connectorId, agent), [
+        connectorId,
+        agent
+    ]);
+    const [session] = useSession();
+    const [isLoading, setIsLoading] = useState(false);
+    const [isResolvable, setIsResolvable] = useState(null);
+    const [error, setError] = useState(null);
+    // Store callback in ref to maintain stable reference
+    const onErrorCallbackRef = useRef(onErrorCallback);
+    useEffect(()=>{
+        onErrorCallbackRef.current = onErrorCallback;
+    });
+    const handleError = useCallback((message)=>{
+        const errorMessage = message || 'Unknown error occurred while checking resolvability';
+        setError(errorMessage);
+        console.error('Quiltt Connector Resolvable Error:', errorMessage);
+        if (onErrorCallbackRef.current) onErrorCallbackRef.current(errorMessage);
+    }, []);
+    const checkResolvable = useCallback(async (providerId)=>{
+        if (!session?.token) {
+            handleError('Missing session token');
+            return null;
+        }
+        if (!connectorId) {
+            handleError('Missing connector ID');
+            return null;
+        }
+        const hasProviderId = Object.values(providerId).some((id)=>!!id);
+        if (!hasProviderId) {
+            handleError('No provider ID specified');
+            return null;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const response = await connectorsAPI.checkResolvable(session.token, connectorId, providerId);
+            if (response.status === 200) {
+                const result = response.data.resolvable;
+                setIsResolvable(result);
+                return result;
+            }
+            handleError(response.data.message || 'Failed to check resolvability');
+            setIsResolvable(null);
+            return null;
+        } catch (error) {
+            handleError(error?.message);
+            setIsResolvable(null);
+            return null;
+        } finally{
+            setIsLoading(false);
+        }
+    }, [
+        session?.token,
+        connectorId,
+        connectorsAPI,
+        handleError
+    ]);
+    return {
+        checkResolvable,
+        isLoading,
+        isResolvable,
+        error
+    };
+};
+
+export { useQuilttResolvable as u };

package/dist/{useQuilttSession-12s-BCq3OL9S.js → useQuilttSession-12s-D10t5Wfh.js}

@@ -1,14 +1,16 @@
 'use client';
-import { useCallback } from 'react';
+import { useMemo, useCallback } from 'react';
 import { AuthAPI } from '@quiltt/core';
-import { u as useImportSession, a as useIdentifySession, b as useAuthenticateSession, c as useRevokeSession } from './QuilttAuthProvider-12s-4hQ7iysR.js';
+import { u as useImportSession, a as useIdentifySession, b as useAuthenticateSession, c as useRevokeSession } from './QuilttAuthProvider-12s-BCpwSX-3.js';
 import { u as useQuilttSettings } from './useQuilttSettings-12s--rCJoNHD.js';
 import { u as useSession } from './useSession-12s-7GOn4sUn.js';
 
 const useQuilttSession = (environmentId)=>{
     const { clientId } = useQuilttSettings();
     const [session, setSession] = useSession();
-    const auth = new AuthAPI(clientId);
+    const auth = useMemo(()=>new AuthAPI(clientId), [
+        clientId
+    ]);
     const importSession = useImportSession(auth, session, setSession, environmentId);
     const identifySession = useIdentifySession(auth, setSession);
     const authenticateSession = useAuthenticateSession(auth, setSession);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quiltt/react",
-  "version": "4.3.3",
+  "version": "4.5.0",
   "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.3"
+    "@quiltt/core": "4.5.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.4",

package/src/components/QuilttButton.tsx

@@ -4,6 +4,7 @@ import { useEffect, useRef } from 'react'
 import type { ConnectorSDKCallbacks } from '@quiltt/core'
 
 import { useQuilttConnector } from '@/hooks/useQuilttConnector'
+import { useQuilttRenderGuard } from '@/hooks/useQuilttRenderGuard'
 import type { PropsOf } from '@/types'
 import { isDeepEqual } from '@/utils/isDeepEqual'
 
@@ -62,6 +63,9 @@ export const QuilttButton = <T extends ElementType = 'button'>({
   children,
   ...props
 }: QuilttButtonProps<T> & PropsOf<T>) => {
+  // Check flag to warn about potential anti-pattern (may produce false positives for valid nested patterns)
+  useQuilttRenderGuard('QuilttButton')
+
   // Keep track of previous connectionId for change detection
   const prevConnectionIdRef = useRef<string | undefined>(connectionId)
   const prevCallbacksRef = useRef({

package/src/components/QuilttContainer.tsx

@@ -4,6 +4,7 @@ import { useEffect, useRef } from 'react'
 import type { ConnectorSDKCallbacks } from '@quiltt/core'
 
 import { useQuilttConnector } from '@/hooks/useQuilttConnector'
+import { useQuilttRenderGuard } from '@/hooks/useQuilttRenderGuard'
 import type { PropsOf } from '@/types'
 import { isDeepEqual } from '@/utils/isDeepEqual'
 
@@ -44,6 +45,9 @@ export const QuilttContainer = <T extends ElementType = 'div'>({
   children,
   ...props
 }: QuilttContainerProps<T> & PropsOf<T>) => {
+  // Check flag to warn about potential anti-pattern (may produce false positives for valid nested patterns)
+  useQuilttRenderGuard('QuilttContainer')
+
   // Keep track of previous connectionId for change detection
   const prevConnectionIdRef = useRef<string | undefined>(connectionId)
   const prevCallbacksRef = useRef({

package/src/contexts/QuilttProviderRender.ts

@@ -0,0 +1,15 @@
+'use client'
+
+import { createContext } from 'react'
+
+type QuilttProviderRenderContext = {
+  /**
+   * Flag indicating that QuilttProvider is in the ancestor tree.
+   * Due to React context propagation, this is true for ALL descendants,
+   * not just those in the same component as the provider.
+   * Used to detect potential anti-patterns in component composition.
+   */
+  isRenderingProvider?: boolean
+}
+
+export const QuilttProviderRender = createContext<QuilttProviderRenderContext>({})

package/src/hooks/index.ts

@@ -3,6 +3,8 @@ export * from './session'
 export * from './useQuilttClient'
 export * from './useQuilttConnector'
 export * from './useQuilttInstitutions'
+export * from './useQuilttRenderGuard'
+export * from './useQuilttResolvable'
 export * from './useQuilttSession'
 export * from './useQuilttSettings'
 export * from './useSession'

package/src/hooks/useQuilttInstitutions.ts

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
 import type { ErrorData, InstitutionsData } from '@quiltt/core'
-import { InstitutionsAPI } from '@quiltt/core'
+import { ConnectorsAPI } from '@quiltt/core'
 import { useDebounce } from 'use-debounce'
 
 import { version } from '../version'
@@ -41,10 +41,7 @@ export const useQuilttInstitutions: UseQuilttInstitutions = (connectorId, onErro
     return isReactNative ? `react-native-${version}` : `react-${version}`
   }, [])
 
-  const institutionsAPI = useMemo(
-    () => new InstitutionsAPI(connectorId, agent),
-    [connectorId, agent]
-  )
+  const connectorsAPI = useMemo(() => new ConnectorsAPI(connectorId, agent), [connectorId, agent])
   const [session] = useSession()
 
   const [searchTermInput, setSearchTermInput] = useState('')
@@ -93,8 +90,8 @@ export const useQuilttInstitutions: UseQuilttInstitutions = (connectorId, onErro
 
     const abortController = new AbortController()
 
-    institutionsAPI
-      .search(session?.token, connectorId, searchTerm, abortController.signal)
+    connectorsAPI
+      .searchInstitutions(session?.token, connectorId, searchTerm, abortController.signal)
       .then((response) => {
         if (!abortController.signal.aborted) {
           if (response.status === 200) {
@@ -113,7 +110,7 @@ export const useQuilttInstitutions: UseQuilttInstitutions = (connectorId, onErro
       })
 
     return () => abortController.abort()
-  }, [session?.token, connectorId, searchTerm, institutionsAPI, handleError])
+  }, [session?.token, connectorId, searchTerm, connectorsAPI, handleError])
 
   return {
     searchTerm,

package/src/hooks/useQuilttRenderGuard.ts

@@ -0,0 +1,76 @@
+'use client'
+
+import { useContext, useEffect, useRef } from 'react'
+
+import { QuilttProviderRender } from '@/contexts/QuilttProviderRender'
+
+/**
+ * Internal hook that detects when a Quiltt SDK component may be rendered
+ * in the same component as QuilttProvider, which is an anti-pattern that
+ * can cause memory context issues and unexpected behavior.
+ *
+ * **Limitation**: Due to React context propagation, this will trigger for ALL
+ * descendants of QuilttProvider, not just direct children. This means it may
+ * produce false positives for valid nested component patterns. However, the
+ * primary use case (same-component rendering) is reliably detected.
+ *
+ * When the flag is set, this hook will emit a console error. This primarily
+ * helps catch the anti-pattern but may also flag valid nested structures.
+ *
+ * @param componentName - The name of the component calling this hook (for error messages)
+ */
+export const useQuilttRenderGuard = (componentName: string) => {
+  const { isRenderingProvider } = useContext(QuilttProviderRender)
+  const hasWarnedRef = useRef(false)
+
+  useEffect(() => {
+    // Only run in development mode and warn once per component instance
+    // Support both Node.js (process.env) and Vite (import.meta.env) environments
+    const isProduction =
+      process.env.NODE_ENV === 'production' ||
+      (typeof import.meta !== 'undefined' && (import.meta as any).env?.PROD)
+
+    if (isProduction) return
+
+    if (isRenderingProvider && !hasWarnedRef.current) {
+      hasWarnedRef.current = true
+      console.error(
+        `[Quiltt] ⚠️  POTENTIAL ANTI-PATTERN: ${componentName} may be rendered in the same component as QuilttProvider.\n\n` +
+          `NOTE: This check uses a simple flag and may produce false positives for valid nested patterns.\n` +
+          `If ${componentName} is in a SEPARATE component from QuilttProvider, you can safely ignore this.\n\n` +
+          `The ANTI-PATTERN we're trying to catch:\n` +
+          `  • Rendering Provider and SDK components in the SAME function component\n` +
+          `  • This causes memory context issues because they run at the same React execution layer\n` +
+          `  • React cannot properly manage the context hierarchy in this case\n\n` +
+          `RECOMMENDED PATTERN:\n` +
+          `  • Move QuilttProvider to a parent component or layout\n` +
+          `  • Render ${componentName} in a child component\n\n` +
+          `Example:\n\n` +
+          `  // ✅ CORRECT: Provider in parent, SDK component in child (separate components)\n` +
+          `  function Providers({ children }) {\n` +
+          `    return (\n` +
+          `      <QuilttProvider token={token}>\n` +
+          `        {children}\n` +
+          `      </QuilttProvider>\n` +
+          `    )\n` +
+          `  }\n\n` +
+          `  function MyFeature() {\n` +
+          `    return <${componentName} connectorId="..." />\n` +
+          `  }\n\n` +
+          `  // ❌ ANTI-PATTERN: Both in SAME component\n` +
+          `  function MyFeature() {\n` +
+          `    return (\n` +
+          `      <QuilttProvider token={token}>\n` +
+          `        <${componentName} connectorId="..." />\n` +
+          `      </QuilttProvider>\n` +
+          `    )\n` +
+          `  }\n\n` +
+          `Learn more:\n` +
+          `  • https://github.com/quiltt/quiltt-js/tree/main/packages/react#provider-usage\n` +
+          `  • https://react.dev/reference/react/useContext#my-component-doesnt-see-the-value-from-my-provider`
+      )
+    }
+  }, [isRenderingProvider, componentName])
+}
+
+export default useQuilttRenderGuard

package/src/hooks/useQuilttResolvable.ts

@@ -0,0 +1,128 @@
+'use client'
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+
+import type { ErrorData, ResolvableData } from '@quiltt/core'
+import { ConnectorsAPI } from '@quiltt/core'
+
+import { version } from '../version'
+import useSession from './useSession'
+
+export type UseQuilttResolvable = (
+  connectorId: string,
+  onErrorCallback?: (msg: string) => void
+) => {
+  checkResolvable: (providerId: {
+    plaid?: string
+    mock?: string
+    mx?: string
+    finicity?: string
+    akoya?: string
+  }) => Promise<boolean | null>
+  isLoading: boolean
+  isResolvable: boolean | null
+  error: string | null
+}
+
+export const useQuilttResolvable: UseQuilttResolvable = (connectorId, onErrorCallback) => {
+  const agent = useMemo(() => {
+    // Try deprecated navigator.product first (still used in some RN versions)
+    if (typeof navigator !== 'undefined' && navigator.product === 'ReactNative') {
+      return `react-native-${version}`
+    }
+
+    // Detect React Native by its unique environment characteristics
+    const isReactNative = !!(
+      // Has window (unlike Node.js)
+      (
+        typeof window !== 'undefined' &&
+        // No document in window (unlike browsers)
+        typeof window.document === 'undefined' &&
+        // Has navigator (unlike Node.js)
+        typeof navigator !== 'undefined'
+      )
+    )
+
+    return isReactNative ? `react-native-${version}` : `react-${version}`
+  }, [])
+
+  const connectorsAPI = useMemo(() => new ConnectorsAPI(connectorId, agent), [connectorId, agent])
+  const [session] = useSession()
+
+  const [isLoading, setIsLoading] = useState(false)
+  const [isResolvable, setIsResolvable] = useState<boolean | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  // Store callback in ref to maintain stable reference
+  const onErrorCallbackRef = useRef(onErrorCallback)
+  useEffect(() => {
+    onErrorCallbackRef.current = onErrorCallback
+  })
+
+  const handleError = useCallback((message: string) => {
+    const errorMessage = message || 'Unknown error occurred while checking resolvability'
+
+    setError(errorMessage)
+    console.error('Quiltt Connector Resolvable Error:', errorMessage)
+    if (onErrorCallbackRef.current) onErrorCallbackRef.current(errorMessage)
+  }, [])
+
+  const checkResolvable = useCallback(
+    async (providerId: {
+      plaid?: string
+      mock?: string
+      mx?: string
+      finicity?: string
+      akoya?: string
+    }): Promise<boolean | null> => {
+      if (!session?.token) {
+        handleError('Missing session token')
+        return null
+      }
+
+      if (!connectorId) {
+        handleError('Missing connector ID')
+        return null
+      }
+
+      const hasProviderId = Object.values(providerId).some((id) => !!id)
+      if (!hasProviderId) {
+        handleError('No provider ID specified')
+        return null
+      }
+
+      setIsLoading(true)
+      setError(null)
+
+      try {
+        const response = await connectorsAPI.checkResolvable(session.token, connectorId, providerId)
+
+        if (response.status === 200) {
+          const result = (response.data as ResolvableData).resolvable
+          setIsResolvable(result)
+          return result
+        }
+
+        handleError((response.data as ErrorData).message || 'Failed to check resolvability')
+        setIsResolvable(null)
+        return null
+      } catch (error: any) {
+        handleError(error?.message)
+        setIsResolvable(null)
+        return null
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [session?.token, connectorId, connectorsAPI, handleError]
+  )
+
+  return {
+    checkResolvable,
+    isLoading,
+    isResolvable,
+    error,
+  }
+}
+
+export default useQuilttResolvable

package/src/hooks/useQuilttSession.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useCallback } from 'react'
+import { useCallback, useMemo } from 'react'
 
 import type { Maybe, QuilttJWT } from '@quiltt/core'
 import { AuthAPI } from '@quiltt/core'
@@ -28,7 +28,7 @@ export const useQuilttSession: UseQuilttSession = (environmentId) => {
   const { clientId } = useQuilttSettings()
   const [session, setSession] = useSession()
 
-  const auth = new AuthAPI(clientId)
+  const auth = useMemo(() => new AuthAPI(clientId), [clientId])
   const importSession = useImportSession(auth, session, setSession, environmentId)
   const identifySession = useIdentifySession(auth, setSession)
   const authenticateSession = useAuthenticateSession(auth, setSession)

package/src/providers/QuilttProvider.tsx

@@ -1,5 +1,7 @@
 import type { FC } from 'react'
 
+import { QuilttProviderRender } from '@/contexts/QuilttProviderRender'
+
 import type { QuilttAuthProviderProps } from './QuilttAuthProvider'
 import { QuilttAuthProvider } from './QuilttAuthProvider'
 import type { QuilttSettingsProviderProps } from './QuilttSettingsProvider'
@@ -13,12 +15,19 @@ export const QuilttProvider: FC<QuilttProviderProps> = ({
   token,
   children,
 }) => {
+  // Set a context flag that SDK components can check to warn about potential anti-patterns.
+  // LIMITATION: This flags ALL descendants due to React context propagation, not just same-component usage.
+  // Will produce false positives for valid patterns like: <QuilttProvider><MyPage /></QuilttProvider>
+  // where MyPage renders SDK components (which is correct usage).
+  // The flag-based approach is simple but imprecise - a proper solution would require render stack tracking.
   return (
-    <QuilttSettingsProvider clientId={clientId}>
-      <QuilttAuthProvider token={token} graphqlClient={graphqlClient}>
-        {children}
-      </QuilttAuthProvider>
-    </QuilttSettingsProvider>
+    <QuilttProviderRender.Provider value={{ isRenderingProvider: true }}>
+      <QuilttSettingsProvider clientId={clientId}>
+        <QuilttAuthProvider token={token} graphqlClient={graphqlClient}>
+          {children}
+        </QuilttAuthProvider>
+      </QuilttSettingsProvider>
+    </QuilttProviderRender.Provider>
   )
 }