najm-auth 1.1.15 → 1.1.17

package/dist/{FetchClient-DbrTaCVq.d.ts → FetchClient-aatsED1a.d.ts}

@@ -26,6 +26,7 @@ interface AuthState {
 interface DecodedToken {
     userId: string;
     jti?: string;
+    sessionVersion?: number;
     roles?: string[];
     permissions?: string[];
     exp?: number;
@@ -79,8 +80,16 @@ interface AuthClientConfig {
 /**
  * Auth event types
  */
-type AuthEvent = 'login' | 'logout' | 'tokenRefresh' | 'sessionExpired' | 'stateChange' | 'userUpdated';
-type AuthEventHandler<T = unknown> = (data: T) => void;
+interface AuthEventMap {
+    login: AuthUser;
+    logout: null;
+    tokenRefresh: null;
+    sessionExpired: null;
+    stateChange: AuthState;
+    userUpdated: AuthUser;
+}
+type AuthEvent = keyof AuthEventMap;
+type AuthEventHandler<K extends AuthEvent = AuthEvent> = (data: AuthEventMap[K]) => void;
 /**
  * Tab sync message types
  */
@@ -142,4 +151,4 @@ declare class FetchClient {
     private parseBody;
 }
 
-export { AuthError as A, type DecodedToken as D, FetchClient as F, type RetryConfig as R, type SyncPayload as S, type TabSyncMessage as T, type AuthClientConfig as a, type AuthState as b, type AuthUser as c, type AuthEvent as d, type AuthEventHandler as e, type ServerResponse as f, type TokenPair as g, type RequestOptions as h };
+export { AuthError as A, type DecodedToken as D, FetchClient as F, type RetryConfig as R, type SyncPayload as S, type TabSyncMessage as T, type AuthClientConfig as a, type AuthEventMap as b, type AuthState as c, type AuthUser as d, type AuthEvent as e, type AuthEventHandler as f, type ServerResponse as g, type TokenPair as h, type RequestOptions as i };

package/dist/{NajmAuthClient-C6yy4mxL.d.ts → NajmAuthClient-FCwA8LIg.d.ts}

@@ -1,4 +1,4 @@
-import { F as FetchClient, a as AuthClientConfig, c as AuthUser, b as AuthState, d as AuthEvent, e as AuthEventHandler } from './FetchClient-DbrTaCVq.js';
+import { F as FetchClient, a as AuthClientConfig, d as AuthUser, c as AuthState, e as AuthEvent, f as AuthEventHandler } from './FetchClient-aatsED1a.js';
 
 interface HydrateSession {
     user: AuthUser | null;
@@ -8,10 +8,14 @@ interface HydrateSession {
 }
 declare class NajmAuthClient {
     private config;
+    private static readonly MAX_REFRESH_FAILURES;
+    private static readonly CIRCUIT_RESET_MS;
     private state;
     private refreshTimer;
+    private refreshCircuitTimer;
     private refreshPromise;
     private fetchUserPromise;
+    private refreshFailures;
     private _hydrated;
     private listeners;
     private eventListeners;
@@ -32,6 +36,10 @@ declare class NajmAuthClient {
     forgotPassword(data: {
         email: string;
     }): Promise<void>;
+    changePassword(data: {
+        currentPassword: string;
+        newPassword: string;
+    }): Promise<void>;
     resetPassword(data: {
         token: string;
         newPassword: string;
@@ -51,15 +59,19 @@ declare class NajmAuthClient {
      */
     hydrate(session: HydrateSession | null): void;
     isHydrated(): boolean;
-    on<T = unknown>(event: AuthEvent, handler: AuthEventHandler<T>): void;
-    off(event: AuthEvent, handler: AuthEventHandler<any>): void;
+    on<K extends AuthEvent>(event: K, handler: AuthEventHandler<K>): void;
+    off<K extends AuthEvent>(event: K, handler: AuthEventHandler<K>): void;
     subscribe(listener: (state: AuthState) => void): () => void;
     destroy(): void;
+    private _refreshWithCircuit;
     private _doRefresh;
     private handleUnauthorized;
     private applyTokens;
     private scheduleRefresh;
     private clearRefreshTimer;
+    private clearRefreshCircuitTimer;
+    private resetRefreshFailures;
+    private registerRefreshFailure;
     private resetState;
     private getSyncPayload;
     private handleTabMessage;

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
-export { N as NajmAuthClient, c as createAuthClient } from '../NajmAuthClient-C6yy4mxL.js';
-import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../FetchClient-DbrTaCVq.js';
-export { a as AuthClientConfig, A as AuthError, d as AuthEvent, e as AuthEventHandler, b as AuthState, c as AuthUser, F as FetchClient, h as RequestOptions, R as RetryConfig, f as ServerResponse, g as TokenPair } from '../FetchClient-DbrTaCVq.js';
+export { H as HydrateSession, N as NajmAuthClient, c as createAuthClient } from '../NajmAuthClient-FCwA8LIg.js';
+import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../FetchClient-aatsED1a.js';
+export { a as AuthClientConfig, A as AuthError, e as AuthEvent, f as AuthEventHandler, b as AuthEventMap, c as AuthState, d as AuthUser, F as FetchClient, i as RequestOptions, R as RetryConfig, g as ServerResponse, h as TokenPair } from '../FetchClient-aatsED1a.js';
 
 /**
  * Decode a JWT token payload without verification.

package/dist/client/index.js

@@ -199,7 +199,7 @@ var INITIAL_STATE = {
   roles: [],
   permissions: []
 };
-var NajmAuthClient = class {
+var NajmAuthClient = class _NajmAuthClient {
   constructor(config) {
     this.config = config;
     this.prefix = config.authPrefix ?? "/auth";
@@ -220,10 +220,14 @@ var NajmAuthClient = class {
   static {
     __name(this, "NajmAuthClient");
   }
+  static MAX_REFRESH_FAILURES = 3;
+  static CIRCUIT_RESET_MS = 6e4;
   state = { ...INITIAL_STATE };
   refreshTimer = null;
+  refreshCircuitTimer = null;
   refreshPromise = null;
   fetchUserPromise = null;
+  refreshFailures = 0;
   _hydrated = false;
   // Subscriptions (for React useSyncExternalStore)
   listeners = /* @__PURE__ */ new Set();
@@ -270,8 +274,11 @@ var NajmAuthClient = class {
     this.emit("logout", null);
   }
   async refresh() {
+    if (this.refreshFailures >= _NajmAuthClient.MAX_REFRESH_FAILURES) {
+      throw new Error("Session expired (circuit open)");
+    }
     if (!this.refreshPromise) {
-      this.refreshPromise = this._doRefresh().finally(() => {
+      this.refreshPromise = this._refreshWithCircuit().finally(() => {
         this.refreshPromise = null;
       });
     }
@@ -290,8 +297,8 @@ var NajmAuthClient = class {
       const res = await this.api.get(`${this.prefix}/me`);
       this.state = { ...this.state, user: res.data };
       this.notify();
-      this.emit("userUpdated", this.state.user);
-      return this.state.user;
+      this.emit("userUpdated", res.data);
+      return res.data;
     } catch {
       return null;
     }
@@ -299,6 +306,12 @@ var NajmAuthClient = class {
   async forgotPassword(data) {
     await this.api.post(`${this.prefix}/forgot-password`, { body: data, skipAuth: true });
   }
+  async changePassword(data) {
+    await this.api.post(`${this.prefix}/change-password`, { body: data });
+    this.resetState();
+    this.tabSync?.broadcastLogout();
+    this.emit("logout", null);
+  }
   async resetPassword(data) {
     await this.api.post(`${this.prefix}/reset-password`, { body: data, skipAuth: true });
   }
@@ -343,6 +356,7 @@ var NajmAuthClient = class {
   hydrate(session) {
     if (this._hydrated) return;
     this._hydrated = true;
+    this.resetRefreshFailures();
     if (!session || !session.user) {
       this.state = { ...INITIAL_STATE };
       this.notify();
@@ -392,8 +406,10 @@ var NajmAuthClient = class {
   // =========================================================================
   destroy() {
     this.clearRefreshTimer();
+    this.clearRefreshCircuitTimer();
     this.tabSync?.destroy();
     this.tabSync = null;
+    this.refreshFailures = 0;
     this.state = { ...INITIAL_STATE };
     this.listeners.clear();
     this.eventListeners.clear();
@@ -401,24 +417,32 @@ var NajmAuthClient = class {
   // =========================================================================
   // Internals
   // =========================================================================
-  async _doRefresh() {
+  async _refreshWithCircuit() {
     try {
-      const res = await this.api.post(
-        `${this.prefix}/refresh`,
-        { skipAuth: true }
-      );
-      this.applyTokens(res.data);
-      this.tabSync?.broadcastSync(this.getSyncPayload());
-      this.emit("tokenRefresh", null);
+      await this._doRefresh();
+      this.resetRefreshFailures();
     } catch (err) {
-      if (err instanceof AuthError && err.status === 401) {
+      const shouldOpenCircuit = this.registerRefreshFailure(err);
+      if (shouldOpenCircuit) {
         this.resetState();
         this.emit("sessionExpired", null);
-        throw new Error("Session expired");
+        if (err instanceof AuthError && err.status === 401) {
+          throw new Error("Session expired");
+        }
+        throw new Error("Session expired (circuit open)");
       }
       throw err;
     }
   }
+  async _doRefresh() {
+    const res = await this.api.post(
+      `${this.prefix}/refresh`,
+      { skipAuth: true }
+    );
+    this.applyTokens(res.data);
+    this.tabSync?.broadcastSync(this.getSyncPayload());
+    this.emit("tokenRefresh", null);
+  }
   async handleUnauthorized() {
     try {
       await this.refresh();
@@ -428,6 +452,7 @@ var NajmAuthClient = class {
     }
   }
   applyTokens(tokens) {
+    this.resetRefreshFailures();
     const decoded = decodeToken(tokens.accessToken);
     this.state = {
       ...this.state,
@@ -454,6 +479,32 @@ var NajmAuthClient = class {
       this.refreshTimer = null;
     }
   }
+  clearRefreshCircuitTimer() {
+    if (this.refreshCircuitTimer) {
+      clearTimeout(this.refreshCircuitTimer);
+      this.refreshCircuitTimer = null;
+    }
+  }
+  resetRefreshFailures() {
+    this.refreshFailures = 0;
+    this.clearRefreshCircuitTimer();
+  }
+  registerRefreshFailure(err) {
+    if (err instanceof AuthError && err.status === 401) {
+      this.refreshFailures = _NajmAuthClient.MAX_REFRESH_FAILURES;
+    } else {
+      this.refreshFailures += 1;
+    }
+    if (this.refreshFailures >= _NajmAuthClient.MAX_REFRESH_FAILURES) {
+      this.clearRefreshCircuitTimer();
+      this.refreshCircuitTimer = setTimeout(() => {
+        this.refreshFailures = 0;
+        this.refreshCircuitTimer = null;
+      }, _NajmAuthClient.CIRCUIT_RESET_MS);
+      return true;
+    }
+    return false;
+  }
   resetState() {
     this.clearRefreshTimer();
     this.state = { ...INITIAL_STATE };

package/dist/client/react/index.d.ts

@@ -1,8 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, CSSProperties, ReactElement } from 'react';
-import { N as NajmAuthClient, H as HydrateSession } from '../../NajmAuthClient-C6yy4mxL.js';
-import { b as AuthState, c as AuthUser, A as AuthError } from '../../FetchClient-DbrTaCVq.js';
+import { N as NajmAuthClient, H as HydrateSession } from '../../NajmAuthClient-FCwA8LIg.js';
+import { c as AuthState, d as AuthUser, A as AuthError, e as AuthEvent, b as AuthEventMap } from '../../FetchClient-aatsED1a.js';
 
 interface AuthProviderProps {
     client: NajmAuthClient;
@@ -16,6 +16,8 @@ interface AuthProviderProps {
 }
 declare function AuthProvider({ client, children, initialSession }: AuthProviderProps): react_jsx_runtime.JSX.Element;
 
+declare function useAuthClient(): NajmAuthClient;
+
 /**
  * Subscribe to the full auth state.
  * Re-renders when any part of the state changes.
@@ -50,6 +52,19 @@ interface UseSessionReturn extends AuthState {
  */
 declare function useSession(opts?: UseSessionOptions): UseSessionReturn;
 
+interface UsePermissionsReturn {
+    can: (permission: string) => boolean;
+    hasRole: (role: string) => boolean;
+    hasAnyRole: (roles: string[]) => boolean;
+    permissions: string[];
+    roles: string[];
+}
+/**
+ * Access RBAC/PBAC checks as hooks.
+ * Permissions are decoded from JWT — no round-trip needed.
+ */
+declare function usePermissions(): UsePermissionsReturn;
+
 interface UseLoginOptions {
     onSuccess?: (user: AuthUser) => void;
     onError?: (error: AuthError | Error) => void;
@@ -64,6 +79,17 @@ interface UseLoginReturn {
 }
 declare function useLogin(opts?: UseLoginOptions): UseLoginReturn;
 
+interface UseRegisterOptions {
+    onSuccess?: (user: AuthUser) => void;
+    onError?: (error: AuthError | Error) => void;
+}
+interface UseRegisterReturn {
+    register: (data: Record<string, unknown>) => Promise<void>;
+    isLoading: boolean;
+    error: AuthError | Error | null;
+}
+declare function useRegister(opts?: UseRegisterOptions): UseRegisterReturn;
+
 interface UseLogoutOptions {
     onSuccess?: () => void;
     onError?: (error: Error) => void;
@@ -74,29 +100,89 @@ interface UseLogoutReturn {
 }
 declare function useLogout(opts?: UseLogoutOptions): UseLogoutReturn;
 
-interface UseRegisterOptions {
-    onSuccess?: (user: AuthUser) => void;
+interface UseForgotPasswordOptions {
+    onSuccess?: () => void;
     onError?: (error: AuthError | Error) => void;
 }
-interface UseRegisterReturn {
-    register: (data: Record<string, unknown>) => Promise<void>;
+interface UseForgotPasswordReturn {
+    forgotPassword: (data: {
+        email: string;
+    }) => Promise<void>;
     isLoading: boolean;
     error: AuthError | Error | null;
+    isSuccess: boolean;
+    reset: () => void;
 }
-declare function useRegister(opts?: UseRegisterOptions): UseRegisterReturn;
+declare function useForgotPassword(opts?: UseForgotPasswordOptions): UseForgotPasswordReturn;
 
-interface UsePermissionsReturn {
-    can: (permission: string) => boolean;
-    hasRole: (role: string) => boolean;
-    hasAnyRole: (roles: string[]) => boolean;
-    permissions: string[];
-    roles: string[];
+interface UseResetPasswordOptions {
+    onSuccess?: () => void;
+    onError?: (error: AuthError | Error) => void;
+}
+interface UseResetPasswordReturn {
+    resetPassword: (data: {
+        token: string;
+        newPassword: string;
+    }) => Promise<void>;
+    isLoading: boolean;
+    error: AuthError | Error | null;
+    isSuccess: boolean;
+    reset: () => void;
+}
+declare function useResetPassword(opts?: UseResetPasswordOptions): UseResetPasswordReturn;
+
+interface UseChangePasswordOptions {
+    onSuccess?: () => void;
+    onError?: (error: AuthError | Error) => void;
+}
+interface UseChangePasswordReturn {
+    changePassword: (data: {
+        currentPassword: string;
+        newPassword: string;
+    }) => Promise<void>;
+    isLoading: boolean;
+    error: AuthError | Error | null;
+    isSuccess: boolean;
+    reset: () => void;
 }
+declare function useChangePassword(opts?: UseChangePasswordOptions): UseChangePasswordReturn;
+
 /**
- * Access RBAC/PBAC checks as hooks.
- * Permissions are decoded from JWT — no round-trip needed.
+ * Subscribe to a specific auth event. Cleans up on unmount.
+ * Uses a stable ref for the handler to avoid re-subscribing on every render.
+ *
+ * @example
+ * ```tsx
+ * useAuthEvent('sessionExpired', () => {
+ *   toast.error('Session expired, please log in again');
+ *   router.push('/login');
+ * });
+ *
+ * useAuthEvent('login', (user) => {
+ *   analytics.track('login', { userId: user.id });
+ * });
+ * ```
  */
-declare function usePermissions(): UsePermissionsReturn;
+declare function useAuthEvent<K extends AuthEvent>(event: K, handler: (data: AuthEventMap[K]) => void): void;
+
+interface AuthEventEntry {
+    event: AuthEvent;
+    data: unknown;
+    timestamp: number;
+}
+/**
+ * Subscribe to all auth events. Returns a log of recent events.
+ * Useful for logging, debug panels, or analytics.
+ *
+ * @example
+ * ```tsx
+ * const events = useAuthEvents({ maxEntries: 50 });
+ * // events = [{ event: 'login', data: {...}, timestamp: 1234 }, ...]
+ * ```
+ */
+declare function useAuthEvents(opts?: {
+    maxEntries?: number;
+}): AuthEventEntry[];
 
 interface SignedInProps {
     children: ReactNode;
@@ -175,6 +261,52 @@ interface CanProps {
  */
 declare function Can({ permission, role, children, fallback }: CanProps): react_jsx_runtime.JSX.Element;
 
+interface RoleProps {
+    /** Required role name */
+    is?: string;
+    /** Allow any of these roles */
+    any?: string[];
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+/**
+ * Role-based conditional rendering gate.
+ *
+ * @example
+ * ```tsx
+ * <Role is="admin">
+ *   <AdminPanel />
+ * </Role>
+ *
+ * <Role any={['admin', 'editor']} fallback={<p>No access</p>}>
+ *   <ContentEditor />
+ * </Role>
+ * ```
+ */
+declare function Role(props: RoleProps): react_jsx_runtime.JSX.Element;
+
+interface IfAuthProps {
+    /** Render when authenticated — receives user */
+    authenticated: (user: AuthUser) => ReactNode;
+    /** Render when not authenticated */
+    unauthenticated?: () => ReactNode;
+    /** Render during loading */
+    loading?: () => ReactNode;
+}
+/**
+ * Render-prop component for full auth state branching.
+ *
+ * @example
+ * ```tsx
+ * <IfAuth
+ *   loading={() => <Skeleton />}
+ *   authenticated={(user) => <p>Welcome, {user.name}</p>}
+ *   unauthenticated={() => <Link href="/login">Sign in</Link>}
+ * />
+ * ```
+ */
+declare function IfAuth({ authenticated, unauthenticated, loading }: IfAuthProps): react_jsx_runtime.JSX.Element;
+
 interface ProtectedProps {
     children: ReactNode;
     /** URL to redirect unauthenticated users to */
@@ -221,6 +353,32 @@ interface UserNameProps {
  */
 declare function UserName({ fallback }: UserNameProps): react_jsx_runtime.JSX.Element;
 
+interface UserEmailProps {
+    fallback?: string;
+}
+/**
+ * Renders the user's email as plain text.
+ *
+ * @example
+ * ```tsx
+ * <p>Email: <UserEmail fallback="Not available" /></p>
+ * ```
+ */
+declare function UserEmail({ fallback }: UserEmailProps): react_jsx_runtime.JSX.Element;
+
+interface UserRoleProps {
+    fallback?: string;
+}
+/**
+ * Renders the user's primary role name.
+ *
+ * @example
+ * ```tsx
+ * <span>Role: <UserRole fallback="none" /></span>
+ * ```
+ */
+declare function UserRole({ fallback }: UserRoleProps): react_jsx_runtime.JSX.Element;
+
 interface UserAvatarProps {
     /** Pixel size of the avatar (default: 32) */
     size?: number;
@@ -247,6 +405,24 @@ interface UserAvatarProps {
  */
 declare function UserAvatar({ size, className, style, alt }: UserAvatarProps): react_jsx_runtime.JSX.Element;
 
+interface PermissionListProps {
+    /** Render function for each permission */
+    children: (permission: string, index: number) => ReactNode;
+    /** Rendered when the user has no permissions */
+    fallback?: ReactNode;
+}
+/**
+ * Iterates over the user's permissions with a render function.
+ *
+ * @example
+ * ```tsx
+ * <PermissionList fallback={<p>No permissions</p>}>
+ *   {(perm) => <Badge key={perm}>{perm}</Badge>}
+ * </PermissionList>
+ * ```
+ */
+declare function PermissionList({ children, fallback }: PermissionListProps): react_jsx_runtime.JSX.Element;
+
 interface SignOutButtonProps {
     /** A single clickable child element. Its `onClick` will be wired to logout. */
     children: ReactNode;
@@ -275,4 +451,45 @@ declare function SignOutButton({ children, onSuccess, onError }: SignOutButtonPr
     disabled?: boolean;
 }, string | react.JSXElementConstructor<any>>;
 
-export { AuthLoading, AuthProvider, Can, Protected, type SessionStatus, SignOutButton, SignedIn, SignedOut, UserAvatar, UserName, useAuth, useLogin, useLogout, usePermissions, useRegister, useSession, useUser };
+interface LoginButtonProps {
+    /** Where to navigate on click (default: '/login') */
+    href?: string;
+    children: ReactNode;
+}
+/**
+ * Wires a child element's onClick to navigate to the login page.
+ * Headless — bring your own button.
+ *
+ * @example
+ * ```tsx
+ * <SignedOut>
+ *   <LoginButton href="/login">
+ *     <Button>Sign in</Button>
+ *   </LoginButton>
+ * </SignedOut>
+ * ```
+ */
+declare function LoginButton({ href, children }: LoginButtonProps): ReactElement<{
+    onClick?: (e: unknown) => void;
+}, string | react.JSXElementConstructor<any>>;
+
+interface RedirectToLoginProps {
+    /** Login URL (default: '/login') */
+    to?: string;
+    /** Preserve current URL as ?from= param (default: true) */
+    preserveFrom?: boolean;
+}
+/**
+ * Immediately redirects to the login page. Renders nothing.
+ * Use inside <SignedOut> or <Protected fallback={...}>.
+ *
+ * @example
+ * ```tsx
+ * <SignedOut>
+ *   <RedirectToLogin to="/login" />
+ * </SignedOut>
+ * ```
+ */
+declare function RedirectToLogin({ to, preserveFrom }: RedirectToLoginProps): any;
+
+export { type AuthEventEntry, AuthLoading, AuthProvider, Can, IfAuth, LoginButton, PermissionList, Protected, RedirectToLogin, Role, type SessionStatus, SignOutButton, SignedIn, SignedOut, UserAvatar, UserEmail, UserName, UserRole, useAuth, useAuthClient, useAuthEvent, useAuthEvents, useChangePassword, useForgotPassword, useLogin, useLogout, usePermissions, useRegister, useResetPassword, useSession, useUser };