@quiltt/react 5.0.0 → 5.0.2

package/dist/components/useQuilttConnector-12s-zU4NFJ-H.cjs

@@ -0,0 +1,174 @@
+'use client';
+var react = require('react');
+var core = require('@quiltt/core');
+var useQuilttSession12s = require('./useQuilttSession-12s-BjyJL1qZ.cjs');
+var useScript12s = require('./useScript-12s-CMIDUHrx.cjs');
+var index_cjs = require('../utils/index.cjs');
+
+var version = "5.0.2";
+
+const useQuilttConnector = (connectorId, options)=>{
+    const userAgent = index_cjs.getUserAgent(version);
+    const status = useScript12s.useScript(`${core.cdnBase}/v1/connector.js?agent=${encodeURIComponent(userAgent)}`, {
+        nonce: options?.nonce
+    });
+    // This ensures we're not destructuring `session` before the script has loaded
+    const useQuilttSessionReturn = useQuilttSession12s.useQuilttSession();
+    const session = useQuilttSessionReturn?.session || null;
+    const [connector, setConnector] = react.useState();
+    const [isOpening, setIsOpening] = react.useState(false);
+    // Keep track of the previous connectionId to detect changes
+    const prevConnectionIdRef = react.useRef(options?.connectionId);
+    const prevConnectorIdRef = react.useRef(connectorId);
+    const prevInstitutionRef = react.useRef(options?.institution);
+    const connectorCreatedRef = react.useRef(false);
+    // Track whether the connector is currently open
+    const isConnectorOpenRef = react.useRef(false);
+    // Store callbacks in refs to maintain stable references
+    const callbacksRef = react.useRef(options || {});
+    react.useEffect(()=>{
+        callbacksRef.current = options || {};
+    });
+    // Set Session
+    // biome-ignore lint/correctness/useExhaustiveDependencies: trigger effects when script status changes too
+    react.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
+    react.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 = !index_cjs.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 = react.useCallback((metadata)=>{
+        isConnectorOpenRef.current = true;
+        callbacksRef.current?.onOpen?.(metadata);
+    }, []);
+    const handleExit = react.useCallback((type, metadata)=>{
+        isConnectorOpenRef.current = false;
+        callbacksRef.current?.onExit?.(type, metadata);
+    }, []);
+    // Create stable wrapper functions for callbacks
+    const stableOnEvent = react.useCallback((type, metadata)=>{
+        callbacksRef.current?.onEvent?.(type, metadata);
+    }, []);
+    const stableOnLoad = react.useCallback((metadata)=>{
+        callbacksRef.current?.onLoad?.(metadata);
+    }, []);
+    const stableOnExitSuccess = react.useCallback((metadata)=>{
+        callbacksRef.current?.onExitSuccess?.(metadata);
+    }, []);
+    const stableOnExitAbort = react.useCallback((metadata)=>{
+        callbacksRef.current?.onExitAbort?.(metadata);
+    }, []);
+    const stableOnExitError = react.useCallback((metadata)=>{
+        callbacksRef.current?.onExitError?.(metadata);
+    }, []);
+    // Register event handlers (only re-runs when connector changes)
+    react.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.
+    react.useEffect(()=>{
+        if (connector && isOpening) {
+            setIsOpening(false);
+            connector.open();
+        }
+    }, [
+        connector,
+        isOpening
+    ]);
+    // Cleanup effect - runs when the hook is torn down
+    react.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 = react.useCallback(()=>{
+        if (connectorId) {
+            setIsOpening(true);
+        } else {
+            throw new Error('Must provide `connectorId` to `open` Quiltt Connector with Method Call');
+        }
+    }, [
+        connectorId
+    ]);
+    return {
+        open
+    };
+};
+
+exports.useQuilttConnector = useQuilttConnector;

package/dist/components/useQuilttRenderGuard-12s-D9WbRzZO.cjs

