@pagamio/frontend-commons-lib/lib/auth/types/auth.types.d.ts

Pagamio library for Frontend reusable components like the form engine and table container

/**
 * @fileoverview Core type definitions for the authentication system.
 * This file contains all the base types and interfaces that can be extended
 * for specific authentication implementations.
 */
declare enum RoleNameProps {
    ROLE_ADMIN = "ROLE_ADMIN",
    ROLE_VENDOR = "ROLE_VENDOR",
    ROLE_MERCHANT = "ROLE_MERCHANT",
    ROLE_PROMOTER = "ROLE_PROMOTER",
    ROLE_ARTIST = "ROLE_ARTIST"
}
/**
 * Generic token structure containing essential token information
 */
export interface BaseTokenInfo {
    token: string;
    expiresIn: number;
    [key: string]: unknown;
}
/**
 * Generic user properties that should be present in all implementations
 */
export interface BaseUserInfo {
    id: number | string;
    userName: string;
    [key: string]: unknown;
}
/**
 * Generic authentication credentials interface
 * Can be extended to include specific credential requirements
 */
export interface BaseAuthCredentials {
    username?: string;
    password?: string;
    [key: string]: unknown;
}
/**
 * Core authentication state interface
 */
export interface BaseAuthState {
    isAuthenticated: boolean;
    isLoading: boolean;
    [key: string]: unknown;
}
/**
 * Generic error structure for authentication errors
 */
export interface BaseAuthError {
    code: string;
    message: string;
    [key: string]: unknown;
}
/**
 * Customizable type generator for specific authentication implementations
 * @template TRole - Role type extending BaseRole
 * @template TPermission - Permission type extending BasePermission
 * @template TPermission - Permission type extending string
 * @template TErrorCode - Error code type extending string
 * @template TTokenInfo - Token info type extending BaseTokenInfo
 * @template TCredentials - Credentials type extending BaseAuthCredentials
 * @template TError - Error type extending BaseAuthError
 */
export type CustomAuthConfig<TRole extends string = string, TPermission extends string = string, TErrorCode extends string = string, TUserInfo extends BaseUserInfo = BaseUserInfo, TTokenInfo extends BaseTokenInfo = BaseTokenInfo, TCredentials extends BaseAuthCredentials = BaseAuthCredentials, TError extends BaseAuthError = BaseAuthError> = {
    UserInfo: TUserInfo;
    TokenInfo: TTokenInfo;
    Credentials: TCredentials;
    Error: TError;
    Role: TRole;
    Permission: TPermission;
    ErrorCode: TErrorCode;
};
/**
 * Type generator for authentication response
 * @template T - CustomAuthConfig type
 */
export type AuthResponse<T extends CustomAuthConfig> = {
    user: T['UserInfo'];
    auth: {
        accessToken: T['TokenInfo'];
        refreshToken?: T['TokenInfo'];
    };
    [key: string]: unknown;
};
export type ExtractUserInfo<T extends CustomAuthConfig> = T['UserInfo'];
export type ExtractAuthError<T extends CustomAuthConfig> = T['Error'];
export type PartialAuthConfig<T extends CustomAuthConfig> = {
    [K in keyof T]?: Partial<T[K]>;
};
/**
 * Generic transformer interface for handling different authentication API response formats.
 * Implements the Strategy pattern to allow multiple response format handlers.
 *
 * @template T - Type extending CustomAuthConfig that defines the shape of user info, token info, and credentials
 *
 * @example
 * ```typescript
 * class MyApiTransformer implements ApiResponseTransformer<MyAuthConfig> {
 *   canHandle(response: any): boolean {
 *     return response.hasOwnProperty('mySpecificField');
 *   }
 *
 *   transform(response: any): AuthResponse<MyAuthConfig> {
 *     // Transform API response to AuthResponse format
 *     return {
 *       user: { ... },
 *       auth: { ... }
 *     };
 *   }
 * }
 * ```
 */
