@lifi/sdk 3.0.2-beta.0 → 3.1.0

package/src/core/Solana/parseSolanaErrors.ts

@@ -0,0 +1,45 @@
+import type { LiFiStep, Process } from '@lifi/types'
+import { BaseError } from '../../errors/baseError.js'
+import { ErrorMessage, LiFiErrorCode } from '../../errors/constants.js'
+import { TransactionError, UnknownError } from '../../errors/errors.js'
+import { SDKError } from '../../errors/SDKError.js'
+
+export const parseSolanaErrors = async (
+  e: Error,
+  step?: LiFiStep,
+  process?: Process
+): Promise<SDKError> => {
+  if (e instanceof SDKError) {
+    e.step = e.step ?? step
+    e.process = e.process ?? process
+    return e
+  }
+
+  const baseError = handleSpecificErrors(e)
+
+  return new SDKError(baseError, step, process)
+}
+
+const handleSpecificErrors = (e: any) => {
+  if (e.name === 'WalletSignTransactionError') {
+    return new TransactionError(LiFiErrorCode.SignatureRejected, e.message, e)
+  }
+
+  if (e.name === 'SendTransactionError') {
+    return new TransactionError(LiFiErrorCode.TransactionFailed, e.message, e)
+  }
+
+  if (e.message?.includes('simulate')) {
+    return new TransactionError(
+      LiFiErrorCode.TransactionSimulationFailed,
+      e.message,
+      e
+    )
+  }
+
+  if (e instanceof BaseError) {
+    return e
+  }
+
+  return new UnknownError(e.message || ErrorMessage.UnknownError, e)
+}

package/src/core/checkBalance.ts

@@ -1,7 +1,7 @@
 import type { LiFiStep } from '@lifi/types'
 import { formatUnits } from 'viem'
 import { getTokenBalance } from '../services/balance.js'
-import { BalanceError } from '../utils/errors.js'
+import { BalanceError } from '../errors/errors.js'
 import { sleep } from './utils.js'
 
 export const checkBalance = async (
@@ -40,7 +40,7 @@ export const checkBalance = async (
             `start a new one with a maximum of ${current} ${token.symbol}.`
         }
 
-        throw new BalanceError('The balance is too low.', errorMessage)
+        throw new BalanceError('The balance is too low.')
       }
     }
   }

package/src/core/stepComparison.ts

@@ -1,5 +1,6 @@
 import type { LiFiStep } from '@lifi/types'
-import { LiFiErrorCode, TransactionError } from '../utils/errors.js'
+import { LiFiErrorCode } from '../errors/constants.js'
+import { TransactionError } from '../errors/errors.js'
 import type { StatusManager } from './StatusManager.js'
 import type { ExecutionOptions } from './types.js'
 import { checkStepSlippageThreshold } from './utils.js'
@@ -41,9 +42,7 @@ export const stepComparison = async (
     // The user declined the new exchange rate, so we are not going to proceed
     throw new TransactionError(
       LiFiErrorCode.ExchangeRateUpdateCanceled,
-      'Exchange rate has changed!',
-      `Transaction was not sent, your funds are still in your wallet.
-      The exchange rate has changed and the previous estimation can not be fulfilled due to value loss.`
+      `Exchange rate has changed!\nTransaction was not sent, your funds are still in your wallet.\nThe exchange rate has changed and the previous estimation can not be fulfilled due to value loss.`
     )
   }
 

package/src/core/types.ts

@@ -114,5 +114,8 @@ export interface ExecutionOptions {
   updateRouteHook?: UpdateRouteHook
   updateTransactionRequestHook?: TransactionRequestUpdateHook
   executeInBackground?: boolean
+  /**
+   * @deprecated
+   */
   infiniteApproval?: boolean
 }

package/src/core/waitForReceivingTransaction.ts

@@ -5,7 +5,7 @@ import type {
   StatusResponse,
 } from '@lifi/types'
 import { getStatus } from '../services/api.js'
-import { ServerError } from '../utils/errors.js'
+import { ServerError } from '../errors/errors.js'
 import { repeatUntilDone } from '../utils/utils.js'
 import type { StatusManager } from './StatusManager.js'
 import { getSubstatusMessage } from './processMessages.js'

