/**
 * Common Utils Module based on the native common_utils_bridge C library.
 *
 * This module provides a collection of common utilities organized into namespaces.
 * It is designed as a stateless, singleton-like utility library.
 *
 * Features:
 * - `crypto`: Hashing (MD5, HMAC-MD5), symmetric encryption (AES),
 *             and asymmetric encryption (RSA).
 * - `fs`: File system operations, such as converting files to/from Base64.
 * - `codec`: Data encoding and decoding functions (Hex, Base64, UTF-8, etc.).
 * - `random`: Generation of cryptographically secure random bytes and simple
 *           random strings.
 *
 * Usage:
 * import dxCommonUtils from './dxCommonUtils.js';
 * const md5Hash = dxCommonUtils.crypto.md5('hello');
 *
 * Doc/Demo: https://github.com/DejaOS/DejaOS
 */
import { commonUtilsClass } from './libvbar-m-dxcommonutils.so'

const dxCommonUtils = {};

// ----------- Constants & Enums -------------------
dxCommonUtils.AES_MODE = {
    ECB: 'ECB',
    CBC: 'CBC',
    CFB: 'CFB',
    OFB: 'OFB',
    CTR: 'CTR'
};

dxCommonUtils.AES_KEY_SIZE = {
    BITS_128: 128,
    BITS_192: 192,
    BITS_256: 256
};

dxCommonUtils.AES_PADDING = {
    PKCS7: 'PKCS7',
    NONE: 'NoPadding'
};

dxCommonUtils.RSA_KEY_SIZE = {
    BITS_1024: 1024,
    BITS_2048: 2048,
    BITS_4096: 4096
};

const utils = new commonUtilsClass();

// ----------- Crypto Namespace -------------------
dxCommonUtils.crypto = {};
dxCommonUtils.crypto.aes = {};
dxCommonUtils.crypto.rsa = {};

/**
 * Calculates MD5 hash of the input string.
 * @param {string|ArrayBuffer|Uint8Array} data - The data to hash. If a string is provided, it will be treated as UTF-8.
 * @returns {string} MD5 hash in hexadecimal format.
 */
dxCommonUtils.crypto.md5 = function (data) {
    const buffer = _normalizeDataToBuffer(data, false, 'Data');
    return utils.md5(buffer);
}

/**
 * Calculates HMAC-MD5 hash using the provided key.
 * @param {string|ArrayBuffer|Uint8Array} data - The data to hash. If a string is provided, it will be treated as UTF-8.
 * @param {string|ArrayBuffer|Uint8Array} key - The secret key for HMAC. If a string is provided, it will be treated as UTF-8.
 * @returns {string} HMAC-MD5 hash in hexadecimal format.
 */
dxCommonUtils.crypto.hmacMd5 = function (data, key) {
    const dataBuffer = _normalizeDataToBuffer(data, false, 'Data');
    const keyBuffer = _normalizeDataToBuffer(key, false, 'Key');
    return utils.hmacMd5(dataBuffer, keyBuffer);
}

/**
 * Calculates a hash of the input data using the specified algorithm.
 * @param {string|ArrayBuffer|Uint8Array} data - The data to hash. If a string is provided, it will be treated as UTF-8.
 * @param {string} [hashAlgorithm='SHA-256'] - The hash algorithm to use (e.g., 'SHA-256', 'MD5', 'SHA1', 'SHA-384', 'SHA-512').
 * @returns {string} The hash in hexadecimal format.
 */
dxCommonUtils.crypto.hash = function (data, hashAlgorithm = 'SHA-256') {
    const buffer = _normalizeDataToBuffer(data, false, 'Data');
    return utils.hash(buffer, hashAlgorithm);
}

/**
 * Encrypts data using AES encryption.
 * @param {string|ArrayBuffer|Uint8Array} data - The data to encrypt. If a string is provided, it will be treated as UTF-8.
 * @param {string|ArrayBuffer|Uint8Array} key - The encryption key. Can be a hex string, an ArrayBuffer, or a Uint8Array.
 * @param {object} options - Encryption options.
 * @param {string} [options.mode='CBC'] - The AES mode, from dxCommonUtils.AES_MODE.
 * @param {number} [options.keySize=256] - The key size in bits (128, 192, or 256), from dxCommonUtils.AES_KEY_SIZE.
 * @param {string|ArrayBuffer|Uint8Array} [options.iv] - The initialization vector (required for non-ECB modes). This is ignored if useSalt is true.
 * @param {string} [options.padding='PKCS7'] - The padding scheme, from dxCommonUtils.AES_PADDING. Defaults to PKCS7.
 * @param {boolean} [options.useSalt=false] - If true, generates an OpenSSL-compatible salted ciphertext. The provided 'key' is used as a password (UTF-8 string) to derive the actual key and IV.
 * @returns {string} The encrypted data as a Base64 string.
 */
