@quiltt/react 5.0.0 → 5.0.2

package/dist/providers/index.d.ts

@@ -0,0 +1,28 @@
+import { FC, PropsWithChildren } from 'react';
+import { QuilttClient } from '@quiltt/core';
+
+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;
+};
+/**
+ * If a token is provided, will validate the token against the api and then import
+ * 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.
+ */
+declare const QuilttAuthProvider: FC<QuilttAuthProviderProps>;
+
+type QuilttSettingsProviderProps = PropsWithChildren & {
+    /** 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, QuilttProvider, QuilttSettingsProvider };
+export type { QuilttAuthProviderProps, QuilttSettingsProviderProps };

package/dist/providers/index.js

@@ -0,0 +1,30 @@
+import { Q as QuilttAuthProvider } from './QuilttAuthProvider-12s-CDgQbarX.js';
+import { jsx } from 'react/jsx-runtime';
+import { useMemo } from 'react';
+import { Q as QuilttProviderRender } from './QuilttProviderRender-12s-DtQtubjL.js';
+import { Q as QuilttSettingsProvider } from './QuilttSettingsProvider-12s-DND2gPQm.js';
+
+const QuilttProvider = ({ clientId, graphqlClient, 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.
+    // Memoize context value to prevent unnecessary re-renders
+    const renderContextValue = useMemo(()=>({
+            isRenderingProvider: true
+        }), []);
+    return /*#__PURE__*/ jsx(QuilttProviderRender.Provider, {
+        value: renderContextValue,
+        children: /*#__PURE__*/ jsx(QuilttSettingsProvider, {
+            clientId: clientId,
+            children: /*#__PURE__*/ jsx(QuilttAuthProvider, {
+                token: token,
+                graphqlClient: graphqlClient,
+                children: children
+            })
+        })
+    });
+};
+
+export { QuilttAuthProvider, QuilttProvider, QuilttSettingsProvider };

package/dist/utils/index.cjs

@@ -0,0 +1,89 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+var core = require('@quiltt/core');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+/**
+ * Performs a deep equality comparison between two values
+ *
+ * This function recursively compares all properties to determine if they are equal.
+ *
+ * @example
+ * ```ts
+ * isDeepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } }) // true
+ * isDeepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 3 } }) // false
+ * ```
+ */ const isDeepEqual = (obj1, obj2)=>{
+    // Handle primitive types and null/undefined
+    if (obj1 === obj2) return true;
+    if (obj1 === null || obj2 === null || typeof obj1 !== 'object' || typeof obj2 !== 'object') return false;
+    // Handle special object types
+    if (obj1 instanceof Date && obj2 instanceof Date) {
+        return obj1.getTime() === obj2.getTime();
+    }
+    if (obj1 instanceof RegExp && obj2 instanceof RegExp) {
+        return obj1.toString() === obj2.toString();
+    }
+    if (obj1 instanceof Map && obj2 instanceof Map) {
+        if (obj1.size !== obj2.size) return false;
+        for (const [key, value] of obj1){
+            if (!obj2.has(key) || !isDeepEqual(value, obj2.get(key))) return false;
+        }
+        return true;
+    }
+    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 (!arr2.some((value)=>isDeepEqual(item, value))) return false;
+        }
+        return true;
+    }
+    // Handle arrays
+    if (Array.isArray(obj1) && Array.isArray(obj2)) {
+        if (obj1.length !== obj2.length) return false;
+        return obj1.every((value, index)=>isDeepEqual(value, obj2[index]));
+    }
+    // If one is array and other isn't, they're not equal
+    if (Array.isArray(obj1) || Array.isArray(obj2)) return false;
+    const keys1 = Object.keys(obj1);
+    const keys2 = Object.keys(obj2);
+    if (keys1.length !== keys2.length) return false;
+    return keys1.every((key)=>{
+        return Object.hasOwn(obj2, key) && isDeepEqual(obj1[key], obj2[key]);
+    });
+};
+
+/**
+ * Gets the React version from the runtime
+ */ const getReactVersion = ()=>{
+    return React__default.default.version || 'unknown';
+};
+/**
+ * Generates platform information string for React web
+ * Format: React/<version>; <browser>/<version>
+ */ const getPlatformInfo = ()=>{
+    const reactVersion = getReactVersion();
+    const browserInfo = core.getBrowserInfo();
+    return `React/${reactVersion}; ${browserInfo}`;
+};
+/**
+ * Generates User-Agent string for React SDK
+ * Format: Quiltt/<sdk-version> (React/<react-version>; <browser>/<version>)
+ */ const getUserAgent = (sdkVersion)=>{
+    const platformInfo = getPlatformInfo();
+    return core.getUserAgent(sdkVersion, platformInfo);
+};
+
+Object.defineProperty(exports, "getBrowserInfo", {
+  enumerable: true,
+  get: function () { return core.getBrowserInfo; }
+});
+exports.getPlatformInfo = getPlatformInfo;
+exports.getReactVersion = getReactVersion;
+exports.getUserAgent = getUserAgent;
+exports.isDeepEqual = isDeepEqual;