package/src/errors/SDKError.ts

@@ -0,0 +1,25 @@
+import type { LiFiStep, Process } from '@lifi/types'
+import { version } from '../version.js'
+import type { BaseError } from './baseError.js'
+import { type ErrorCode } from './constants.js'
+
+// Note: SDKError is used to wrapper and present errors at the top level
+// Where opportunity allows we also add the step and the process related to the error
+export class SDKError extends Error {
+  step?: LiFiStep
+  process?: Process
+  code: ErrorCode
+  override name = 'SDKError'
+  override cause: BaseError
+
+  constructor(cause: BaseError, step?: LiFiStep, process?: Process) {
+    const errorMessage = `${cause.message ? `[${cause.name}] ${cause.message}` : 'Unknown error occurred'}\nLI.FI SDK version: ${version}`
+    super(errorMessage)
+    this.name = 'SDKError'
+    this.step = step
+    this.process = process
+    this.cause = cause
+    this.stack = this.cause.stack
+    this.code = cause.code
+  }
+}

package/src/errors/baseError.ts

@@ -0,0 +1,22 @@
+import type { ErrorCode, ErrorName } from './constants.js'
+import { getRootCause } from './utils/rootCause.js'
+
+// Note: we use the BaseErrors to capture errors at specific points in the code
+//  they can carry addition to help give more context
+export class BaseError extends Error {
+  code: ErrorCode
+  override cause?: Error
+
+  constructor(name: ErrorName, code: number, message: string, cause?: Error) {
+    super(message)
+
+    this.name = name
+    this.code = code
+    this.cause = cause
+
+    const rootCause = getRootCause(this.cause)
+    if (rootCause && rootCause.stack) {
+      this.stack = rootCause.stack
+    }
+  }
+}

package/src/errors/constants.ts

@@ -0,0 +1,45 @@
+export enum ErrorName {
+  RPCError = 'RPCError',
+  ProviderError = 'ProviderError',
+  ServerError = 'ServerError',
+  TransactionError = 'TransactionError',
+  ValidationError = 'ValidationError',
+  BalanceError = 'BalanceError',
+  NotFoundError = 'NotFoundError',
+  UnknownError = 'UnknownError',
+  SlippageError = 'SlippageError',
+  HTTPError = 'HTTPError',
+}
+
+export type ErrorCode = LiFiErrorCode
+
+export enum LiFiErrorCode {
+  InternalError = 1000,
+  ValidationError = 1001,
+  TransactionUnderpriced = 1002,
+  TransactionFailed = 1003,
+  Timeout = 1004,
+  ProviderUnavailable = 1005,
+  NotFound = 1006,
+  ChainSwitchError = 1007,
+  TransactionUnprepared = 1008,
+  GasLimitError = 1009,
+  TransactionCanceled = 1010,
+  SlippageError = 1011,
+  SignatureRejected = 1012,
+  BalanceError = 1013,
+  AllowanceRequired = 1014,
+  InsufficientFunds = 1015,
+  ExchangeRateUpdateCanceled = 1016,
+  WalletChangedDuringExecution = 1017,
+  TransactionExpired = 1018,
+  TransactionSimulationFailed = 1019,
+}
+
+export enum ErrorMessage {
+  UnknownError = 'Unknown error occurred.',
+  SlippageError = 'The slippage is larger than the defined threshold. Please request a new route to get a fresh quote.',
+  GasLimitLow = 'Gas limit is too low.',
+  TransactionUnderpriced = 'Transaction is underpriced.',
+  TransactionReverted = 'Transaction was reverted.',
+}

package/src/errors/errors.ts

