je_nfc_sdk
Version:
A comprehensive React Native SDK for NFC-based device control and communication
179 lines • 7.21 kB
TypeScript
/**
* NFC Frame Server
*
* Handles framing and processing of NFC communication frames
* according to the specified protocol.
* Enhanced to handle ISO 7816 status words and APDU responses.
* Includes state machine for handling frame errors and processing status.
*/
type ErrorCodes = {
NONE: number;
PROCESSING: number;
INVALID_COMMAND_ID: number;
COMMAND_ID_INDEX: number;
INVALID_DATA_ARGUMENTS: number;
INVALID_FRAME_PAYLOAD_SIZE: number;
INVALID_STOP_FRAME_SIZE: number;
EXCEED_MAX_PAYLOAD_SIZE: number;
};
type StatusWords = {
SUCCESS: number[];
COMMAND_NOT_ALLOWED: number[];
WRONG_PARAMETERS: number[];
FILE_NOT_FOUND: number[];
SECURITY_STATUS_NOT_SATISFIED: number[];
};
interface ParsedFrame {
commandId: number;
idIndex: number;
payload: Uint8Array;
actualData: Uint8Array;
dataLength: number;
errorCode: number;
isValid: boolean;
statusWord?: number[] | null;
apduSuccess?: boolean;
isProcessing?: boolean;
}
interface ResponseResult {
success: boolean;
data?: ParsedFrame | Uint8Array | null;
errorCode?: number;
errorMessage?: string;
statusWord?: number[];
statusMessage?: string;
isProcessing?: boolean;
}
declare class FrameServer {
MAX_FRAME_SIZE: number;
RECORD_SEPARATOR: number;
ERROR_CODES: ErrorCodes;
STATUS_WORDS: StatusWords;
DEFAULT_TIMEOUT: number;
constructor();
/**
* Creates a properly formatted frame for sending to NFC device
* Frame format: [Header(4)] [PayloadLen(1)] [CmdId(1)] [IdIndex(1)] [DataLen(1)] [Data(n)] [ErrorCode(1)] [Separator(1)]
*
* @param {number} commandId - Command ID for the frame
* @param {number} idIndex - ID Index for tracking related frames
* @param {Array|Uint8Array} data - Data payload to include in the frame
* @param {number} instruction - Instruction byte (0xB2 for read, 0xD6 for write)
* @returns {Uint8Array} - Properly formatted frame
*/
createSendFrame(commandId: number, idIndex: number, data?: number[] | Uint8Array, instruction?: number): Uint8Array;
/**
* Create a read request frame
*
* @param {number} commandId - Command ID for the read operation
* @param {number} idIndex - ID Index for tracking
* @param {Array|Uint8Array} parameters - Optional parameters for the read request
* @returns {Uint8Array} - Properly formatted read frame
*/
createReadFrame(commandId: number, idIndex: number, parameters?: number[] | Uint8Array): Uint8Array;
/**
* Create a write request frame
*
* @param {number} commandId - Command ID for the write operation
* @param {number} idIndex - ID Index for tracking
* @param {Array|Uint8Array} data - Data to write
* @returns {Uint8Array} - Properly formatted write frame
*/
createWriteFrame(commandId: number, idIndex: number, data: number[] | Uint8Array): Uint8Array;
/**
* Parse a received frame from the NFC device
* Frame format: [Header(4)] [PayloadLen(1)] [CmdId(1)] [IdIndex(1)] [DataLen(1)] [Data(n)] [ErrorCode(1)] [Separator(1)] [StatusWord(2)]
*
* @param {Uint8Array} frameData - Raw frame data received from NFC
* @returns {ParsedFrame} - Parsed frame with command, index, payload, and error information
*/
parseFrame(frameData: Uint8Array | number[]): ParsedFrame;
/**
* Write data to NFC device with proper framing
* Only checks SW1 and SW2 status words for success/failure
*
* @param {number} commandId - Command ID for the operation
* @param {number} idIndex - ID Index for tracking
* @param {Array|Uint8Array} data - Data to write
* @returns {Promise<ResponseResult>} - Result of the write operation
*/
writeData(commandId: number, idIndex: number, data: number[] | Uint8Array): Promise<ResponseResult>;
/**
* Create a read request frame and send it to the NFC device
*
* @param {number} commandId - Command ID for the read operation
* @param {number} idIndex - ID Index for tracking
* @param {Array|Uint8Array} parameters - Optional parameters for the read request
* @returns {Promise<ResponseResult>} - Result of the read operation
*/
readReq(commandId: number, idIndex: number, parameters?: number[] | Uint8Array): Promise<ResponseResult>;
/**
* Process a response from the NFC device
* Enhanced to first check status words in payload, then apply state machine logic
*
* @param {Uint8Array} responseData - Raw response data from NFC
* @returns {ResponseResult} - Processed response with parsed data
*/
processResponse(responseData: Uint8Array): ResponseResult;
/**
* Check if a status word indicates success (0x90 0x00)
*
* @param {Array|Uint8Array} statusWord - Status word to check
* @returns {boolean} - True if status word indicates success
*/
isSuccessStatusWord(statusWord: number[] | Uint8Array | null): boolean;
/**
* Get human-readable error message for an error code
*
* @param {number} errorCode - Error code from NFC device
* @returns {string} - Human-readable error message
*/
getErrorMessage(errorCode: number): string;
/**
* Get human-readable message for ISO 7816 status word
*
* @param {Array|Uint8Array} statusWord - Status word from ISO 7816 response
* @returns {string} - Human-readable message
*/
getStatusWordMessage(statusWord: number[] | Uint8Array | null): string;
/**
* Utility to send APDU with timeout
*
* @param {Array|Uint8Array} apduCommand - APDU command to send
* @param {number} timeout - Timeout in milliseconds
* @returns {Promise<Uint8Array>} - Response from NFC device
*/
transceiveWithTimeout(apduCommand: number[] | Uint8Array, timeout?: number): Promise<Uint8Array>;
hexFrameToDecimal(hexFrame: Uint8Array, dataLength: number): Promise<number>;
/**
* Poll for operation completion when receiving PROCESSING state
*
* @param {number} commandId - Command ID to poll
* @param {number} idIndex - ID Index to poll
* @param {number} maxAttempts - Maximum number of polling attempts
* @param {number} pollInterval - Time between polls in milliseconds
* @returns {Promise<ResponseResult>} - Final result after polling
*/
pollUntilComplete(commandId: number, idIndex: number, maxAttempts?: number, pollInterval?: number): Promise<ResponseResult>;
/**
* Helper method to format byte array for logging
*
* @param {Array|Uint8Array} bytes - Byte array to format
* @returns {string} - Formatted hex string
*/
formatBytes(bytes: number[] | Uint8Array): string;
/**
* Validate frame structure for debugging
*
* @param {Array|Uint8Array} frame - Frame to validate
* @returns {Object} - Validation result with details
*/
validateFrame(frame: number[] | Uint8Array): {
isValid: boolean;
errors: string[];
details: any;
};
}
declare const _default: FrameServer;
export default _default;
//# sourceMappingURL=NfcServer.d.ts.map