Transport Errors

/**
 * TransportError is used for any generic transport errors.
 * e.g. Error thrown when data received by exchanges are incorrect or if exchanged failed to communicate with the device for various reason.
 * @param message - Error message describing the issue
 * @param id - Unique identifier for the error instance
 */
function TransportError(message: string, id: string): void;

import { TransportError } from "@ledgerhq/errors";

// Create a transport error
const error = new TransportError("Failed to exchange data with device", "APDU_001");
console.log(error.message); // "Failed to exchange data with device"
console.log(error.id); // "APDU_001"
console.log(error.name); // "TransportError"

// instanceof checks work
console.log(error instanceof TransportError); // true
console.log(error instanceof Error); // true

// Common transport error scenarios
const usbError = new TransportError("USB connection lost", "USB_DISCONNECT");
const bluetoothError = new TransportError("Bluetooth pairing failed", "BT_PAIR_FAIL");
const webHidError = new TransportError("WebHID device not found", "WEBHID_404");

/**
 * Error thrown when a device returned a non success status.
 * the error.statusCode is one of the `StatusCodes` exported by this library.
 * @param statusCode - The numeric status code returned by the device
 */
function TransportStatusError(statusCode: number): void;

import { TransportStatusError, StatusCodes } from "@ledgerhq/errors";

// Create status error with known status code
const error = new TransportStatusError(StatusCodes.CONDITIONS_OF_USE_NOT_SATISFIED);
console.log(error.statusCode); // 0x6985
console.log(error.statusText); // "CONDITIONS_OF_USE_NOT_SATISFIED"
console.log(error.message); // "Ledger device: Condition of use not satisfied (denied by the user?) (0x6985)"

// Create status error with unknown status code
const unknownError = new TransportStatusError(0x1234);
console.log(unknownError.statusCode); // 0x1234
console.log(unknownError.statusText); // "UNKNOWN_ERROR"
console.log(unknownError.message); // "Ledger device: UNKNOWN_ERROR (0x1234)"

// Common status error scenarios
const lockedError = new TransportStatusError(StatusCodes.SECURITY_STATUS_NOT_SATISFIED);
const incorrectLengthError = new TransportStatusError(StatusCodes.INCORRECT_LENGTH);
const technicalError = new TransportStatusError(StatusCodes.TECHNICAL_PROBLEM);

const StatusCodes: {
  readonly PIN_REMAINING_ATTEMPTS: 0x63c0;
  readonly INCORRECT_LENGTH: 0x6700;
  readonly MISSING_CRITICAL_PARAMETER: 0x6800;
  readonly COMMAND_INCOMPATIBLE_FILE_STRUCTURE: 0x6981;
  readonly SECURITY_STATUS_NOT_SATISFIED: 0x6982;
  readonly CONDITIONS_OF_USE_NOT_SATISFIED: 0x6985;
  readonly INCORRECT_DATA: 0x6a80;
  readonly NOT_ENOUGH_MEMORY_SPACE: 0x6a84;
  readonly REFERENCED_DATA_NOT_FOUND: 0x6a88;
  readonly FILE_ALREADY_EXISTS: 0x6a89;
  readonly INCORRECT_P1_P2: 0x6b00;
  readonly INS_NOT_SUPPORTED: 0x6d00;
  readonly CLA_NOT_SUPPORTED: 0x6e00;
  readonly TECHNICAL_PROBLEM: 0x6f00;
  readonly OK: 0x9000;
  readonly MEMORY_PROBLEM: 0x9240;
  readonly NO_EF_SELECTED: 0x9400;
  readonly INVALID_OFFSET: 0x9402;
  readonly FILE_NOT_FOUND: 0x9404;
  readonly INCONSISTENT_FILE: 0x9408;
  readonly ALGORITHM_NOT_SUPPORTED: 0x9484;
  readonly INVALID_KCV: 0x9485;
  readonly CODE_NOT_INITIALIZED: 0x9802;
  readonly ACCESS_CONDITION_NOT_FULFILLED: 0x9804;
  readonly CONTRADICTION_SECRET_CODE_STATUS: 0x9808;
  readonly CONTRADICTION_INVALIDATION: 0x9810;
  readonly CODE_BLOCKED: 0x9840;
  readonly MAX_VALUE_REACHED: 0x9850;
  readonly GP_AUTH_FAILED: 0x6300;
  readonly LICENSING: 0x6f42;
  readonly HALTED: 0x6faa;
};

import { StatusCodes, TransportStatusError } from "@ledgerhq/errors";

// Check specific status codes
if (statusCode === StatusCodes.OK) {
  console.log("Operation successful");
} else if (statusCode === StatusCodes.CONDITIONS_OF_USE_NOT_SATISFIED) {
  console.log("User denied the operation");
}

// Use status codes with TransportStatusError
const createStatusError = (code: number) => {
  return new TransportStatusError(code);
};

// Common status code patterns
const successCode = StatusCodes.OK; // 0x9000
const userDenialCode = StatusCodes.CONDITIONS_OF_USE_NOT_SATISFIED; // 0x6985
const securityCode = StatusCodes.SECURITY_STATUS_NOT_SATISFIED; // 0x6982
const technicalCode = StatusCodes.TECHNICAL_PROBLEM; // 0x6f00

/**
 * Returns human-readable message for common status codes
 * @param code - The numeric status code
 * @returns Human-readable message or undefined for unknown codes
 */
function getAltStatusMessage(code: number): string | undefined | null;

import { getAltStatusMessage, StatusCodes } from "@ledgerhq/errors";

// Get alternative messages for common codes
console.log(getAltStatusMessage(StatusCodes.INCORRECT_LENGTH)); 
// "Incorrect length"

console.log(getAltStatusMessage(StatusCodes.SECURITY_STATUS_NOT_SATISFIED)); 
// "Security not satisfied (dongle locked or have invalid access rights)"

console.log(getAltStatusMessage(StatusCodes.CONDITIONS_OF_USE_NOT_SATISFIED)); 
// "Condition of use not satisfied (denied by the user?)"

console.log(getAltStatusMessage(StatusCodes.INCORRECT_DATA)); 
// "Invalid data received"

// Technical problem range
console.log(getAltStatusMessage(0x6f01)); // "Internal error, please report"

// Unknown codes return undefined
console.log(getAltStatusMessage(0x1234)); // undefined

// Transport interface errors
const TransportOpenUserCancelled: CustomErrorFunc;
const TransportInterfaceNotAvailable: CustomErrorFunc;
const TransportRaceCondition: CustomErrorFunc;
const TransportWebUSBGestureRequired: CustomErrorFunc;

import { 
  TransportOpenUserCancelled,
  TransportInterfaceNotAvailable,
  TransportRaceCondition,
  TransportWebUSBGestureRequired
} from "@ledgerhq/errors";

// User cancelled transport selection
throw new TransportOpenUserCancelled("User cancelled device selection");

// Transport interface not available
throw new TransportInterfaceNotAvailable("WebUSB not supported in this browser");

// Multiple operations competing for transport
throw new TransportRaceCondition("Another operation is already using the transport");

// WebUSB requires user gesture
throw new TransportWebUSBGestureRequired("WebUSB requires user gesture to access device");