/**
 * Validates a Vehicle Identification Number (VIN) based on ISO 3779.
 *
 * Checks for:
 * - Exactly 17 characters length.
 * - Exclusion of characters I, O, and Q.
 * - Checksum validation using the check digit at position 9.
 *
 * @param vin - The VIN string to validate
 * @returns boolean indicating if the VIN is valid
 *
 * @example
 * ```typescript
 * import { validateVIN } from '@indodev/toolkit/vin';
 *
 * validateVIN('1HBHA82L7ZB000001'); // true
 * validateVIN('1HBHA82I7ZB000001'); // false (contains 'I')
 * ```
 */
declare function validateVIN(vin: string): boolean;

/**
 * VIN Validation options.
 */
interface VINOptions {
    /**
     * Whether to include error messages in the validation result.
     */
    includeDetails?: boolean;
}
/**
 * Options for masking a VIN.
 */
interface VINMaskOptions {
    /**
     * Number of characters visible at the start (default: 11).
     */
    visibleStart?: number;
    /**
     * Number of characters visible at the end (default: 0).
     */
    visibleEnd?: number;
    /**
     * Character to use for masking (default: '*').
     */
    maskChar?: string;
}
/**
 * Detailed validation result.
 */
interface VINValidationResult {
    isValid: boolean;
    error?: string;
}
/**
 * Information extracted from a valid Vehicle Identification Number (VIN).
 *
 * Contains parsed data including the world manufacturer identifier (WMI),
 * vehicle descriptor section (VDS), check digit, model year code, plant code,
 * and serial number.
 *
 * @example
 * ```typescript
 * const info: VINInfo = {
 *   wmi: '1HB',
 *   vds: 'HA82L7',
 *   checkDigit: 'Z',
 *   modelYearCode: 'B',
 *   plantCode: '7',
 *   serialNumber: 'ZB000001',
 *   isValid: true,
 * };
 * ```
 *
 * @public
 */
interface VINInfo {
    /**
     * World manufacturer identifier (positions 1-3).
     * Identifies the manufacturer and vehicle type.
     */
    wmi: string;
    /**
     * Vehicle descriptor section (positions 4-9).
     * Contains information about the vehicle attributes.
     */
    vds: string;
    /**
     * Check digit (position 9).
     * Used for VIN validation checksum.
     */
    checkDigit: string;
    /**
     * Model year code (position 10).
     * Indicates the vehicle's model year.
     */
    modelYearCode: string;
    /**
     * Plant code (position 11).
     * Identifies the manufacturing plant.
     */
    plantCode: string;
    /**
     * Serial number (positions 12-17).
     * Uniquely identifies the vehicle.
     */
    serialNumber: string;
    /**
     * Whether the VIN passed validation.
     * If `false`, other fields may contain partial data.
     */
    isValid: boolean;
}

/**
 * Error thrown when an invalid VIN is provided to a function.
 * Extends native Error with a `code` property for programmatic error handling.
 *
 * @example
 * ```typescript
 * try {
 *   requireVIN('invalid');
 * } catch (error) {
 *   if (error instanceof InvalidVINError) {
 *     console.log(error.code); // 'INVALID_VIN'
 *   }
 * }
 * ```
 *
 * @public
 */
declare class InvalidVINError extends Error {
    readonly code: "INVALID_VIN";
    constructor(message?: string);
}

/**
 * Parses a Vehicle Identification Number (VIN) into its component parts.
 *
 * Extracts the WMI (World Manufacturer Identifier), VDS (Vehicle Descriptor Section),
 * check digit, model year code, plant code, and serial number from a VIN.
 *
 * @param vin - The VIN string to parse
 * @returns VINInfo object with extracted components, or null if invalid
 *
 * @example
 * Valid VIN:
 * ```typescript
 * parseVIN('1HBHA82L7ZB000001');
 * // {
 * //   wmi: '1HB',
 * //   vds: 'HA82L7',
 * //   checkDigit: '7',
 * //   modelYearCode: 'Z',
 * //   plantCode: 'B',
 * //   serialNumber: '0000001',
 * //   isValid: true
 * // }
 * ```
 *
 * @example
 * Invalid VIN returns null:
 * ```typescript
 * parseVIN('invalid');
 * // null
 * ```
 *
 * @public
 */
declare function parseVIN(vin: string): VINInfo | null;

/**
 * Masks a Vehicle Identification Number (VIN) for privacy.
 *
 * By default, masks the serial number section (positions 12-17).
 * VIN must pass validation to be masked.
 *
 * @param vin - The VIN to mask
 * @param options - Mask options (visibleStart, visibleEnd, maskChar)
 * @returns Masked VIN string, or empty string if invalid
 *
 * @example
 * Default masking (masks serial section):
 * ```typescript
 * maskVIN('1HGBH41JXMN109186'); // '1HGBH41JXMN******'
 * ```
 *
 * @example
 * Custom visibility:
 * ```typescript
 * maskVIN('1HGBH41JXMN109186', { visibleEnd: 2 }); // '1HGBH41JXMN109***'
 * maskVIN('1HGBH41JXMN109186', { visibleEnd: 6 }); // '1HGBH41JXMN******'
 * ```
 *
 * @example
 * Custom mask character:
 * ```typescript
 * maskVIN('1HGBH41JXMN109186', { maskChar: '#' }); // '1HGBH41JXMN######'
 * ```
 *
 * @example
 * Invalid VIN returns empty string:
 * ```typescript
 * maskVIN('invalid');   // ''
 * maskVIN('');          // ''
 * ```
 *
 * @public
 */
declare function maskVIN(vin: string, options?: VINMaskOptions): string;

/**
 * Cleans a VIN by removing all non-alphanumeric characters
 * and converting to uppercase.
 *
 * @param vin - The VIN to clean
 * @returns Cleaned VIN string (alphanumeric only, uppercase), or empty string if empty input
 *
 * @example
 * ```typescript
 * cleanVIN('1HGBH-41JXMN-109186'); // '1HGBH41JXMN109186'
 * cleanVIN(' 1hgbh41jxmn109186 '); // '1HGBH41JXMN109186'
 * cleanVIN(''); // ''
 * ```
 *
 * @public
 */
declare function cleanVIN(vin: string): string;

export { InvalidVINError, type VINInfo, type VINMaskOptions, type VINOptions, type VINValidationResult, cleanVIN, maskVIN, parseVIN, validateVIN };