@insforge/react 0.5.4 → 0.5.6

package/README.md

@@ -5,7 +5,8 @@
 ## Why @insforge/react?
 
 ✅ **Framework Agnostic** - Works with any React setup (Vite, CRA, or no bundler)  
-✅ **Zero Router Dependencies** - Use with any routing solution or none at all  
+✅ **Zero Router Dependencies** - Built-in navigation abstraction works with any routing solution  
+✅ **Route Protection** - Built-in `RouteGuard` for vanilla React apps  
 ✅ **Production Ready** - Complete auth flows with business logic included  
 ✅ **Full TypeScript** - Complete type safety out of the box
 
@@ -38,21 +39,30 @@ npm install react@^19.0.0 react-dom@^19.0.0
 VITE_INSFORGE_BASE_URL=https://your-project.insforge.app/
 ```
 
-### 2. Setup Provider
+### 2. Setup Provider & Route Guard
 
-Wrap your app with `InsforgeProvider`:
+Wrap your app with `InsforgeProvider` and `RouteGuard`:
 
 ```tsx
 // src/main.tsx (Vite) or src/index.tsx (CRA)
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { InsforgeProvider } from '@insforge/react';
+import { InsforgeProvider, RouteGuard } from '@insforge/react';
 import App from './App';
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
-    <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL} afterSignInUrl="/dashboard">
-      <App />
+    <InsforgeProvider 
+      baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}
+      afterSignInUrl="/dashboard"
+    >
+      <RouteGuard
+        builtInAuth
+        publicRoutes={['/', '/about']}
+        loadingFallback={<div>Loading...</div>}
+      >
+        <App />
+      </RouteGuard>
     </InsforgeProvider>
   </StrictMode>
 );
@@ -90,7 +100,7 @@ export default function App() {
 }
 ```
 
-**That's it!** 🎉 You now have production-ready authentication.
+**That's it!** 🎉 Your app is now protected with authentication.
 
 ---
 
@@ -186,7 +196,8 @@ function CustomAuthForm() {
 - `<ResetPassword />` - Reset password with token validation
 - `<VerifyEmail />` - Verify email with automatic token handling
 - `<UserButton />` - User dropdown with sign-out
-- `<Protect />` - Route protection wrapper
+- `<RouteGuard />` - **NEW:** App-level route protection for vanilla React
+- `<Protect />` - Component-level protection wrapper
 - `<SignedIn>` / `<SignedOut>` - Conditional rendering
 
 **Form Components (Pure UI):**
@@ -204,8 +215,24 @@ function CustomAuthForm() {
 ### Hooks
 
 ```tsx
-const { signIn, signUp, signOut, isSignedIn, isLoaded } = useAuth();
+// Authentication state and methods
+const { 
+  signIn, 
+  signUp, 
+  signOut, 
+  isSignedIn, 
+  isLoaded,
+  baseUrl,           // From provider
+  afterSignInUrl     // From provider
+} = useAuth();
+
+// Or use useInsforge (same as useAuth)
+const context = useInsforge();
+
+// User information
 const { user, updateUser, isLoaded } = useUser();
+
+// Public auth configuration (OAuth providers, password requirements, etc.)
 const { oauthProviders, authConfig, isLoaded } = usePublicAuthConfig();
 ```
 
@@ -347,8 +374,16 @@ function Dashboard() {
         <UserContent />
       </Protect>
 
+      {/* With redirect */}
+      <Protect redirectTo="/sign-in">
+        <UserContent />
+      </Protect>
+
       {/* Custom condition - e.g., role-based */}
-      <Protect condition={(user) => user.email.endsWith('@admin.com')}>
+      <Protect 
+        condition={(user) => user.email.endsWith('@admin.com')}
+        redirectTo="/unauthorized"
+      >
         <AdminPanel />
       </Protect>
     </div>
@@ -356,7 +391,185 @@ function Dashboard() {
 }
 ```
 
