@ukeyfe/react-native-nfc-litecard 1.0.0

package/dist/reader.js

@@ -0,0 +1,488 @@
+"use strict";
+/**
+ * NFC Reader Module
+ *
+ * Public API:
+ *   - checkCard()          – detect whether a card is empty or contains data
+ *   - readMnemonic()       – read mnemonic (password required)
+ *   - readUserNickname()   – read user nickname (password optional)
+ *   - readMnemonicRetryCount() – read the PIN retry counter
+ *   - resetRetryCountTo10()    – reset the retry counter to default
+ *   - cardInfoToJson()     – serialise card-info to JSON
+ *
+ * Based on MIFARE Ultralight AES (MF0AES(H)20) datasheet.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PIN_RETRY_COUNT = exports.clearNfcOperationCancelledByCleanup = exports.getNfcOperationCancelledByCleanupTimestamp = exports.consumeNfcOperationCancelledByCleanup = exports.markNfcOperationCancelledByCleanup = exports.releaseNfcOperationLock = exports.isNfcOperationLocked = exports.ResultCode = void 0;
+exports.cardInfoToJson = cardInfoToJson;
+exports.checkCard = checkCard;
+exports.readMnemonic = readMnemonic;
+exports.readUserNickname = readUserNickname;
+exports.readMnemonicRetryCount = readMnemonicRetryCount;
+exports.resetRetryCountTo10 = resetRetryCountTo10;
+const bip39 = __importStar(require("bip39"));
+const constants_1 = require("./constants");
+Object.defineProperty(exports, "DEFAULT_PIN_RETRY_COUNT", { enumerable: true, get: function () { return constants_1.DEFAULT_PIN_RETRY_COUNT; } });
+const types_1 = require("./types");
+Object.defineProperty(exports, "ResultCode", { enumerable: true, get: function () { return types_1.ResultCode; } });
+const utils_1 = require("./utils");
+const crypto_1 = require("./crypto");
+const nfc_core_1 = require("./nfc-core");
+Object.defineProperty(exports, "isNfcOperationLocked", { enumerable: true, get: function () { return 
+    // re-export lock helpers so consumers can manage lock from outside
+    nfc_core_1.isNfcOperationLocked; } });
+Object.defineProperty(exports, "releaseNfcOperationLock", { enumerable: true, get: function () { return nfc_core_1.releaseNfcOperationLock; } });
+Object.defineProperty(exports, "markNfcOperationCancelledByCleanup", { enumerable: true, get: function () { return nfc_core_1.markNfcOperationCancelledByCleanup; } });
+Object.defineProperty(exports, "consumeNfcOperationCancelledByCleanup", { enumerable: true, get: function () { return nfc_core_1.consumeNfcOperationCancelledByCleanup; } });
+Object.defineProperty(exports, "getNfcOperationCancelledByCleanupTimestamp", { enumerable: true, get: function () { return nfc_core_1.getNfcOperationCancelledByCleanupTimestamp; } });
+Object.defineProperty(exports, "clearNfcOperationCancelledByCleanup", { enumerable: true, get: function () { return nfc_core_1.clearNfcOperationCancelledByCleanup; } });
+// ===========================================================================
+// Internal read helpers
+// ===========================================================================
+/** FAST_READ pages 0x08–0x27 (user memory). */
+async function readUserMemory() {
+    const response = await (0, nfc_core_1.transceive)([constants_1.CMD_FAST_READ, constants_1.USER_PAGE_START, constants_1.USER_PAGE_END]);
+    if (!response || response.length < constants_1.USER_MEMORY_SIZE)
+        throw new Error('READ_FAILED');
+    return new Uint8Array(response.slice(0, constants_1.USER_MEMORY_SIZE));
+}
+/** FAST_READ pages 0x04–0x07 (card info area). */
+async function readUserCardInfo() {
+    const response = await (0, nfc_core_1.transceive)([constants_1.CMD_FAST_READ, constants_1.USER_CARD_INFO_PAGE_START, constants_1.USER_CARD_INFO_PAGE_END]);
+    if (!response || response.length < constants_1.USER_CARD_INFO_SIZE)
+        throw new Error('READ_FAILED');
+    return new Uint8Array(response.slice(0, constants_1.USER_CARD_INFO_SIZE));
+}
+/** FAST_READ nickname pages (last 3 pages of user memory). */
+async function readUserNicknameInternal() {
+    const response = await (0, nfc_core_1.transceive)([constants_1.CMD_FAST_READ, constants_1.USER_NICKNAME_PAGE_START, constants_1.USER_NICKNAME_PAGE_END]);
+    if (!response || response.length < constants_1.USER_NICKNAME_MAX_LENGTH)
+        throw new Error('READ_FAILED');
+    const responseArray = Array.isArray(response) ? response : Array.from(response);
+    const nicknameBytes = new Uint8Array(responseArray.slice(0, constants_1.USER_NICKNAME_MAX_LENGTH));
+    // Find actual length (ignore trailing 0x00 padding)
+    let actualLength = 0;
+    for (let i = 0; i < constants_1.USER_NICKNAME_MAX_LENGTH; i++) {
+        if (nicknameBytes[i] !== 0x00)
+            actualLength = i + 1;
+    }
+    if (actualLength === 0)
+        return '';
+    try {
+        return new TextDecoder('utf-8').decode(nicknameBytes.slice(0, actualLength));
+    }
+    catch {
+        // Fallback: ASCII-compatible manual conversion
+        let result = '';
+        for (let i = 0; i < actualLength; i++)
+            result += String.fromCharCode(nicknameBytes[i]);
+        return result;
+    }
+}
+// ===========================================================================
+// Entropy → mnemonic conversion
+// ===========================================================================
+/**
+ * Decode on-card data into a BIP-39 mnemonic.
+ *
+ * Data layout: [type 1B] [entropy 16-32B] [CRC16 2B]
+ */
+function entropyToMnemonic(data) {
+    if (data.length < 19)
+        throw new Error('INVALID_CARD_DATA');
+    if (data.every(b => b === 0))
+        throw new Error('EMPTY_CARD');
+    const typeId = data[0];
+    let entropyLength;
+    let typeStr;
+    switch (typeId) {
+        case constants_1.MNEMONIC_TYPE_12:
+            entropyLength = 16;
+            typeStr = '12 words (128-bit)';
+            break;
+        case constants_1.MNEMONIC_TYPE_15:
+            entropyLength = 20;
+            typeStr = '15 words (160-bit)';
+            break;
+        case constants_1.MNEMONIC_TYPE_18:
+            entropyLength = 24;
+            typeStr = '18 words (192-bit)';
+            break;
+        case constants_1.MNEMONIC_TYPE_21:
+            entropyLength = 28;
+            typeStr = '21 words (224-bit)';
+            break;
+        case constants_1.MNEMONIC_TYPE_24:
+            entropyLength = 32;
+            typeStr = '24 words (256-bit)';
+            break;
+        default: throw new Error('INVALID_CARD_DATA');
+    }
+    const expectedTotal = 1 + entropyLength + 2;
+    if (data.length < expectedTotal)
+        throw new Error('INVALID_CARD_DATA');
+    const dataBlock = data.slice(0, 1 + entropyLength);
+    const storedCRC = (0, utils_1.extractCRC16)(data.slice(1 + entropyLength, expectedTotal));
+    const calcCRC = (0, utils_1.calculateCRC16)(dataBlock);
+    if (storedCRC !== calcCRC)
+        throw new Error('CRC16_CHECK_FAILED');
+    const entropyBytes = data.slice(1, 1 + entropyLength);
+    const entropyHex = (0, utils_1.bytesToHex)(Array.from(entropyBytes));
+    const rawBytes = (0, utils_1.bytesToHex)(Array.from(dataBlock));
+    const mnemonic = bip39.entropyToMnemonic(entropyHex);
+    return { mnemonic, entropyHex, type: typeStr, rawBytes, crc16: calcCRC };
+}
+// ===========================================================================
+// Card info parsing
+// ===========================================================================
+const CARD_TYPE_MAP = {
+    0x00: 'Unknown',
+    0x01: 'Standard',
+    0x02: 'Encrypted',
+    0x10: 'Test',
+    0x14: 'UKey',
+    0x20: 'Development',
+};
+function parseCardInfo(data) {
+    if (!data || data.length < constants_1.USER_CARD_INFO_SIZE)
+        throw new Error('INVALID_CARD_DATA');
+    const version = data[0];
+    const cardType = data[1];
+    const infoBytes = data.slice(2, constants_1.USER_CARD_INFO_SIZE);
+    const rawBytes = (0, utils_1.bytesToHex)(Array.from(data.slice(0, constants_1.USER_CARD_INFO_SIZE)));
+    const pageBreakdown = [];
+    for (let i = 0; i < Math.ceil(constants_1.USER_CARD_INFO_SIZE / constants_1.PAGE_SIZE); i++) {
+        const off = i * constants_1.PAGE_SIZE;
+        const pageBytes = Array.from(data.slice(off, off + constants_1.PAGE_SIZE));
+        pageBreakdown.push({
+            page: constants_1.USER_CARD_INFO_PAGE_START + i,
+            bytes: pageBytes,
+            hex: (0, utils_1.bytesToHex)(pageBytes),
+        });
+    }
+    return {
+        version,
+        cardType,
+        rawBytes,
+        infoBytes,
+        json: {
+            pageInfo: {
+                startPage: constants_1.USER_CARD_INFO_PAGE_START,
+                endPage: constants_1.USER_CARD_INFO_PAGE_END,
+                totalPages: Math.ceil(constants_1.USER_CARD_INFO_SIZE / constants_1.PAGE_SIZE),
+                totalBytes: constants_1.USER_CARD_INFO_SIZE,
+            },
+            version: { value: version, hex: `0x${version.toString(16).padStart(2, '0')}` },
+            cardType: {
+                value: cardType,
+                hex: `0x${cardType.toString(16).padStart(2, '0')}`,
+                description: CARD_TYPE_MAP[cardType] || `Unknown (0x${cardType.toString(16).padStart(2, '0')})`,
+                known: cardType in CARD_TYPE_MAP,
+            },
+            additionalInfo: { hex: (0, utils_1.bytesToHex)(Array.from(infoBytes)), bytes: Array.from(infoBytes) },
+            rawData: { hex: rawBytes, bytes: Array.from(data.slice(0, constants_1.USER_CARD_INFO_SIZE)), length: constants_1.USER_CARD_INFO_SIZE },
+            pageBreakdown,
+        },
+    };
+}
+/** Serialise parseCardInfo result to JSON. */
+function cardInfoToJson(cardInfo, pretty = true) {
+    return pretty ? JSON.stringify(cardInfo.json, null, 2) : JSON.stringify(cardInfo.json);
+}
+// ===========================================================================
+// Public API
+// ===========================================================================
+/**
+ * Detect whether the card is empty or already contains data.
+ *
+ * Logic:
+ *   - Read succeeds & first byte is a valid mnemonic type → HAS_DATA
+ *   - Read succeeds & first byte is other → EMPTY
+ *   - Read fails (auth required) → HAS_DATA (read-protection is on)
+ */
+async function checkCard(onCardIdentified) {
+    try {
+        await (0, nfc_core_1.acquireNfcLock)();
+    }
+    catch {
+        return { code: types_1.ResultCode.UNKNOWN_ERROR, success: false };
+    }
+    try {
+        try {
+            await (0, nfc_core_1.requestNfcTech)();
+        }
+        catch {
+            (0, nfc_core_1.releaseNfcLock)();
+            return { code: types_1.ResultCode.NFC_CONNECT_FAILED, success: false };
+        }
+        onCardIdentified?.();
+        let response = null;
+        try {
+            response = await (0, nfc_core_1.transceive)([constants_1.CMD_READ, constants_1.USER_PAGE_START]);
+        }
+        catch { /* read-protected */ }
+        await (0, nfc_core_1.releaseNfcTech)();
+        (0, nfc_core_1.releaseNfcLock)();
+        if (response && response.length >= 4) {
+            const first = response[0];
+            const hasData = first === constants_1.MNEMONIC_TYPE_12 ||
+                first === constants_1.MNEMONIC_TYPE_15 ||
+                first === constants_1.MNEMONIC_TYPE_18 ||
+                first === constants_1.MNEMONIC_TYPE_21 ||
+                first === constants_1.MNEMONIC_TYPE_24;
+            const code = hasData ? types_1.ResultCode.CHECK_HAS_DATA : types_1.ResultCode.CHECK_EMPTY;
+            return { code, success: true };
+        }
+        return { code: types_1.ResultCode.CHECK_HAS_DATA, success: true };
+    }
+    catch (error) {
+        (0, nfc_core_1.releaseNfcLock)();
+        throw error;
+    }
+}
+/**
+ * Read the mnemonic from a password-protected card.
+ *
+ * Flow: connect → pre-decrement retry counter → authenticate → read →
+ *       decode entropy → read nickname → reset retry counter → release
+ */
+async function readMnemonic(password, onCardIdentified) {
+    try {
+        await (0, nfc_core_1.acquireNfcLock)();
+    }
+    catch {
+        return { code: types_1.ResultCode.UNKNOWN_ERROR, success: false };
+    }
+    let retryCountAfterPreDecrement;
+    try {
+        try {
+            await (0, nfc_core_1.requestNfcTech)();
+        }
+        catch {
+            (0, nfc_core_1.releaseNfcLock)();
+            return { code: types_1.ResultCode.NFC_CONNECT_FAILED, success: false };
+        }
+        try {
+            // Pre-decrement retry counter before auth attempt
+            try {
+                const next = await (0, nfc_core_1.decrementRetryCountInSession)();
+                if (typeof next === 'number')
+                    retryCountAfterPreDecrement = next;
+            }
+            catch { /* non-fatal */ }
+            const aesKey = (0, crypto_1.passwordToAesKey)(password);
+            await (0, nfc_core_1.authenticate)(aesKey);
+            onCardIdentified?.();
+            const data = await readUserMemory();
+            await readUserCardInfo(); // read but not used directly yet
+            const result = entropyToMnemonic(data);
+            let nickname;
+            try {
+                nickname = await readUserNicknameInternal();
+            }
+            catch { /* non-fatal */ }
+            // Auth succeeded – reset counter to default
+            let finalRetryCount;
+            try {
+                await (0, nfc_core_1.writeRetryCountInSession)(constants_1.DEFAULT_PIN_RETRY_COUNT);
+                finalRetryCount = constants_1.DEFAULT_PIN_RETRY_COUNT;
+            }
+            catch { /* non-fatal */ }
+            await (0, nfc_core_1.releaseNfcTech)();
+            (0, nfc_core_1.releaseNfcLock)();
+            return {
+                code: types_1.ResultCode.READ_SUCCESS,
+                success: true,
+                data: {
+                    mnemonic: result.mnemonic,
+                    type: result.type,
+                    entropyHex: result.entropyHex,
+                    rawBytes: result.rawBytes,
+                    nickname,
+                    retryCount: finalRetryCount,
+                },
+            };
+        }
+        catch (error) {
+            const isTimeout = error?.message?.includes('TRANSCEIVE_TIMEOUT') ||
+                error?.message?.includes('timeout') ||
+                error?.message?.includes('TagLost');
+            await (0, nfc_core_1.releaseNfcTech)(isTimeout);
+            (0, nfc_core_1.releaseNfcLock)();
+            const code = (0, types_1.errorToCode)(error);
+            return {
+                code,
+                success: false,
+                data: typeof retryCountAfterPreDecrement === 'number' ? { retryCount: retryCountAfterPreDecrement } : undefined,
+            };
+        }
+    }
+    catch (error) {
+        (0, nfc_core_1.releaseNfcLock)();
+        throw error;
+    }
+}
+/**
+ * Read the user nickname from the card.
+ * @param password – supply if the card has read-protection enabled.
+ */
+async function readUserNickname(password) {
+    try {
+        await (0, nfc_core_1.acquireNfcLock)();
+    }
+    catch {
+        return { code: types_1.ResultCode.UNKNOWN_ERROR, success: false };
+    }
+    try {
+        try {
+            await (0, nfc_core_1.requestNfcTech)();
+        }
+        catch {
+            (0, nfc_core_1.releaseNfcLock)();
+            return { code: types_1.ResultCode.NFC_CONNECT_FAILED, success: false };
+        }
+        try {
+            if (password) {
+                const aesKey = (0, crypto_1.passwordToAesKey)(password);
+                await (0, nfc_core_1.authenticate)(aesKey);
+            }
+            const nickname = await readUserNicknameInternal();
+            await (0, nfc_core_1.releaseNfcTech)();
+            (0, nfc_core_1.releaseNfcLock)();
+            return {
+                code: types_1.ResultCode.READ_NICKNAME_SUCCESS,
+                success: true,
+                data: { nickname },
+            };
+        }
+        catch (error) {
+            await (0, nfc_core_1.releaseNfcTech)();
+            (0, nfc_core_1.releaseNfcLock)();
+            const code = (0, types_1.errorToCode)(error);
+            return { code, success: false };
+        }
+    }
+    catch (error) {
+        (0, nfc_core_1.releaseNfcLock)();
+        throw error;
+    }
+}
+/** Read the current PIN retry counter from the card. */
+async function readMnemonicRetryCount() {
+    try {
+        await (0, nfc_core_1.acquireNfcLock)();
+    }
+    catch {
+        return { code: types_1.ResultCode.UNKNOWN_ERROR, success: false };
+    }
+    try {
+        try {
+            await (0, nfc_core_1.requestNfcTech)();
+        }
+        catch {
+            (0, nfc_core_1.releaseNfcLock)();
+            return { code: types_1.ResultCode.NFC_CONNECT_FAILED, success: false };
+        }
+        try {
+            const pageBlock = await (0, nfc_core_1.transceive)([constants_1.CMD_READ, constants_1.RETRY_COUNTER_PAGE]);
+            if (!pageBlock || pageBlock.length < constants_1.PAGE_SIZE) {
+                await (0, nfc_core_1.releaseNfcTech)();
+                (0, nfc_core_1.releaseNfcLock)();
+                return {
+                    code: types_1.ResultCode.READ_RETRY_COUNT_SUCCESS,
+                    success: true,
+                    data: { retryCount: 0 },
+                };
+            }
+            const retryCount = typeof pageBlock[constants_1.RETRY_COUNTER_OFFSET] === 'number' ? pageBlock[constants_1.RETRY_COUNTER_OFFSET] & 0xff : 0;
+            await (0, nfc_core_1.releaseNfcTech)();
+            (0, nfc_core_1.releaseNfcLock)();
+            return {
+                code: types_1.ResultCode.READ_RETRY_COUNT_SUCCESS,
+                success: true,
+                data: { retryCount },
+            };
+        }
+        catch (error) {
+            await (0, nfc_core_1.releaseNfcTech)();
+            (0, nfc_core_1.releaseNfcLock)();
+            const code = (0, types_1.errorToCode)(error);
+            return { code, success: false };
+        }
+    }
+    catch (error) {
+        (0, nfc_core_1.releaseNfcLock)();
+        throw error;
+    }
+}
+/** Reset the PIN retry counter to the default value (10). */
+async function resetRetryCountTo10() {
+    try {
+        await (0, nfc_core_1.acquireNfcLock)();
+    }
+    catch {
+        return { code: types_1.ResultCode.UNKNOWN_ERROR, success: false };
+    }
+    try {
+        try {
+            await (0, nfc_core_1.requestNfcTech)();
+        }
+        catch {
+            (0, nfc_core_1.releaseNfcLock)();
+            return { code: types_1.ResultCode.NFC_CONNECT_FAILED, success: false };
+        }
+        try {
+            await (0, nfc_core_1.writeRetryCountInSession)(constants_1.DEFAULT_PIN_RETRY_COUNT);
+            await (0, nfc_core_1.releaseNfcTech)();
+            (0, nfc_core_1.releaseNfcLock)();
+            return {
+                code: types_1.ResultCode.READ_RETRY_COUNT_SUCCESS,
+                success: true,
+                data: { retryCount: constants_1.DEFAULT_PIN_RETRY_COUNT },
+            };
+        }
+        catch (error) {
+            await (0, nfc_core_1.releaseNfcTech)();
+            (0, nfc_core_1.releaseNfcLock)();
+            const code = (0, types_1.errorToCode)(error);
+            return { code, success: false };
+        }
+    }
+    catch (error) {
+        (0, nfc_core_1.releaseNfcLock)();
+        throw error;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Unified result codes, NfcResult interface, and error mapping helpers.
+ *
+ * All codes are unique across reader and writer to prevent ambiguity.
+ *   - Reader success : 101xx
+ *   - Writer success : 102xx
+ *   - Failure        : 4xxxx (shared)
+ *
+ * This library does NOT provide user-facing messages.
+ * The caller should map ResultCode to their own localised strings.
+ */
+export declare const ResultCode: {
+    readonly READ_SUCCESS: 10102;
+    readonly READ_NICKNAME_SUCCESS: 10103;
+    readonly CHECK_EMPTY: 10104;
+    readonly CHECK_HAS_DATA: 10105;
+    readonly READ_RETRY_COUNT_SUCCESS: 10106;
+    readonly INIT_SUCCESS: 10201;
+    readonly WRITE_SUCCESS: 10203;
+    readonly UPDATE_PASSWORD_SUCCESS: 10204;
+    readonly WRITE_NICKNAME_SUCCESS: 10205;
+    readonly RESET_SUCCESS: 10206;
+    readonly NFC_CONNECT_FAILED: 40001;
+    readonly AUTH_WRONG_PASSWORD: 40002;
+    readonly AUTH_INVALID_RESPONSE: 40003;
+    readonly AUTH_VERIFY_FAILED: 40004;
+    readonly READ_FAILED: 40005;
+    readonly WRITE_FAILED: 40006;
+    readonly INVALID_MNEMONIC: 40007;
+    readonly UNSUPPORTED_MNEMONIC_LENGTH: 40008;
+    readonly INVALID_CARD_DATA: 40009;
+    readonly UNKNOWN_ERROR: 40010;
+    readonly NFC_USER_CANCELED: 40011;
+    readonly READ_TIMEOUT: 40012;
+    readonly NFC_LOCK_TIMEOUT: 40013;
+    readonly CRC16_CHECK_FAILED: 40014;
+};
+export interface NfcResult {
+    /** Numeric result code – compare against ResultCode constants */
+    code: number;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Returned data (optional, only present for some operations) */
+    data?: {
+        mnemonic?: string;
+        type?: string;
+        entropyHex?: string;
+        rawBytes?: string;
+        nickname?: string;
+        retryCount?: number;
+        aesKeyHex?: string;
+        crc16?: number;
+    };
+}
+/**
+ * Derive a ResultCode from an error thrown during NFC operations.
+ * Handles iOS-specific cancel detection, known error strings, and fallback.
+ */
+export declare function errorToCode(error: any): number;

package/dist/types.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Unified result codes, NfcResult interface, and error mapping helpers.
+ *
+ * All codes are unique across reader and writer to prevent ambiguity.
+ *   - Reader success : 101xx
+ *   - Writer success : 102xx
+ *   - Failure        : 4xxxx (shared)
+ *
+ * This library does NOT provide user-facing messages.
+ * The caller should map ResultCode to their own localised strings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResultCode = void 0;
+exports.errorToCode = errorToCode;
+const react_native_1 = require("react-native");
+// ---------------------------------------------------------------------------
+// Unified result codes
+// ---------------------------------------------------------------------------
+exports.ResultCode = {
+    // Reader success (101xx)
+    READ_SUCCESS: 10102,
+    READ_NICKNAME_SUCCESS: 10103,
+    CHECK_EMPTY: 10104,
+    CHECK_HAS_DATA: 10105,
+    READ_RETRY_COUNT_SUCCESS: 10106,
+    // Writer success (102xx)
+    INIT_SUCCESS: 10201,
+    WRITE_SUCCESS: 10203,
+    UPDATE_PASSWORD_SUCCESS: 10204,
+    WRITE_NICKNAME_SUCCESS: 10205,
+    RESET_SUCCESS: 10206,
+    // Failure (4xxxx – shared by reader & writer)
+    NFC_CONNECT_FAILED: 40001,
+    AUTH_WRONG_PASSWORD: 40002,
+    AUTH_INVALID_RESPONSE: 40003,
+    AUTH_VERIFY_FAILED: 40004,
+    READ_FAILED: 40005,
+    WRITE_FAILED: 40006,
+    INVALID_MNEMONIC: 40007,
+    UNSUPPORTED_MNEMONIC_LENGTH: 40008,
+    INVALID_CARD_DATA: 40009,
+    UNKNOWN_ERROR: 40010,
+    NFC_USER_CANCELED: 40011,
+    READ_TIMEOUT: 40012,
+    NFC_LOCK_TIMEOUT: 40013,
+    CRC16_CHECK_FAILED: 40014,
+};
+// ---------------------------------------------------------------------------
+// Error → code mapping (internal use)
+// ---------------------------------------------------------------------------
+/**
+ * Derive a ResultCode from an error thrown during NFC operations.
+ * Handles iOS-specific cancel detection, known error strings, and fallback.
+ */
+function errorToCode(error) {
+    const msg = (typeof error === 'string'
+        ? error
+        : (error?.message || '')).trim();
+    // iOS user-cancel detection
+    if (react_native_1.Platform.OS === 'ios') {
+        if (error &&
+            typeof error === 'object' &&
+            (error.name === 'UserCancel' || error.constructor?.name === 'UserCancel')) {
+            return exports.ResultCode.NFC_USER_CANCELED;
+        }
+        if (!msg || msg.includes('User Canceled') || msg.includes('Unknown empty error')) {
+            return exports.ResultCode.NFC_USER_CANCELED;
+        }
+    }
+    if (msg.includes('NFC_USER_CANCELED_SIGNAL'))
+        return exports.ResultCode.NFC_USER_CANCELED;
+    const keywords = [
+        ['AUTH_WRONG_PASSWORD', exports.ResultCode.AUTH_WRONG_PASSWORD],
+        ['AUTH_INVALID_RESPONSE', exports.ResultCode.AUTH_INVALID_RESPONSE],
+        ['AUTH_VERIFY_FAILED', exports.ResultCode.AUTH_VERIFY_FAILED],
+        ['READ_FAILED', exports.ResultCode.READ_FAILED],
+        ['WRITE_FAILED', exports.ResultCode.WRITE_FAILED],
+        ['CRC16_CHECK_FAILED', exports.ResultCode.CRC16_CHECK_FAILED],
+        ['EMPTY_CARD', exports.ResultCode.CHECK_EMPTY],
+        ['INVALID_CARD_DATA', exports.ResultCode.INVALID_CARD_DATA],
+        ['INVALID_MNEMONIC', exports.ResultCode.INVALID_MNEMONIC],
+        ['UNSUPPORTED_MNEMONIC_LENGTH', exports.ResultCode.UNSUPPORTED_MNEMONIC_LENGTH],
+        ['NFC_LOCK_TIMEOUT', exports.ResultCode.NFC_LOCK_TIMEOUT],
+        ['NFC_CONNECT_FAILED', exports.ResultCode.NFC_CONNECT_FAILED],
+        ['connection failed', exports.ResultCode.NFC_CONNECT_FAILED],
+        ['transceive fail', exports.ResultCode.NFC_CONNECT_FAILED],
+    ];
+    for (const [keyword, code] of keywords) {
+        if (msg.includes(keyword))
+            return code;
+    }
+    return exports.ResultCode.UNKNOWN_ERROR;
+}

package/dist/utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure utility functions – no NFC or platform dependencies.
+ */
+export declare function bytesToHex(bytes: Uint8Array | number[]): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * CRC16-Modbus checksum.
+ * Polynomial 0xA001, initial value 0xFFFF, right-shift algorithm.
+ */
+export declare function calculateCRC16(data: Uint8Array): number;
+/** Convert CRC16 to 2-byte little-endian array. */
+export declare function crc16ToBytes(crc16: number): Uint8Array;
+/**
+ * Extract CRC16 from the last 2 bytes of a data buffer (little-endian).
+ * @throws if buffer is shorter than 2 bytes.
+ */
+export declare function extractCRC16(data: Uint8Array): number;