@gofreego/tsutils 0.1.12 → 0.1.14

package/dist/index.d.mts

@@ -511,6 +511,15 @@ interface HttpResponse<T = any> {
     statusText: string;
     headers: Headers;
 }
+interface ErrorData {
+    code: number;
+    message: string;
+}
+interface HttpError extends Error {
+    status?: number;
+    statusText?: string;
+    data?: ErrorData;
+}
 
 declare class HttpClient {
     private baseURL;
@@ -519,12 +528,16 @@ declare class HttpClient {
     constructor(config?: HttpClientConfig);
     private buildURL;
     private request;
+    setDefaultHeader(key: string, value: string): void;
+    removeDefaultHeader(key: string): void;
+    getDefaultHeaders(): Record<string, string>;
     get<T = any>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
     post<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
     put<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
     patch<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
     delete<T = any>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
 }
+declare function extractErrorMessage(error: any): string;
 
 /**
  * Merges class names together
@@ -591,64 +604,179 @@ declare class LocalStorage {
 
 declare const getHighlighter: () => Promise<Highlighter>;
 
-/**
- * Context State Interface
- */
-interface AuthContextType {
-    isAuthenticated: boolean;
-    isLoading: boolean;
-}
-interface AuthProviderProps {
-    /** Name of the cookie containing the JWT token. Defaults to "authorization" */
-    cookieName?: string;
-    /** URL to redirect the user to if authentication fails */
-    redirectUrl: string;
-    /** Components to render if deeply authenticated */
-    children: ReactNode;
-    /** Custom fallback logic to fire upon failed auth (overrides redirectUrl behavior) */
-    onAuthFail?: () => void;
-    /** Custom callback fired strictly on successful auth */
-    onAuthSuccess?: () => void;
-    /** Optional loading element while checking cookies asynchronously */
-    loadingElement?: ReactNode;
+interface User {
+    id: string;
+    uuid: string;
+    username: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    /** Display name for the user */
+    name?: string | undefined;
+    /** URL to user's avatar image */
+    avatarUrl?: string | undefined;
+    emailVerified: boolean;
+    phoneVerified: boolean;
+    deactivated: boolean;
+    isActive: boolean;
+    isLocked: boolean;
+    failedLoginAttempts: number;
+    lastLoginAt?: string | undefined;
+    passwordChangedAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SignInMetadata {
+    /** Unique device identifier */
+    deviceId?: string | undefined;
+    /** Human-readable device name */
+    deviceName?: string | undefined;
+    /** web, mobile, desktop, tablet */
+    deviceType?: string | undefined;
+    lat?: number | undefined;
+    long?: number | undefined;
+}
+/** SignInRequest for user authentication */
+interface SignInRequest {
+    username: string;
+    password?: string | undefined;
+    otp?: string | undefined;
+    rememberMe?: boolean | undefined;
+    metadata?: SignInMetadata | undefined;
+    profiles?: boolean | undefined;
+    includePermissions?: boolean | undefined;
+    verificationId?: string | undefined;
+}
+/** SignInResponse with authentication tokens and user data */
+interface SignInResponse {
+    accessToken: string;
+    refreshToken: string;
+    /** Access token expiration (Unix timestamp) */
+    expiresAt: string;
+    /** Refresh token expiration (Unix timestamp) */
+    refreshExpiresAt: string;
+    user: User | undefined;
+    /** Session UUID for tracking */
+    sessionId: string;
+    message: string;
+}
+/** RefreshTokenRequest to refresh access token */
+interface RefreshTokenRequest {
+    refreshToken: string;
+    deviceId?: string | undefined;
+    profiles?: boolean | undefined;
+    includePermissions?: boolean | undefined;
+}
+/** RefreshTokenResponse with new tokens */
+interface RefreshTokenResponse {
+    accessToken: string;
+    /** New refresh token (rotation) */
+    refreshToken: string;
+    expiresAt: string;
+    refreshExpiresAt: string;
+    message: string;
+}
+/** LogoutRequest to end user session */
+interface LogoutRequest {
+    /** Specific session to logout */
+    sessionId?: string | undefined;
+    /** Logout from all devices */
+    allSessions?: boolean | undefined;
+}
+/** LogoutResponse */
+interface LogoutResponse {
+    success: boolean;
+    message: string;
+    /** Number of sessions ended */
+    sessionsTerminated: number;
+}
+/** GenerateLoginTokenRequest - user is identified from Authorization header */
+interface GenerateLoginTokenRequest {
+    /** Token TTL in seconds (default: 60, max: 300) */
+    ttlSeconds?: number | undefined;
+}
+/** SignInWithLoginTokenRequest - sign in using a single-use login token */
+interface SignInWithLoginTokenRequest {
+    loginToken: string;
+    metadata?: SignInMetadata | undefined;
+    profiles?: boolean | undefined;
+    includePermissions?: boolean | undefined;
+}
+/** GenerateLoginTokenResponse - short-lived single-use token */
+interface GenerateLoginTokenResponse {
+    /** Opaque single-use token (prefix: ltk_) */
+    loginToken: string;
+    /** Unix timestamp (seconds), TTL ~1 min */
+    expiresAt: string;
 }
-/**
- * AuthProvider verifies a JWT embedded in document.cookie.
- * Checks for existence, decodes the signature, and evaluates the `exp` claim.
- * Redirects heavily dependent or kicks custom callbacks if failed.
- */
-declare const AuthProvider: React.FC<AuthProviderProps>;
-/**
- * React Hook for easily accessing the authenticated JWT context
- */
-declare const useAuth: () => AuthContextType;
 
-/**
- * A utility class to manage user permissions using the browser's localStorage.
- * Employs an internal memory cache to prevent repeated synchronous parsing.
- */
-declare class PermissionManager {
-    private static cachedPermissions;
-    /**
-     * Saves an array of permission strings to local storage.
-     * @param permissions Array of permission strings.
-     */
-    static setPermissions(permissions: string[]): void;
-    /**
-     * Retrieves the currently stored permissions from local storage or memory cache.
-     * @returns Array of permission strings, or an empty array if none exist.
-     */
-    static getPermissions(): string[];
-    /**
-     * Clears all stored permissions from memory and local storage.
-     */
-    static clearPermissions(): void;
-    /**
-     * Checks whether the given permission string exists in the currently stored permissions.
-     * @param permission The permission string to check for.
-     * @returns True if the permission exists, false otherwise.
-     */
-    static hasPermission(permission: string): boolean;
+interface ISessionManager {
+    /** Persist session to localStorage and set the auth header. */
+    save(session: SignInResponse): void;
+    /** Partially update stored session fields (e.g. after token refresh). */
+    patch(updates: Partial<SignInResponse>): void;
+    /** Clear session from localStorage and remove the auth header. */
+    clear(): void;
+    /** Return the full stored session, or null if absent / unparseable. */
+    get(): SignInResponse | null;
+    /** Return the stored access token, or undefined. */
+    getAccessToken(): string | undefined;
+    /** Return the stored refresh token, or undefined. */
+    getRefreshToken(): string | undefined;
+    /** Return the session UUID, or undefined. */
+    getSessionId(): string | undefined;
+    /** True when a non-expired access token is stored. */
+    isAuthenticated(): boolean;
+    /** Called on app startup: restore the auth header or wipe an expired session. */
+    initialize(): void;
+}
+declare class SessionManager implements ISessionManager {
+    private static instance;
+    private readonly key;
+    private readonly client;
+    private cache;
+    private constructor();
+    static getInstance(client: HttpClient): SessionManager;
+    save(session: SignInResponse): void;
+    patch(updates: Partial<SignInResponse>): void;
+    clear(): void;
+    get(): SignInResponse | null;
+    getAccessToken(): string | undefined;
+    getRefreshToken(): string | undefined;
+    getSessionId(): string | undefined;
+    isAuthenticated(): boolean;
+    initialize(): void;
+    private setAuthToken;
+    private clearAuthToken;
+}
+
+interface IAuthService {
+    signIn(request: SignInRequest): Promise<SignInResponse>;
+    refreshToken(request?: Partial<RefreshTokenRequest>): Promise<RefreshTokenResponse>;
+    logout(request: LogoutRequest): Promise<LogoutResponse>;
+    generateLoginToken(request?: GenerateLoginTokenRequest): Promise<GenerateLoginTokenResponse>;
+    signInWithLoginToken(request: SignInWithLoginTokenRequest): Promise<SignInResponse>;
+    isAuthenticated(): boolean;
+    getAccessToken(): string | undefined;
+    getSessionDetails(): SignInResponse | null;
+    getSessionId(): string | undefined;
+    initializeAuth(): void;
+}
+declare class AuthService implements IAuthService {
+    private static instance;
+    private readonly client;
+    private readonly sessionManager;
+    private constructor();
+    static getInstance(client: HttpClient): AuthService;
+    signIn(request: SignInRequest): Promise<SignInResponse>;
+    refreshToken(request?: Partial<RefreshTokenRequest>): Promise<RefreshTokenResponse>;
+    logout(request: LogoutRequest): Promise<LogoutResponse>;
+    generateLoginToken(request?: GenerateLoginTokenRequest): Promise<GenerateLoginTokenResponse>;
+    signInWithLoginToken(request: SignInWithLoginTokenRequest): Promise<SignInResponse>;
+    isAuthenticated(): boolean;
+    getAccessToken(): string | undefined;
+    getSessionDetails(): SignInResponse | null;
+    getSessionId(): string | undefined;
+    initializeAuth(): void;
 }
 
-export { type AuthContextType, AuthProvider, type AuthProviderProps, ConfirmDialog, type ConfirmDialogProps, HttpClient, type HttpClientConfig, type HttpResponse, LocalStorage, type MenuItem, type Notification, type NotificationContextType, NotificationProvider, type NotificationProviderProps, PermissionManager, ReadmeViewer, type RequestConfig, type ResolvedThemeMode, SidebarLayout, type SidebarLayoutProps, type Theme, type ThemeContextValue, type ThemeMode, ThemeProvider, ThemeToggle, borderRadius, cn, darkTheme, debounce, elevation, fontSize, fontWeight, formatDate, getHighlighter, lightTheme, lineHeight, spacing, throttle, tokens, transition, useAuth, useNotification, useTheme, zIndex };
+export { AuthService, ConfirmDialog, type ConfirmDialogProps, type ErrorData, type GenerateLoginTokenRequest, type GenerateLoginTokenResponse, HttpClient, type HttpClientConfig, type HttpError, type HttpResponse, type IAuthService, type ISessionManager, LocalStorage, type LogoutRequest, type LogoutResponse, type MenuItem, type Notification, type NotificationContextType, NotificationProvider, type NotificationProviderProps, ReadmeViewer, type RefreshTokenRequest, type RefreshTokenResponse, type RequestConfig, type ResolvedThemeMode, SessionManager, SidebarLayout, type SidebarLayoutProps, type SignInMetadata, type SignInRequest, type SignInResponse, type SignInWithLoginTokenRequest, type Theme, type ThemeContextValue, type ThemeMode, ThemeProvider, ThemeToggle, type User, borderRadius, cn, darkTheme, debounce, elevation, extractErrorMessage, fontSize, fontWeight, formatDate, getHighlighter, lightTheme, lineHeight, spacing, throttle, tokens, transition, useNotification, useTheme, zIndex };

package/dist/index.d.ts

@@ -511,6 +511,15 @@ interface HttpResponse<T = any> {
     statusText: string;
     headers: Headers;
 }
+interface ErrorData {
+    code: number;
+    message: string;
+}
+interface HttpError extends Error {
+    status?: number;
+    statusText?: string;
+    data?: ErrorData;
+}
 
 declare class HttpClient {
     private baseURL;
@@ -519,12 +528,16 @@ declare class HttpClient {
     constructor(config?: HttpClientConfig);
     private buildURL;
     private request;
+    setDefaultHeader(key: string, value: string): void;
+    removeDefaultHeader(key: string): void;
+    getDefaultHeaders(): Record<string, string>;
     get<T = any>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
     post<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
     put<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
     patch<T = any>(url: string, data?: any, config?: RequestConfig): Promise<HttpResponse<T>>;
     delete<T = any>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
 }
+declare function extractErrorMessage(error: any): string;
 
 /**
  * Merges class names together
@@ -591,64 +604,179 @@ declare class LocalStorage {
 
 declare const getHighlighter: () => Promise<Highlighter>;
 
-/**
- * Context State Interface
- */
-interface AuthContextType {
-    isAuthenticated: boolean;
-    isLoading: boolean;
-}
-interface AuthProviderProps {
-    /** Name of the cookie containing the JWT token. Defaults to "authorization" */
-    cookieName?: string;
-    /** URL to redirect the user to if authentication fails */
-    redirectUrl: string;
-    /** Components to render if deeply authenticated */
-    children: ReactNode;
-    /** Custom fallback logic to fire upon failed auth (overrides redirectUrl behavior) */
-    onAuthFail?: () => void;
-    /** Custom callback fired strictly on successful auth */
-    onAuthSuccess?: () => void;
-    /** Optional loading element while checking cookies asynchronously */
-    loadingElement?: ReactNode;
+interface User {
+    id: string;
+    uuid: string;
+    username: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    /** Display name for the user */
+    name?: string | undefined;
+    /** URL to user's avatar image */
+    avatarUrl?: string | undefined;
+    emailVerified: boolean;
+    phoneVerified: boolean;
+    deactivated: boolean;
+    isActive: boolean;
+    isLocked: boolean;
+    failedLoginAttempts: number;
+    lastLoginAt?: string | undefined;
+    passwordChangedAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SignInMetadata {
+    /** Unique device identifier */
+    deviceId?: string | undefined;
+    /** Human-readable device name */
+    deviceName?: string | undefined;
+    /** web, mobile, desktop, tablet */
+    deviceType?: string | undefined;
+    lat?: number | undefined;
+    long?: number | undefined;
+}
+/** SignInRequest for user authentication */
+interface SignInRequest {
+    username: string;
+    password?: string | undefined;
+    otp?: string | undefined;
+    rememberMe?: boolean | undefined;
+    metadata?: SignInMetadata | undefined;
+    profiles?: boolean | undefined;
+    includePermissions?: boolean | undefined;
+    verificationId?: string | undefined;
+}
+/** SignInResponse with authentication tokens and user data */
+interface SignInResponse {
+    accessToken: string;
+    refreshToken: string;
+    /** Access token expiration (Unix timestamp) */
+    expiresAt: string;
+    /** Refresh token expiration (Unix timestamp) */
+    refreshExpiresAt: string;
+    user: User | undefined;
+    /** Session UUID for tracking */
+    sessionId: string;
+    message: string;
+}
+/** RefreshTokenRequest to refresh access token */
+interface RefreshTokenRequest {
+    refreshToken: string;
+    deviceId?: string | undefined;
+    profiles?: boolean | undefined;
+    includePermissions?: boolean | undefined;
+}
+/** RefreshTokenResponse with new tokens */
+interface RefreshTokenResponse {
+    accessToken: string;
+    /** New refresh token (rotation) */
+    refreshToken: string;
+    expiresAt: string;
+    refreshExpiresAt: string;
+    message: string;
+}
+/** LogoutRequest to end user session */
+interface LogoutRequest {
+    /** Specific session to logout */
+    sessionId?: string | undefined;
+    /** Logout from all devices */
+    allSessions?: boolean | undefined;
+}
+/** LogoutResponse */
+interface LogoutResponse {
+    success: boolean;
+    message: string;
+    /** Number of sessions ended */
+    sessionsTerminated: number;
+}
+/** GenerateLoginTokenRequest - user is identified from Authorization header */
+interface GenerateLoginTokenRequest {
+    /** Token TTL in seconds (default: 60, max: 300) */
+    ttlSeconds?: number | undefined;
+}
+/** SignInWithLoginTokenRequest - sign in using a single-use login token */
+interface SignInWithLoginTokenRequest {
+    loginToken: string;
+    metadata?: SignInMetadata | undefined;
+    profiles?: boolean | undefined;
+    includePermissions?: boolean | undefined;
+}
+/** GenerateLoginTokenResponse - short-lived single-use token */
+interface GenerateLoginTokenResponse {
+    /** Opaque single-use token (prefix: ltk_) */
+    loginToken: string;
+    /** Unix timestamp (seconds), TTL ~1 min */
+    expiresAt: string;
 }
-/**
- * AuthProvider verifies a JWT embedded in document.cookie.
- * Checks for existence, decodes the signature, and evaluates the `exp` claim.
- * Redirects heavily dependent or kicks custom callbacks if failed.
- */
-declare const AuthProvider: React.FC<AuthProviderProps>;
-/**
- * React Hook for easily accessing the authenticated JWT context
- */
-declare const useAuth: () => AuthContextType;
 
-/**
- * A utility class to manage user permissions using the browser's localStorage.
- * Employs an internal memory cache to prevent repeated synchronous parsing.
- */
-declare class PermissionManager {
-    private static cachedPermissions;
-    /**
-     * Saves an array of permission strings to local storage.
-     * @param permissions Array of permission strings.
-     */
-    static setPermissions(permissions: string[]): void;
-    /**
-     * Retrieves the currently stored permissions from local storage or memory cache.
-     * @returns Array of permission strings, or an empty array if none exist.
-     */
-    static getPermissions(): string[];
-    /**
-     * Clears all stored permissions from memory and local storage.
-     */
-    static clearPermissions(): void;
-    /**
-     * Checks whether the given permission string exists in the currently stored permissions.
-     * @param permission The permission string to check for.
-     * @returns True if the permission exists, false otherwise.
-     */
-    static hasPermission(permission: string): boolean;
+interface ISessionManager {
+    /** Persist session to localStorage and set the auth header. */
+    save(session: SignInResponse): void;
+    /** Partially update stored session fields (e.g. after token refresh). */
+    patch(updates: Partial<SignInResponse>): void;
+    /** Clear session from localStorage and remove the auth header. */
+    clear(): void;
+    /** Return the full stored session, or null if absent / unparseable. */
+    get(): SignInResponse | null;
+    /** Return the stored access token, or undefined. */
+    getAccessToken(): string | undefined;
+    /** Return the stored refresh token, or undefined. */
+    getRefreshToken(): string | undefined;
+    /** Return the session UUID, or undefined. */
+    getSessionId(): string | undefined;
+    /** True when a non-expired access token is stored. */
+    isAuthenticated(): boolean;
+    /** Called on app startup: restore the auth header or wipe an expired session. */
+    initialize(): void;
+}
+declare class SessionManager implements ISessionManager {
+    private static instance;
+    private readonly key;
+    private readonly client;
+    private cache;
+    private constructor();
+    static getInstance(client: HttpClient): SessionManager;
+    save(session: SignInResponse): void;
+    patch(updates: Partial<SignInResponse>): void;
+    clear(): void;
+    get(): SignInResponse | null;
+    getAccessToken(): string | undefined;
+    getRefreshToken(): string | undefined;
+    getSessionId(): string | undefined;
+    isAuthenticated(): boolean;
+    initialize(): void;
+    private setAuthToken;
+    private clearAuthToken;
+}
+
+interface IAuthService {
+    signIn(request: SignInRequest): Promise<SignInResponse>;
+    refreshToken(request?: Partial<RefreshTokenRequest>): Promise<RefreshTokenResponse>;
+    logout(request: LogoutRequest): Promise<LogoutResponse>;
+    generateLoginToken(request?: GenerateLoginTokenRequest): Promise<GenerateLoginTokenResponse>;
+    signInWithLoginToken(request: SignInWithLoginTokenRequest): Promise<SignInResponse>;
+    isAuthenticated(): boolean;
+    getAccessToken(): string | undefined;
+    getSessionDetails(): SignInResponse | null;
+    getSessionId(): string | undefined;
+    initializeAuth(): void;
+}
+declare class AuthService implements IAuthService {
+    private static instance;
+    private readonly client;
+    private readonly sessionManager;
+    private constructor();
+    static getInstance(client: HttpClient): AuthService;
+    signIn(request: SignInRequest): Promise<SignInResponse>;
+    refreshToken(request?: Partial<RefreshTokenRequest>): Promise<RefreshTokenResponse>;
+    logout(request: LogoutRequest): Promise<LogoutResponse>;
+    generateLoginToken(request?: GenerateLoginTokenRequest): Promise<GenerateLoginTokenResponse>;
+    signInWithLoginToken(request: SignInWithLoginTokenRequest): Promise<SignInResponse>;
+    isAuthenticated(): boolean;
+    getAccessToken(): string | undefined;
+    getSessionDetails(): SignInResponse | null;
+    getSessionId(): string | undefined;
+    initializeAuth(): void;
 }
 
-export { type AuthContextType, AuthProvider, type AuthProviderProps, ConfirmDialog, type ConfirmDialogProps, HttpClient, type HttpClientConfig, type HttpResponse, LocalStorage, type MenuItem, type Notification, type NotificationContextType, NotificationProvider, type NotificationProviderProps, PermissionManager, ReadmeViewer, type RequestConfig, type ResolvedThemeMode, SidebarLayout, type SidebarLayoutProps, type Theme, type ThemeContextValue, type ThemeMode, ThemeProvider, ThemeToggle, borderRadius, cn, darkTheme, debounce, elevation, fontSize, fontWeight, formatDate, getHighlighter, lightTheme, lineHeight, spacing, throttle, tokens, transition, useAuth, useNotification, useTheme, zIndex };
+export { AuthService, ConfirmDialog, type ConfirmDialogProps, type ErrorData, type GenerateLoginTokenRequest, type GenerateLoginTokenResponse, HttpClient, type HttpClientConfig, type HttpError, type HttpResponse, type IAuthService, type ISessionManager, LocalStorage, type LogoutRequest, type LogoutResponse, type MenuItem, type Notification, type NotificationContextType, NotificationProvider, type NotificationProviderProps, ReadmeViewer, type RefreshTokenRequest, type RefreshTokenResponse, type RequestConfig, type ResolvedThemeMode, SessionManager, SidebarLayout, type SidebarLayoutProps, type SignInMetadata, type SignInRequest, type SignInResponse, type SignInWithLoginTokenRequest, type Theme, type ThemeContextValue, type ThemeMode, ThemeProvider, ThemeToggle, type User, borderRadius, cn, darkTheme, debounce, elevation, extractErrorMessage, fontSize, fontWeight, formatDate, getHighlighter, lightTheme, lineHeight, spacing, throttle, tokens, transition, useNotification, useTheme, zIndex };