@tonycodes/auth-react 1.0.1 → 1.1.1

package/dist/useProviders.js

@@ -1,47 +1,103 @@
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { useAuthConfig } from './useAuth.js';
+const CACHE_TTL = 60000; // 60 seconds
+const cache = new Map();
+function getCacheKey(authUrl, clientId) {
+    return `${authUrl}::${clientId}`;
+}
+function getCachedProviders(key) {
+    const entry = cache.get(key);
+    if (!entry)
+        return null;
+    return entry;
+}
+function isStale(entry) {
+    return Date.now() - entry.fetchedAt > CACHE_TTL;
+}
+async function fetchProviders(authUrl, clientId) {
+    const url = new URL(`${authUrl}/providers`);
+    url.searchParams.set('client_id', clientId);
+    const res = await fetch(url.toString());
+    if (!res.ok) {
+        throw new Error('Failed to fetch providers');
+    }
+    const data = await res.json();
+    return data.providers || [];
+}
+// ─── Hook ────────────────────────────────────────────────────────────────
 /**
- * Hook to fetch available SSO providers for the current organization.
- * Automatically fetches providers based on the client_id from AuthProvider config.
+ * Hook to fetch available SSO providers from the auth service.
+ * Uses module-level cache with 60s TTL and stale-while-revalidate.
+ * Clears cache on window.focus for admin changes to take effect.
  */
 export function useProviders() {
     const config = useAuthConfig();
-    const [providers, setProviders] = useState([]);
-    const [isLoading, setIsLoading] = useState(true);
+    const cacheKey = getCacheKey(config.authUrl, config.clientId);
+    // Initialize from cache if available
+    const cached = getCachedProviders(cacheKey);
+    const [providers, setProviders] = useState(cached?.providers || []);
+    const [isLoading, setIsLoading] = useState(!cached);
     const [error, setError] = useState(null);
+    const [refreshCounter, setRefreshCounter] = useState(0);
+    const refresh = useCallback(() => {
+        cache.delete(cacheKey);
+        setRefreshCounter((c) => c + 1);
+    }, [cacheKey]);
     useEffect(() => {
         let mounted = true;
-        async function fetchProviders() {
-            try {
+        async function doFetch(showLoading) {
+            if (showLoading)
                 setIsLoading(true);
-                setError(null);
-                const url = new URL(`${config.authUrl}/providers`);
-                url.searchParams.set('client_id', config.clientId);
-                const res = await fetch(url.toString());
-                if (!res.ok) {
-                    throw new Error(`Failed to fetch providers: ${res.status}`);
-                }
-                const data = await res.json();
+            try {
+                const result = await fetchProviders(config.authUrl, config.clientId);
+                cache.set(cacheKey, { providers: result, fetchedAt: Date.now() });
                 if (mounted) {
-                    setProviders(data.providers || []);
+                    setProviders(result);
+                    setError(null);
                 }
             }
             catch (err) {
                 if (mounted) {
                     setError(err instanceof Error ? err.message : 'Failed to fetch providers');
+                    // Keep stale data if we have it
+                    if (!cached)
+                        setProviders([]);
                 }
             }
             finally {
-                if (mounted) {
+                if (mounted)
                     setIsLoading(false);
-                }
             }
         }
-        fetchProviders();
+        const entry = getCachedProviders(cacheKey);
+        if (!entry) {
+            // No cache — fetch with loading state
+            doFetch(true);
+        }
+        else if (isStale(entry)) {
+            // Stale cache — show cached data, refresh in background
+            setProviders(entry.providers);
+            setIsLoading(false);
+            doFetch(false);
+        }
+        else {
+            // Fresh cache — use it directly
+            setProviders(entry.providers);
+            setIsLoading(false);
+        }
+        // Refetch on window focus (admin changes take effect when tab refocused)
+        function handleFocus() {
+            const current = getCachedProviders(cacheKey);
+            if (!current || isStale(current)) {
+                doFetch(false);
+            }
+        }
+        window.addEventListener('focus', handleFocus);
         return () => {
             mounted = false;
+            window.removeEventListener('focus', handleFocus);
         };
-    }, [config.authUrl, config.clientId]);
-    return { providers, isLoading, error };
+    }, [config.authUrl, config.clientId, cacheKey, refreshCounter]);
+    return { providers, isLoading, error, refresh };
 }
 //# sourceMappingURL=useProviders.js.map