@@ -0,0 +1,44 @@
+import { ErrorName, LiFiErrorCode } from './constants.js'
+import { BaseError } from './baseError.js'
+
+export class RPCError extends BaseError {
+  constructor(code: LiFiErrorCode, message: string, cause?: Error) {
+    super(ErrorName.RPCError, code, message, cause)
+  }
+}
+
+export class ProviderError extends BaseError {
+  constructor(code: LiFiErrorCode, message: string, cause?: Error) {
+    super(ErrorName.ProviderError, code, message, cause)
+  }
+}
+
+export class TransactionError extends BaseError {
+  constructor(code: LiFiErrorCode, message: string, cause?: Error) {
+    super(ErrorName.TransactionError, code, message, cause)
+  }
+}
+
+export class UnknownError extends BaseError {
+  constructor(message: string, cause?: Error) {
+    super(ErrorName.UnknownError, LiFiErrorCode.InternalError, message, cause)
+  }
+}
+
+export class BalanceError extends BaseError {
+  constructor(message: string, cause?: Error) {
+    super(ErrorName.BalanceError, LiFiErrorCode.BalanceError, message, cause)
+  }
+}
+
+export class ServerError extends BaseError {
+  constructor(message: string) {
+    super(ErrorName.ServerError, LiFiErrorCode.InternalError, message)
+  }
+}
+
+export class ValidationError extends BaseError {
+  constructor(message: string) {
+    super(ErrorName.ValidationError, LiFiErrorCode.ValidationError, message)
+  }
+}

package/src/errors/httpError.ts

