@quiltt/react 4.5.1 → 5.0.1

package/dist/hooks/useQuilttSession-12s-DQFfjmob.js

@@ -0,0 +1,135 @@
+'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 within the expected environment?
+        if (environmentId && jwt.claims.eid !== environmentId) 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 { useAuthenticateSession as a, useIdentifySession as b, useImportSession as c, useRevokeSession as d, useQuilttSession as u };

package/dist/hooks/useQuilttSettings-12s--rCJoNHD.js

@@ -0,0 +1,10 @@
+'use client';
+import { useContext } from 'react';
+import { Q as QuilttSettings } from './QuilttSettings-12s-BK-0SQME.js';
+
+const useQuilttSettings = ()=>{
+    const settings = useContext(QuilttSettings);
+    return settings;
+};
+
+export { useQuilttSettings as u };

package/dist/hooks/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/hooks/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/hooks/useScript-12s-JCgaTW9n.js

@@ -0,0 +1,92 @@
+'use client';
+import { useState, useEffect } from '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] = useState(()=>{
+        if (!src || options?.shouldPreventLoad) {
+            return 'idle';
+        }
+        if (typeof window === 'undefined') {
+            // SSR Handling - always return 'loading'
+            return 'loading';
+        }
+        return cachedScriptStatuses[src] ?? 'loading';
+    });
+    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;
+}
+
+export { useScript as u };

package/dist/hooks/useSession-12s-BNPsfKY-.js

