@ledgerhq/live-common 34.54.0-nightly.20251206023719 → 34.54.0-nightly.20251209140356

package/src/wallet-api/Exchange/SwapError.ts

@@ -0,0 +1,159 @@
+/**
+ * Simplified Swap Error System
+ * Base error class and specific error types for swap transaction flows
+ */
+
+/**
+ * Base error class for all swap-related errors
+ * Contains error code and nested error information
+ */
+export class SwapError extends Error {
+  cause: {
+    swapCode: string;
+    [key: string]: string | Error | unknown | undefined;
+  };
+  message: string;
+
+  constructor(code = "swap000", nestedError?: Error) {
+    super();
+    this.name = "SwapError";
+
+    // Preserve nested error information
+    this.cause = {
+      swapCode: code,
+      ...(nestedError?.constructor !== Object && nestedError?.constructor !== Array
+        ? { message: `${nestedError}` }
+        : {}),
+      ...nestedError,
+    };
+
+    this.message = nestedError?.message ? nestedError.message : `${nestedError}`;
+  }
+}
+
+/**
+ * Error during nonce/deviceTransactionId generation step
+ * Typically occurs when calling startSwap()
+ */
+export class NonceStepError extends SwapError {
+  constructor(nestedError?: Error) {
+    super("swap001", nestedError);
+    this.name = "NonceStepError";
+  }
+}
+
+/**
+ * Error during payload retrieval step
+ * Occurs when communicating with backend to get transaction payload
+ */
+export class PayloadStepError extends SwapError {
+  constructor(nestedError?: Error) {
+    super("swap002", nestedError);
+    this.name = "PayloadStepError";
+  }
+}
+
+/**
+ * Error during transaction signature step
+ * Occurs when user rejects or device fails during completeSwap()
+ */
+export class SignatureStepError extends SwapError {
+  constructor(nestedError?: Error) {
+    super("swap003", nestedError);
+    this.name = "SignatureStepError";
+  }
+}
+
+/**
+ * Special case: signature error that should be ignored/handled silently
+ * Used for expected user cancellations
+ */
+export class IgnoredSignatureStepError extends SwapError {
+  constructor(nestedError?: Error) {
+    super("swap003Ignored", nestedError);
+    this.name = "SignatureStepError";
+  }
+}
+
+/**
+ * Error when user doesn't have sufficient funds
+ * Thrown during balance validation
+ */
+export class NotEnoughFunds extends SwapError {
+  constructor() {
+    super("swap004");
+    this.name = "NotEnoughFunds";
+  }
+}
+
+/**
+ * Error when unable to retrieve account list
+ * Occurs during account lookup phase
+ */
+export class ListAccountError extends SwapError {
+  constructor(nestedError?: Error) {
+    super("swap005", nestedError);
+    this.name = "ListAccountError";
+  }
+}
+
+/**
+ * Error when unable to retrieve currency information
+ * Occurs during currency lookup phase
+ */
+export class ListCurrencyError extends SwapError {
+  constructor(nestedError?: Error) {
+    super("swap006", nestedError);
+    this.name = "ListCurrencyError";
+  }
+}
+
+/**
+ * Error when specified account ID cannot be found
+ * Thrown when fromAccountId or toAccountId is invalid
+ */
+export class UnknownAccountError extends SwapError {
+  constructor(nestedError?: Error) {
+    super("swap007", nestedError);
+    this.name = "UnknownAccountError";
+  }
+}
+
+/**
+ * Error when extra identifier is required but missing
+ * Some chains require payinExtraId (e.g., XLM memo, XRP tag)
+ */
+export class PayinExtraIdError extends SwapError {
+  constructor(nestedError?: Error) {
+    super("swap010", nestedError);
+    this.name = "PayinExtraIdError";
+  }
+}
+
+/**
+ * CompleteSwap/CompleteExchange step information
+ * Tracks which hardware wallet step failed
+ */
+export type CompleteExchangeStep =
+  | "INIT"
+  | "SET_PARTNER_KEY"
+  | "CHECK_PARTNER"
+  | "PROCESS_TRANSACTION"
+  | "CHECK_TRANSACTION_SIGNATURE"
+  | "CHECK_PAYOUT_ADDRESS"
+  | "CHECK_REFUND_ADDRESS"
+  | "SIGN_COIN_TRANSACTION";
+
+/**
+ * Error that occurs during completeSwap with step tracking
+ * Useful for debugging hardware wallet interactions
+ */
+export class CompleteExchangeError extends Error {
+  step: CompleteExchangeStep;
+
+  constructor(step: CompleteExchangeStep, message?: string) {
+    super(message);
+    this.name = "CompleteExchangeError";
+    this.step = step;
+  }
+}