package/dist/useProviders.js.map

@@ -1 +1 @@
-{"version":3,"file":"useProviders.js","sourceRoot":"","sources":["../src/useProviders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAc7C;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAiB,EAAE,CAAC,CAAC;IAC/D,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAExD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,GAAG,IAAI,CAAC;QAEnB,KAAK,UAAU,cAAc;YAC3B,IAAI,CAAC;gBACH,YAAY,CAAC,IAAI,CAAC,CAAC;gBACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAEf,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;gBACnD,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;gBAEnD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACxC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;oBACZ,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC9D,CAAC;gBAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;gBAC9B,IAAI,OAAO,EAAE,CAAC;oBACZ,YAAY,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;gBACrC,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,OAAO,EAAE,CAAC;oBACZ,QAAQ,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC;gBAC7E,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,IAAI,OAAO,EAAE,CAAC;oBACZ,YAAY,CAAC,KAAK,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;QAED,cAAc,EAAE,CAAC;QAEjB,OAAO,GAAG,EAAE;YACV,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEtC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACzC,CAAC"}
+{"version":3,"file":"useProviders.js","sourceRoot":"","sources":["../src/useProviders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAyB7C,MAAM,SAAS,GAAG,KAAM,CAAC,CAAC,aAAa;AACvC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C,SAAS,WAAW,CAAC,OAAe,EAAE,QAAgB;IACpD,OAAO,GAAG,OAAO,KAAK,QAAQ,EAAE,CAAC;AACnC,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAW;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,OAAO,CAAC,KAAiB;IAChC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;AAClD,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,OAAe,EAAE,QAAgB;IAC7D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,OAAO,YAAY,CAAC,CAAC;IAC5C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAE5C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,OAAO,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED,4EAA4E;AAE5E;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE9D,qCAAqC;IACrC,MAAM,MAAM,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAiB,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC;IACpF,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,cAAc,EAAE,iBAAiB,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAExD,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE;QAC/B,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,iBAAiB,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,GAAG,IAAI,CAAC;QAEnB,KAAK,UAAU,OAAO,CAAC,WAAoB;YACzC,IAAI,WAAW;gBAAE,YAAY,CAAC,IAAI,CAAC,CAAC;YACpC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACrE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBAClE,IAAI,OAAO,EAAE,CAAC;oBACZ,YAAY,CAAC,MAAM,CAAC,CAAC;oBACrB,QAAQ,CAAC,IAAI,CAAC,CAAC;gBACjB,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,OAAO,EAAE,CAAC;oBACZ,QAAQ,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC;oBAC3E,gCAAgC;oBAChC,IAAI,CAAC,MAAM;wBAAE,YAAY,CAAC,EAAE,CAAC,CAAC;gBAChC,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,IAAI,OAAO;oBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAED,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QAE3C,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,sCAAsC;YACtC,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC;aAAM,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,wDAAwD;YACxD,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YAC9B,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,gCAAgC;YAChC,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YAC9B,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,yEAAyE;QACzE,SAAS,WAAW;YAClB,MAAM,OAAO,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC7C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBACjC,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;QAED,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAE9C,OAAO,GAAG,EAAE;YACV,OAAO,GAAG,KAAK,CAAC;YAChB,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC;IAEhE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAClD,CAAC"}

package/dist/validateConfig.d.ts

@@ -0,0 +1,14 @@
+import type { AuthConfig } from './types.js';
+/**
+ * Configuration validation errors for better developer experience.
+ */
+export declare class AuthConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates AuthConfig and throws descriptive errors if invalid.
+ * Called at initialization time to fail fast with helpful messages.
+ * Only clientId is required — authUrl and appUrl can be auto-discovered.
+ */
+export declare function validateConfig(config: AuthConfig): void;
+//# sourceMappingURL=validateConfig.d.ts.map

package/dist/validateConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateConfig.d.ts","sourceRoot":"","sources":["../src/validateConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CA4EvD"}

package/dist/validateConfig.js

@@ -0,0 +1,71 @@
+/**
+ * Configuration validation errors for better developer experience.
+ */
+export class AuthConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthConfigError';
+    }
+}
+/**
+ * Validates AuthConfig and throws descriptive errors if invalid.
+ * Called at initialization time to fail fast with helpful messages.
+ * Only clientId is required — authUrl and appUrl can be auto-discovered.
+ */
+export function validateConfig(config) {
+    if (!config) {
+        throw new AuthConfigError('AuthProvider requires a config prop. ' +
+            'At minimum, provide { clientId: "your-app-id" }.');
+    }
+    // Required field
+    if (!config.clientId) {
+        throw new AuthConfigError('Missing required config: clientId. ' +
+            'This is the client ID registered with the auth service.');
+    }
+    // URL format validation (only if provided)
+    if (config.authUrl) {
+        try {
+            new URL(config.authUrl);
+        }
+        catch {
+            throw new AuthConfigError(`Invalid authUrl: "${config.authUrl}" is not a valid URL. ` +
+                'It should include the protocol (e.g., "https://auth.tony.codes").');
+        }
+    }
+    if (config.appUrl) {
+        try {
+            new URL(config.appUrl);
+        }
+        catch {
+            throw new AuthConfigError(`Invalid appUrl: "${config.appUrl}" is not a valid URL. ` +
+                'It should include the protocol (e.g., "https://myapp.tony.codes").');
+        }
+    }
+    if (config.apiUrl) {
+        try {
+            new URL(config.apiUrl);
+        }
+        catch {
+            throw new AuthConfigError(`Invalid apiUrl: "${config.apiUrl}" is not a valid URL. ` +
+                'It should include the protocol (e.g., "https://api.myapp.tony.codes").');
+        }
+    }
+    // Common misconfiguration warnings (logged but don't throw)
+    if (typeof window !== 'undefined') {
+        const isProduction = !window.location.hostname.includes('test') &&
+            !window.location.hostname.includes('localhost');
+        if (isProduction && config.authUrl?.includes('localhost')) {
+            console.warn('[auth-react] Warning: authUrl contains "localhost" but app appears to be in production. ' +
+                'Make sure to update authUrl for production.');
+        }
+        if (config.authUrl?.endsWith('/')) {
+            console.warn('[auth-react] Warning: authUrl has a trailing slash. ' +
+                'This may cause double slashes in URLs.');
+        }
+        if (config.appUrl?.endsWith('/')) {
+            console.warn('[auth-react] Warning: appUrl has a trailing slash. ' +
+                'This may cause double slashes in URLs.');
+        }
+    }
+}
+//# sourceMappingURL=validateConfig.js.map