dxCommonUtils.crypto.aes.encrypt = function (data, key, options = {}) {
    // Set default options, including PKCS7 padding by default
    const finalOptions = Object.assign({
        mode: dxCommonUtils.AES_MODE.CBC,
        keySize: 256,
        padding: dxCommonUtils.AES_PADDING.PKCS7,
        useSalt: false // Default to false for backward compatibility
    }, options);

    let keyBuffer;
    if (finalOptions.useSalt) {
        // In salted mode, a string key is treated as a password (UTF-8).
        keyBuffer = _normalizeDataToBuffer(key, false, 'Key');
    } else {
        // In non-salted mode, a string key is treated as a raw key in hex format.
        keyBuffer = _normalizeHexInput(key, 'Key');

        // Key length must be validated for non-salted keys.
        const expectedKeyLength = finalOptions.keySize / 8;
        if (keyBuffer.byteLength !== expectedKeyLength) {
            throw new Error(`Key length must be ${expectedKeyLength} bytes for ${finalOptions.keySize}-bit AES`);
        }
    }

    // Validate mode and keySize
    if (!Object.values(dxCommonUtils.AES_MODE).includes(finalOptions.mode)) {
        throw new Error("options.mode must be one of dxCommonUtils.AES_MODE values");
    }
    if (!Object.values(dxCommonUtils.AES_KEY_SIZE).includes(finalOptions.keySize)) {
        throw new Error("options.keySize must be one of dxCommonUtils.AES_KEY_SIZE values");
    }

    // Validate padding
    if (finalOptions.padding !== undefined) {
        if (typeof finalOptions.padding !== 'string' || !Object.values(dxCommonUtils.AES_PADDING).includes(finalOptions.padding)) {
            throw new Error("options.padding must be one of dxCommonUtils.AES_PADDING values");
        }
        if (finalOptions.padding === dxCommonUtils.AES_PADDING.NONE) {
            const dataBuffer = _normalizeDataToBuffer(data, false, 'Data');
            if (dataBuffer.byteLength % 16 !== 0) {
                throw new Error("Data length must be a multiple of 16 bytes when using NoPadding");
            }
        }
    }

    const ivBuffer = (finalOptions.iv && !finalOptions.useSalt) ? _normalizeHexInput(finalOptions.iv) : null;
    const dataBuffer = _normalizeDataToBuffer(data, false, 'Data');

    const encrypted = utils.aesEncrypt(dataBuffer, keyBuffer, { ...finalOptions, iv: ivBuffer });
    if (encrypted === null) {
        throw new Error("AES encryption failed. Check parameters.");
    }
    return dxCommonUtils.codec.arrayBufferToBase64(encrypted);
};

/**
 * Decrypts data using AES encryption.
 * Note: This function automatically handles OpenSSL's "Salted__" format if present in the encrypted data.
 * @param {string|ArrayBuffer|Uint8Array} encryptedData - The encrypted data. If a string, it is assumed to be Base64.
 * @param {string|ArrayBuffer|Uint8Array} key - The decryption key. If a string, it will be treated as a password (UTF-8) for salted data, or as a hex string for non-salted data.
 * @param {object} options - Decryption options.
 * @param {string} [options.mode='CBC'] - The AES mode, from dxCommonUtils.AES_MODE.
 * @param {number} [options.keySize=256] - The key size in bits (128, 192, or 256), from dxCommonUtils.AES_KEY_SIZE. This is also used for key derivation in "Salted__" format.
 * @param {string|ArrayBuffer|Uint8Array} [options.iv] - The initialization vector (required for non-ECB modes and non-salted data). If a string, it must be Hex.
 * @param {string} [options.padding='PKCS7'] - The padding scheme, from dxCommonUtils.AES_PADDING. Defaults to PKCS7.
 * @returns {ArrayBuffer|null} The decrypted data as an ArrayBuffer. Returns null on decryption failure (e.g., bad key or padding).
 */