package/src/wallet-api/Exchange/handleSwapErrors.test.ts

@@ -0,0 +1,46 @@
+/* eslint-env jest */
+import { handleErrors, isHandledError } from "./handleSwapErrors";
+import { IgnoredSignatureStepError, SignatureStepError } from "./SwapError";
+
+describe("handleErrors", () => {
+  it("marks default ignored message errors as handled and rethrows", async () => {
+    const error = new Error("User refused");
+
+    expect(() => handleErrors(error)).toThrow(error);
+    expect(isHandledError(error)).toBe(true);
+  });
+
+  it("marks default ignored error names as handled and rethrows", async () => {
+    const nestedError = new Error("Device mismatch");
+    nestedError.name = "WrongDeviceForAccount";
+    const error = new SignatureStepError(nestedError);
+
+    expect(() => handleErrors(error)).toThrow(error);
+    expect(isHandledError(error)).toBe(true);
+  });
+
+  it("invokes onDisplayError for swap errors that should be surfaced", async () => {
+    const error = new SignatureStepError(new Error("Unexpected failure"));
+    const onDisplayError = jest.fn().mockResolvedValue(undefined);
+
+    await expect(handleErrors(error, { onDisplayError })).resolves.toBeUndefined();
+    expect(onDisplayError).toHaveBeenCalledWith(error);
+  });
+
+  it("skips onDisplayError for swap003Ignored errors and marks them handled", async () => {
+    const error = new IgnoredSignatureStepError(new Error("User rejected"));
+    const onDisplayError = jest.fn();
+
+    expect(() => handleErrors(error, { onDisplayError })).toThrow(error);
+    expect(onDisplayError).not.toHaveBeenCalled();
+    expect(isHandledError(error)).toBe(true);
+  });
+
+  it("respects custom ignored error names", async () => {
+    const error = new Error("Rate limited");
+    Object.assign(error, { cause: { name: "RateLimitedError" } });
+
+    expect(() => handleErrors(error, { ignoredErrorNames: ["RateLimitedError"] })).toThrow(error);
+    expect(isHandledError(error)).toBe(true);
+  });
+});

package/src/wallet-api/Exchange/handleSwapErrors.ts

