/**
 * @module JwtUtils
 * @description A comprehensive collection of utility functions for working with JSON Web Tokens (JWT).
 * Provides methods for decoding, parsing, validating, and managing JWT tokens including expiration checks,
 * claim extraction, and token lifecycle management.
 * @example
 * ```typescript
 * import { JwtUtils } from 'houser-js-utils';
 *
 * // Decode a JWT token
 * const payload = JwtUtils.decodeToken(token);
 *
 * // Check if token is expired
 * const isExpired = JwtUtils.isTokenExpired(token);
 *
 * // Get specific claim
 * const userId = JwtUtils.getPayloadClaim(token, 'sub');
 * ```
 */
/**
 * Interface representing the structure of a JWT payload with standard claims.
 */
export interface JwtPayload {
    /** Subject (user ID) */
    sub?: string;
    /** Issuer */
    iss?: string;
    /** Audience */
    aud?: string;
    /** Expiration time (Unix timestamp in seconds) */
    exp?: number;
    /** Not before time (Unix timestamp in seconds) */
    nbf?: number;
    /** Issued at time (Unix timestamp in seconds) */
    iat?: number;
    /** JWT ID */
    jti?: string;
    /** Additional custom claims */
    [key: string]: any;
}
export declare const JwtUtils: {
    /**
     * Decodes and parses a JWT token into its payload object.
     * @param token - The JWT token string to decode
     * @returns The decoded JWT payload containing all claims
     * @throws Error if token is invalid, malformed, or cannot be parsed
     * @example
     * ```typescript
     * const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
     * const payload = JwtUtils.decodeToken(token);
     * console.log(payload.sub); // '1234567890'
     * console.log(payload.exp); // 1234567890
     * ```
     */
    decodeToken(token: string): JwtPayload;
    /**
     * Extracts a specific claim value from a JWT token's payload.
     * @param token - The JWT token string to parse
     * @param claim - The name of the claim to retrieve
     * @returns The claim value or undefined if the claim is not found
     * @throws Error if token is invalid or cannot be parsed
     * @example
     * ```typescript
     * const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
     * const userId = JwtUtils.getPayloadClaim(token, 'sub'); // "1234567890"
     * const role = JwtUtils.getPayloadClaim(token, 'role'); // "admin"
     * const email = JwtUtils.getPayloadClaim(token, 'email'); // "user@example.com"
     * ```
     */
    getPayloadClaim(token: string, claim: string): any;
    /**
     * Calculates the time remaining until a JWT token expires.
     * @param token - The JWT token to check for expiration
     * @returns The time remaining in seconds, or null if no expiration time is set
     * @throws Error if token is invalid or cannot be parsed
     * @example
     * ```typescript
     * const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
     * const timeRemaining = JwtUtils.getTokenTimeRemaining(token);
     * if (timeRemaining !== null) {
     *   console.log(`Token expires in ${timeRemaining} seconds`);
     * } else {
     *   console.log('Token has no expiration time');
     * }
     * ```
     */
    getTokenTimeRemaining(token: string): number | null;
    /**
     * Validates if a string follows the correct JWT token format (three base64url-encoded parts).
     * @param token - The string to validate as a JWT token
     * @returns True if the string follows JWT format, false otherwise
     * @example
     * ```typescript
     * const validToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature';
     * const invalidToken = 'not.a.jwt.token';
     *
     * JwtUtils.isJwt(validToken); // true
     * JwtUtils.isJwt(invalidToken); // false
     * JwtUtils.isJwt('invalid'); // false
     * ```
     */
    isJwt(token: string): boolean;
    /**
     * Checks if the JWT token stored in localStorage will expire within the next hour.
     * @returns True if token will expire within an hour, false if not expiring soon, null if no token exists
     * @example
     * ```typescript
     * const result = JwtUtils.isTokenExpiringSoon();
     * if (result === null) {
     *   console.log('No token found in localStorage');
     * } else if (result) {
     *   console.log('Token expires soon - consider refreshing');
     * } else {
     *   console.log('Token is still valid for more than an hour');
     * }
     * ```
     */
    isTokenExpiringSoon(): boolean | null;
    /**
     * Determines if a JWT token has expired based on its expiration time claim.
     * @param token - The JWT token string to check
     * @returns True if the token is expired, false if still valid or has no expiration
     * @throws Error if token is invalid or cannot be parsed
     * @example
     * ```typescript
     * const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
     *
     * if (JwtUtils.isTokenExpired(token)) {
     *   console.log('Token has expired - please authenticate again');
     * } else {
     *   console.log('Token is still valid');
     * }
     * ```
     */
    isTokenExpired(token: string): boolean;
    /**
     * Performs comprehensive validation of a JWT token including expiration and required claims.
     * @param token - The JWT token string to validate
     * @param requiredClaims - Array of claim names that must be present in the token
     * @returns True if token is valid, not expired, and contains all required claims
     * @throws Error if token is invalid or cannot be parsed
     * @example
     * ```typescript
     * const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
     *
     * // Basic validation (just check expiration)
     * const isValid = JwtUtils.isValidToken(token);
     *
     * // Validation with required claims
     * const isValidWithClaims = JwtUtils.isValidToken(token, ['sub', 'role', 'email']);
     *
     * if (isValidWithClaims) {
     *   console.log('Token is valid and has all required claims');
     * }
     * ```
     */
    isValidToken(token: string, requiredClaims?: string[]): boolean;
};