@auditauth/react 0.2.0-beta.1

package/README.md

@@ -0,0 +1,173 @@
+# @auditauth/react
+
+`@auditauth/react` is the AuditAuth SDK integration for React applications. It
+provides a provider, a hook, and a route guard to handle redirect callbacks,
+session state, login and logout actions, and authenticated HTTP calls.
+
+## Install
+
+Install the package in your React application.
+
+```bash
+npm install @auditauth/react
+```
+
+`@auditauth/react` has peer dependencies on `react` and `react-dom` version 18
+or higher.
+
+## Wrap your app with the provider
+
+Create one top-level `AuditAuthProvider` and pass your AuditAuth config.
+
+```tsx
+import { AuditAuthProvider } from '@auditauth/react'
+
+export function AppRoot() {
+  return (
+    <AuditAuthProvider
+      config={{
+        apiKey: import.meta.env.VITE_AUDITAUTH_API_KEY,
+        appId: import.meta.env.VITE_AUDITAUTH_APP_ID,
+        baseUrl: 'http://localhost:5173',
+        redirectUrl: 'http://localhost:5173/private',
+      }}
+    >
+      <App />
+    </AuditAuthProvider>
+  )
+}
+```
+
+The provider runs `handleRedirect()` on startup and exposes the current user
+and session actions through `useAuditAuth()`.
+
+## Protect private UI with `RequireAuth`
+
+Wrap private content with `RequireAuth` to trigger login when the user is not
+authenticated.
+
+```tsx
+import { RequireAuth } from '@auditauth/react'
+
+export function PrivatePage() {
+  return (
+    <RequireAuth>
+      <h1>Private area</h1>
+    </RequireAuth>
+  )
+}
+```
+
+`RequireAuth` renders children only after the SDK is ready and the user has a
+valid session.
+
+## Use auth state and actions in components
+
+Use `useAuditAuth()` inside components that are children of
+`AuditAuthProvider`.
+
+```tsx
+import { useAuditAuth } from '@auditauth/react'
+
+export function AccountMenu() {
+  const { user, ready, login, logout, goToPortal } = useAuditAuth()
+
+  if (!ready) return null
+
+  if (!user) {
+    return <button onClick={() => login()}>Login</button>
+  }
+
+  return (
+    <div>
+      <span>{user.email}</span>
+      <button onClick={() => goToPortal()}>Portal</button>
+      <button onClick={() => logout()}>Logout</button>
+    </div>
+  )
+}
+```
+
+## Make authenticated API calls
+
+Use `fetch` from `useAuditAuth()` instead of `window.fetch()` for authenticated
+requests. The SDK attaches the session token and handles refresh behavior when
+needed.
+
+```tsx
+import { useAuditAuth } from '@auditauth/react'
+
+export function ProfileButton() {
+  const { fetch } = useAuditAuth()
+
+  const loadProfile = async () => {
+    const response = await fetch('https://api.example.com/private/profile')
+    const data = await response.json()
+    console.log(data)
+  }
+
+  return <button onClick={loadProfile}>Load profile</button>
+}
+```
+
+## Track navigation metrics
+
+If you use a client router such as React Router, call `trackNavigationPath()`
+when the path changes.
+
+```tsx
+import { useEffect } from 'react'
+import { useLocation } from 'react-router-dom'
+import { useAuditAuth } from '@auditauth/react'
+
+export function NavigationTracker() {
+  const { pathname } = useLocation()
+  const { trackNavigationPath } = useAuditAuth()
+
+  useEffect(() => {
+    trackNavigationPath(pathname)
+  }, [pathname, trackNavigationPath])
+
+  return null
+}
+```
+
+## API reference
+
+`useAuditAuth()` returns:
+
+- `ready: boolean`
+- `user: SessionUser | null`
+- `fetch(input, init?): Promise<Response>`
+- `login(): Promise<void>`
+- `logout(): Promise<void>`
+- `goToPortal(): Promise<void>`
+- `isAuthenticated(): boolean`
+- `trackNavigationPath(path: string): void`
+
+Exports from `@auditauth/react`:
+
+- `AuditAuthProvider`
+- `useAuditAuth`
+- `RequireAuth`
+
+## Compatibility
+
+This package requires:
+
+- Node.js `>=18.18.0` for tooling and build environments
+- React `>=18`
+- React DOM `>=18`
+
+## Resources
+
+- Repository: https://github.com/nimibyte/auditauth-sdk
+- Documentation: https://docs.auditauth.com
+
+## Example
+
+See `examples/react` for a complete Vite + React Router integration.
+
+## License
+
+MIT

package/dist/guard.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+type RequireAuthProps = {
+    children: ReactNode;
+};
+declare const RequireAuth: ({ children }: RequireAuthProps) => import("react/jsx-runtime").JSX.Element | null;
+export { RequireAuth };

package/dist/guard.js