@@ -0,0 +1,161 @@
+/**
+ * Error Handler
+ * Decides how to handle errors - display to user, mark as handled, or throw
+ */
+
+import { SwapError } from "./SwapError";
+
+/**
+ * Interface for error handler options
+ */
+export interface ErrorHandlerOptions {
+  /**
+   * Callback to display error to user (optional)
+   * If not provided, errors are simply thrown
+   */
+  onDisplayError?: (error: SwapError) => Promise<void>;
+
+  /**
+   * Additional error names to ignore (won't be displayed)
+   */
+  ignoredErrorNames?: string[];
+
+  /**
+   * Additional error messages to ignore (won't be displayed)
+   */
+  ignoredMessages?: string[];
+}
+
+/**
+ * Default error names that should be marked as "handled"
+ * These are typically user input errors that can be retried
+ */
+const DEFAULT_IGNORED_ERROR_NAMES = new Set([
+  "WrongDeviceForAccount",
+  "WrongDeviceForAccountPayout",
+  "WrongDeviceForAccountRefund",
+  "UserRefusedOnDevice",
+]);
+
+/**
+ * Default error messages that should be marked as "handled"
+ */
+const DEFAULT_IGNORED_MESSAGES = new Set(["User refused", "User rejected"]);
+
+type SwapErrorCauseDetails = {
+  swapCode?: string;
+  name?: string;
+  message?: string;
+};
+
+type ErrorWithCause = Error & { cause?: unknown };
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function hasCause(value: Error): value is ErrorWithCause {
+  return "cause" in value;
+}
+
+function toCauseDetails(rawCause: unknown): SwapErrorCauseDetails | undefined {
+  if (!isRecord(rawCause)) {
+    return undefined;
+  }
+
+  const swapCode = typeof rawCause.swapCode === "string" ? rawCause.swapCode : undefined;
+  const name = typeof rawCause.name === "string" ? rawCause.name : undefined;
+  const message = typeof rawCause.message === "string" ? rawCause.message : undefined;
+
+  if (swapCode || name || message) {
+    return { swapCode, name, message };
+  }
+
+  return undefined;
+}
+
+function extractErrorDetails(value: unknown): {
+  message: string;
+  cause?: SwapErrorCauseDetails;
+} {
+  if (value instanceof SwapError) {
+    return { message: value.message, cause: value.cause };
+  }
+
+  if (value instanceof Error) {
+    return {
+      message: value.message,
+      cause: hasCause(value) ? toCauseDetails(value.cause) : undefined,
+    };
+  }
+
+  if (isRecord(value) && typeof value.message === "string") {
+    const rawCause = "cause" in value ? value.cause : undefined;
+    const cause = toCauseDetails(rawCause);
+    return { message: value.message, cause };
+  }
+
+  return { message: typeof value === "string" ? value : JSON.stringify(value ?? "Unknown error") };
+}
+
+function markErrorAsHandled<T>(error: T): T {
+  if (isRecord(error)) {
+    Object.assign(error, { handled: true });
+  }
+
+  return error;
+}
+
+/**
+ * Handles errors by deciding whether to display them or mark as handled
+ *
+ * @param error - The error to handle
+ * @param options - Configuration options
+ * @throws Enhanced error with `handled` flag if applicable
+ */
+export function handleErrors(error: unknown, options: ErrorHandlerOptions = {}): Promise<void> {
+  const { onDisplayError, ignoredErrorNames = [], ignoredMessages = [] } = options;
+
+  // Merge default and custom ignored values
+  const allIgnoredNames = new Set([...DEFAULT_IGNORED_ERROR_NAMES, ...ignoredErrorNames]);
+
+  const allIgnoredMessages = new Set([...DEFAULT_IGNORED_MESSAGES, ...ignoredMessages]);
+
+  const { message, cause } = extractErrorDetails(error);
+
+  // Check if error should be marked as handled (retry-ready)
+  const isIgnoredMessage = allIgnoredMessages.has(message);
+  const isIgnoredName = typeof cause?.name === "string" && allIgnoredNames.has(cause.name);
+  const isIgnoredSwapCode = cause?.swapCode === "swap003Ignored";
+
+  if (isIgnoredMessage || isIgnoredName || isIgnoredSwapCode) {
+    throw markErrorAsHandled(error);
+  }
+
+  // Display error to user if handler provided
+  if (error instanceof SwapError && onDisplayError) {
+    // Skip displaying "swap003Ignored" errors
+    if (cause?.swapCode !== "swap003Ignored") {
+      return onDisplayError(error);
+    }
+  }
+
+  // Always throw the error so caller can handle it
+  throw error;
+}
+
+/**
+ * Type guard to check if an error is marked as handled
+ */
+export function isHandledError(error: unknown): boolean {
+  return isRecord(error) && error.handled === true;
+}
+
+/**
+ * Extracts swap code from error if available
+ */
+export function getSwapCode(error: unknown): string | undefined {
+  if (error instanceof SwapError) {
+    return error.cause.swapCode;
+  }
+  return undefined;
+}

package/src/wallet-api/Exchange/index.ts