@@ -0,0 +1,36 @@
+'use client';
+var react = require('react');
+var QuilttProviderRender12s = require('./QuilttProviderRender-12s-pvnc98Lj.cjs');
+
+/**
+ * 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 } = react.useContext(QuilttProviderRender12s.QuilttProviderRender);
+    const hasWarnedRef = react.useRef(false);
+    react.useEffect(()=>{
+        // Only run in development mode and warn once per component instance
+        const isProduction = process.env.NODE_ENV === 'production';
+        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
+    ]);
+};
+
+exports.useQuilttRenderGuard = useQuilttRenderGuard;

package/dist/components/useQuilttSession-12s-BjyJL1qZ.cjs

@@ -0,0 +1,133 @@
+'use client';
+var react = require('react');
+var core = require('@quiltt/core');
+var useQuilttSettings12s = require('./useQuilttSettings-12s-aDLXY6z3.cjs');
+var useSession12s = require('./useSession-12s-BNotXj5T.cjs');
+
+const useAuthenticateSession = (auth, setSession)=>{
+    const authenticateSession = react.useCallback(async (payload, callbacks)=>{
+        const response = await auth.authenticate(payload);
+        switch(response.status){
+            case 201:
+                setSession(response.data.token);
+                if (callbacks.onSuccess) return callbacks.onSuccess();
+                break;
+            case 401:
+                if (callbacks.onFailure) return callbacks.onFailure();
+                break;
+            case 422:
+                if (callbacks.onError) return callbacks.onError(response.data);
+                break;
+            default:
+                throw new Error(`AuthAPI.authenticate: Unexpected response status ${response.status}`);
+        }
+    }, [
+        auth,
+        setSession
+    ]);
+    return authenticateSession;
+};
+
+const useIdentifySession = (auth, setSession)=>{
+    const identifySession = react.useCallback(async (payload, callbacks)=>{
+        const response = await auth.identify(payload);
+        switch(response.status){
+            case 201:
+                setSession(response.data.token);
+                if (callbacks.onSuccess) return callbacks.onSuccess();
+                break;
+            case 202:
+                if (callbacks.onChallenged) return callbacks.onChallenged();
+                break;
+            case 403:
+                if (callbacks.onForbidden) return callbacks.onForbidden();
+                break;
+            case 422:
+                if (callbacks.onError) return callbacks.onError(response.data);
+                break;
+            default:
+                throw new Error(`AuthAPI.identify: Unexpected response status ${response.status}`);
+        }
+    }, [
+        auth,
+        setSession
+    ]);
+    return identifySession;
+};
+
+/**
+ * Optionally Accepts environmentId to validate session is from with your desired environment
+ */ const useImportSession = (auth, session, setSession, environmentId)=>{
+    const importSession = react.useCallback(async (token)=>{
+        // Is there a token?
+        if (!token) return !!session;
+        // Is this token already imported?
+        if (session && session.token === token) return true;
+        const jwt = core.JsonWebTokenParse(token);
+        // Is this token a valid JWT?
+        if (!jwt) return false;
+        // Is this token active?
+        const response = await auth.ping(token);
+        switch(response.status){
+            case 200:
+                setSession(token);
+                return true;
+            case 401:
+                return false;
+            default:
+                throw new Error(`AuthAPI.ping: Unexpected response status ${response.status}`);
+        }
+    }, [
+        auth,
+        session,
+        setSession,
+        environmentId
+    ]);
+    return importSession;
+};
+
+const useRevokeSession = (auth, session, setSession)=>{
+    const revokeSession = react.useCallback(async ()=>{
+        if (!session) return;
+        await auth.revoke(session.token);
+        setSession(null);
+    }, [
+        auth,
+        session,
+        setSession
+    ]);
+    return revokeSession;
+};
+
+const useQuilttSession = (environmentId)=>{
+    const { clientId } = useQuilttSettings12s.useQuilttSettings();
+    const [session, setSession] = useSession12s.useSession();
+    const auth = react.useMemo(()=>new core.AuthAPI(clientId), [
+        clientId
+    ]);
+    const importSession = useImportSession(auth, session, setSession, environmentId);
+    const identifySession = useIdentifySession(auth, setSession);
+    const authenticateSession = useAuthenticateSession(auth, setSession);
+    const revokeSession = useRevokeSession(auth, session, setSession);
+    /**
+   * Forget current session.
+   * @param token specific token to forget, to help guard against async processes clearing the wrong session
+   */ const forgetSession = react.useCallback(async (token)=>{
+        if (!token || session && token && token === session.token) {
+            setSession(null);
+        }
+    }, [
+        session,
+        setSession
+    ]);
+    return {
+        session,
+        importSession,
+        identifySession,
+        authenticateSession,
+        revokeSession,
+        forgetSession
+    };
+};
+
+exports.useQuilttSession = useQuilttSession;