dxCommonUtils.crypto.aes.decrypt = function (encryptedData, key, options = {}) {
    // Set default options, including PKCS7 padding by default
    const finalOptions = Object.assign({
        mode: dxCommonUtils.AES_MODE.CBC,
        keySize: 256,
        padding: dxCommonUtils.AES_PADDING.PKCS7
    }, options);

    // Validate mode and keySize
    if (!Object.values(dxCommonUtils.AES_MODE).includes(finalOptions.mode)) {
        throw new Error("options.mode must be one of dxCommonUtils.AES_MODE values");
    }
    if (!Object.values(dxCommonUtils.AES_KEY_SIZE).includes(finalOptions.keySize)) {
        throw new Error("options.keySize must be one of dxCommonUtils.AES_KEY_SIZE values");
    }

    // Validate padding
    if (finalOptions.padding !== undefined) {
        if (typeof finalOptions.padding !== 'string' || !Object.values(dxCommonUtils.AES_PADDING).includes(finalOptions.padding)) {
            throw new Error("options.padding must be one of dxCommonUtils.AES_PADDING values");
        }
    }

    const encryptedDataBuffer = _normalizeDataToBuffer(encryptedData, true); // true for base64

    // Auto-detect if the data is in OpenSSL's "Salted__" format
    let isSalted = false;
    if (encryptedDataBuffer.byteLength >= 16) {
        const header = new Uint8Array(encryptedDataBuffer, 0, 8);
        // "Salted__" in ASCII: 83 97 108 116 101 100 95 95
        const saltedHeader = new Uint8Array([83, 97, 108, 116, 101, 100, 95, 95]);
        isSalted = header.every((value, index) => value === saltedHeader[index]);
    }

    let keyBuffer;
    if (isSalted) {
        // If data is salted, a string key is treated as a password (UTF-8).
        keyBuffer = _normalizeDataToBuffer(key, false, 'Key');
    } else {
        // If data is not salted, a string key is treated as a raw key in hex format.
        keyBuffer = _normalizeHexInput(key, 'Key');

        // Key length must be validated for non-salted keys.
        const expectedKeyLength = finalOptions.keySize / 8;
        if (keyBuffer.byteLength !== expectedKeyLength) {
            throw new Error(`Key length must be ${expectedKeyLength} bytes for ${finalOptions.keySize}-bit AES`);
        }
    }

    const ivBuffer = finalOptions.iv ? _normalizeHexInput(finalOptions.iv) : null;

    return utils.aesDecrypt(encryptedDataBuffer, keyBuffer, { ...finalOptions, iv: ivBuffer });
};

/**
 * Convenience method for AES-256-CBC encryption with automatic IV generation.
 * The key is treated as a Hex string. The plaintext data is treated as a UTF-8 string.
 * @param {string} data - The UTF-8 data to encrypt.
 * @param {string|ArrayBuffer|Uint8Array} key - The encryption key (32 bytes). If a string, it must be Hex.
 * @returns {{encrypted: string, iv: string}} Object containing Base64 encrypted data and the generated IV as a hex string.
 */
dxCommonUtils.crypto.aes.encryptWithRandomIV = function (data, key) {
    if (typeof data !== 'string') {
        throw new Error('Data must be a UTF-8 string for this convenience function.');
    }

    const keyBuffer = _normalizeHexInput(key, 'Key');
    if (keyBuffer.byteLength !== 32) {
        throw new Error('Key must be 32 bytes for AES-256');
    }

    // 1. Generate 16 random bytes, returned directly as a hex string.
    const ivHex = dxCommonUtils.random.getBytes(16);

    // 2. Encrypt using the main AES function.
    const encrypted = dxCommonUtils.crypto.aes.encrypt(data, keyBuffer, {
        mode: 'CBC',
        keySize: 256,
        iv: ivHex
    });

    // 3. Return the encrypted data and the hex-encoded IV.
    return {
        encrypted: encrypted,
        iv: ivHex
    };
}

/**
 * Generates a new RSA key pair.
 * @param {number} [bits=2048] - Key size in bits: 1024, 2048, or 4096.
 * @returns {object} Object containing privateKey and publicKey in PEM format.
 */
dxCommonUtils.crypto.rsa.generateKeyPair = function (bits = 2048) {
    if (![1024, 2048, 4096].includes(bits)) {
        throw new Error('RSA key size must be 1024, 2048, or 4096 bits');
    }
    return utils.generateRsaKeyPair(bits);
}

/**
 * Encrypts data using RSA public key.
 * @param {string|ArrayBuffer|Uint8Array} data - The data to encrypt. If a string is provided, it will be treated as UTF-8.
 * @param {string} publicKey - PEM formatted RSA public key.
 * @returns {string} Base64 encoded encrypted data.
 */
dxCommonUtils.crypto.rsa.encrypt = function (data, publicKey) {
    const dataBuffer = _normalizeDataToBuffer(data, false, 'Data');

    if (typeof publicKey !== 'string') {
        throw new Error('Public key must be a PEM string');
    }
    if (!publicKey.includes('-----BEGIN PUBLIC KEY-----')) {
        throw new Error('Public key must be in PEM format');
    }
    return utils.rsaEncrypt(dataBuffer, publicKey);
}

