@rationalbloks/frontblok-auth 0.1.0

package/README.md

@@ -0,0 +1,195 @@
+# @rationalbloks/frontblok-auth
+
+**Universal Frontend Authentication for RationalBloks Apps**
+
+Pure authentication, API, and token management. **NO STYLING** - each template app provides its own aesthetics.
+
+---
+
+## 🎯 Philosophy
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    FRONTBLOK-AUTH (npm package)                    │
+│                                                                     │
+│  ┌───────────┐  ┌───────────┐  ┌──────────────────────────────┐   │
+│  │   AUTH    │  │    API    │  │        PROVIDERS             │   │
+│  │           │  │           │  │                              │   │
+│  │ • Tokens  │  │ • BaseApi │  │ • createAppRoot              │   │
+│  │ • Storage │  │ • Client  │  │ • createAuthProvider         │   │
+│  │ • Context │  │ • Types   │  │ • useAuth                    │   │
+│  └───────────┘  └───────────┘  └──────────────────────────────┘   │
+│                                                                     │
+│                          ↓  NO STYLING  ↓                          │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        │                     │                     │
+        ▼                     ▼                     ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│  Template #1  │   │  Template #2  │   │  Template #3  │
+│ (rationalbloks│   │ (Investment   │   │ (E-commerce   │
+│    front)     │   │   Portfolio)  │   │   Template)   │
+│               │   │               │   │               │
+│ ✓ Own theme   │   │ ✓ Own theme   │   │ ✓ Own theme   │
+│ ✓ Own styles  │   │ ✓ Own styles  │   │ ✓ Own styles  │
+│ ✓ Own Navbar  │   │ ✓ Own Navbar  │   │ ✓ Own Navbar  │
+└───────────────┘   └───────────────┘   └───────────────┘
+```
+
+---
+
+## 📦 Installation
+
+### For Published Package (Production)
+```bash
+npm install @rationalbloks/frontblok-auth
+```
+
+### For Local Development (npm link)
+```bash
+# In frontblok-auth directory
+cd frontblok-auth
+npm install
+npm run build
+npm link
+
+# In your app directory
+cd your-app
+npm link @rationalbloks/frontblok-auth
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Bootstrap Your App
+
+```tsx
+// main.tsx
+import { createAppRoot } from '@rationalbloks/frontblok-auth';
+import './styles/globals.css';  // YOUR app's styling
+import App from './App';
+
+createAppRoot(App, {
+  googleClientId: import.meta.env.VITE_GOOGLE_CLIENT_ID || '',
+});
+```
+
+### 2. Create Your Auth Provider
+
+```tsx
+// contexts/ClientAuthContext.tsx
+import { createAuthProvider, useAuth } from '@rationalbloks/frontblok-auth';
+import { myApi } from '../services/myApi';
+
+export const ClientAuthProvider = createAuthProvider(myApi);
+export const useClientAuth = useAuth;
+```
+
+### 3. Extend BaseApi for Your App
+
+```tsx
+// services/myApi.ts
+import { BaseApi, getStoredUser, getStoredToken, isAuthenticated } from '@rationalbloks/frontblok-auth';
+import type { User } from '@rationalbloks/frontblok-auth';
+
+// Re-export utilities
+export { getStoredUser, getStoredToken, isAuthenticated };
+export type { User };
+
+// Your custom endpoints
+class MyAppApi extends BaseApi {
+  async getProjects() {
+    return this.get<Project[]>('/projects');
+  }
+  
+  async createProject(data: CreateProjectDTO) {
+    return this.post<Project>('/projects', data);
+  }
+}
+
+export const myApi = new MyAppApi({
+  baseURL: import.meta.env.VITE_API_URL,
+});
+```
+
+---
+
+## 📚 API Reference
+
+### Auth Exports
+
+| Export | Description |
+|--------|-------------|
+| `createAppRoot(App, config)` | Bootstrap app with Google OAuth provider |
+| `createAuthProvider(api)` | Create auth context provider for your API |
+| `useAuth()` | Hook to access auth state and actions |
+
+### API Exports
+
+| Export | Description |
+|--------|-------------|
+| `BaseApi` | Extensible API client with token management |
+| `createAuthApi(baseUrl)` | Create pre-configured auth API instance |
+| `getStoredUser()` | Get user from localStorage |
+| `getStoredToken()` | Get token from localStorage |
+| `isAuthenticated()` | Check if user is logged in |
+
+---
+
+## 🔧 Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Build library
+npm run build
+
+# Outputs:
+#   dist/index.js     - ESM bundle
+#   dist/index.cjs    - CommonJS bundle  
+#   dist/index.d.ts   - TypeScript declarations
+```
+
+---
+
+## 📋 Peer Dependencies
+
+This package requires these dependencies in your app:
+
+```json
+{
+  "react": "^18.0.0 || ^19.0.0",
+  "react-dom": "^18.0.0 || ^19.0.0",
+  "react-router-dom": "^6.0.0 || ^7.0.0",
+  "@react-oauth/google": "^0.12.0"
+}
+```
+
+---
+
+## 🏗️ Architecture for New Template Apps
+
+When creating a new template app that uses frontblok-auth:
+
+1. **Install the package**
+   ```bash
+   npm install @rationalbloks/frontblok-auth
+   ```
+
+2. **Create your own styling** (theme/, styles/)
+3. **Create your own components** (style them yourself)
+4. **Create your own API service** (extend BaseApi)
+5. **Use createAuthProvider** with your API
+6. **Bootstrap with createAppRoot**
+
+---
+
+## 📝 License
+
+MIT © RationalBloks Team

package/dist/api/client.d.ts

@@ -0,0 +1,119 @@
+import type { User, ApiKey, ApiKeyCreateResponse, AuthResponse } from './types';
+/**
+ * BaseApi - Universal HTTP client with authentication.
+ *
+ * Extend this class to add your application-specific API methods.
+ *
+ * @example
+ * ```typescript
+ * class MyAppApi extends BaseApi {
+ *   constructor() {
+ *     super(import.meta.env.VITE_API_URL || 'https://api.myapp.com');
+ *   }
+ *
+ *   async getProducts() {
+ *     return this.request<Product[]>('/api/products/');
+ *   }
+ * }
+ * ```
+ */
+export declare class BaseApi {
+    protected token: string | null;
+    protected refreshToken: string | null;
+    protected isRefreshing: boolean;
+    protected refreshPromise: Promise<boolean> | null;
+    protected proactiveRefreshTimer: ReturnType<typeof setTimeout> | null;
+    protected refreshCheckInterval: ReturnType<typeof setInterval> | null;
+    protected tokenRefreshPromise: Promise<void> | null;
+    protected readonly apiBaseUrl: string;
+    constructor(apiBaseUrl: string);
+    /**
+     * Sync tokens across browser tabs when localStorage changes.
+     * Prevents "stale refresh token" issue where Tab A rotates the token
+     * but Tab B still has the old (now invalid) refresh token in memory.
+     */
+    private setupStorageListener;
+    /**
+     * Start interval-based token check (runs every 60 seconds).
+     * More reliable than setTimeout which browsers throttle in background tabs.
+     */
+    private startRefreshCheckInterval;
+    /**
+     * Handle tab visibility changes - check token when user returns to tab.
+     */
+    private setupVisibilityHandler;
+    /**
+     * Check token expiry and refresh if needed.
+     */
+    protected checkAndRefreshToken(): Promise<void>;
+    /**
+     * Parse JWT to get expiration time.
+     */
+    protected getTokenExpiry(token: string): number | null;
+    /**
+     * Schedule proactive refresh 5 minutes before token expires.
+     */
+    protected scheduleProactiveRefresh(): void;
+    /**
+     * Load tokens from localStorage on initialization.
+     */
+    protected loadTokens(): void;
+    /**
+     * Wait for any pending token refresh to complete before making API calls.
+     */
+    ensureTokenReady(): Promise<void>;
+    /**
+     * Refresh the access token using the refresh token.
+     */
+    refreshAccessToken(): Promise<boolean>;
+    /**
+     * Make an authenticated HTTP request.
+     * Handles token refresh, 401 retry, and rate limiting automatically.
+     *
+     * This method is public so apps can make custom API calls without extending BaseApi.
+     *
+     * @example
+     * const authApi = createAuthApi(API_URL);
+     * const data = await authApi.request<MyType>('/api/my-endpoint/', { method: 'POST', body: JSON.stringify(payload) });
+     */
+    request<T>(endpoint: string, options?: RequestInit, isRetry?: boolean, retryCount?: number): Promise<T>;
+    login(email: string, password: string): Promise<AuthResponse>;
+    register(email: string, password: string, firstName: string, lastName: string): Promise<AuthResponse>;
+    getMe(): Promise<{
+        user: User;
+    }>;
+    getCurrentUser(): Promise<User>;
+    deleteAccount(password: string, confirmText: string): Promise<{
+        message: string;
+        note: string;
+    }>;
+    logout(): Promise<void>;
+    logoutAllDevices(): Promise<void>;
+    protected clearAuth(): void;
+    listApiKeys(): Promise<{
+        api_keys: ApiKey[];
+        total: number;
+    }>;
+    createApiKey(data: {
+        name: string;
+        scopes?: string;
+        expires_in_days?: number;
+        rate_limit_per_minute?: number;
+    }): Promise<ApiKeyCreateResponse>;
+    revokeApiKey(keyId: string): Promise<{
+        message: string;
+        key_prefix: string;
+        revoked_at: string;
+    }>;
+}
+/**
+ * Creates an auth API client instance.
+ * Preferred over class inheritance - simpler and cleaner.
+ *
+ * @param apiBaseUrl - The backend API base URL
+ * @returns A BaseApi instance with all auth methods
+ */
+export declare function createAuthApi(apiBaseUrl: string): BaseApi;
+export declare const getStoredUser: () => User | null;
+export declare const getStoredToken: () => string | null;
+export declare const isAuthenticated: () => boolean;

package/dist/api/index.d.ts

@@ -0,0 +1,2 @@
+export { BaseApi, createAuthApi, getStoredUser, getStoredToken, isAuthenticated } from './client';
+export type { User, ApiKey, ApiKeyCreateResponse, AuthResponse } from './types';

package/dist/api/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Authenticated user interface.
+ * Represents the user data returned from authentication endpoints.
+ */
+export interface User {
+    id: string;
+    email: string;
+    first_name: string;
+    last_name: string;
+    full_name: string;
+    role: string;
+    is_active: boolean;
+    is_admin: boolean;
+    created_at: string;
+    last_login?: string;
+    oauth_provider?: string | null;
+    has_google_linked?: boolean;
+}
+/**
+ * API Key interface for MCP servers and external integrations.
+ */
+export interface ApiKey {
+    id: string;
+    name: string;
+    key_prefix: string;
+    scopes: string;
+    rate_limit_per_minute: number;
+    expires_at: string | null;
+    last_used_at: string | null;
+    created_at: string;
+}
+/**
+ * Response from creating a new API key.
+ * Includes the full key (only shown once).
+ */
+export interface ApiKeyCreateResponse {
+    api_key: string;
+    id: string;
+    name: string;
+    key_prefix: string;
+    scopes: string;
+    rate_limit_per_minute: number;
+    expires_at: string | null;
+    created_at: string;
+    message: string;
+}
+/**
+ * Login/Register response with tokens and user data.
+ */
+export interface AuthResponse {
+    access_token: string;
+    refresh_token?: string;
+    user: User;
+}

package/dist/auth/AppProvider.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+export interface AuthConfig {
+    /** Google OAuth Client ID (optional - only needed if using Google Sign-In) */
+    googleClientId?: string;
+}
+/**
+ * Creates and renders the app root with authentication providers.
+ * This is the universal way to bootstrap a React app with auth.
+ */
+export declare function createAppRoot(App: React.ComponentType, config?: AuthConfig): void;

package/dist/auth/AuthContext.d.ts

@@ -0,0 +1,38 @@
+import React from 'react';
+import type { User } from '../api';
+import type { BaseApi } from '../api/client';
+export interface AuthState {
+    user: User | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    error: string | null;
+}
+export interface AuthActions {
+    login: (email: string, password: string) => Promise<boolean>;
+    register: (email: string, password: string, firstName: string, lastName: string) => Promise<boolean>;
+    logout: () => void;
+    clearError: () => void;
+    refreshUser: () => Promise<void>;
+}
+export type AuthContextType = AuthState & AuthActions;
+/**
+ * Hook to access authentication state and actions.
+ * Must be used within an AuthProvider.
+ */
+export declare const useAuth: () => AuthContextType;
+/**
+ * Creates an AuthProvider component that uses the specified API instance.
+ * This allows the universal auth context to work with any API that extends BaseApi.
+ *
+ * @example
+ * ```typescript
+ * // In your app's auth setup:
+ * import { createAuthProvider } from '@/core/auth';
+ * import { myAppApi } from '@/services/myAppApi';
+ *
+ * export const MyAppAuthProvider = createAuthProvider(myAppApi);
+ * ```
+ */
+export declare function createAuthProvider(api: BaseApi): React.FC<{
+    children: React.ReactNode;
+}>;

package/dist/auth/index.d.ts

@@ -0,0 +1,4 @@
+export { useAuth, createAuthProvider } from './AuthContext';
+export type { AuthState, AuthActions, AuthContextType } from './AuthContext';
+export { createAppRoot } from './AppProvider';
+export type { AuthConfig } from './AppProvider';