@@ -0,0 +1,24 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { useAuditAuth } from './provider';
+const RequireAuth = ({ children }) => {
+    const { ready, isAuthenticated, login } = useAuditAuth();
+    const startedRef = useRef(false);
+    const authed = isAuthenticated();
+    useEffect(() => {
+        if (!ready)
+            return;
+        if (authed)
+            return;
+        if (startedRef.current)
+            return;
+        startedRef.current = true;
+        login();
+    }, [ready, authed, login]);
+    if (!ready)
+        return null;
+    if (!authed)
+        return null;
+    return _jsx(_Fragment, { children: children });
+};
+export { RequireAuth };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './provider';
+export * from './guard';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './provider';
+export * from './guard';

package/dist/provider.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { AuditAuthConfig, SessionUser } from '@auditauth/core';
+import { AuditAuthWeb } from '@auditauth/web';
+type AuditAuthContextValue = {
+    ready: boolean;
+    user: SessionUser | null;
+    fetch: AuditAuthWeb['fetch'];
+    login: () => Promise<void>;
+    logout: () => Promise<void>;
+    goToPortal: () => Promise<void>;
+    isAuthenticated: () => boolean;
+    trackNavigationPath: (path: string) => void;
+};
+type AuditAuthProviderProps = {
+    config: AuditAuthConfig;
+    children: ReactNode;
+};
+declare const AuditAuthProvider: ({ config, children }: AuditAuthProviderProps) => import("react/jsx-runtime").JSX.Element;
+declare const useAuditAuth: () => AuditAuthContextValue;
+export { AuditAuthProvider, useAuditAuth, };

package/dist/provider.js

@@ -0,0 +1,114 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { AuditAuthWeb } from '@auditauth/web';
+const AuditAuthContext = createContext(null);
+const createSdk = (config) => {
+    const safeStorage = {
+        get: (name) => {
+            if (typeof window === 'undefined')
+                return null;
+            return localStorage.getItem(name);
+        },
+        set: (name, value) => {
+            if (typeof window === 'undefined')
+                return;
+            localStorage.setItem(name, value);
+        },
+        remove: (name) => {
+            if (typeof window === 'undefined')
+                return;
+            localStorage.removeItem(name);
+        },
+    };
+    return new AuditAuthWeb(config, safeStorage);
+};
+const AuditAuthProvider = ({ config, children }) => {
+    const sdkRef = useRef(null);
+    const [ready, setReady] = useState(false);
+    const [user, setUser] = useState(null);
+    if (!sdkRef.current) {
+        sdkRef.current = createSdk(config);
+    }
+    const sdk = sdkRef.current;
+    useEffect(() => {
+        let mounted = true;
+        const init = async () => {
+            try {
+                await sdk.handleRedirect();
+                const sessionUser = sdk.getSessionUser();
+                if (!mounted)
+                    return;
+                setUser(sessionUser);
+            }
+            catch {
+                if (!mounted)
+                    return;
+                setUser(null);
+            }
+            finally {
+                if (!mounted)
+                    return;
+                setReady(true);
+            }
+        };
+        init();
+        return () => {
+            mounted = false;
+        };
+    }, [sdk]);
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const handler = (event) => {
+            if (event.key !== '__auditauth_sync__')
+                return;
+            const sessionUser = sdk.getSessionUser();
+            setUser(sessionUser);
+        };
+        window.addEventListener('storage', handler);
+        return () => {
+            window.removeEventListener('storage', handler);
+        };
+    }, [sdk]);
+    const logout = useMemo(() => {
+        return async () => {
+            await sdk.logout();
+            setUser(null);
+            localStorage.setItem('__auditauth_sync__', Date.now().toString());
+        };
+    }, [sdk]);
+    const fetchWrapper = useMemo(() => {
+        return async (...args) => {
+            try {
+                const res = await sdk.fetch(...args);
+                return res;
+            }
+            catch (err) {
+                setUser(null);
+                throw err;
+            }
+        };
+    }, [sdk]);
+    const value = useMemo(() => {
+        return {
+            ready,
+            user,
+            fetch: fetchWrapper,
+            login: sdk.login.bind(sdk),
+            logout,
+            goToPortal: sdk.goToPortal.bind(sdk),
+            isAuthenticated: () => !!user,
+            trackNavigationPath: sdk.trackNavigationPath.bind(sdk),
+        };
+    }, [ready, user, sdk, logout, fetchWrapper]);
+    return (_jsx(AuditAuthContext.Provider, { value: value, children: children }));
+};
+const useAuditAuth = () => {
+    const ctx = useContext(AuditAuthContext);
+    if (!ctx) {
+        throw new Error('useAuditAuth must be used inside AuditAuthProvider');
+    }
+    return ctx;
+};
+export { AuditAuthProvider, useAuditAuth, };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@auditauth/react",
+  "version": "0.2.0-beta.1",
+  "description": "AuditAuth React SDK",
+  "license": "MIT",
+  "author": "Nimibyte",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nimibyte/auditauth-sdk.git"
+  },
+  "homepage": "https://docs.auditauth.com",
+  "bugs": {
+    "url": "https://github.com/nimibyte/auditauth-sdk/issues"
+  },
+  "keywords": [
+    "authentication",
+    "auth",
+    "oauth",
+    "identity",
+    "jwt",
+    "security",
+    "auditauth"
+  ],
+  "module": "dist/index.js",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@auditauth/web": "^0.2.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0"
+  }
+}