package/dist/validateConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateConfig.js","sourceRoot":"","sources":["../src/validateConfig.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,eAAe,CACvB,uCAAuC;YACrC,kDAAkD,CACrD,CAAC;IACJ,CAAC;IAED,iBAAiB;IACjB,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,IAAI,eAAe,CACvB,qCAAqC;YACnC,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IAED,2CAA2C;IAC3C,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,eAAe,CACvB,qBAAqB,MAAM,CAAC,OAAO,wBAAwB;gBACzD,mEAAmE,CACtE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,eAAe,CACvB,oBAAoB,MAAM,CAAC,MAAM,wBAAwB;gBACvD,oEAAoE,CACvE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,eAAe,CACvB,oBAAoB,MAAM,CAAC,MAAM,wBAAwB;gBACvD,wEAAwE,CAC3E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,YAAY,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC1C,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAErE,IAAI,YAAY,IAAI,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1D,OAAO,CAAC,IAAI,CACV,0FAA0F;gBACxF,6CAA6C,CAChD,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CACV,sDAAsD;gBACpD,wCAAwC,CAC3C,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CACV,qDAAqD;gBACnD,wCAAwC,CAC3C,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonycodes/auth-react",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "React SDK for Tony Auth service",
   "type": "module",
   "main": "dist/index.js",
@@ -12,32 +12,9 @@
     },
     "./style.css": "./dist/style.css"
   },