package/dist/components/useQuilttSession-12s-VOH0S5zh.js

@@ -0,0 +1,133 @@
+'use client';
+import { useCallback, useMemo } from 'react';
+import { JsonWebTokenParse, AuthAPI } from '@quiltt/core';
+import { u as useQuilttSettings } from './useQuilttSettings-12s--rCJoNHD.js';
+import { u as useSession } from './useSession-12s-BNPsfKY-.js';
+
+const useAuthenticateSession = (auth, setSession)=>{
+    const authenticateSession = useCallback(async (payload, callbacks)=>{
+        const response = await auth.authenticate(payload);
+        switch(response.status){
+            case 201:
+                setSession(response.data.token);
+                if (callbacks.onSuccess) return callbacks.onSuccess();
+                break;
+            case 401:
+                if (callbacks.onFailure) return callbacks.onFailure();
+                break;
+            case 422:
+                if (callbacks.onError) return callbacks.onError(response.data);
+                break;
+            default:
+                throw new Error(`AuthAPI.authenticate: Unexpected response status ${response.status}`);
+        }
+    }, [
+        auth,
+        setSession
+    ]);
+    return authenticateSession;
+};
+
+const useIdentifySession = (auth, setSession)=>{
+    const identifySession = useCallback(async (payload, callbacks)=>{
+        const response = await auth.identify(payload);
+        switch(response.status){
+            case 201:
+                setSession(response.data.token);
+                if (callbacks.onSuccess) return callbacks.onSuccess();
+                break;
+            case 202:
+                if (callbacks.onChallenged) return callbacks.onChallenged();
+                break;
+            case 403:
+                if (callbacks.onForbidden) return callbacks.onForbidden();
+                break;
+            case 422:
+                if (callbacks.onError) return callbacks.onError(response.data);
+                break;
+            default:
+                throw new Error(`AuthAPI.identify: Unexpected response status ${response.status}`);
+        }
+    }, [
+        auth,
+        setSession
+    ]);
+    return identifySession;
+};
+
+/**
+ * Optionally Accepts environmentId to validate session is from with your desired environment
+ */ const useImportSession = (auth, session, setSession, environmentId)=>{
+    const importSession = useCallback(async (token)=>{
+        // Is there a token?
+        if (!token) return !!session;
+        // Is this token already imported?
+        if (session && session.token === token) return true;
+        const jwt = JsonWebTokenParse(token);
+        // Is this token a valid JWT?
+        if (!jwt) return false;
+        // Is this token active?
+        const response = await auth.ping(token);
+        switch(response.status){
+            case 200:
+                setSession(token);
+                return true;
+            case 401:
+                return false;
+            default:
+                throw new Error(`AuthAPI.ping: Unexpected response status ${response.status}`);
+        }
+    }, [
+        auth,
+        session,
+        setSession,
+        environmentId
+    ]);
+    return importSession;
+};
+
+const useRevokeSession = (auth, session, setSession)=>{
+    const revokeSession = useCallback(async ()=>{
+        if (!session) return;
+        await auth.revoke(session.token);
+        setSession(null);
+    }, [
+        auth,
+        session,
+        setSession
+    ]);
+    return revokeSession;
+};
+
+const useQuilttSession = (environmentId)=>{
+    const { clientId } = useQuilttSettings();
+    const [session, setSession] = useSession();
+    const auth = useMemo(()=>new AuthAPI(clientId), [
+        clientId
+    ]);
+    const importSession = useImportSession(auth, session, setSession, environmentId);
+    const identifySession = useIdentifySession(auth, setSession);
+    const authenticateSession = useAuthenticateSession(auth, setSession);
+    const revokeSession = useRevokeSession(auth, session, setSession);
+    /**
+   * Forget current session.
+   * @param token specific token to forget, to help guard against async processes clearing the wrong session
+   */ const forgetSession = useCallback(async (token)=>{
+        if (!token || session && token && token === session.token) {
+            setSession(null);
+        }
+    }, [
+        session,
+        setSession
+    ]);
+    return {
+        session,
+        importSession,
+        identifySession,
+        authenticateSession,
+        revokeSession,
+        forgetSession
+    };
+};
+
+export { useQuilttSession as u };