package/dist/utils/index.d.ts

@@ -0,0 +1,31 @@
+export { getBrowserInfo } from '@quiltt/core';
+
+/**
+ * Performs a deep equality comparison between two values
+ *
+ * This function recursively compares all properties to determine if they are equal.
+ *
+ * @example
+ * ```ts
+ * isDeepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } }) // true
+ * isDeepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 3 } }) // false
+ * ```
+ */
+declare const isDeepEqual: (obj1: unknown, obj2: unknown) => boolean;
+
+/**
+ * Gets the React version from the runtime
+ */
+declare const getReactVersion: () => string;
+/**
+ * Generates platform information string for React web
+ * Format: React/<version>; <browser>/<version>
+ */
+declare const getPlatformInfo: () => string;
+/**
+ * Generates User-Agent string for React SDK
+ * Format: Quiltt/<sdk-version> (React/<react-version>; <browser>/<version>)
+ */
+declare const getUserAgent: (sdkVersion: string) => string;
+
+export { getPlatformInfo, getReactVersion, getUserAgent, isDeepEqual };

package/dist/utils/index.js

@@ -0,0 +1,77 @@
+import React from 'react';
+import { getBrowserInfo, getUserAgent as getUserAgent$1 } from '@quiltt/core';
+export { getBrowserInfo } from '@quiltt/core';
+
+/**
+ * Performs a deep equality comparison between two values
+ *
+ * This function recursively compares all properties to determine if they are equal.
+ *
+ * @example
+ * ```ts
+ * isDeepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } }) // true
+ * isDeepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 3 } }) // false
+ * ```
+ */ const isDeepEqual = (obj1, obj2)=>{
+    // Handle primitive types and null/undefined
+    if (obj1 === obj2) return true;
+    if (obj1 === null || obj2 === null || typeof obj1 !== 'object' || typeof obj2 !== 'object') return false;
+    // Handle special object types
+    if (obj1 instanceof Date && obj2 instanceof Date) {
+        return obj1.getTime() === obj2.getTime();
+    }
+    if (obj1 instanceof RegExp && obj2 instanceof RegExp) {
+        return obj1.toString() === obj2.toString();
+    }
+    if (obj1 instanceof Map && obj2 instanceof Map) {
+        if (obj1.size !== obj2.size) return false;
+        for (const [key, value] of obj1){
+            if (!obj2.has(key) || !isDeepEqual(value, obj2.get(key))) return false;
+        }
+        return true;
+    }
+    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 (!arr2.some((value)=>isDeepEqual(item, value))) return false;
+        }
+        return true;
+    }
+    // Handle arrays
+    if (Array.isArray(obj1) && Array.isArray(obj2)) {
+        if (obj1.length !== obj2.length) return false;
+        return obj1.every((value, index)=>isDeepEqual(value, obj2[index]));
+    }
+    // If one is array and other isn't, they're not equal
+    if (Array.isArray(obj1) || Array.isArray(obj2)) return false;
+    const keys1 = Object.keys(obj1);
+    const keys2 = Object.keys(obj2);
+    if (keys1.length !== keys2.length) return false;
+    return keys1.every((key)=>{
+        return Object.hasOwn(obj2, key) && isDeepEqual(obj1[key], obj2[key]);
+    });
+};
+
+/**
+ * Gets the React version from the runtime
+ */ const getReactVersion = ()=>{
+    return React.version || 'unknown';
+};
+/**
+ * Generates platform information string for React web
+ * Format: React/<version>; <browser>/<version>
+ */ const getPlatformInfo = ()=>{
+    const reactVersion = getReactVersion();
+    const browserInfo = getBrowserInfo();
+    return `React/${reactVersion}; ${browserInfo}`;
+};
+/**
+ * Generates User-Agent string for React SDK
+ * Format: Quiltt/<sdk-version> (React/<react-version>; <browser>/<version>)
+ */ const getUserAgent = (sdkVersion)=>{
+    const platformInfo = getPlatformInfo();
+    return getUserAgent$1(sdkVersion, platformInfo);
+};
+
+export { getPlatformInfo, getReactVersion, getUserAgent, isDeepEqual };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quiltt/react",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "React Components and Hooks for Quiltt Connector",
   "keywords": [
     "quiltt",
@@ -22,8 +22,34 @@
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "require": "./dist/hooks/index.cjs",
+      "import": "./dist/hooks/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "require": "./dist/components/index.cjs",
+      "import": "./dist/components/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "require": "./dist/providers/index.cjs",
+      "import": "./dist/providers/index.js"
+    },
+    "./contexts": {
+      "types": "./dist/contexts/index.d.ts",
+      "require": "./dist/contexts/index.cjs",
+      "import": "./dist/contexts/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "require": "./dist/utils/index.cjs",
+      "import": "./dist/utils/index.js"
     }
   },
   "types": "./dist/index.d.ts",