/**
 * Decrypts RSA encrypted data using private key.
 * @param {string} encryptedData - Base64 encoded encrypted data.
 * @param {string} privateKey - PEM formatted RSA private key.
 * @returns {ArrayBuffer|null} The decrypted data as an ArrayBuffer. Returns null on decryption failure.
 */
dxCommonUtils.crypto.rsa.decrypt = function (encryptedData, privateKey) {
    if (typeof encryptedData !== 'string') {
        throw new Error('Encrypted data must be a Base64 string');
    }
    if (typeof privateKey !== 'string') {
        throw new Error('Private key must be a PEM string');
    }
    if (!privateKey.includes('-----BEGIN PRIVATE KEY-----')) {
        throw new Error('Private key must be in PEM format');
    }

    // Decode the Base64 input to an ArrayBuffer before passing to native code.
    const encryptedBuffer = dxCommonUtils.codec.base64ToArrayBuffer(encryptedData);

    // Pass the privateKey string directly, as the C layer expects a PEM string.
    const decryptedBuffer = utils.rsaDecrypt(encryptedBuffer, privateKey);
    if (!decryptedBuffer) {
        // Return null instead of throwing to match AES behavior
        return null;
    }

    return decryptedBuffer; // Return the raw ArrayBuffer
};

/**
 * Creates a digital signature for data using an RSA private key.
 * This is the core function needed for standards like JWT (RS256/RS384/RS512).
 * @param {string|ArrayBuffer|Uint8Array} data - The data to sign. If a string, it will be treated as UTF-8.
 * @param {string} privateKey - The PEM formatted RSA private key.
 * @param {string} [hashAlgorithm='SHA-256'] - The hash algorithm to use (e.g., 'SHA-256', 'SHA-384', 'SHA-512').
 * @returns {string} The signature as a Base64 encoded string.
 */
dxCommonUtils.crypto.rsa.sign = function (data, privateKey, hashAlgorithm = 'SHA-256') {
    const dataBuffer = _normalizeDataToBuffer(data, false, 'Data');
    if (typeof privateKey !== 'string' || !privateKey.includes('-----BEGIN PRIVATE KEY-----')) {
        throw new Error('Private key must be a PEM string');
    }
    return utils.rsaSign(dataBuffer, privateKey, hashAlgorithm);
};

/**
 * Verifies a digital signature using an RSA public key.
 * This is the counterpart to `rsa.sign` and is used to validate signatures like those in JWT.
 * @param {string|ArrayBuffer|Uint8Array} data - The original, unsigned data.
 * @param {string|ArrayBuffer|Uint8Array} signature - The signature to verify. If a string, it must be Base64 encoded.
 * @param {string} publicKey - The PEM formatted RSA public key.
 * @param {string} [hashAlgorithm='SHA-256'] - The hash algorithm used for signing (e.g., 'SHA-256', 'SHA-384', 'SHA-512').
 * @returns {boolean} True if the signature is valid, otherwise false.
 */
dxCommonUtils.crypto.rsa.verify = function (data, signature, publicKey, hashAlgorithm = 'SHA-256') {
    const dataBuffer = _normalizeDataToBuffer(data, false, 'Data');
    // The C layer expects a raw ArrayBuffer, so we decode the Base64 signature here in JS.
    const signatureBuffer = _normalizeDataToBuffer(signature, true, 'Signature');
    if (typeof publicKey !== 'string' || !publicKey.includes('-----BEGIN PUBLIC KEY-----')) {
        throw new Error('Public key must be a PEM string');
    }
    return utils.rsaVerify(dataBuffer, signatureBuffer, publicKey, hashAlgorithm);
};

/**
 * Parses a PEM formatted X.509 certificate and returns its details.
 * @param {string} pemString - The certificate content in PEM format.
 * @returns {object} An object containing certificate details:
 *                   - serialNumber (string)
 *                   - issuer (string)
 *                   - subject (string)
 *                   - validFrom (string)
 *                   - validTo (string)
 *                   - publicKey (string, in PEM format)
 */
dxCommonUtils.crypto.parsePEM = function (pemString) {
    if (typeof pemString !== 'string' || !pemString.includes('-----BEGIN CERTIFICATE-----')) {
        throw new Error('Input must be a PEM formatted certificate string');
    }
    return utils.parsePEMCertificate(pemString);
};

/**
 * Verifies if a certificate was signed by a given Certificate Authority (CA).
 * @param {string} certPEM - The certificate to verify, in PEM format.
 * @param {string} caCertPEM - The CA's certificate, in PEM format.
 * @returns {boolean} True if the certificate is signed by the CA.
 * @throws {Error} If the native verification fails due to parsing errors or signature mismatch.
 */
