@ledgerhq/live-common 34.54.0 → 34.55.0-nightly.20251210100832

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

@@ -0,0 +1,126 @@
+/* eslint-env jest */
+import {
+  IgnoredSignatureStepError,
+  ListAccountError,
+  ListCurrencyError,
+  NonceStepError,
+  NotEnoughFunds,
+  PayloadStepError,
+  PayinExtraIdError,
+  SignatureStepError,
+  SwapError,
+  UnknownAccountError,
+} from "./SwapError";
+
+describe("SwapError", () => {
+  it("captures nested error metadata", () => {
+    const nested = new Error("payload failed");
+    Object.assign(nested, { code: "E500" });
+
+    const error = new SwapError("swap999", nested);
+
+    expect(error).toBeInstanceOf(SwapError);
+    expect(error.cause.swapCode).toBe("swap999");
+    expect(error.cause.message).toBe(String(nested));
+    expect(error.cause.code).toBe("E500");
+    expect(error.message).toBe("payload failed");
+  });
+
+  it("defaults to swap000 when no code provided", () => {
+    const error = new SwapError();
+
+    expect(error.cause.swapCode).toBe("swap000");
+    expect(error.message).toBe("undefined");
+  });
+});
+
+type DerivedErrorCase = {
+  label: string;
+  create: (nested?: Error) => SwapError;
+  swapCode: string;
+  name: string;
+  propagatesMessage?: boolean;
+};
+
+const DERIVED_ERROR_CASES: DerivedErrorCase[] = [
+  {
+    label: "NonceStepError",
+    create: nested => new NonceStepError(nested),
+    swapCode: "swap001",
+    name: "NonceStepError",
+    propagatesMessage: true,
+  },
+  {
+    label: "PayloadStepError",
+    create: nested => new PayloadStepError(nested),
+    swapCode: "swap002",
+    name: "PayloadStepError",
+    propagatesMessage: true,
+  },
+  {
+    label: "SignatureStepError",
+    create: nested => new SignatureStepError(nested),
+    swapCode: "swap003",
+    name: "SignatureStepError",
+    propagatesMessage: true,
+  },
+  {
+    label: "IgnoredSignatureStepError",
+    create: nested => new IgnoredSignatureStepError(nested),
+    swapCode: "swap003Ignored",
+    name: "SignatureStepError",
+    propagatesMessage: true,
+  },
+  {
+    label: "NotEnoughFunds",
+    create: () => new NotEnoughFunds(),
+    swapCode: "swap004",
+    name: "NotEnoughFunds",
+  },
+  {
+    label: "ListAccountError",
+    create: nested => new ListAccountError(nested),
+    swapCode: "swap005",
+    name: "ListAccountError",
+    propagatesMessage: true,
+  },
+  {
+    label: "ListCurrencyError",
+    create: nested => new ListCurrencyError(nested),
+    swapCode: "swap006",
+    name: "ListCurrencyError",
+    propagatesMessage: true,
+  },
+  {
+    label: "UnknownAccountError",
+    create: nested => new UnknownAccountError(nested),
+    swapCode: "swap007",
+    name: "UnknownAccountError",
+    propagatesMessage: true,
+  },
+  {
+    label: "PayinExtraIdError",
+    create: nested => new PayinExtraIdError(nested),
+    swapCode: "swap010",
+    name: "PayinExtraIdError",
+    propagatesMessage: true,
+  },
+];
+
+describe.each(DERIVED_ERROR_CASES)(
+  "Derived $label",
+  ({ create, swapCode, name, propagatesMessage }) => {
+    it("inherits SwapError defaults", () => {
+      const nested = new Error("step failure");
+      const error = create(propagatesMessage ? nested : undefined);
+
+      expect(error).toBeInstanceOf(SwapError);
+      expect(error.name).toBe(name);
+      expect(error.cause.swapCode).toBe(swapCode);
+
+      if (propagatesMessage) {
+        expect(error.message).toBe("step failure");
+      }
+    });
+  },
+);

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);
+    },
+  );
+});