@@ -36,12 +62,12 @@
   "dependencies": {
     "@apollo/client": "^4.1.3",
     "use-debounce": "^10.1.0",
-    "@quiltt/core": "5.0.0"
+    "@quiltt/core": "5.0.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.13",
-    "@types/node": "24.10.9",
-    "@types/react": "19.2.10",
+    "@biomejs/biome": "2.3.14",
+    "@types/node": "24.10.10",
+    "@types/react": "19.2.11",
     "@types/react-dom": "19.2.3",
     "bunchee": "6.9.4",
     "react": "19.2.4",

package/src/components/QuilttContainer.tsx

@@ -13,6 +13,7 @@ type QuilttContainerProps<T extends ElementType> = PropsWithChildren<
     as?: T
     connectorId: string
     connectionId?: string // For Reconnect Mode
+    institution?: string // For Connect Mode
 
     /**
      * Forces complete remount when connectionId changes.
@@ -35,6 +36,7 @@ export const QuilttContainer = <T extends ElementType = 'div'>({
   as,
   connectorId,
   connectionId,
+  institution,
   forceRemountOnConnectionChange = false,
   onEvent,
   onLoad,
@@ -88,6 +90,7 @@ export const QuilttContainer = <T extends ElementType = 'div'>({
 
   useQuilttConnector(connectorId, {
     connectionId,
+    institution,
     nonce: props?.nonce, // Pass nonce for script loading if needed
     onEvent,
     onLoad,

package/src/hooks/useSession.ts

@@ -42,13 +42,39 @@ export const useSession = (storageKey = 'session'): [Maybe<QuilttJWT> | undefine
     const expirationMS = session.claims.exp * 1000
     const expire = () => setToken(null)
 
+    const checkExpiration = () => {
+      if (Date.now() >= expirationMS) {
+        expire()
+        return true
+      }
+      return false
+    }
+
     // Clear immediately if already expired
-    if (Date.now() >= expirationMS) {
-      expire()
-    } else {
-      // Set timer to clear session at expiration time
-      sessionTimer.set(expire, expirationMS - Date.now())
-      return () => sessionTimer.clear(expire)
+    if (checkExpiration()) {
+      return
+    }
+
+    // Set timer to clear session at expiration time
+    sessionTimer.set(expire, expirationMS - Date.now())
+
+    // Also check expiration when tab becomes visible (handles idle sessions)
+    const handleVisibilityChange = () => {
+      if (!document.hidden) {
+        checkExpiration()
+      }
+    }
+
+    // Only add listener in browser environment
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', handleVisibilityChange)
+    }
+
+    return () => {
+      sessionTimer.clear(expire)
+      if (typeof document !== 'undefined') {
+        document.removeEventListener('visibilitychange', handleVisibilityChange)
+      }
     }
   }, [session, setToken])
 

package/src/providers/QuilttAuthProvider.tsx

@@ -30,6 +30,12 @@ export const QuilttAuthProvider: FC<QuilttAuthProviderProps> = ({
   const { session, importSession } = useQuilttSession()
   const previousSessionRef = useRef(session)
   const previousTokenRef = useRef<string | undefined>(undefined)
+  const importSessionRef = useRef(importSession)
+
+  // Keep importSession ref up to date
+  useEffect(() => {
+    importSessionRef.current = importSession
+  }, [importSession])
 
   // Memoize the client to avoid unnecessary re-renders
   const apolloClient = useMemo(
@@ -45,13 +51,13 @@ export const QuilttAuthProvider: FC<QuilttAuthProviderProps> = ({
   // Import passed in token (only if value has changed)
   useEffect(() => {
     if (token && token !== previousTokenRef.current) {
-      importSession(token)
+      importSessionRef.current(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])
+  }, [token])
 
   // Reset Client Store when session changes (using deep comparison)
   useEffect(() => {

package/src/providers/QuilttProvider.tsx

@@ -1,4 +1,5 @@
 import type { FC } from 'react'
+import { useMemo } from 'react'
 
 import { QuilttProviderRender } from '@/contexts/QuilttProviderRender'
 
@@ -20,8 +21,11 @@ export const QuilttProvider: FC<QuilttProviderProps> = ({
   // 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.
+  // Memoize context value to prevent unnecessary re-renders
+  const renderContextValue = useMemo(() => ({ isRenderingProvider: true }), [])
+
   return (
-    <QuilttProviderRender.Provider value={{ isRenderingProvider: true }}>
+    <QuilttProviderRender.Provider value={renderContextValue}>
       <QuilttSettingsProvider clientId={clientId}>
         <QuilttAuthProvider token={token} graphqlClient={graphqlClient}>
           {children}

package/src/providers/QuilttSettingsProvider.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 import type { FC, PropsWithChildren } from 'react'
-import { useState } from 'react'
+import { useMemo } from 'react'
 
 import { QuilttSettings } from '@/contexts/QuilttSettings'
 
@@ -11,11 +11,10 @@ export type QuilttSettingsProviderProps = PropsWithChildren & {
 }
 
 export const QuilttSettingsProvider: FC<QuilttSettingsProviderProps> = ({ clientId, children }) => {
-  const [_clientId] = useState(clientId)
+  // Memoize context value to prevent unnecessary re-renders
+  const contextValue = useMemo(() => ({ clientId }), [clientId])
 
-  return (
-    <QuilttSettings.Provider value={{ clientId: _clientId }}>{children}</QuilttSettings.Provider>
-  )
+  return <QuilttSettings.Provider value={contextValue}>{children}</QuilttSettings.Provider>
 }
 
 export default QuilttSettingsProvider