dxCommonUtils.crypto.verifyCertificate = function (certPEM, caCertPEM) {
    if (typeof certPEM !== 'string' || !certPEM.includes('-----BEGIN CERTIFICATE-----')) {
        throw new Error('Input certPEM must be a PEM formatted certificate string');
    }
    if (typeof caCertPEM !== 'string' || !caCertPEM.includes('-----BEGIN CERTIFICATE-----')) {
        throw new Error('Input caCertPEM must be a PEM formatted certificate string');
    }
    return utils.verifyCertificate(certPEM, caCertPEM);
};

// =====================================================================================
// == FS (File System) Namespace =====================================================
// =====================================================================================
dxCommonUtils.fs = {};

/**
 * Reads the entire content of a file and returns it as a Base64 encoded string.
 * @memberof dxCommonUtils.fs
 * @param {string} filePath - The path to the file.
 * @returns {string} The Base64 encoded content of the file.
 */
dxCommonUtils.fs.fileToBase64 = function (filePath) {
    if (typeof filePath !== 'string' || filePath.length === 0) {
        throw new Error("filePath must be a non-empty string.");
    }
    return utils.fileToBase64(filePath);
}

/**
 * Decodes a Base64 string and writes the binary data to a file.
 * This will overwrite the file if it already exists.
 * @memberof dxCommonUtils.fs
 * @param {string} filePath - The path to the file to be written.
 * @param {string} base64String - The Base64 encoded data.
 * @returns {boolean} Returns true on success.
 */
dxCommonUtils.fs.base64ToFile = function (filePath, base64String) {
    if (typeof filePath !== 'string' || filePath.length === 0) {
        throw new Error("filePath must be a non-empty string.");
    }
    if (typeof base64String !== 'string') {
        throw new Error("base64String must be a string.");
    }
    return utils.base64ToFile(filePath, base64String);
}

// =====================================================================================
// == Random Namespace ===============================================================
// =====================================================================================
dxCommonUtils.random = {};

/**
 * Generates cryptographically secure random bytes.
 * @param {number} length - Number of bytes to generate.
 * @returns {string} Random bytes as a hex string.
 */
dxCommonUtils.random.getBytes = function (length) {
    if (typeof length !== 'number' || length <= 0) {
        throw new Error('Length must be a positive number');
    }
    return utils.generateRandomBytes(length);
}

/**
 * Generates a non-cryptographically secure random string from a given charset.
 * @param {number} length - The length of the string to generate.
 * @param {string} [charset] - The set of characters to use. Defaults to alphanumeric.
 * @returns {string} The generated random string.
 */
dxCommonUtils.random.getStr = function (length, charset) {
    if (typeof length !== 'number' || length <= 0) {
        throw new Error('Length must be a positive number');
    }
    const charSet = charset || 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
    let result = '';
    const charSetLength = charSet.length;
    for (let i = 0; i < length; i++) {
        result += charSet.charAt(Math.floor(Math.random() * charSetLength));
    }
    return result;
}

// ----------- Codec Namespace -------------------
dxCommonUtils.codec = {};

/**
 * Hexadecimal to byte array eg: 313233616263->[49,50,51,97,98,99]
 * @param {string} str A hexadecimal string in lowercase with no space in between
 * @returns {number[]} Digital numbers
 */
dxCommonUtils.codec.hexToBytes = function (str) {
    if (str === undefined || str === null || (typeof str) != 'string' || str.length < 1) {
        throw new Error("dxCommonUtils.codec.hexToBytes:'str' parameter should not be empty")
    }
    if (!/^[0-9a-fA-F]+$/.test(str) || str.length % 2 !== 0) {
        throw new Error("dxCommonUtils.codec.hexToBytes: 'str' parameter must be a valid hex string with an even length");
    }
    let regex = /.{2}/g;
    let arr = str.match(regex);
    return arr.map(item => parseInt(item, 16));
}
/**
 * Byte array to hexadecimal eg: [49,50,51,97,98,99] ->313233616263
 * @param {number[]} numbers Numeric array
 * @returns {string} A hexadecimal string in lowercase with no space in between
 */
dxCommonUtils.codec.bytesToHex = function (numbers) {
    const hexArray = numbers.map(num => num.toString(16).padStart(2, '0').toLowerCase());
    const hexString = hexArray.join('');
    return hexString;
}
/**
 * Hexadecimal to string conversion eg: 313233616263->123abc
 * @description WARNING: This function only works for single-byte character sets (like ASCII).
 * For multi-byte characters (like Chinese), please use `codec.utf8HexToStr`.
 * @param {string} str The hexadecimal string to be converted
 * @returns {string} The real string
 */
