CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

tessl/npm-ledgerhq--errors

Comprehensive error handling library for the Ledger ecosystem with unified error classes, serialization, and hardware wallet status codes

Overview
Eval results
Files

index.mddocs/

@ledgerhq/errors

@ledgerhq/errors provides a comprehensive error handling library for the Ledger ecosystem, offering a unified way to create, serialize, and deserialize custom error classes across Ledger Live and LedgerJS libraries. It includes utilities for creating custom error classes with specific names and properties, serialization/deserialization capabilities for error persistence and transmission, and defines over 100 specific error types for various Ledger hardware wallet operations.

Package Information

  • Package Name: @ledgerhq/errors
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ledgerhq/errors

Core Imports

import { 
  TransportError, 
  TransportStatusError, 
  StatusCodes,
  serializeError, 
  deserializeError,
  createCustomErrorClass,
  // Import specific error classes as needed
  DeviceNotGenuineError,
  UserRefusedOnDevice,
  NotEnoughBalance
} from "@ledgerhq/errors";

For CommonJS:

const { 
  TransportError, 
  TransportStatusError, 
  StatusCodes,
  serializeError, 
  deserializeError,
  createCustomErrorClass
} = require("@ledgerhq/errors");

Basic Usage

import { 
  TransportError, 
  TransportStatusError, 
  StatusCodes,
  serializeError, 
  deserializeError,
  UserRefusedOnDevice 
} from "@ledgerhq/errors";

// Using predefined error classes
try {
  // Device operation that might be refused
  await performDeviceOperation();
} catch (error) {
  if (error instanceof UserRefusedOnDevice) {
    console.log("User declined the operation on device");
  }
}

// Using transport errors
const transportError = new TransportError("Connection failed", "USB_001");
console.log(transportError.message); // "Connection failed"
console.log(transportError.id); // "USB_001"

// Using status errors
const statusError = new TransportStatusError(StatusCodes.USER_REFUSED_ON_DEVICE);
console.log(statusError.statusCode); // Status code number
console.log(statusError.statusText); // Human readable status

// Serializing errors for transmission
const serialized = serializeError(transportError);
console.log(JSON.stringify(serialized));

// Deserializing errors
const deserialized = deserializeError(serialized);
console.log(deserialized instanceof TransportError); // true

Architecture

@ledgerhq/errors is built around several key components:

  • Error Creation System: Factory functions for creating custom error classes with consistent patterns
  • Transport Errors: Specialized error classes for device communication failures
  • Status Code System: Comprehensive mapping of hardware wallet status codes to human-readable messages
  • Serialization Engine: Utilities for converting error objects to/from JSON for persistence and transmission
  • Custom Error Registry: Centralized registry of all Ledger-specific error types with deserialization support
  • Type Safety: Full TypeScript integration with proper error inheritance and type checking

Capabilities

Core Utilities

Essential utility functions for error serialization, deserialization, and custom error class creation.

function serializeError(value: any): undefined | To | string;
function deserializeError(object: any): Error;
function createCustomErrorClass(name: string): CustomErrorFunc;
function addCustomErrorDeserializer(name: string, deserializer: (obj: any) => any): void;

interface To {
  name?: string;
  message?: string;
  stack?: string;
}

type CustomErrorFunc = (message?: string, fields?: { [key: string]: any }) => void;

Core Utilities

Transport Errors

Specialized error classes for handling device communication failures and status code responses.

function TransportError(message: string, id: string): void;
function TransportStatusError(statusCode: number): void;

const StatusCodes: {
  readonly PIN_REMAINING_ATTEMPTS: 0x63c0;
  readonly INCORRECT_LENGTH: 0x6700;
  readonly SECURITY_STATUS_NOT_SATISFIED: 0x6982;
  readonly CONDITIONS_OF_USE_NOT_SATISFIED: 0x6985;
  readonly OK: 0x9000;
  // ... 33+ additional status codes
};

function getAltStatusMessage(code: number): string | undefined | null;

Transport Errors

Device and Hardware Errors

Error classes specific to Ledger hardware device operations, authentication, and device state management.

// Device Communication Errors
const CantOpenDevice: CustomErrorFunc;
const DeviceNotGenuineError: CustomErrorFunc;
const DeviceHalted: CustomErrorFunc;
const DisconnectedDevice: CustomErrorFunc;
const DisconnectedDeviceDuringOperation: CustomErrorFunc;

// Device State Errors
const DeviceOnDashboardExpected: CustomErrorFunc;
const DeviceOnDashboardUnexpected: CustomErrorFunc;
const DeviceInOSUExpected: CustomErrorFunc;
const DeviceShouldStayInApp: CustomErrorFunc;

Device and Hardware Errors

Account and Balance Errors

Error classes for account management, balance validation, and transaction-related operations.

// Account Errors
const AccountNameRequiredError: CustomErrorFunc;
const AccountNotSupported: CustomErrorFunc;
const WrongDeviceForAccount: CustomErrorFunc;

// Balance Errors  
const NotEnoughBalance: CustomErrorFunc;
const NotEnoughBalanceToDelegate: CustomErrorFunc;
const NotEnoughBalanceInParentAccount: CustomErrorFunc;
const NotEnoughSpendableBalance: CustomErrorFunc;
const NotEnoughBalanceBecauseDestinationNotCreated: CustomErrorFunc;

Account and Balance Errors

Validation and Input Errors

Error classes for input validation, address verification, and transaction parameter validation.

// Required Field Errors
const AmountRequired: CustomErrorFunc;
const RecipientRequired: CustomErrorFunc;
const FeeRequired: CustomErrorFunc;

// Address Validation Errors
const InvalidAddress: CustomErrorFunc;
const InvalidAddressBecauseDestinationIsAlsoSource: CustomErrorFunc;
const InvalidXRPTag: CustomErrorFunc;

// Fee Validation Errors
const FeeNotLoaded: CustomErrorFunc;
const FeeTooHigh: CustomErrorFunc;
const FeeEstimationFailed: CustomErrorFunc;

Validation and Input Errors

Network and API Errors

Error classes for network connectivity, API communication, and service availability issues.

// Network Errors
const NetworkDown: CustomErrorFunc;
const WebsocketConnectionError: CustomErrorFunc;
const WebsocketConnectionFailed: CustomErrorFunc;

// API Errors
const LedgerAPIError: CustomErrorFunc;
const LedgerAPIErrorWithMessage: CustomErrorFunc;
const LedgerAPINotAvailable: CustomErrorFunc;
const LedgerAPI4xx: CustomErrorFunc;
const LedgerAPI5xx: CustomErrorFunc;

Network and API Errors

User Interaction Errors

Error classes for user-initiated cancellations, refusals, and interaction-related failures.

// User Refusal Errors
const UserRefusedDeviceNameChange: CustomErrorFunc;
const UserRefusedAddress: CustomErrorFunc;
const UserRefusedFirmwareUpdate: CustomErrorFunc;
const UserRefusedAllowManager: CustomErrorFunc;
const UserRefusedOnDevice: CustomErrorFunc;

// Transport User Errors
const TransportOpenUserCancelled: CustomErrorFunc;
const TransportWebUSBGestureRequired: CustomErrorFunc;

User Interaction Errors

tessl i tessl/npm-ledgerhq--errors@5.50.0

docs

account-errors.md

device-errors.md

index.md

network-errors.md

transport-errors.md

user-errors.md

utilities.md

validation-errors.md

tile.json