@@ -0,0 +1,26 @@
+// Export all error classes
+export {
+  SwapError,
+  NonceStepError,
+  PayloadStepError,
+  SignatureStepError,
+  IgnoredSignatureStepError,
+  NotEnoughFunds,
+  ListAccountError,
+  ListCurrencyError,
+  UnknownAccountError,
+  PayinExtraIdError,
+  CompleteExchangeError,
+  type CompleteExchangeStep,
+} from "./SwapError";
+
+// Export parser utilities
+export { createStepError, StepError, CustomErrorType, type ParseError } from "./parser";
+
+// Export error handler
+export {
+  handleErrors,
+  isHandledError,
+  getSwapCode,
+  type ErrorHandlerOptions,
+} from "./handleSwapErrors";

package/src/wallet-api/Exchange/parser.test.ts

@@ -0,0 +1,86 @@
+import { createStepError, CustomErrorType, parseError, StepError } from "./parser";
+import {
+  IgnoredSignatureStepError,
+  ListAccountError,
+  ListCurrencyError,
+  NonceStepError,
+  NotEnoughFunds,
+  PayloadStepError,
+  PayinExtraIdError,
+  SignatureStepError,
+  SwapError,
+  UnknownAccountError,
+} from "./SwapError";
+
+type StepExpectation = {
+  step: StepError;
+  ExpectedError: new (err?: Error) => SwapError;
+  swapCode: string;
+};
+
+const STEP_EXPECTATIONS: StepExpectation[] = [
+  { step: StepError.NONCE, ExpectedError: NonceStepError, swapCode: "swap001" },
+  { step: StepError.PAYLOAD, ExpectedError: PayloadStepError, swapCode: "swap002" },
+  { step: StepError.SIGNATURE, ExpectedError: SignatureStepError, swapCode: "swap003" },
+  {
+    step: StepError.IGNORED_SIGNATURE,
+    ExpectedError: IgnoredSignatureStepError,
+    swapCode: "swap003Ignored",
+  },
+  { step: StepError.CHECK_FUNDS, ExpectedError: NotEnoughFunds, swapCode: "swap004" },
+  { step: StepError.LIST_ACCOUNT, ExpectedError: ListAccountError, swapCode: "swap005" },
+  { step: StepError.LIST_CURRENCY, ExpectedError: ListCurrencyError, swapCode: "swap006" },
+  { step: StepError.UNKNOWN_ACCOUNT, ExpectedError: UnknownAccountError, swapCode: "swap007" },
+  { step: StepError.PAYIN_EXTRA_ID, ExpectedError: PayinExtraIdError, swapCode: "swap010" },
+];
+
+const mockDownstreamError = new Error("error message");
+
+describe("parseError", () => {
+  it.each(STEP_EXPECTATIONS)(
+    "$step - returns generic error when customErrorType is not passed in",
+    ({ step }) => {
+      const typedStep = step as StepError;
+
+      const error = parseError({
+        error: mockDownstreamError,
+        step: typedStep,
+      });
+
+      expect(error).toBe(mockDownstreamError);
+    },
+  );
+
+  it.each(STEP_EXPECTATIONS)(
+    "$step - returns specific swap error when customErrorType is 'swap'",
+    ({ step, ExpectedError, swapCode }) => {
+      const typedStep = step as StepError;
+
+      const error = parseError({
+        error: mockDownstreamError,
+        step: typedStep,
+        customErrorType: CustomErrorType.SWAP,
+      }) as SwapError;
+
+      expect(error).toBeInstanceOf(ExpectedError);
+      expect(error.cause.swapCode).toBe(swapCode);
+    },
+  );
+});
+
+describe("createStepError", () => {
+  it("returns downstream error when no step is supplied", () => {
+    expect(createStepError({ error: mockDownstreamError })).toBe(mockDownstreamError);
+  });
+
+  it.each(STEP_EXPECTATIONS)(
+    "$step - wraps downstream error with appropriate swap error",
+    ({ step, ExpectedError, swapCode }) => {
+      const typedStep = step as StepError;
+      const wrapped = createStepError({ error: mockDownstreamError, step: typedStep }) as SwapError;
+
+      expect(wrapped).toBeInstanceOf(ExpectedError);
+      expect(wrapped.cause.swapCode).toBe(swapCode);
+    },
+  );
+});