dxCommonUtils.codec.hexToStr = function (str) {
    let regex = /.{2}/g;
    let arr = str.match(regex);
    arr = arr.map(item => String.fromCharCode(parseInt(item, 16)));
    return arr.join("");
}
/**
 * Convert a string to a UTF-8 encoded hexadecimal string
 * @param {string} str 
 * @returns {string}
 */
dxCommonUtils.codec.strToUtf8Hex = function (str) {
    const bytes = [];
    for (let i = 0; i < str.length; i++) {
        let code = str.charCodeAt(i);
        if (code < 0x80) {
            bytes.push(code);
        } else if (code < 0x800) {
            bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
        } else if (code < 0xd800 || code >= 0xe000) {
            bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
        } else {
            i++;
            code = 0x10000 + (((code & 0x3ff) << 10) | (str.charCodeAt(i) & 0x3ff));
            bytes.push(
                0xf0 | (code >> 18),
                0x80 | ((code >> 12) & 0x3f),
                0x80 | ((code >> 6) & 0x3f),
                0x80 | (code & 0x3f)
            );
        }
    }
    return dxCommonUtils.codec.bytesToHex(bytes);
}
/**
 * Convert the hexadecimal string of utf-8 passed over to a string
 * @param {string} hex Hexadecimal string
 * @returns {string} The real string
 */
dxCommonUtils.codec.utf8HexToStr = function (hex) {
    let array = dxCommonUtils.codec.hexToBytes(hex)
    var out, i, len, c;
    var char2, char3;
    out = "";
    len = array.length;
    i = 0;
    while (i < len) {
        c = array[i++];
        switch (c >> 4) {
            case 0: case 1: case 2: case 3: case 4: case 5: case 6: case 7:
                out += String.fromCharCode(c);
                break;
            case 12: case 13:
                char2 = array[i++];
                out += String.fromCharCode(((c & 0x1F) << 6) | (char2 & 0x3F));
                break;
            case 14:
                char2 = array[i++];
                char3 = array[i++];
                out += String.fromCharCode(((c & 0x0F) << 12) |
                    ((char2 & 0x3F) << 6) |
                    ((char3 & 0x3F) << 0));
                break;
        }
    }
    return out;
}
/**
 * Convert string to hexadecimal eg: 123abc ->313233616263
 * @description WARNING: This function only works for single-byte character sets (like ASCII).
 * For multi-byte characters (like Chinese), please use `codec.strToUtf8Hex`.
 * @param {string} str The string to be converted
 * @returns {string} Hexadecimal string
 */
dxCommonUtils.codec.strToHex = function (str) {
    if (str === undefined || str === null || typeof (str) != "string") {
        return null
    }
    let val = "";
    for (let i = 0; i < str.length; i++) {
        val += str.charCodeAt(i).toString(16).padStart(2, '0');
    }
    return val
}

/**
 * Convert small format to decimal eg: 001001->69632
 * @param {string} hexString A hexadecimal string in lowercase with no space in between
 * @returns {number} Decimal number
 */
dxCommonUtils.codec.leToDecimal = function (hexString) {
    let reversedHexString = hexString
        .match(/.{2}/g)
        .reverse()
        .join("");
    let decimal = parseInt(reversedHexString, 16);
    return decimal;
}

/**
 * Convert decimal numbers to hexadecimal small format strings
 * @param {number} decimalNumber Decimal digit
 * @param {number} byteSize Generate the number of bytes, defaults to 2
 * @returns {string} Hexadecimal small format string
 */
dxCommonUtils.codec.decimalToLeHex = function (decimalNumber, byteSize) {
    if (decimalNumber === undefined || decimalNumber === null || (typeof decimalNumber) != 'number') {
        throw new Error("dxCommonUtils.codec.decimalToLeHex:'decimalNumber' parameter should be number")
    }
    if (byteSize === undefined || byteSize === null || (typeof byteSize) != 'number' || byteSize <= 0) {
        byteSize = 2
    }
    const littleEndianBytes = [];
    for (let i = 0; i < byteSize; i++) {
        littleEndianBytes.push(decimalNumber & 0xFF);
        decimalNumber >>= 8;
    }
    const littleEndianHex = littleEndianBytes
        .map((byte) => byte.toString(16).padStart(2, '0'))
        .join('');
    return littleEndianHex;
}

/**
 * Convert a hexadecimal string to an ArrayBuffer
 * @param {string} hexString The hexadecimal string to be converted
 * @returns {ArrayBuffer} Converted ArrayBuffer
 */
