@rationalbloks/frontblok-auth 0.4.1 → 0.4.2

package/dist/api/client.d.ts

@@ -1,49 +1,7 @@
 import type { User, ApiKey, ApiKeyCreateResponse, AuthResponse, GoogleOAuthResponse, PasswordResetRequestResponse, PasswordResetResponse, EmailVerificationResponse, SetPasswordResponse } from './types';
-/**
- * Generate a cryptographically secure nonce for OAuth CSRF protection.
- *
- * USAGE:
- * 1. Call generateOAuthNonce() in component useState (runs once on mount)
- * 2. Pass the nonce to GoogleLogin component via the 'nonce' prop
- * 3. On success, call authApi.googleLogin(credential) - it handles the rest
- *
- * @example
- * ```typescript
- * const [nonce] = useState(() => generateOAuthNonce());
- * // Pass to GoogleLogin: <GoogleLogin nonce={nonce} onSuccess={...} />
- * // On success: await authApi.googleLogin(credential);
- * ```
- *
- * @returns The generated nonce string
- */
 export declare const generateOAuthNonce: () => string;
-/**
- * Retrieve the stored OAuth nonce.
- * @returns The stored nonce or null if not found
- */
 export declare const getOAuthNonce: () => string | null;
-/**
- * Clear the stored OAuth nonce (call after successful login).
- */
 export declare const clearOAuthNonce: () => void;
-/**
- * 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;
@@ -54,55 +12,15 @@ export declare class BaseApi {
     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>;
@@ -110,79 +28,12 @@ export declare class BaseApi {
         user: User;
     }>;
     getCurrentUser(): Promise<User>;
-    /**
-     * Internal: Authenticate with Google OAuth.
-     * Use googleLogin() instead.
-     */
     private _googleOAuthLogin;
-    /**
-     * Simplified Google OAuth login.
-     *
-     * This is the default method for Google Sign-In. It handles the complete
-     * OAuth flow in a single call:
-     *
-     * 1. Retrieve nonce from sessionStorage (must exist from generateOAuthNonce())
-     * 2. Send credential + nonce to backend for verification
-     * 3. Store JWT tokens on success
-     * 4. Clear nonce to prevent replay attacks
-     *
-     * If any step fails, the entire operation fails cleanly. No partial states.
-     *
-     * @param credential - The Google ID token (JWT from GoogleLogin onSuccess)
-     * @returns GoogleOAuthResponse with tokens, user data, and is_new_user flag
-     * @throws Error if nonce is missing or authentication fails
-     *
-     * @example
-     * ```typescript
-     * // In component: generate nonce ONCE on mount
-     * const [nonce] = useState(() => generateOAuthNonce());
-     *
-     * // Pass nonce to GoogleLogin, then on success:
-     * const handleSuccess = async (response: CredentialResponse) => {
-     *   const result = await authApi.googleLogin(response.credential!);
-     *   // Done! Tokens stored, nonce cleared, user authenticated.
-     * };
-     * ```
-     */
     googleLogin(credential: string): Promise<GoogleOAuthResponse>;
-    /**
-     * Request a password reset email (forgot password flow).
-     *
-     * @param email - The email address to send reset link to
-     * @returns Message confirming email was sent (or would be sent)
-     */
     requestPasswordReset(email: string): Promise<PasswordResetRequestResponse>;
-    /**
-     * Reset password using token from email.
-     *
-     * @param token - The password reset token from the email link
-     * @param newPassword - The new password (min 8 characters)
-     * @returns Success message
-     */
     resetPassword(token: string, newPassword: string): Promise<PasswordResetResponse>;
-    /**
-     * Verify email address using token from verification email.
-     *
-     * @param token - The verification token from the email link
-     * @returns Success message
-     */
     verifyEmail(token: string): Promise<EmailVerificationResponse>;
-    /**
-     * Request a new verification email.
-     *
-     * @param email - The email address to send verification to
-     * @returns Message confirming email was sent
-     */
     requestVerificationEmail(email: string): Promise<EmailVerificationResponse>;