export interface ApiResponseTransformer<T extends CustomAuthConfig> {
    /**
     * Transforms raw API response into standardized AuthResponse format
     * @param response - Raw API response data
     * @param remember
     * @returns Standardized auth response matching the generic type T
     */
    transform(response: any, remember?: boolean): AuthResponse<T>;
    /**
     * Determines if this transformer can handle the given response format
     * @param response - Raw API response data to check
     * @returns True if this transformer can handle the response format
     */
    canHandle(response: any): boolean;
}
/**
 * Authentication configuration for the Events application.
 * Defines the structure of user information, token data, and login credentials
 * specific to the Events app authentication flow.
 *
 * @example
 * ```typescript
 * const authService = createAuthService<EventsAppAuthConfig>({
 *   baseUrl: 'https://api.events.example.com',
 *   endpoints: {
 *     login: '/auth/login',
 *     // ...other endpoints
 *   }
 * });
 * ```
 */
export interface EventsAppAuthConfig extends CustomAuthConfig {
    /** User information structure for Events app */
    UserInfo: {
        /** Unique identifier for the user */
        id: string;
        /** Username used for authentication */
        userName: string;
        /** User's first name */
        firstName: string;
        /** User's last name */
        lastName: string;
        /** Array of role identifiers assigned to the user */
        roles: string[];
        /** Primary role name */
        roleName: RoleNameProps;
        /** Description of the user's role */
        roleDesc: string;
        /** Associated vendor identifier */
        vendorId: number;
        /** Optional promoter identifier */
        promoterId: number | null;
        /** Company name associated with the user */
        company: string;
        /** IQ Retail access flag */
        hasIQRetailAccess?: boolean;
    };
    /** Token information structure */
    TokenInfo: {
        /** JWT or other authentication token */
        token: string;
        /** Token expiration time in seconds */
        expiresIn: number;
    };
    /** Login credentials structure */
    Credentials: {
        /** Username for authentication */
        username: string;
        /** User's password */
        password: string;
    };
}
/**
 * Authentication configuration for the VAS (Value Added Services) application.
 * Defines the structure of user information, token data, and login credentials
 * specific to the VAS app authentication flow.
 *
 * @example
 * ```typescript
 * const authService = createAuthService<VasAppAuthConfig>({
 *   baseUrl: 'https://api.vas.example.com',
 *   endpoints: {
 *     login: '/auth/login',
 *     // ...other endpoints
 *   }
 * });
 * ```
 */
export interface VasAppAuthConfig extends CustomAuthConfig {
    /** User information structure for VAS app */
    UserInfo: {
        /** Numeric user identifier */
        id: number;
        /** Username used for authentication */
        userName: string;
        /** Array of role identifiers assigned to the user */
        roles: string[];
        /** Secondary user identifier */
        userId: number;
        /** User type (e.g., PARTNER_USER, VENDOR_USER) */
        userType: string;
        /** User type identifier from backend */
        userTypeId: string;
        /** Flag indicating if the user has an associated wallet */
        hasWallet: boolean;
    };
    /** Token information structure */
    TokenInfo: {
        /** JWT or other authentication token */
        token: string;
        /** Token expiration time in seconds */
        expiresIn: number;
    };
    /** Login credentials structure */
    Credentials: {
        /** Username for authentication */
        username: string;
        /** User's password */
        password: string;
    };
}
/**
 * Authentication configuration for the Commerce application.
 * Defines the structure of user information, token data, and login credentials
 * specific to the Commerce app authentication flow.
 *
 * @example
 * ```typescript
 * const authService = createAuthService<CommerceAppAuthConfig>({
 *   baseUrl: 'https://api.commerce.example.com',
 *   endpoints: {
 *     login: '/auth/login',
 *     register: '/auth/register',
 *   }
 * });
 * ```
 */
export interface CommerceAppAuthConfig extends CustomAuthConfig {
    /** User information structure for Commerce app */
    UserInfo: {
        /** Unique identifier for the user */
        id: string;
        /** Username used for authentication */
        userName: string;
        /** Array of role identifiers assigned to the user */
        roles: string[];
        /** Current onboarding step */
        onboardingStep?: string | null;
        /** Secondary user identifier */
        userId: string;
        /** User type (e.g., customer, merchant, admin) */
        userType: string;
        /** User type identifier */
        userTypeId: string;
    };
    /** Token information structure */
    TokenInfo: {
        /** JWT or other authentication token */
        token: string;
        /** Token expiration time in seconds */
        expiresIn: number;
    };
    /** Login credentials structure */
    Credentials: {
        /** Username or email for authentication */
        username: string;
        /** User's password */
        password: string;
    };
}
export {};