-> **Note:** `<Protect>` is for conditional rendering only. For route-level protection, use your router's authentication guards with `useAuth()` hook.
+> **Note:** `<Protect>` is for component-level conditional rendering. For app-level route protection, use `<RouteGuard>`
+
+---
+
+## Route Protection (Detailed)
+
+### RouteGuard for Vanilla React
+
+`RouteGuard` provides app-level authentication protection without requiring any routing library.
+
+#### Option 1: External Built-in Auth (Simplest)
+
+Redirects to your deployed Insforge Auth pages:
+
+```tsx
+import { InsforgeProvider, RouteGuard } from '@insforge/react';
+
+createRoot(document.getElementById('root')!).render(
+  <InsforgeProvider 
+    baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}
+    afterSignInUrl="/dashboard"
+  >
+    <RouteGuard
+      builtInAuth
+      publicRoutes={['/', '/about', '/pricing']}
+      loadingFallback={<div>Loading...</div>}
+    >
+      <App />
+    </RouteGuard>
+  </InsforgeProvider>
+);
+```
+
+**Behavior:**
+- User visits `/sign-in` → Redirects to `baseUrl/auth/sign-in`
+- User visits `/sign-up` → Redirects to `baseUrl/auth/sign-up`
+- User visits `/dashboard` (protected) → Redirects to `baseUrl/auth/sign-in`
+- User visits `/` (public) → ✅ Renders normally
+
+#### Option 2: Custom Auth Pages
+
+Use @insforge/react components in your own app:
+
+```tsx
+import { InsforgeProvider, RouteGuard, SignIn, SignUp } from '@insforge/react';
+
+// Simple hash-based routing
+function App() {
+  const path = window.location.hash.slice(1) || '/';
+  
+  return (
+    <>
+      {path === '/login' && <SignIn />}
+      {path === '/register' && <SignUp />}
+      {path === '/dashboard' && <Dashboard />}
+      {path === '/' && <HomePage />}
+    </>
+  );
+}
+
+createRoot(document.getElementById('root')!).render(
+  <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}>
+    <RouteGuard
+      builtInAuth={false}
+      publicRoutes={['/login', '/register', '/forgot-password', '/']}
+      paths={{ signIn: '/login', signUp: '/register' }}
+      loadingFallback={<div>Loading...</div>}
+    >
+      <App />
+    </RouteGuard>
+  </InsforgeProvider>
+);
+```
+
+**Behavior:**
+- User visits `/login` → ✅ Renders `<SignIn />` (in publicRoutes)
+- User visits `/dashboard` (protected) → Redirects to `/login?redirect=/dashboard`
+- After login → Redirects to `/dashboard`
+
+#### RouteGuard Props Reference
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `builtInAuth` | `boolean` | No | `true` | Use external auth pages (`true`) or custom pages (`false`) |
+| `publicRoutes` | `string[]` | No | `[]` | Routes accessible without authentication |
+| `paths` | `object` | No | `{ signIn: '/sign-in', ... }` | Custom auth page paths (when `builtInAuth=false`) |
+| `paths.signIn` | `string` | No | `'/sign-in'` | Custom sign-in page path |
+| `paths.signUp` | `string` | No | `'/sign-up'` | Custom sign-up page path |
+| `paths.forgotPassword` | `string` | No | `'/forgot-password'` | Custom forgot password page path |
+| `loadingFallback` | `ReactNode` | **Yes** | - | Loading UI displayed while checking authentication |
+
+**Public Routes with Wildcards:**
+
+```tsx
+<RouteGuard
+  publicRoutes={[
+    '/',           // Home page
+    '/about',      // About page
+    '/blog/*',     // All blog routes
+    '/docs/*',     // All documentation routes
+  ]}
+>
+  <App />
+</RouteGuard>
+```
+
+> **Note:** When `builtInAuth=true`, auth paths (`/sign-in`, `/sign-up`, `/forgot-password`) are automatically redirected. Don't include them in `publicRoutes`.
+
+### React Router Integration
+
+For React Router apps, use the dedicated adapter:
+
+```bash
+npm install @insforge/react-router
+```
+
+```tsx
+import { InsforgeProvider } from '@insforge/react-router';
+import { getInsforgeRoutes } from '@insforge/react-router/router';
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
+
+const router = createBrowserRouter([
+  { path: '/', element: <Home /> },
+  { path: '/dashboard', element: <Dashboard /> },
+  ...getInsforgeRoutes({
+    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
+    builtInAuth: true
+  })
+]);
+
+function App() {
+  return (
+    <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}>
+      <RouterProvider router={router} />
+    </InsforgeProvider>
+  );
+}
+```
+
+**Features:**
+- Pre-configured routes for authentication flows
+- React Router's `Link` and `useSearchParams` integration
+- Optimized navigation with client-side routing
+
+**Docs:** [@insforge/react-router](https://github.com/InsForge/InsForge/tree/main/packages/react-router)
+
+### Next.js Integration
+
+For Next.js App Router with SSR:
+
+```bash
+npm install @insforge/nextjs
+```
+
+```tsx
+// app/layout.tsx
+import { InsforgeProvider } from '@insforge/nextjs';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <InsforgeProvider baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL}>
+          {children}
+        </InsforgeProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+**Features:**
+- Server-side rendering (SSR) support
+- Middleware-based route protection
+- Next.js `Link` and `useSearchParams` integration
+- Cookie-based session management
+- Automatic token refresh
+
+**Docs:** [@insforge/nextjs](https://github.com/InsForge/InsForge/tree/main/packages/nextjs)
 
 ---
 
@@ -401,17 +614,117 @@ Low-level building blocks for complete customization:
 
 ---
 
-## Framework Integration
 
-### Next.js
+## API Reference
 
-For Next.js App Router with full SSR support:
+### InsforgeProvider
 
-```bash
-npm install @insforge/nextjs
+The root provider component that manages authentication state.
+
+**Props:**
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `baseUrl` | `string` | **Yes** | - | Your Insforge backend URL |
+| `afterSignInUrl` | `string` | No | `'/'` | Redirect URL after successful sign-in |
+| `onAuthChange` | `(user: InsforgeUser \| null) => void` | No | - | Callback when auth state changes |
+| `onSignIn` | `(authToken: string) => Promise<void>` | No | - | Custom handler after sign-in (e.g., cookie sync) |
+| `onSignOut` | `() => Promise<void>` | No | - | Custom handler after sign-out (e.g., clear cookies) |
+
+**Example:**
+
+```tsx
+<InsforgeProvider
+  baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}
+  afterSignInUrl="/dashboard"
+  onAuthChange={(user) => {
+    console.log('Auth changed:', user);
+  }}
+>
+  {children}
+</InsforgeProvider>
+```
+
+### RouteGuard
+
+App-level route protection for vanilla React apps (no router library needed).
+
+See [Route Protection (Detailed)](#route-protection-detailed) for full documentation.
+
+**Quick Props:**
+
+- `builtInAuth` (default: `true`) - Use external auth or custom pages
+- `publicRoutes` - Array of paths accessible without auth
+- `paths` - Custom auth page paths (when `builtInAuth=false`)
+- `loadingFallback` (required) - Loading UI
+
+### useAuth() / useInsforge()
+
+Primary hook for authentication. Both are aliases for the same hook.
+
+**Returns:**
+
+```tsx
+{
+  // Auth state
+  user: InsforgeUser | null;
+  isLoaded: boolean;
+  isSignedIn: boolean;
+  
+  // Auth methods
+  signIn: (email: string, password: string) => Promise<...>;
+  signUp: (email: string, password: string) => Promise<...>;
+  signOut: () => Promise<void>;
+  updateUser: (data: Partial<InsforgeUser>) => Promise<...>;
+  reloadAuth: () => Promise<...>;
+  
+  // Email verification
+  sendVerificationEmail: (email: string) => Promise<...>;
+  verifyEmail: (otp: string, email?: string) => Promise<...>;
+  
+  // Password reset
+  sendResetPasswordEmail: (email: string) => Promise<...>;
+  resetPassword: (token: string, newPassword: string) => Promise<...>;
+  exchangeResetPasswordToken: (email: string, code: string) => Promise<...>;
+  
+  // OAuth
+  loginWithOAuth: (provider: OAuthProvider, redirectTo: string) => Promise<void>;
+  
+  // Config (from provider)
+  baseUrl: string;
+  afterSignInUrl: string;
+  
+  // Public config
+  getPublicAuthConfig: () => Promise<...>;
+}
 ```
 
-See [@insforge/nextjs documentation](https://github.com/InsForge/InsForge/tree/main/packages/nextjs)
+### useUser()
+
+Simplified hook for user data only.
+
+**Returns:**
+
+```tsx
+{
+  user: InsforgeUser | null;
+  isLoaded: boolean;
+}
+```
+
+### usePublicAuthConfig()
+
+Hook for fetching public auth configuration (OAuth providers, password requirements, etc.).
+
+**Returns:**
+
+```tsx
+{
+  oauthProviders: OAuthProviderConfig[];
+  authConfig: AuthConfig;
+  isLoaded: boolean;
+}
+```
 
 ---
 

package/dist/atoms.cjs

@@ -107,7 +107,10 @@ var NavigationContext = react.createContext(null);
 function useNavigationAdapter() {
   const adapter = react.useContext(NavigationContext);
   if (!adapter) {
-    throw new Error("useNavigationAdapter must be used within NavigationProvider");
+    return {
+      useSearchParams: () => new URLSearchParams(),
+      Link: ({ href, children }) => /* @__PURE__ */ jsxRuntime.jsx("a", { href, children })
+    };
   }
   return adapter;
 }
@@ -646,7 +649,8 @@ function useInsforge() {
       loginWithOAuth: async () => {
       },
       getPublicAuthConfig: async () => null,
-      baseUrl: ""
+      baseUrl: "",
+      afterSignInUrl: "/"
     };
   }
   return context;