@@ -0,0 +1,93 @@
+import type { UnavailableRoutes } from '@lifi/types'
+import { LiFiErrorCode } from './constants.js'
+import { BaseError } from './baseError.js'
+import type { ExtendedRequestInit } from '../types/request.js'
+import { ErrorName, ErrorMessage } from './constants.js'
+
+interface ServerErrorResponseBody {
+  code: number
+  message: string
+  errors?: UnavailableRoutes
+}
+
+const statusCodeToErrorClassificationMap = new Map([
+  [
+    400,
+    { type: ErrorName.ValidationError, code: LiFiErrorCode.ValidationError },
+  ],
+  [404, { type: ErrorName.NotFoundError, code: LiFiErrorCode.NotFound }],
+  [
+    409,
+    {
+      type: ErrorName.SlippageError,
+      code: LiFiErrorCode.SlippageError,
+      message: ErrorMessage.SlippageError,
+    },
+  ],
+  [500, { type: ErrorName.ServerError, code: LiFiErrorCode.InternalError }],
+])
+
+const getErrorClassificationFromStatusCode = (code: number) =>
+  statusCodeToErrorClassificationMap.get(code) ?? {
+    type: ErrorName.ServerError,
+    code: LiFiErrorCode.InternalError,
+  }
+
+const createInitialMessage = (response: Response) => {
+  const statusCode =
+    response.status || response.status === 0 ? response.status : ''
+  const title = response.statusText || ''
+  const status = `${statusCode} ${title}`.trim()
+  const reason = status ? `status code ${status}` : 'an unknown error'
+  return `Request failed with ${reason}`
+}
+
+export class HTTPError extends BaseError {
+  public response: Response
+  public status: number
+  public url: RequestInfo | URL
+  public fetchOptions: ExtendedRequestInit
+  public type?: ErrorName
+  public responseBody?: ServerErrorResponseBody
+
+  constructor(
+    response: Response,
+    url: RequestInfo | URL,
+    options: ExtendedRequestInit
+  ) {
+    const errorClassification = getErrorClassificationFromStatusCode(
+      response.status
+    )
+    const additionalMessage = errorClassification?.message
+      ? `\n${errorClassification.message}`
+      : ''
+    const message = createInitialMessage(response) + additionalMessage
+
+    super(ErrorName.HTTPError, errorClassification.code, message)
+
+    this.type = errorClassification.type
+    this.response = response
+    this.status = response.status
+    this.message = message
+    this.url = url
+    this.fetchOptions = options
+  }
+
+  async buildAdditionalDetails() {
+    if (this.type) {
+      this.message = `[${this.type}] ${this.message}`
+    }
+
+    try {
+      this.responseBody = await this.response.json()
+
+      const spacer = '\n        '
+
+      if (this.responseBody) {
+        this.message += `${spacer}responseMessage: ${this.responseBody?.message.toString().replaceAll('\n', spacer)}`
+      }
+    } catch {}
+
+    return this
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+export * from './baseError.js'
+export * from './constants.js'
+export * from './errors.js'
+export * from './httpError.js'
+export * from './SDKError.js'
+export * from './utils/rootCause.js'
+export * from './utils/baseErrorRootCause.js'

package/src/errors/utils/baseErrorRootCause.ts

@@ -0,0 +1,18 @@
+import { BaseError } from '../baseError.js'
+import { HTTPError } from '../httpError.js'
+
+export const getRootCauseBaseError = (e: Error) => {
+  let rootCause = e
+  while (rootCause.cause && rootCause.cause instanceof BaseError) {
+    rootCause = rootCause.cause as BaseError
+  }
+  return rootCause as BaseError
+}
+
+export const getRootCauseBaseErrorMessage = (e: Error) => {
+  const rootCause = getRootCauseBaseError(e)
+
+  return rootCause instanceof HTTPError
+    ? (rootCause as HTTPError).responseBody?.message || rootCause.message
+    : rootCause.message
+}

package/src/errors/utils/rootCause.ts

@@ -0,0 +1,7 @@
+export const getRootCause = (e: Error | undefined) => {
+  let rootCause = e
+  while (rootCause?.cause) {
+    rootCause = rootCause.cause as Error
+  }
+  return rootCause
+}

package/src/helpers.ts

@@ -1,8 +1,7 @@
-import type { LiFiStep, Route } from '@lifi/types'
-import { request } from './request.js'
-import type { TenderlyResponse } from './types/index.js'
-import { ValidationError } from './utils/errors.js'
 import { name, version } from './version.js'
+import { ValidationError } from './errors/errors.js'
+import { SDKError } from './errors/SDKError.js'
+import type { Route, LiFiStep } from '@lifi/types'
 
 export const checkPackageUpdates = async (
   packageName?: string,
@@ -10,12 +9,11 @@ export const checkPackageUpdates = async (
 ) => {
   try {
     const pkgName = packageName ?? name
-    const response = await request<{ version: string }>(
-      `https://registry.npmjs.org/${pkgName}/latest`,
-      { skipTrackingHeaders: true }
-    )
-    const latestVersion = response.version
+    const response = await fetch(`https://registry.npmjs.org/${pkgName}/latest`)
+    const reponseBody = await response.json()
+    const latestVersion = reponseBody.version
     const currentVersion = packageVersion ?? version
+
     if (latestVersion > currentVersion) {
       console.warn(
         // eslint-disable-next-line max-len
@@ -30,16 +28,22 @@ export const checkPackageUpdates = async (
 /**
  * Converts a quote to Route
  * @param step - Step returned from the quote endpoint.
+ * @param txHash
+ * @param chainId
  * @returns - The route to be executed.
- * @throws {ValidationError} Throws a ValidationError if the step has missing values.
+ * @throws {BaseError} Throws a ValidationError if the step has missing values.
  */
 export const convertQuoteToRoute = (step: LiFiStep): Route => {
   if (!step.estimate.fromAmountUSD) {
-    throw new ValidationError("Missing 'fromAmountUSD' in step estimate.")
+    throw new SDKError(
+      new ValidationError("Missing 'fromAmountUSD' in step estimate.")
+    )
   }
 
   if (!step.estimate.toAmountUSD) {
-    throw new ValidationError("Missing 'toAmountUSD' in step estimate.")
+    throw new SDKError(
+      new ValidationError("Missing 'toAmountUSD' in step estimate.")
+    )
   }
 
   const route: Route = {
@@ -61,9 +65,12 @@ export const convertQuoteToRoute = (step: LiFiStep): Route => {
 }
 
 export const fetchTxErrorDetails = async (txHash: string, chainId: number) => {
-  const response = await request<TenderlyResponse>(
-    `https://api.tenderly.co/api/v1/public-contract/${chainId}/tx/${txHash}`
-  )
+  try {
+    const response = await fetch(
+      `https://api.tenderly.co/api/v1/public-contract/${chainId}/tx/${txHash}`
+    )
+    const reponseBody = await response.json()
 
-  return response
+    return reponseBody
+  } catch (_) {}
 }

package/src/index.ts

@@ -26,5 +26,5 @@ export * from './services/api.js'
 export * from './services/balance.js'
 export * from './services/getNameServiceAddress.js'
 export * from './types/index.js'
-export * from './utils/errors.js'
-export { LiFiError, type ErrorCode } from './utils/errors.js'
+export * from './errors/index.js'
+export { type ErrorCode } from './errors/index.js'

package/src/request.ts

@@ -1,16 +1,21 @@
 import { config } from './config.js'
-import { HTTPError } from './utils/errors.js'
+import { HTTPError } from './errors/httpError.js'
 import { wait } from './utils/utils.js'
+import { ValidationError } from './errors/errors.js'
+import { SDKError } from './errors/SDKError.js'
+import type { ExtendedRequestInit } from './types/request.js'
 import { version } from './version.js'
 
 export const requestSettings = {
   retries: 1,
 }
 
-interface ExtendedRequestInit extends RequestInit {
-  retries?: number
-  skipTrackingHeaders?: boolean
-}
+const stripExtendRequestInitProperties = ({
+  retries,
+  ...rest
+}: ExtendedRequestInit): RequestInit => ({
+  ...rest,
+})
 
 export const request = async <T = Response>(
   url: RequestInfo | URL,
@@ -19,61 +24,70 @@ export const request = async <T = Response>(
   }
 ): Promise<T> => {
   const { userId, integrator, widgetVersion, apiKey } = config.get()
+
   if (!integrator) {
-    throw new Error(
-      'Integrator not found. Please see documentation https://docs.li.fi/integrate-li.fi-js-sdk/set-up-the-sdk'
+    throw new SDKError(
+      new ValidationError(
+        'You need to provide the Integrator property. Please see documentation https://docs.li.fi/integrate-li.fi-js-sdk/set-up-the-sdk'
+      )
     )
   }
+
   options.retries = options.retries ?? requestSettings.retries
-  try {
-    if (!options.skipTrackingHeaders) {
-      if (apiKey) {
-        options.headers = {
-          ...options.headers,
-          'x-lifi-api-key': apiKey,
-        }
-      }
 
-      if (userId) {
-        options.headers = {
-          ...options.headers,
-          'x-lifi-userid': userId,
-        }
+  try {
+    if (apiKey) {
+      options.headers = {
+        ...options.headers,
+        'x-lifi-api-key': apiKey,
       }
+    }
 
-      if (widgetVersion) {
-        options.headers = {
-          ...options.headers,
-          'x-lifi-widget': widgetVersion,
-        }
+    if (userId) {
+      options.headers = {
+        ...options.headers,
+        'x-lifi-userid': userId,
       }
+    }
 
-      if (version) {
-        options.headers = {
-          ...options.headers,
-          'x-lifi-sdk': version,
-        }
+    if (widgetVersion) {
+      options.headers = {
+        ...options.headers,
+        'x-lifi-widget': widgetVersion,
       }
+    }
 
-      // integrator is mandatory during SDK initialization
+    if (version) {
       options.headers = {
         ...options.headers,
-        'x-lifi-integrator': integrator,
+        'x-lifi-sdk': version,
       }
     }
 
-    const response: Response = await fetch(url, options)
+    // integrator is mandatory during SDK initialization
+    options.headers = {
+      ...options.headers,
+      'x-lifi-integrator': integrator,
+    }
+
+    const response: Response = await fetch(
+      url,
+      stripExtendRequestInitProperties(options)
+    )
+
     if (!response.ok) {
-      throw new HTTPError(response)
+      throw new HTTPError(response, url, options)
     }
 
-    const data: T = await response.json()
-    return data
+    return await response.json()
   } catch (error) {
-    if (options.retries > 0 && (error as HTTPError)?.status === 500) {
+    if (options.retries > 0 && (error as HTTPError).status === 500) {
       await wait(500)
       return request<T>(url, { ...options, retries: options.retries - 1 })
     }
-    throw error
+
+    await (error as HTTPError).buildAdditionalDetails?.()
+
+    throw new SDKError(error as HTTPError)
   }
 }