package/src/wallet-api/Exchange/parser.ts

@@ -0,0 +1,119 @@
+/**
+ * Error Parser
+ * Routes errors to appropriate error classes based on step and context
+ */
+
+import {
+  IgnoredSignatureStepError,
+  ListAccountError,
+  ListCurrencyError,
+  NonceStepError,
+  NotEnoughFunds,
+  PayinExtraIdError,
+  PayloadStepError,
+  SignatureStepError,
+  UnknownAccountError,
+} from "./SwapError";
+
+/**
+ * Transaction step where error occurred
+ */
+export enum StepError {
+  NONCE = "NonceStepError",
+  PAYLOAD = "PayloadStepError",
+  SIGNATURE = "SignatureStepError",
+  IGNORED_SIGNATURE = "IgnoredSignatureStepError",
+  CHECK_FUNDS = "CheckFundsStepError",
+  LIST_ACCOUNT = "ListAccountStepError",
+  LIST_CURRENCY = "ListCurrencyStepError",
+  UNKNOWN_ACCOUNT = "UnknownAccountStepError",
+  PAYIN_EXTRA_ID = "PayinExtraIdStepError",
+}
+
+/**
+ * Input for error parsing
+ */
+export enum CustomErrorType {
+  SWAP = "swap",
+}
+
+export type ParseError = {
+  error: Error;
+  step?: StepError;
+  customErrorType?: CustomErrorType;
+};
+
+/**
+ * Maps step errors to error constructors
+ */
+const ErrorMap: Record<StepError, new (err?: Error) => Error> = {
+  [StepError.NONCE]: NonceStepError,
+  [StepError.PAYLOAD]: PayloadStepError,
+  [StepError.SIGNATURE]: SignatureStepError,
+  [StepError.IGNORED_SIGNATURE]: IgnoredSignatureStepError,
+  [StepError.CHECK_FUNDS]: NotEnoughFunds,
+  [StepError.LIST_ACCOUNT]: ListAccountError,
+  [StepError.LIST_CURRENCY]: ListCurrencyError,
+  [StepError.UNKNOWN_ACCOUNT]: UnknownAccountError,
+  [StepError.PAYIN_EXTRA_ID]: PayinExtraIdError,
+};
+
+/**
+ * Creates a step-specific error by wrapping the original error
+ *
+ * @param error - Original error that occurred
+ * @param step - Step where error occurred (optional)
+ * @returns Wrapped error or original error if no step specified
+ */
+export function createStepError({ error, step }: ParseError): Error {
+  // If no step specified, return original error
+  if (!step) {
+    return error;
+  }
+
+  // Get error constructor for this step
+  const ErrorConstructor = ErrorMap[step];
+
+  if (!ErrorConstructor) {
+    return error;
+  }
+
+  // Wrap original error in step-specific error class
+  return new ErrorConstructor(error);
+}
+
+/**
+ * Parses an error to determine the correct error class to return based on the context.
+ */
+export function parseError({ error, step, customErrorType }: ParseError): Error {
+  if (!step || customErrorType !== CustomErrorType.SWAP) {
+    return error;
+  }
+
+  return createStepError({ error, step });
+}
+
+export const hasMessage = (value: unknown): value is { message?: unknown } =>
+  Boolean(value && typeof value === "object" && "message" in value);
+
+export const toError = (value: unknown): Error => {
+  if (value instanceof Error) {
+    return value;
+  }
+
+  if (hasMessage(value) && typeof value.message === "string") {
+    return new Error(value.message);
+  }
+
+  return new Error(
+    typeof value === "string"
+      ? value
+      : (() => {
+          try {
+            return JSON.stringify(value);
+          } catch {
+            return String(value);
+          }
+        })(),
+  );
+};