verifio/dist/url/validator.d.ts

Smart validation and verification library for URLs, with future support for emails and more

import { VerifioURLResult, VerifioURLValidityResult, VerifioDomainResult } from './types';
export declare class VerifioURL {
    /**
     * Checks if a given string is a valid IPv4 address
     * @param {string} address - The string to check
     * @returns {boolean} True if the string is a valid IPv4 address, false otherwise
     * @example
     * VerifioURL.isIPv4Address('192.168.1.1') // returns true
     * VerifioURL.isIPv4Address('256.1.2.3') // returns false
     */
    static isIPv4Address(address: string): boolean;
    /**
     * Checks if a given string is a valid IPv6 address
     * @param {string} address - The string to check
     * @returns {boolean} True if the string is a valid IPv6 address, false otherwise
     * @example
     * VerifioURL.isIPv6Address('2001:0db8:85a3:0000:0000:8a2e:0370:7334') // returns true
     * VerifioURL.isIPv6Address('2001:0db8:85a3:0000') // returns false
     * VerifioURL.isIPv6Address('::ffff:192.168.1.1') // returns true
     */
    static isIPv6Address(address: string): boolean;
    /**
     * Checks if a given string is either a valid IPv4 or IPv6 address
     * @param {string} address - The string to check
     * @returns {boolean} True if the string is either a valid IPv4 or IPv6 address
     * @example
     * VerifioURL.isIPAddress('192.168.1.1') // returns true
     * VerifioURL.isIPAddress('2001:0db8::1') // returns true
     * VerifioURL.isIPAddress('256.256.256.256') // returns false
     * VerifioURL.isIPAddress('2001:xyz::1') // returns false
     */
    static isIPAddress(address: string): boolean;
    /**
     * Validates a URL and returns detailed results including any validation errors
     * @param {string} url - The URL to validate
     * @returns {VerifioURLValidityResult} Object containing validation results and any errors
     * @example
     * VerifioURL.isValid('https://example.com ') // returns { isValid: true, normalizedURL: 'https://example.com' }
     */
    static isValid(url: string): VerifioURLValidityResult;
    /**
     * Expands a shortened URL to its full form by following redirects
     * @param {string} url - The URL to expand
     * @param {number} [timeoutMs=5000] - The timeout in milliseconds for the request
     * @returns {Promise<string | null>} The expanded URL if successful, null if expansion fails
     * @throws {Error} If timeout value is invalid
     * @example
     * await VerifioURL.expand('https://bit.ly/xyz') // returns 'https://example.com/full-url'
     */
    static expand(url: string, timeoutMs?: number): Promise<string | null>;
    /**
     * Performs comprehensive URL verification including validation, expansion, and accessibility check
     * @param {string} url - The URL to verify
     * @returns {Promise<VerifioURLResult>} Complete verification results including validity, expansion, and accessibility
     * @example
     * await VerifioURL.verify('https://example.com')
     * // returns {
     * //   originalURL: 'https://example.com',
     * //   validity: { isValid: true },
     * //   expandedURL: 'https://example.com',
     * //   isAccessible: true
     * // }
     */
    static verify(url: string): Promise<VerifioURLResult>;
    /**
     * Extracts and validates the domain from a URL. For shortened URLs (e.g., bit.ly links),
     * the URL will first be expanded to get the final destination domain.
     * @param {string} url - The URL to extract domain from
     * @returns {Promise<VerifioDomainResult>} Object containing the extracted domain or error information
     * @example
     * // Regular URL
     * await VerifioURL.extractDomain('https://sub.example.com/path')
     * // returns {
     * //   success: true,
     * //   domain: 'sub.example.com'
     * // }
     *
     * // Shortened URL
     * await VerifioURL.extractDomain('https://bit.ly/xyz')
     * // returns {
     * //   success: true,
     * //   domain: 'example.com'  // domain from expanded URL
     * // }
     */
    static extractDomain(url: string): Promise<VerifioDomainResult>;
}