-  "files": [
-    "dist"
-  ],
   "scripts": {
     "build": "tsc && npx tailwindcss -i src/style.css -o dist/style.css --minify",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "react",
-    "auth",
-    "authentication",
-    "sdk"
-  ],
-  "author": "Tony <tony@tony.codes>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tonycodes/auth-react.git"
-  },
-  "homepage": "https://github.com/tonycodes/auth-react#readme",
-  "bugs": {
-    "url": "https://github.com/tonycodes/auth-react/issues"
-  },
-  "publishConfig": {
-    "access": "public"
+    "dev": "tsc --watch"
   },
   "peerDependencies": {
     "react": ">=18.0.0",

package/src/AuthCallback.tsx

@@ -0,0 +1,128 @@
+import { useContext, useEffect, useRef, useState } from 'react';
+import { AuthConfigContext } from './AuthProvider.js';
+
+interface AuthCallbackProps {
+  /** API URL to exchange code (overrides config.apiUrl, defaults to current origin) */
+  apiUrl?: string;
+  /** Where to redirect after successful auth */
+  onSuccess?: (returnTo: string) => void;
+  /** Called on auth failure */
+  onError?: (error: string) => void;
+}
+
+/**
+ * Component that handles the OAuth callback.
+ * Mount at /auth/callback route in your React router.
+ *
+ * When mounted, this component:
+ * 1. Extracts the authorization code from the URL
+ * 2. Calls /api/auth/callback on the backend to exchange the code for tokens
+ * 3. Redirects to the original page (from state)
+ *
+ * Your Express backend should mount callbackHandler() at /api/auth/callback.
+ *
+ * The API URL is resolved in this order:
+ * 1. `apiUrl` prop (explicit override)
+ * 2. `config.apiUrl` from AuthProvider
+ * 3. `config.appUrl` from AuthProvider
+ * 4. Current window origin (fallback)
+ */
+export function AuthCallback({ apiUrl: apiUrlProp, onSuccess, onError }: AuthCallbackProps) {
+  const config = useContext(AuthConfigContext);
+  const [error, setError] = useState<string | null>(null);
+  const exchangedRef = useRef(false);
+
+  useEffect(() => {
+    // Guard against React 18 strict mode double-firing
+    if (exchangedRef.current) return;
+    exchangedRef.current = true;
+
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get('code');
+    const state = params.get('state');
+    const errorParam = params.get('error');
+
+    if (errorParam) {
+      setError(errorParam);
+      if (onError) {
+        onError(errorParam);
+      } else {
+        let redirectReturnTo = '/';
+        if (state) {
+          try {
+            const decoded = JSON.parse(atob(state));
+            redirectReturnTo = decoded.returnTo || '/';
+          } catch {
+            // Invalid state — default to /
+          }
+        }
+        const loginUrl = new URL('/login', window.location.origin);
+        loginUrl.searchParams.set('error', errorParam);
+        if (redirectReturnTo !== '/') loginUrl.searchParams.set('returnTo', redirectReturnTo);
+        window.location.href = loginUrl.toString();
+      }
+      return;
+    }
+
+    if (!code) {
+      setError('Missing authorization code');
+      onError?.('Missing authorization code');
+      return;
+    }
+
+    // Resolve API URL: prop > config.apiUrl > config.appUrl > current origin
+    const baseUrl = apiUrlProp || config?.apiUrl || config?.appUrl || window.location.origin;
+
+    async function exchange() {
+      try {
+        const res = await fetch(`${baseUrl}/api/auth/callback?code=${encodeURIComponent(code!)}`, {
+          credentials: 'include',
+        });
+
+        if (!res.ok) {
+          const data = await res.json();
+          throw new Error(data.error || 'Authentication failed');
+        }
+
+        // Decode state to get returnTo path
+        let returnTo = '/';
+        if (state) {
+          try {
+            const decoded = JSON.parse(atob(state));
+            returnTo = decoded.returnTo || '/';
+          } catch {
+            // Invalid state — default to /
+          }
+        }
+
+        if (onSuccess) {
+          onSuccess(returnTo);
+        } else {
+          window.location.href = returnTo;
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Authentication failed';
+        setError(message);
+        onError?.(message);
+      }
+    }
+
+    exchange();
+  }, [apiUrlProp, config, onSuccess, onError]);
+
+  if (error) {
+    return (
+      <div style={{ padding: '2rem', textAlign: 'center' }}>
+        <h2>Authentication Failed</h2>
+        <p>{error}</p>
+        <a href="/">Go Home</a>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ padding: '2rem', textAlign: 'center' }}>
+      <p>Signing in...</p>
+    </div>
+  );
+}