package/dist/components/useQuilttSettings-12s-aDLXY6z3.cjs

@@ -0,0 +1,10 @@
+'use client';
+var react = require('react');
+var QuilttSettings12s = require('./QuilttSettings-12s-cLPT_GLC.cjs');
+
+const useQuilttSettings = ()=>{
+    const settings = react.useContext(QuilttSettings12s.QuilttSettings);
+    return settings;
+};
+
+exports.useQuilttSettings = useQuilttSettings;

package/dist/components/useScript-12s-CMIDUHrx.cjs

@@ -0,0 +1,92 @@
+'use client';
+var react = require('react');
+
+// Cached script statuses
+const cachedScriptStatuses = {};
+function getScriptNode(src) {
+    const node = document.querySelector(`script[src="${src}"]`);
+    const status = node?.getAttribute('data-status');
+    return {
+        node,
+        status
+    };
+}
+// @see https://usehooks-ts.com/react-hook/use-script
+function useScript(src, options) {
+    const [status, setStatus] = react.useState(()=>{
+        if (!src || options?.shouldPreventLoad) {
+            return 'idle';
+        }
+        if (typeof window === 'undefined') {
+            // SSR Handling - always return 'loading'
+            return 'loading';
+        }
+        return cachedScriptStatuses[src] ?? 'loading';
+    });
+    react.useEffect(()=>{
+        if (!src || options?.shouldPreventLoad) {
+            return;
+        }
+        const cachedScriptStatus = cachedScriptStatuses[src];
+        if (cachedScriptStatus === 'ready' || cachedScriptStatus === 'error') {
+            // If the script is already cached, set its status immediately
+            setStatus(cachedScriptStatus);
+            return;
+        }
+        // Fetch existing script element by src
+        // It may have been added by another instance of this hook
+        const script = getScriptNode(src);
+        let scriptNode = script.node;
+        if (!scriptNode) {
+            // Create script element and add it to document body
+            scriptNode = document.createElement('script');
+            scriptNode.src = src;
+            scriptNode.async = true;
+            if (options?.nonce && options.nonce.trim() !== '') {
+                scriptNode.nonce = options.nonce;
+            }
+            scriptNode.setAttribute('data-status', 'loading');
+            document.body.appendChild(scriptNode);
+            // Store status in attribute on script
+            // This can be read by other instances of this hook
+            const setAttributeFromEvent = (event)=>{
+                const scriptStatus = event.type === 'load' ? 'ready' : 'error';
+                scriptNode?.setAttribute('data-status', scriptStatus);
+            };
+            scriptNode.addEventListener('load', setAttributeFromEvent);
+            scriptNode.addEventListener('error', setAttributeFromEvent);
+        } else {
+            // Grab existing script status from attribute and set to state.
+            setStatus(script.status ?? cachedScriptStatus ?? 'loading');
+        }
+        // Script event handler to update status in state
+        // Note: Even if the script already exists we still need to add
+        // event handlers to update the state for *this* hook instance.
+        const setStateFromEvent = (event)=>{
+            const newStatus = event.type === 'load' ? 'ready' : 'error';
+            setStatus(newStatus);
+            cachedScriptStatuses[src] = newStatus;
+        };
+        // Add event listeners
+        scriptNode.addEventListener('load', setStateFromEvent);
+        scriptNode.addEventListener('error', setStateFromEvent);
+        // Remove event listeners on cleanup
+        return ()=>{
+            if (scriptNode) {
+                scriptNode.removeEventListener('load', setStateFromEvent);
+                scriptNode.removeEventListener('error', setStateFromEvent);
+            }
+            if (scriptNode && options?.removeOnUnmount) {
+                scriptNode.remove();
+            }
+        };
+    }, [
+        src,
+        options?.shouldPreventLoad,
+        options?.nonce,
+        options?.removeOnUnmount
+    ]);
+    return status;
+}
+
+exports.useScript = useScript;

package/dist/{useSession-12s-BlrWOArd.js → components/useSession-12s-BNPsfKY-.js}

@@ -30,14 +30,35 @@ const sessionTimer = new Timeoutable();
         if (!session) return;
         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