dxCommonUtils.codec.hexToArrayBuffer = function (hexString) {
    return dxCommonUtils.codec.hexToUint8Array(hexString).buffer;
}

/**
 * Convert hexadecimal string to Uint8Array
 * @param {string} hexString The hexadecimal string to be converted
 * @returns {Uint8Array} Uint8Array object
 */
dxCommonUtils.codec.hexToUint8Array = function (hexString) {
    if (hexString === undefined || hexString === null || (typeof hexString) != 'string' || hexString.length <= 0) {
        throw new Error("dxCommonUtils.codec.hexToUint8Array:'hexString' parameter should not be empty")
    }
    if (!/^[0-9a-fA-F]+$/.test(hexString) || hexString.length % 2 !== 0) {
        throw new Error("dxCommonUtils.codec.hexToUint8Array: 'hexString' parameter must be a valid hex string with an even length");
    }
    let byteString = hexString.match(/.{1,2}/g);
    let byteArray = byteString.map(function (byte) {
        return parseInt(byte, 16);
    });
    let buffer = new Uint8Array(byteArray);
    return buffer;
}

/**
 * Convert ArrayBuffer to hexadecimal string format
 * @param {ArrayBuffer} buffer 
 * @returns {string} A hexadecimal string in lowercase with no space in between
 */
dxCommonUtils.codec.arrayBufferToHex = function (buffer) {
    return dxCommonUtils.codec.uint8ArrayToHex(new Uint8Array(buffer))
}
/**
 * Convert Uint8Array to hexadecimal string format
 * @param {Uint8Array} array 
 * @returns {string} A hexadecimal string in lowercase with no space in between
 */
dxCommonUtils.codec.uint8ArrayToHex = function (array) {
    let hexString = '';
    for (let i = 0; i < array.length; i++) {
        const byte = array[i].toString(16).padStart(2, '0');
        hexString += byte;
    }
    return hexString
}

/**
 * Decodes a Base64 string into an ArrayBuffer.
 * This implementation is robust and handles padding correctly.
 * @memberof dxCommonUtils.codec
 * @param {string} b64 - The Base64 encoded string.
 * @returns {ArrayBuffer} The decoded data as an ArrayBuffer.
 */
dxCommonUtils.codec.base64ToArrayBuffer = function (b64) {
    if (typeof b64 !== 'string') {
        throw new Error("Input must be a Base64 string.");
    }

    // First, clean up any whitespace from the input string.
    const b64_clean = b64.replace(/\s+/g, "");

    // Regex inspired by the js-base64 library to validate the structure of the string.
    // This provides a fast failure for malformed strings.
    const b64re = /^(?:[A-Za-z0-9+/]{4})*?(?:[A-Za-z0-9+/]{2}(?:==)?|[A-Za-z0-9+/]{3}=?)?$/;
    if (!b64re.test(b64_clean)) {
        throw new Error("Input is not a valid Base64 string (malformed).");
    }

    const B64_MAP = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
    const len = b64_clean.length;

    // This calculation correctly determines the output byte length
    let byte_len = len * 3 / 4;
    if (b64_clean.slice(-2) === '==') {
        byte_len -= 2;
    } else if (b64_clean.slice(-1) === '=') {
        byte_len -= 1;
    }

    const arr = new Uint8Array(byte_len);
    let j = 0;

    for (let i = 0; i < len; i += 4) {
        // Get the index of each base64 character.
        // It will be -1 for '=' or any other invalid character.
        const c1 = B64_MAP.indexOf(b64_clean[i]);
        const c2 = B64_MAP.indexOf(b64_clean[i + 1]);
        const c3 = B64_MAP.indexOf(b64_clean[i + 2]);
        const c4 = B64_MAP.indexOf(b64_clean[i + 3]);

        // Reconstruct the original 3 bytes from the 4 base64 character indices.
        const b1 = (c1 << 2) | (c2 >> 4);
        const b2 = ((c2 & 15) << 4) | (c3 >> 2);
        const b3 = ((c3 & 3) << 6) | c4;

        // Write the first byte, which is always present.
        arr[j++] = b1;

        // Write the second byte if the third base64 character was not a padding character.
        if (c3 !== -1) {
            arr[j++] = b2;
        }

        // Write the third byte if the fourth base64 character was not a padding character.
        if (c4 !== -1) {
            arr[j++] = b3;
        }
    }
    return arr.buffer;
}

/**
 * Encodes an ArrayBuffer into a Base64 string.
 * This implementation is robust and handles padding correctly.
 * @memberof dxCommonUtils.codec
 * @param {ArrayBuffer} buffer - The ArrayBuffer to encode.
 * @returns {string} The Base64 encoded string.
 */