-    /**
-     * Set password for OAuth-only accounts.
-     *
-     * Allows users who registered via Google OAuth to set a password
-     * so they can also log in with email/password.
-     *
-     * @param newPassword - The password to set (min 8 characters)
-     * @returns Success message
-     */
     setPassword(newPassword: string): Promise<SetPasswordResponse>;
     deleteAccount(password: string, confirmText: string): Promise<{
         message: string;
@@ -207,13 +58,6 @@ export declare class BaseApi {
         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;

package/dist/api/createApiUrl.d.ts

@@ -1,39 +1,5 @@
-/**
- * Options for createApiUrl.
- */
 export interface CreateApiUrlOptions {
-    /**
-     * Override the env variable name. Default: 'VITE_DATABASE_API_URL'.
-     * This is read from import.meta.env at call time.
-     */
     envVar?: string;
-    /**
-     * Fallback URL for local development (only used when import.meta.env.DEV is true).
-     * Default: 'http://localhost:8000'
-     */
     devFallback?: string;
 }
-/**
- * Resolves the backend API URL for the current environment.
- *
- * Resolution order:
- * 1. `import.meta.env.VITE_DATABASE_API_URL` (injected at build time)
- * 2. `import.meta.env.VITE_API_URL` (alternative env var name)
- * 3. In development mode only: devFallback (default: 'http://localhost:8000')
- * 4. In production: empty string (will cause API calls to fail loudly)
- *
- * @param options - Configuration options
- * @returns The resolved API base URL
- *
- * @example
- * ```typescript
- * import { createApiUrl, createAuthApi } from '@rationalbloks/frontblok-auth';
- *
- * // Simple usage
- * const authApi = createAuthApi(createApiUrl());
- *
- * // Custom dev fallback
- * const authApi = createAuthApi(createApiUrl({ devFallback: 'http://localhost:3000' }));
- * ```
- */
 export declare function createApiUrl(options?: CreateApiUrlOptions): string;

package/dist/api/types.d.ts

@@ -1,7 +1,3 @@
-/**
- * Authenticated user interface.
- * Represents the user data returned from authentication endpoints.
- */
 export interface User {
     id: string;
     email: string;
@@ -16,9 +12,6 @@ export interface User {
     oauth_provider?: string | null;
     has_google_linked?: boolean;
 }
-/**
- * API Key interface for MCP servers and external integrations.
- */
 export interface ApiKey {
     id: string;
     name: string;
@@ -29,10 +22,6 @@ export interface ApiKey {
     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;
@@ -44,17 +33,11 @@ export interface ApiKeyCreateResponse {
     created_at: string;
     message: string;
 }
-/**
- * Login/Register response with tokens and user data.
- */
 export interface AuthResponse {
     access_token: string;
     refresh_token?: string;
     user: User;
 }
-/**
- * Google OAuth login response.
- */
 export interface GoogleOAuthResponse {
     message: string;
     access_token: string;
@@ -65,29 +48,17 @@ export interface GoogleOAuthResponse {
     is_new_user: boolean;
     is_account_link?: boolean;
 }
-/**
- * Password reset request response.
- */
 export interface PasswordResetRequestResponse {
     message: string;
     dev_token?: string;
 }
-/**
- * Password reset response.
- */
 export interface PasswordResetResponse {
     message: string;
 }
-/**
- * Email verification response.
- */
 export interface EmailVerificationResponse {
     message: string;
     dev_token?: string;
 }
-/**
- * Set password response (for OAuth-only accounts).
- */
 export interface SetPasswordResponse {
     message: string;
 }

package/dist/auth/AppProvider.d.ts

@@ -1,10 +1,5 @@
 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

@@ -15,24 +15,7 @@ export interface AuthActions {
     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/ProtectedRoute.d.ts

@@ -1,20 +1,9 @@
 import React from 'react';
 export interface ProtectedRouteProps {
     children: React.ReactNode;
-    /**
-     * The useAuth hook from your app's datablokApi.ts (useClientAuth).
-     * We accept this as a prop instead of importing it directly to avoid
-     * circular dependencies and keep the package decoupled.
-     */
     useAuth: () => {
         isAuthenticated: boolean;
     };
-    /**
-     * Where to redirect unauthenticated users. Default: '/auth'
-     */
     redirectTo?: string;
 }
-/**
- * Route wrapper that redirects to the auth page if the user is not authenticated.
- */
 export declare const ProtectedRoute: React.FC<ProtectedRouteProps>;

package/dist/index.cjs

@@ -40,11 +40,9 @@ class BaseApi {
   // ========================================================================
   // TOKEN MANAGEMENT
   // ========================================================================
-  /**
-   * 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.
-   */
+  // 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.
   setupStorageListener() {
     if (typeof window !== "undefined") {
       window.addEventListener("storage", (event) => {
@@ -63,10 +61,8 @@ class BaseApi {
       });
     }
   }
-  /**
-   * Start interval-based token check (runs every 60 seconds).
-   * More reliable than setTimeout which browsers throttle in background tabs.
-   */
+  // Start interval-based token check (runs every 60 seconds).
+  // More reliable than setTimeout which browsers throttle in background tabs.
   startRefreshCheckInterval() {
     if (this.refreshCheckInterval) {
       clearInterval(this.refreshCheckInterval);
@@ -77,9 +73,7 @@ class BaseApi {
       }
     }, 60 * 1e3);
   }
-  /**
-   * Handle tab visibility changes - check token when user returns to tab.
-   */
+  // Handle tab visibility changes - check token when user returns to tab.
   setupVisibilityHandler() {
     if (typeof document !== "undefined") {
       document.addEventListener("visibilitychange", () => {
@@ -96,9 +90,7 @@ class BaseApi {
       });
     }
   }
-  /**
-   * Check token expiry and refresh if needed.
-   */
+  // Check token expiry and refresh if needed.
   async checkAndRefreshToken() {
     if (!this.token) return;
     const expiry = this.getTokenExpiry(this.token);
@@ -114,9 +106,7 @@ class BaseApi {
       await this.refreshAccessToken();
     }
   }
-  /**
-   * Parse JWT to get expiration time.
-   */
+  // Parse JWT to get expiration time.
   getTokenExpiry(token) {
     try {
       const payload = JSON.parse(atob(token.split(".")[1]));
@@ -125,9 +115,7 @@ class BaseApi {
       return null;
     }
   }
-  /**
-   * Schedule proactive refresh 5 minutes before token expires.
-   */
+  // Schedule proactive refresh 5 minutes before token expires.
   scheduleProactiveRefresh() {
     if (this.proactiveRefreshTimer) {
       clearTimeout(this.proactiveRefreshTimer);
@@ -156,9 +144,7 @@ class BaseApi {
       await this.refreshAccessToken();
     }, refreshIn);
   }
-  /**
-   * Load tokens from localStorage on initialization.
-   */
+  // Load tokens from localStorage on initialization.
   loadTokens() {
     const storedToken = localStorage.getItem("auth_token");
     const storedRefreshToken = localStorage.getItem("refresh_token");
@@ -175,18 +161,14 @@ class BaseApi {
       this.scheduleProactiveRefresh();
     }
   }
-  /**
-   * Wait for any pending token refresh to complete before making API calls.
-   */
+  // Wait for any pending token refresh to complete before making API calls.
   async ensureTokenReady() {
     if (this.tokenRefreshPromise) {
       await this.tokenRefreshPromise;
       this.tokenRefreshPromise = null;
     }
   }
-  /**
-   * Refresh the access token using the refresh token.
-   */
+  // Refresh the access token using the refresh token.
   async refreshAccessToken() {
     if (this.isRefreshing) {
       return this.refreshPromise || Promise.resolve(false);
@@ -244,16 +226,14 @@ class BaseApi {
   // ========================================================================
   // HTTP REQUEST METHOD
   // ========================================================================
-  /**
-   * 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) });
-   */
+  // 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) });
   async request(endpoint, options = {}, isRetry = false, retryCount = 0) {
     await this.ensureTokenReady();
     if (this.token && !isRetry && !endpoint.includes("/auth/")) {
@@ -364,10 +344,8 @@ class BaseApi {
   // ========================================================================
   // GOOGLE OAUTH AUTHENTICATION
   // ========================================================================
-  /**
-   * Internal: Authenticate with Google OAuth.
-   * Use googleLogin() instead.
-   */
+  // Internal: Authenticate with Google OAuth.
+  // Use googleLogin() instead.
   async _googleOAuthLogin(credential, nonce) {
     console.log("[API] Google OAuth login attempt");
     const data = await this.request("/api/auth/google/login", {
@@ -385,35 +363,31 @@ class BaseApi {
     console.log(`[API] Google OAuth successful (new_user: ${data.is_new_user})`);
     return data;
   }
-  /**
-   * Simplified Google OAuth login.
-   * 
-   * This is the default method for Google Sign-In. It handles the complete
-   * OAuth flow in a single call:
-   * 
-   * 1. Retrieve nonce from sessionStorage (must exist from generateOAuthNonce())
-   * 2. Send credential + nonce to backend for verification
-   * 3. Store JWT tokens on success
-   * 4. Clear nonce to prevent replay attacks
-   * 
-   * If any step fails, the entire operation fails cleanly. No partial states.
-   * 
-   * @param credential - The Google ID token (JWT from GoogleLogin onSuccess)
-   * @returns GoogleOAuthResponse with tokens, user data, and is_new_user flag
-   * @throws Error if nonce is missing or authentication fails
-   * 
-   * @example
-   * ```typescript
-   * // In component: generate nonce ONCE on mount
-   * const [nonce] = useState(() => generateOAuthNonce());
-   * 
-   * // Pass nonce to GoogleLogin, then on success:
-   * const handleSuccess = async (response: CredentialResponse) => {
-   *   const result = await authApi.googleLogin(response.credential!);
-   *   // Done! Tokens stored, nonce cleared, user authenticated.
-   * };
-   * ```
-   */
+  // Simplified Google OAuth login.
+  //
+  // This is the default method for Google Sign-In. It handles the complete
+  // OAuth flow in a single call:
+  //
+  // 1. Retrieve nonce from sessionStorage (must exist from generateOAuthNonce())
+  // 2. Send credential + nonce to backend for verification
+  // 3. Store JWT tokens on success
+  // 4. Clear nonce to prevent replay attacks
+  //
+  // If any step fails, the entire operation fails cleanly. No partial states.
+  //
+  // credential - The Google ID token (JWT from GoogleLogin onSuccess)
+  // Returns GoogleOAuthResponse with tokens, user data, and is_new_user flag
+  // Throws Error if nonce is missing or authentication fails
+  //
+  // Example:
+  //   // In component: generate nonce ONCE on mount
+  //   const [nonce] = useState(() => generateOAuthNonce());
+  //
+  //   // Pass nonce to GoogleLogin, then on success:
+  //   const handleSuccess = async (response: CredentialResponse) => {
+  //     const result = await authApi.googleLogin(response.credential!);
+  //     // Done! Tokens stored, nonce cleared, user authenticated.
+  //   };
   async googleLogin(credential) {
     console.log("[API] Google OAuth login");
     const nonce = getOAuthNonce();
@@ -428,12 +402,9 @@ class BaseApi {
   // ========================================================================
   // PASSWORD RESET FLOW
   // ========================================================================
-  /**
-   * Request a password reset email (forgot password flow).
-   * 
-   * @param email - The email address to send reset link to
-   * @returns Message confirming email was sent (or would be sent)
-   */
+  // Request a password reset email (forgot password flow).
+  // email - The email address to send reset link to.
+  // Returns message confirming email was sent (or would be sent).
   async requestPasswordReset(email) {
     console.log("[API] Requesting password reset for:", email);
     return this.request("/api/auth/request-password-reset", {
@@ -441,13 +412,10 @@ class BaseApi {
       body: JSON.stringify({ email })
     });
   }
-  /**
-   * Reset password using token from email.
-   * 
-   * @param token - The password reset token from the email link
-   * @param newPassword - The new password (min 8 characters)
-   * @returns Success message
-   */
+  // Reset password using token from email.
+  // token - The password reset token from the email link.
+  // newPassword - The new password (min 8 characters).
+  // Returns success message.
   async resetPassword(token, newPassword) {
     console.log("[API] Resetting password with token");
     return this.request("/api/auth/reset-password", {
@@ -458,12 +426,9 @@ class BaseApi {
   // ========================================================================
   // EMAIL VERIFICATION FLOW
   // ========================================================================
-  /**
-   * Verify email address using token from verification email.
-   * 
-   * @param token - The verification token from the email link
-   * @returns Success message
-   */
+  // Verify email address using token from verification email.
+  // token - The verification token from the email link.
+  // Returns success message.
   async verifyEmail(token) {
     console.log("[API] Verifying email with token");
     return this.request("/api/auth/verify-email", {
@@ -471,12 +436,9 @@ class BaseApi {
       body: JSON.stringify({ token })
     });
   }
-  /**
-   * Request a new verification email.
-   * 
-   * @param email - The email address to send verification to
-   * @returns Message confirming email was sent
-   */
+  // Request a new verification email.
+  // email - The email address to send verification to.
+  // Returns message confirming email was sent.
   async requestVerificationEmail(email) {
     console.log("[API] Requesting verification email for:", email);
     return this.request("/api/auth/request-verification-email", {
@@ -487,15 +449,12 @@ class BaseApi {
   // ========================================================================
   // SET PASSWORD (FOR OAUTH-ONLY ACCOUNTS)
   // ========================================================================
-  /**
-   * Set password for OAuth-only accounts.
-   * 
-   * Allows users who registered via Google OAuth to set a password
-   * so they can also log in with email/password.
-   * 
-   * @param newPassword - The password to set (min 8 characters)
-   * @returns Success message
-   */
+  // Set password for OAuth-only accounts.
+  //
+  // Allows users who registered via Google OAuth to set a password
+  // so they can also log in with email/password.
+  // newPassword - The password to set (min 8 characters).
+  // Returns success message.
   async setPassword(newPassword) {
     console.log("[API] Setting password for OAuth account");
     return this.request("/api/auth/set-password", {