@vergeinfosoft/react 1.0.0

package/README.md

@@ -0,0 +1,277 @@
+# @verge-auth/react
+
+React SDK for Verge Auth - Single-line authentication integration for your React applications.
+
+## Installation
+
+```bash
+npm install @verge-auth/react
+```
+
+## Quick Start
+
+### One-Line Integration
+
+Wrap your entire app with the `VergeAuth` component:
+
+```jsx
+import { VergeAuth } from '@verge-auth/react';
+
+function App() {
+  return (
+    <VergeAuth>
+      <YourApp />
+    </VergeAuth>
+  );
+}
+```
+
+That's it! Your app is now protected with Verge Auth.
+
+### With Custom Configuration
+
+```jsx
+import { VergeAuth } from '@verge-auth/react';
+
+function App() {
+  return (
+    <VergeAuth 
+      config={{
+        apiBaseUrl: '/api',
+        authEndpoint: '/auth/me',
+        loginUrl: 'https://auth.vergeinfosoft.com/login',
+        logoutUrl: '/auth/logout',
+        redirectUrl: window.location.origin
+      }}
+      callbackPath="/auth/callback"
+    >
+      <YourApp />
+    </VergeAuth>
+  );
+}
+```
+
+## Environment Variables
+
+Set these in your `.env` file:
+
+```env
+VITE_VERGEAUTH_LOGIN_URL=https://auth.vergeinfosoft.com/login
+```
+
+## Advanced Usage
+
+### Using Individual Components
+
+If you need more control, you can use the individual components:
+
+```jsx
+import { AuthProvider, useAuth, ProtectedRoute } from '@verge-auth/react';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <AuthProvider>
+      <BrowserRouter>
+        <Routes>
+          <Route path="/auth/callback" element={<AuthCallback />} />
+          <Route path="/*" element={
+            <ProtectedRoute>
+              <YourApp />
+            </ProtectedRoute>
+          } />
+        </Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+```
+
+### Permission-Based Route Protection
+
+```jsx
+import { ProtectedRoute } from '@verge-auth/react';
+
+function Dashboard() {
+  return (
+    <ProtectedRoute requiredPermissions={['hrms-service:/api/dashboard/stats:get']}>
+      <DashboardContent />
+    </ProtectedRoute>
+  );
+}
+```
+
+### Using the Auth Hook
+
+```jsx
+import { useAuth } from '@verge-auth/react';
+
+function UserProfile() {
+  const { isAuthenticated, loading, permissions, hasPermission, login, logout } = useAuth();
+
+  if (loading) return <div>Loading...</div>;
+
+  if (!isAuthenticated) {
+    return <button onClick={login}>Login</button>;
+  }
+
+  return (
+    <div>
+      <h1>Welcome!</h1>
+      <p>Permissions: {permissions.join(', ')}</p>
+      {hasPermission('admin') && <button>Admin Panel</button>}
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+}
+```
+
+### Require All Permissions
+
+By default, `ProtectedRoute` requires ANY of the specified permissions. To require ALL:
+
+```jsx
+<ProtectedRoute 
+  requiredPermissions={['perm1', 'perm2']} 
+  requireAll={true}
+>
+  <AdminPanel />
+</ProtectedRoute>
+```
+
+### Custom Fallback Path
+
+```jsx
+<ProtectedRoute 
+  requiredPermissions={['admin']} 
+  fallbackPath="/unauthorized"
+>
+  <AdminPanel />
+</ProtectedRoute>
+```
+
+## API Reference
+
+### VergeAuth
+
+Main wrapper component for one-line integration.
+
+**Props:**
+- `children` (ReactNode): Your application
+- `config?` (VergeAuthConfig): Configuration object
+- `callbackPath?` (string): Path for auth callback (default: `/auth/callback`)
+
+### AuthProvider
+
+Provides auth context to your app.
+
+**Props:**
+- `children` (ReactNode): Child components
+- `config?` (VergeAuthConfig): Configuration object
+
+### ProtectedRoute
+
+Protects routes based on authentication and permissions.
+
+**Props:**
+- `children` (ReactNode): Protected content
+- `requiredPermissions?` (string[]): Required permissions
+- `requireAll?` (boolean): Require all permissions instead of any (default: false)
+- `fallbackPath?` (string): Redirect path if unauthorized (default: `/`)
+
+### AuthCallback
+
+Handles OAuth callback from Verge Auth.
+
+**Props:**
+- `redirectPath?` (string): Path to redirect after successful auth (default: `/`)
+
+### useAuth
+
+Hook to access auth state and methods.
+
+**Returns:**
+- `isAuthenticated` (boolean | null): Authentication status
+- `loading` (boolean): Loading state
+- `permissions` (string[]): User permissions
+- `appBrandName` (string | null): App brand name
+- `user` (any): User data
+- `hasPermission(permission: string)` (function): Check if user has permission
+- `hasAnyPermission(permissions: string[])` (function): Check if user has any of the permissions
+- `login()` (function): Redirect to login
+- `logout()` (function): Redirect to logout
+
+## Configuration
+
+### VergeAuthConfig
+
+```typescript
+interface VergeAuthConfig {
+  apiBaseUrl?: string;        // Default: '/api'
+  authEndpoint?: string;      // Default: '/auth/me'
+  loginUrl?: string;          // Default: from VITE_VERGEAUTH_LOGIN_URL
+  logoutUrl?: string;         // Default: '/auth/logout'
+  redirectUrl?: string;       // Default: current URL
+}
+```
+
+## How It Works
+
+1. **Auth Check**: On mount, the SDK calls `/api/auth/me` to check authentication status
+2. **403 Handling**: A 403 response means the user is authenticated but lacks route permission
+3. **Login Redirect**: Unauthenticated users are redirected to the Verge Auth login page
+4. **Callback Handling**: After login, the callback route handles the OAuth code exchange
+5. **Permission Checks**: Routes can be protected based on user permissions
+
+## Backend Requirements
+
+Your backend must:
+- Use the Verge Auth Python SDK with `add_central_auth(app)`
+- Provide an `/api/auth/me` endpoint (handled automatically by the SDK)
+- Handle OAuth code exchange at `/api/?code=` (handled automatically by the SDK)
+
+## Example: Full HRMS Integration
+
+```jsx
+import { VergeAuth, ProtectedRoute, useAuth } from '@verge-auth/react';
+
+const PERMISSIONS = {
+  DASHBOARD_GET: "hrms-service:/api/dashboard/stats:get",
+  EMPLOYEES_GET: "hrms-service:/api/employees:get",
+  ATTENDANCE_GET: "hrms-service:/api/attendance:get",
+};
+
+function App() {
+  return (
+    <VergeAuth>
+      <Dashboard />
+      <Employees />
+      <Attendance />
+    </VergeAuth>
+  );
+}
+
+function Dashboard() {
+  return (
+    <ProtectedRoute requiredPermissions={[PERMISSIONS.DASHBOARD_GET]}>
+      <DashboardContent />
+    </ProtectedRoute>
+  );
+}
+
+function Employees() {
+  return (
+    <ProtectedRoute requiredPermissions={[PERMISSIONS.EMPLOYEES_GET]}>
+      <EmployeesContent />
+    </ProtectedRoute>
+  );
+}
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please contact Verge Infosoft support.

package/dist/AuthCallback.d.ts

@@ -0,0 +1,5 @@
+export interface AuthCallbackProps {
+    redirectPath?: string;
+}
+export declare function AuthCallback({ redirectPath }: AuthCallbackProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=AuthCallback.d.ts.map

package/dist/AuthCallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthCallback.d.ts","sourceRoot":"","sources":["../src/AuthCallback.tsx"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,YAAY,CAAC,EAAE,YAAkB,EAAE,EAAE,iBAAiB,2CA4BrE"}

package/dist/AuthContext.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+import { AuthContextValue, VergeAuthConfig } from './types';
+export interface AuthProviderProps {
+    children: ReactNode;
+    config?: VergeAuthConfig;
+}
+export declare function AuthProvider({ children, config }: AuthProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare const useAuth: () => AuthContextValue;
+//# sourceMappingURL=AuthContext.d.ts.map

package/dist/AuthContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthContext.d.ts","sourceRoot":"","sources":["../src/AuthContext.tsx"],"names":[],"mappings":"AAAA,OAAc,EAAkD,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzF,OAAO,EAAa,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAIvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAUD,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,MAAW,EAAE,EAAE,iBAAiB,2CA6FxE;AAED,eAAO,MAAM,OAAO,QAAO,gBAM1B,CAAC"}

package/dist/ProtectedRoute.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+export interface ProtectedRouteProps {
+    children: ReactNode;
+    requiredPermissions?: string[];
+    requireAll?: boolean;
+    fallbackPath?: string;
+}
+export declare function ProtectedRoute({ children, requiredPermissions, requireAll, fallbackPath, }: ProtectedRouteProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=ProtectedRoute.d.ts.map

package/dist/ProtectedRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProtectedRoute.d.ts","sourceRoot":"","sources":["../src/ProtectedRoute.tsx"],"names":[],"mappings":"AAAA,OAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGzC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,SAAS,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,mBAAwB,EACxB,UAAkB,EAClB,YAAkB,GACnB,EAAE,mBAAmB,kDA8BrB"}

package/dist/VergeAuth.d.ts

@@ -0,0 +1,25 @@
+import { ReactNode } from 'react';
+import { VergeAuthConfig } from './types';
+export interface VergeAuthProps {
+    children: ReactNode;
+    config?: VergeAuthConfig;
+    callbackPath?: string;
+}
+/**
+ * VergeAuth - One-line integration wrapper for Verge Auth
+ *
+ * Usage:
+ * ```jsx
+ * import { VergeAuth } from '@verge-auth/react';
+ *
+ * function App() {
+ *   return (
+ *     <VergeAuth>
+ *       <YourApp />
+ *     </VergeAuth>
+ *   );
+ * }
+ * ```
+ */
+export declare function VergeAuth({ children, config, callbackPath }: VergeAuthProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=VergeAuth.d.ts.map

package/dist/VergeAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VergeAuth.d.ts","sourceRoot":"","sources":["../src/VergeAuth.tsx"],"names":[],"mappings":"AAAA,OAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIzC,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,YAA+B,EAAE,EAAE,cAAc,2CAW9F"}

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface AuthState {
+    isAuthenticated: boolean | null;
+    loading: boolean;
+    permissions: string[];
+    appBrandName: string | null;
+    user: any;
+}
+interface VergeAuthConfig {
+    apiBaseUrl?: string;
+    authEndpoint?: string;
+    loginUrl?: string;
+    logoutUrl?: string;
+    appBaseUrl?: string;
+}
+interface AuthContextValue extends AuthState {
+    hasPermission: (permission: string) => boolean;
+    hasAnyPermission: (permissions: string[]) => boolean;
+    login: () => void;
+    logout: () => void;
+}
+interface AuthProviderProps$1 {
+    children: ReactNode;
+    config?: VergeAuthConfig;
+}
+interface ProtectedRouteProps$1 {
+    children: ReactNode;
+    requiredPermissions?: string[];
+    requireAll?: boolean;
+    fallbackPath?: string;
+}
+interface AuthCallbackProps$1 {
+    redirectPath?: string;
+}
+interface VergeAuthProps$1 {
+    children: ReactNode;
+    config?: VergeAuthConfig;
+    callbackPath?: string;
+}
+
+interface VergeAuthProps {
+    children: ReactNode;
+    config?: VergeAuthConfig;
+    callbackPath?: string;
+}
+/**
+ * VergeAuth - One-line integration wrapper for Verge Auth
+ *
+ * Usage:
+ * ```jsx
+ * import { VergeAuth } from '@verge-auth/react';
+ *
+ * function App() {
+ *   return (
+ *     <VergeAuth>
+ *       <YourApp />
+ *     </VergeAuth>
+ *   );
+ * }
+ * ```
+ */
+declare function VergeAuth({ children, config, callbackPath }: VergeAuthProps): react_jsx_runtime.JSX.Element;
+
+interface AuthProviderProps {
+    children: ReactNode;
+    config?: VergeAuthConfig;
+}
+declare function AuthProvider({ children, config }: AuthProviderProps): react_jsx_runtime.JSX.Element;
+declare const useAuth: () => AuthContextValue;
+
+interface ProtectedRouteProps {
+    children: ReactNode;
+    requiredPermissions?: string[];
+    requireAll?: boolean;
+    fallbackPath?: string;
+}
+declare function ProtectedRoute({ children, requiredPermissions, requireAll, fallbackPath, }: ProtectedRouteProps): react_jsx_runtime.JSX.Element | null;
+
+interface AuthCallbackProps {
+    redirectPath?: string;
+}
+declare function AuthCallback({ redirectPath }: AuthCallbackProps): react_jsx_runtime.JSX.Element;
+
+export { AuthCallback, AuthProvider, ProtectedRoute, VergeAuth, useAuth };
+export type { AuthCallbackProps$1 as AuthCallbackProps, AuthContextValue, AuthProviderProps$1 as AuthProviderProps, AuthState, ProtectedRouteProps$1 as ProtectedRouteProps, VergeAuthConfig, VergeAuthProps$1 as VergeAuthProps };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}