@fluoce/auth-react 1.2.0 → 1.2.1

package/README.md

@@ -0,0 +1,349 @@
+# @fluoce/auth-react
+
+**React authentication for applications powered by Fluoce Auth.**
+
+Provider, guard, hook, and code-exchange flow — four lightweight pieces, zero boilerplate.
+
+[GitHub](https://github.com/Ashit-mulani/SDK/tree/main/%40fluoce/auth_react) · [Ashit Mulani](https://me.fluoce.com)
+
+---
+
+## 📋 Table of Contents
+
+- [Why This SDK](#-why-this-sdk)
+- [📦 Installation](#-installation)
+- [🛠️ Quick Start](#-quick-start)
+- [🧩 Core Primitives](#-core-primitives)
+  - [1. FluoceAuthProvider](#1-fluoceauthprovider)
+  - [2. useFluoceAuth()](#2-usefluoceauth)
+  - [3. FluoceAuthGuard](#3-fluoceauthguard)
+  - [4. FluoceAuthFlow](#4-fluoceauthflow)
+- [🔄 Authentication Flow Diagram](#-authentication-flow-diagram)
+- [💻 Full Implementation Example](#-full-implementation-example)
+- [💡 Best Practices](#-best-practices)
+- [🏷️ Type Reference](#%EF%B8%8F-type-reference)
+
+---
+
+## 🚀 Why This SDK
+
+`@fluoce/auth-react` completely abstracts the Fluoce Auth lifecycle—session bootstrapping, token refresh management, route guarding, and login token exchanges—into a developer-friendly React ecosystem.
+
+| Component / Hook     | Primary Purpose                                                                               |
+| -------------------- | --------------------------------------------------------------------------------------------- |
+| `FluoceAuthProvider` | Injects global auth context, orchestrates tokens, and initializes sessions on mount.          |
+| `useFluoceAuth()`    | Consumes user metadata, async loading states, and programmatic actions (`logout`, `refresh`). |
+| `FluoceAuthGuard`    | Protects specific route trees and manages automated redirection gates.                        |
+| `FluoceAuthFlow`     | Concludes the handshake sequence by exchanging temporary URL codes for active sessions.       |
+
+No manual token parsing, no custom `fetch` interceptors, and no complex state synchronization.
+
+---
+
+## 📦 Installation
+
+Ensure your project has the minimum peer dependencies met (`react >= 18` and `react-dom >= 18`).
+
+```bash
+npm install @fluoce/auth-react
+# or
+pnpm add @fluoce/auth-react
+# or
+yarn add @fluoce/auth-react
+```
+
+---
+
+## 🛠️ Quick Start
+
+Setting up authentication requires only three structural steps: wrapping your application tree, protecting target views, and mounting an exchange callback route.
+
+### Configure the Root Provider
+
+Wrap your main application layout inside a routing tree using `FluoceAuthProvider`.
+
+```tsx
+// main.tsx or index.tsx
+import { createRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import { FluoceAuthProvider } from "@fluoce/auth-react";
+import App from "./App.tsx";
+
+createRoot(document.getElementById("root")!).render(
+  <BrowserRouter>
+    <FluoceAuthProvider
+      app_url="https://your-app-domain.com" // Use only the root domain (no trailing slash)
+      on_unauthorized_redirect={{ type: "fluoce" }}
+      on_error={(error) => console.error("Fluoce Auth Error:", error)}
+    >
+      <App />
+    </FluoceAuthProvider>
+  </BrowserRouter>,
+);
+```
+
+---
+
+## 🧩 Core Primitives
+
+### 1. `FluoceAuthProvider`
+
+The parent context engine. It evaluates active storage footprints at startup, resolves token validity, and powers down-stream child elements.
+
+```typescript
+interface FluoceAuthProviderType {
+  children: ReactNode;
+  app_url: string;
+  on_error?: (error: unknown) => void;
+  on_unauthorized_redirect?: FluoceRedirectType;
+}
+```
+
+| Prop                       | Type                       | Required | Description                                                                                              |
+| -------------------------- | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| `children`                 | `ReactNode`                | Yes      | The inner application component tree.                                                                    |
+| `app_url`                  | `string`                   | Yes      | **Your app's public base address**, where users are returned following an active login session.          |
+| `on_error`                 | `(error: unknown) => void` | No       | Triggered on token rotation failures, validation anomalies, or connection dropouts.                      |
+| `on_unauthorized_redirect` | `FluoceRedirectType`       | No       | Policy detailing how unauthenticated guard interventions are resolved. Defaults to `{"type": "fluoce"}`. |
+
+#### `FluoceRedirectType`
+
+```typescript
+type FluoceRedirectType =
+  | { type: "fluoce" }
+  | { type: "custom"; redirect: (error: unknown) => void }
+  | { type: "none" };
+```
+
+- `"fluoce"`: Instantly pivots unauthenticated instances outward to your hosted Fluoce identification interface.
+- `"custom"`: Intercepts structural redirection routines, enabling user loops back to custom internal routes (e.g., `/login`) or firing specific analytics tracking hooks.
+- `"none"`: Freezes routing layers in place with no automated interventions.
+
+---
+
+### 2. `useFluoceAuth()`
+
+Hook interface mapping states and functional operations out of context. Must be invoked inside components within the provider tree.
+
+```typescript
+interface FluoceAuthContextType {
+  user: FluoceUserType | null;
+  safe_loading: boolean;
+  auth_flow_loading: boolean;
+  app_url: string;
+  on_unauthorized_redirect: FluoceRedirectType | undefined | null;
+  logout(): Promise<boolean>;
+  refresh(): Promise<boolean>;
+  auth_flow({ code }: { code: string }): Promise<boolean>;
+  get_safe_user(): Promise<FluoceUserType | null>;
+  refresh_token: string | null;
+  access_token: string | null;
+}
+```
+
+| Property / Method                | Returns                 | Description                                                                                                       |
+| -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `user`                           | `FluoceUserType         | null`                                                                                                             | Read-only object containing active profile values, or `null` if unauthenticated.               |
+| `safe_loading`                   | `boolean`               | `true` exclusively during standard initialization boots. Block layouts using this to eliminate rendering flashes. |
+| `auth_flow_loading`              | `boolean`               | `true` while the system actively exchanges the code query param for production keys.                              |
+| `logout()`                       | `Promise<boolean>`      | Destroys token signatures, invalidates memory blocks, and signs out users.                                        |
+| `refresh()`                      | `Promise<boolean>`      | Forces the runtime engine to prompt refresh sequences against token services.                                     |
+| `auth_flow({ code })`            | `Promise<boolean>`      | Exchanges the code for production session, usually internal use only.                                             |
+| `get_safe_user()`                | `Promise<FluoceUserType | null>`                                                                                                            | Re-fetch safely the active user, returns user or null.                                         |
+| `access_token` / `refresh_token` | `string                 | null`                                                                                                             | Raw context variables exposed if tokens are required inside distinct back-end network headers. |
+
+---
+
+### 3. `FluoceAuthGuard`
+
+Shield component designed to block unauthorized access to target page views.
+
+```typescript
+interface auth_guard_interface {
+  children: ReactNode;
+  fallback?: ReactNode;
+  can_redirect?: boolean;
+}
+```
+
+- `fallback`: Target loader or custom component array to show while evaluation cycles process.
+- `can_redirect`: When true, users missing credentials automatically trigger behaviors configured inside the parent `on_unauthorized_redirect` configuration block.
+
+> ⚠️ **CRITICAL ARCHITECTURAL WARNING**
+>
+> **Never wrap the** `/auth` **callback pathway inside** `FluoceAuthGuard`**.** When users pass authenticators, they arrive at the application as an unauthenticated shell delivering a one-time token (`?code=...`). Guarding that target entry component blocks the `FluoceAuthFlow` context from receiving and resolving the hash string, resulting in an endless loop.
+
+---
+
+### 4. `FluoceAuthFlow`
+
+The structural landing handler dedicated exclusively to reading and resolving handshakes.
+
+```typescript
+declare const FluoceAuthFlow: (props: {
+  code: string;
+  redirect: string;
+  fallback?: ReactNode;
+}) => JSX.Element;
+```
+
+| Prop       | Required | Description                                                                                                         |
+| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `code`     | ✅       | The individual string argument read from your router's query params.                                                |
+| `redirect` | ✅       | Internal application route path to forward users toward upon authentication validation (e.g., `/` or `/dashboard`). |
+| `fallback` | ❌       | Custom element tree rendered while background network validations resolve.                                          |
+
+---
+
+## 🔄 Authentication Flow Diagram
+
+```text
+  Protected Route
+         │
+         ▼
+  FluoceAuthGuard
+         │
+         ▼
+   Authenticated?
+    ├── Yes ──> Render Component View
+    └── No
+           │
+           ▼
+  Redirect to Fluoce Login
+           │
+           ▼
+    User Signs In
+           │
+           ▼
+  /auth?code=YOUR_CODE
+           │
+           ▼
+    FluoceAuthFlow  <─── (Keep this route UNGUARDED!)
+           │
+           ▼
+   Exchange Code Flow
+           │
+           ▼
+  Redirect to Application Target (e.g., "/")
+```
+
+---
+
+## 💻 Full Implementation Example
+
+Here is a full integration architecture mapping an application utilizing `react-router-dom`:
+
+### `App.tsx`
+
+```tsx
+import { Routes, Route } from "react-router-dom";
+import { FluoceAuthGuard, useFluoceAuth } from "@fluoce/auth-react";
+import Dashboard from "./Dashboard";
+import AuthCallback from "./AuthCallback";
+
+export default function App() {
+  const { safe_loading } = useFluoceAuth();
+
+  // Keep app in a holding state while initial session validation completes
+  if (safe_loading) {
+    return <div className="spinner">Initializing Secure Session...</div>;
+  }
+
+  return (
+    <Routes>
+      <Route
+        path="/"
+        element={
+          <FluoceAuthGuard
+            can_redirect={true}
+            fallback={<p>Redirecting to login...</p>}
+          >
+            <Dashboard />
+          </FluoceAuthGuard>
+        }
+      />
+      {/* Absolute public route for handling OAuth callbacks */}
+      <Route path="/auth" element={<AuthCallback />} />
+    </Routes>
+  );
+}
+```
+
+### `AuthCallback.tsx`
+
+```tsx
+import { useSearchParams } from "react-router-dom";
+import { FluoceAuthFlow } from "@fluoce/auth-react";
+
+export default function AuthCallback() {
+  const [searchParams] = useSearchParams();
+  const code = searchParams.get("code");
+
+  if (!code) {
+    return (
+      <div className="error">
+        Authentication failed. Missing authorization code parameter.
+      </div>
+    );
+  }
+
+  return (
+    <FluoceAuthFlow
+      code={code}
+      redirect="/"
+      fallback={<div>Verifying credentials, finalizing authorization...</div>}
+    />
+  );
+}
+```
+
+### `Dashboard.tsx`
+
+```tsx
+import { useFluoceAuth } from "@fluoce/auth-react";
+
+export default function Dashboard() {
+  const { user, logout } = useFluoceAuth();
+
+  return (
+    <main style={{ padding: "2rem" }}>
+      <h1>Welcome back, {user?.name}!</h1>
+      <p>Registered Email: {user?.email}</p>
+      <button onClick={() => logout()} className="btn-logout">
+        Sign Out
+      </button>
+    </main>
+  );
+}
+```
+
+---
+
+## 💡 Best Practices
+
+1. **Wrap At the True Root**: Place `FluoceAuthProvider` inside your router component configuration blocks to ensure contextual redirections fire cleanly without throwing layout exceptions.
+2. **Utilize** `safe_loading` **Flags**: Always lock initialization screens behind the `safe_loading` boolean parameter to give your layout time to discover existing tokens from memory frames cleanly.
+3. **Isolate Callbacks**: Dedicate a pure `/auth` layout page solely to processing the `FluoceAuthFlow` payload string. Keep it structurally clear of custom middleware actions or layout elements.
+
+---
+
+## 🏷️ Type Reference
+
+### `FluoceUserType`
+
+```typescript
+type FluoceUserType = {
+  id: string;
+  name: string;
+  email: string | null;
+  phone: string | null;
+  photo: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+};
+```
+
+---
+
+Built with ❤️ by **[Ashit Mulani](https://github.com/Ashit-mulani)**  
+Portfolio: [me.fluoce.com](https://me.fluoce.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluoce/auth-react",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "React SDK for Fluoce Auth",
   "license": "MIT",
   "type": "module",