dxCommonUtils.codec.arrayBufferToBase64 = function (buffer) {
    const B64_MAP = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
    const bytes = new Uint8Array(buffer);
    const len = bytes.byteLength;
    let b64 = "";

    for (let i = 0; i < len; i += 3) {
        const b1 = bytes[i];
        const b2 = bytes[i + 1];
        const b3 = bytes[i + 2];

        const c1 = b1 >> 2;
        const c2 = ((b1 & 3) << 4) | (b2 >> 4);
        const c3 = ((b2 & 15) << 2) | (b3 >> 6);
        const c4 = b3 & 63;

        b64 += B64_MAP[c1];
        b64 += B64_MAP[c2];

        if (i + 1 >= len) {
            b64 += "==";
        } else {
            b64 += B64_MAP[c3];
            if (i + 2 >= len) {
                b64 += "=";
            } else {
                b64 += B64_MAP[c4];
            }
        }
    }
    return b64;
}

/**
 * Calculates the BCC (Block Check Character / XOR Checksum) of the input data.
 * @memberof dxCommonUtils.codec
 * @param {string|ArrayBuffer|Uint8Array} data - The data to calculate the checksum for. If a string, it will be treated as UTF-8.
 * @returns {number} The calculated 8-bit BCC value (0-255).
 */
dxCommonUtils.codec.bcc = function (data) {
    const buffer = _normalizeDataToBuffer(data, false, 'Data');
    return utils.calculateBcc(buffer);
}

/**
 * Get disk space usage
 * @returns {object} 
 *          -total: The total disk space in MB.
 *          -used: The used disk space in MB.
 *          -free: The available disk space in MB.
 */
dxCommonUtils.getDiskStats = function () {
    return utils.getDiskStats();
}

/**
 * @private
 * Internal helper to normalize various data inputs into an ArrayBuffer.
 * This function is crucial for ensuring that the native C layer receives data in a consistent format.
 * @param {string|ArrayBuffer|Uint8Array} data The input data.
 * @param {boolean} [isBase64=false] - If the input is a string, specifies if it's Base64 encoded. Defaults to false (UTF-8).
 * @param {string} [paramName='Input'] - The name of the parameter for error messages.
 * @returns {ArrayBuffer}
 */
function _normalizeDataToBuffer(data, isBase64 = false, paramName = 'Input') {
    if (typeof data === 'string') {
        if (isBase64) {
            return dxCommonUtils.codec.base64ToArrayBuffer(data);
        } else {
            // Treat as a UTF-8 string by converting to hex and then to ArrayBuffer.
            return dxCommonUtils.codec.hexToArrayBuffer(dxCommonUtils.codec.strToUtf8Hex(data));
        }
    } else if (data instanceof ArrayBuffer) {
        return data;
    } else if (data instanceof Uint8Array) {
        // Correctly handle views on larger ArrayBuffers by creating a copy of the viewed section.
        // If it's not a view, slice() will create a copy of the buffer.
        return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
    } else {
        throw new Error(`${paramName} must be a string, ArrayBuffer, or Uint8Array`);
    }
}

/**
 * @private
 * Internal helper to normalize crypto inputs, converting Hex strings to ArrayBuffer.
 * @param {string|ArrayBuffer|Uint8Array} data The input data.
 * @param {string} paramName The name of the parameter for error messages.
 * @returns {ArrayBuffer}
 */
function _normalizeHexInput(data, paramName = 'Input') {
    if (typeof data === 'string') {
        return dxCommonUtils.codec.hexToArrayBuffer(data);
    } else if (data instanceof ArrayBuffer) {
        return data;
    } else if (data instanceof Uint8Array) {
        return data.buffer;
    } else {
        throw new Error(`${paramName} must be a hex string, ArrayBuffer, or Uint8Array`);
    }
}

/**
 * Internal helper to convert an ArrayBuffer to a UTF-8 string.
 * This is a workaround for environments that lack a built-in TextDecoder.
 * @param {ArrayBuffer} buffer - The ArrayBuffer to convert.
 * @returns {string} The UTF-8 string.
 */
function _arrayBufferToUtf8String(buffer) {
    if (!buffer || buffer.byteLength === 0) {
        return "";
    }
    // Use the existing, environment-safe codec functions
    const hex = dxCommonUtils.codec.arrayBufferToHex(buffer);
    return dxCommonUtils.codec.utf8HexToStr(hex);
}

/**
 * Gets the native common utils client object.
 * @returns {Object} The native client object.
 */
dxCommonUtils.getNative = function () {
    return utils;
}

export default dxCommonUtils;