@@ -0,0 +1,90 @@
+'use client';
+import { useMemo, useEffect, useCallback } from 'react';
+import { Timeoutable, JsonWebTokenParse } from '@quiltt/core';
+import { u as useStorage } from './useStorage-12s-CpG6X57D.js';
+
+// Initialize JWT parser with our specific claims type
+const parse = JsonWebTokenParse;
+// Global timer to manage token expiration across all hook instances
+const sessionTimer = new Timeoutable();
+/**
+ * Custom hook to manage JWT session state with automatic expiration handling.
+ * Provides global singleton access to the session across components and windows.
+ *
+ * TODO: Support Rotation before Expiry
+ *
+ * Handles two types of data flow:
+ * 1. Bottom-up (Login): Token passed through setSession callback
+ * 2. Top-down (Refresh): State reinitialized on page reload
+ *
+ * @param storageKey - Key used for storing session in useStorage (defaults to 'session')
+ * @returns [session, setSession] - Current session state and setter function
+ */ const useSession = (storageKey = 'session')=>{
+    const [token, setToken] = useStorage(storageKey);
+    // Parse token into session data, updates when token changes
+    const session = useMemo(()=>parse(token), [
+        token
+    ]);
+    // Handle session expiration
+    useEffect(()=>{
+        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 (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
+    ]);
+    /**
+   * Validates and updates the session token.
+   * - Handles both direct values and updater functions
+   * - Validates new tokens before setting them
+   * - Prevents unnecessary updates for same token value
+   * - Allows clearing the session with null/undefined
+   */ const setSession = useCallback((nextState)=>{
+        const newState = nextState instanceof Function ? nextState(token) : nextState;
+        // Only update if:
+        // 1. The token has actually changed AND
+        // 2. Either the new state is falsy (clearing session) OR it's a valid token
+        if (token !== newState && (!newState || parse(newState))) {
+            setToken(newState);
+        }
+    }, [
+        token,
+        setToken
+    ]);
+    return [
+        session,
+        setSession
+    ];
+};
+
+export { useSession as u };

package/dist/hooks/useSession-12s-BNotXj5T.cjs

@@ -0,0 +1,90 @@
+'use client';
+var react = require('react');
+var core = require('@quiltt/core');
+var useStorage12s = require('./useStorage-12s-D7nllsrI.cjs');
+
+// Initialize JWT parser with our specific claims type
+const parse = core.JsonWebTokenParse;
+// Global timer to manage token expiration across all hook instances
+const sessionTimer = new core.Timeoutable();
+/**
+ * Custom hook to manage JWT session state with automatic expiration handling.
+ * Provides global singleton access to the session across components and windows.
+ *
+ * TODO: Support Rotation before Expiry
+ *
+ * Handles two types of data flow:
+ * 1. Bottom-up (Login): Token passed through setSession callback
+ * 2. Top-down (Refresh): State reinitialized on page reload
+ *
+ * @param storageKey - Key used for storing session in useStorage (defaults to 'session')
+ * @returns [session, setSession] - Current session state and setter function
+ */ const useSession = (storageKey = 'session')=>{
+    const [token, setToken] = useStorage12s.useStorage(storageKey);
+    // Parse token into session data, updates when token changes
+    const session = react.useMemo(()=>parse(token), [
+        token
+    ]);
+    // Handle session expiration
+    react.useEffect(()=>{
+        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 (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
+    ]);
+    /**
+   * Validates and updates the session token.
+   * - Handles both direct values and updater functions
+   * - Validates new tokens before setting them
+   * - Prevents unnecessary updates for same token value
+   * - Allows clearing the session with null/undefined
+   */ const setSession = react.useCallback((nextState)=>{
+        const newState = nextState instanceof Function ? nextState(token) : nextState;
+        // Only update if:
+        // 1. The token has actually changed AND
+        // 2. Either the new state is falsy (clearing session) OR it's a valid token
+        if (token !== newState && (!newState || parse(newState))) {
+            setToken(newState);
+        }
+    }, [
+        token,
+        setToken
+    ]);
+    return [
+        session,
+        setSession
+    ];
+};
+
+exports.useSession = useSession;

package/dist/hooks/useStorage-12s-CpG6X57D.js

@@ -0,0 +1,61 @@
+'use client';
+import { useCallback, useState, useEffect } from 'react';
+import { GlobalStorage } from '@quiltt/core';
+
+/**
+ * Attempt to persist state with local storage, so it remains after refresh and
+ * across open documents. Falls back to in memory storage when localStorage is
+ * unavailable.
+ *
+ * This hook is used in the same way as useState except that you must pass the
+ * storage key in the 1st parameter. If the window object is not present (as in SSR),
+ * useStorage() will return the default nextState.
+ *
+ * Expect values to remain in sync
+ *   Across Hooks
+ *   Across Reloads
+ *   Across Windows (Documents)
+ *
+ * @param key
+ * @param initialState
+ * @returns {Array} [storage, setStorage]
+ */ const useStorage = (key, initialState)=>{
+    const getStorage = useCallback(()=>{
+        const state = GlobalStorage.get(key);
+        if (state !== undefined) {
+            return state;
+        }
+        return initialState;
+    }, [
+        key,
+        initialState
+    ]);
+    const [hookState, setHookState] = useState(getStorage());
+    const setStorage = useCallback((nextState)=>{
+        const newState = nextState instanceof Function ? nextState(hookState) : nextState;
+        if (hookState !== newState) {
+            GlobalStorage.set(key, newState);
+            // Immediately update hook state as well
+            setHookState(newState);
+        }
+    }, [
+        key,
+        hookState
+    ]);
+    useEffect(()=>{
+        // Subscribe to storage changes from other sources (e.g., other hook instances, browser tabs)
+        const handleStorageChange = (newValue)=>{
+            setHookState(newValue);
+        };
+        GlobalStorage.subscribe(key, handleStorageChange);
+        return ()=>GlobalStorage.unsubscribe(key, handleStorageChange);
+    }, [
+        key
+    ]);
+    return [
+        hookState,
+        setStorage
+    ];
+};
+
+export { useStorage as u };

package/dist/hooks/useStorage-12s-D7nllsrI.cjs

@@ -0,0 +1,61 @@
+'use client';
+var react = require('react');
+var core = require('@quiltt/core');
+
+/**
+ * Attempt to persist state with local storage, so it remains after refresh and
+ * across open documents. Falls back to in memory storage when localStorage is
+ * unavailable.
+ *
+ * This hook is used in the same way as useState except that you must pass the
+ * storage key in the 1st parameter. If the window object is not present (as in SSR),
+ * useStorage() will return the default nextState.
+ *
+ * Expect values to remain in sync
+ *   Across Hooks
+ *   Across Reloads
+ *   Across Windows (Documents)
+ *
+ * @param key
+ * @param initialState
+ * @returns {Array} [storage, setStorage]
+ */ const useStorage = (key, initialState)=>{
+    const getStorage = react.useCallback(()=>{
+        const state = core.GlobalStorage.get(key);
+        if (state !== undefined) {
+            return state;
+        }
+        return initialState;
+    }, [
+        key,
+        initialState
+    ]);
+    const [hookState, setHookState] = react.useState(getStorage());
+    const setStorage = react.useCallback((nextState)=>{
+        const newState = nextState instanceof Function ? nextState(hookState) : nextState;
+        if (hookState !== newState) {
+            core.GlobalStorage.set(key, newState);
+            // Immediately update hook state as well
+            setHookState(newState);
+        }
+    }, [
+        key,
+        hookState
+    ]);
+    react.useEffect(()=>{
+        // Subscribe to storage changes from other sources (e.g., other hook instances, browser tabs)
+        const handleStorageChange = (newValue)=>{
+            setHookState(newValue);
+        };
+        core.GlobalStorage.subscribe(key, handleStorageChange);
+        return ()=>core.GlobalStorage.unsubscribe(key, handleStorageChange);
+    }, [
+        key
+    ]);
+    return [
+        hookState,
+        setStorage
+    ];
+};
+
+exports.useStorage = useStorage;