@arow-software/auth-client 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,251 @@
+import React, { ReactNode } from 'react';
+import { AxiosInstance } from 'axios';
+
+/**
+ * User object returned from ArowAuth
+ */
+interface User {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    emailVerified: boolean;
+    roles?: string[];
+    permissions?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * JWT token payload structure
+ */
+interface JwtPayload {
+    sub: string;
+    email: string;
+    given_name?: string;
+    family_name?: string;
+    name?: string;
+    picture?: string;
+    email_verified?: boolean;
+    roles?: string[];
+    permissions?: string[];
+    iat: number;
+    exp: number;
+    iss: string;
+    aud: string | string[];
+}
+/**
+ * Token pair returned from auth endpoints
+ */
+interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn?: number;
+    tokenType?: string;
+}
+/**
+ * Auth context state
+ */
+interface AuthState {
+    user: User | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    error: string | null;
+}
+/**
+ * Auth context value including actions
+ */
+interface AuthContextValue extends AuthState {
+    login: (redirectPath?: string) => void;
+    logout: () => Promise<void>;
+    refreshUser: () => Promise<void>;
+}
+/**
+ * Configuration for the auth client
+ */
+interface AuthConfig {
+    /**
+     * Base URL of the ArowAuth SSO server
+     * @example "https://sso.arowsoftware.co.uk"
+     */
+    ssoBaseUrl: string;
+    /**
+     * Client ID registered with ArowAuth
+     * @example "arowtrades"
+     */
+    clientId: string;
+    /**
+     * Base URL of your API that will validate tokens
+     * @example "http://localhost:5001"
+     */
+    apiBaseUrl?: string;
+    /**
+     * Custom redirect URI after SSO login (defaults to current origin + /callback)
+     */
+    redirectUri?: string;
+    /**
+     * Scopes to request from SSO (defaults to ['openid', 'email', 'profile'])
+     */
+    scopes?: string[];
+    /**
+     * Storage key prefix (defaults to 'arowauth')
+     */
+    storagePrefix?: string;
+    /**
+     * Use sessionStorage instead of localStorage (defaults to false)
+     */
+    useSessionStorage?: boolean;
+    /**
+     * Callback when tokens are refreshed
+     */
+    onTokenRefresh?: (tokens: TokenPair) => void;
+    /**
+     * Callback when auth error occurs
+     */
+    onAuthError?: (error: Error) => void;
+    /**
+     * Callback when user is logged out
+     */
+    onLogout?: () => void;
+}
+/**
+ * Props for AuthProvider component
+ */
+interface AuthProviderProps extends AuthConfig {
+    children: ReactNode;
+}
+
+/**
+ * Initialize token manager with configuration
+ */
+declare function initTokenManager(authConfig: AuthConfig): void;
+/**
+ * Decode a JWT token without verification
+ */
+declare function decodeJwt(token: string): JwtPayload | null;
+/**
+ * Get the access token from storage
+ */
+declare function getAccessToken(): string | null;
+/**
+ * Get the refresh token from storage
+ */
+declare function getRefreshToken(): string | null;
+/**
+ * Store tokens in storage
+ */
+declare function setTokens(accessToken: string, refreshToken: string): void;
+/**
+ * Clear all tokens from storage
+ */
+declare function clearTokens(): void;
+/**
+ * Check if the access token is expired or about to expire
+ */
+declare function isTokenExpired(token?: string | null): boolean;
+/**
+ * Check if we have a valid (non-expired) access token
+ */
+declare function hasValidToken(): boolean;
+/**
+ * Get user info from the current access token
+ */
+declare function getUserFromToken(): JwtPayload | null;
+/**
+ * Refresh tokens using the refresh token
+ * Handles concurrent refresh requests by returning the same promise
+ */
+declare function refreshTokens(): Promise<TokenPair | null>;
+/**
+ * Get a valid access token, refreshing if necessary
+ */
+declare function getValidAccessToken(): Promise<string | null>;
+
+/**
+ * Create and configure axios instance with auth interceptors
+ */
+declare function createAuthClient(axiosInstance: AxiosInstance, config: AuthConfig): AxiosInstance;
+/**
+ * Create a new axios instance with auth interceptors
+ */
+declare function createApiClient(config: AuthConfig): AxiosInstance;
+
+declare const AuthContext: React.Context<AuthContextValue | undefined>;
+/**
+ * AuthProvider component - wraps app with auth context
+ */
+declare function AuthProvider(props: AuthProviderProps): React.ReactElement;
+
+/**
+ * Hook to access auth state and actions
+ *
+ * @returns Auth context value with user, isAuthenticated, login, logout, etc.
+ * @throws Error if used outside of AuthProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { user, isAuthenticated, login, logout, isLoading } = useAuth();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   if (!isAuthenticated) {
+ *     return <button onClick={() => login()}>Login</button>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <p>Welcome, {user?.displayName || user?.email}!</p>
+ *       <button onClick={logout}>Logout</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useAuth(): AuthContextValue;
+/**
+ * Hook to check if user is authenticated (convenience wrapper)
+ *
+ * @returns Boolean indicating if user is authenticated
+ */
+declare function useIsAuthenticated(): boolean;
+/**
+ * Hook to get current user (convenience wrapper)
+ *
+ * @returns Current user or null
+ */
+declare function useUser(): User | null;
+
+/**
+ * Hook to get a configured axios instance with auth interceptors
+ *
+ * The returned axios instance will:
+ * - Automatically attach Bearer token to requests
+ * - Handle 401 responses by refreshing tokens and retrying
+ * - Queue concurrent requests during token refresh
+ *
+ * @returns Configured axios instance
+ * @throws Error if used outside of AuthProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const client = useAuthClient();
+ *
+ *   const fetchData = async () => {
+ *     try {
+ *       const response = await client.get('/api/data');
+ *       console.log(response.data);
+ *     } catch (error) {
+ *       console.error('Failed to fetch data', error);
+ *     }
+ *   };
+ *
+ *   return <button onClick={fetchData}>Fetch Data</button>;
+ * }
+ * ```
+ */
+declare function useAuthClient(): AxiosInstance;
+
+export { type AuthConfig, AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type AuthState, type JwtPayload, type TokenPair, type User, clearTokens, createApiClient, createAuthClient, decodeJwt, getAccessToken, getRefreshToken, getUserFromToken, getValidAccessToken, hasValidToken, initTokenManager, isTokenExpired, refreshTokens, setTokens, useAuth, useAuthClient, useIsAuthenticated, useUser };