@lifi/sdk 0.0.0-preview-f5cf9f8

package/src/errors/httpError.ts

@@ -0,0 +1,92 @@
+import type { UnavailableRoutes } from '@lifi/types'
+import type { ExtendedRequestInit } from '../types/request.js'
+import { BaseError } from './baseError.js'
+import { ErrorMessage, ErrorName, LiFiErrorCode } 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,
+    },
+  ],
+  [424, { type: ErrorName.ServerError, code: LiFiErrorCode.ThirdPartyError }],
+  [429, { type: ErrorName.ServerError, code: LiFiErrorCode.RateLimitExceeded }],
+  [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(): Promise<void> {
+    if (this.type) {
+      this.message = `[${this.type}] ${this.message}`
+    }
+
+    try {
+      this.responseBody = await this.response.json()
+
+      if (this.responseBody?.message) {
+        this.message += this.message.endsWith('.')
+          ? ` ${this.responseBody.message.toString()}`
+          : `. ${this.responseBody.message.toString()}`
+      }
+    } catch {}
+  }
+}

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): BaseError => {
+  let rootCause = e
+  while (rootCause.cause && rootCause.cause instanceof BaseError) {
+    rootCause = rootCause.cause as BaseError
+  }
+  return rootCause as BaseError
+}
+
+export const getRootCauseBaseErrorMessage = (e: Error): string => {
+  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): Error | undefined => {
+  let rootCause = e
+  while (rootCause?.cause) {
+    rootCause = rootCause.cause as Error
+  }
+  return rootCause
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+// biome-ignore lint/performance/noBarrelFile: module entrypoint
+// biome-ignore lint/performance/noReExportAll: types
+export * from '@lifi/types'
+export { getChains } from './actions/getChains.js'
+export { getConnections } from './actions/getConnections.js'
+export { getContractCallsQuote } from './actions/getContractCallsQuote.js'
+export { getGasRecommendation } from './actions/getGasRecommendation.js'
+export { getNameServiceAddress } from './actions/getNameServiceAddress.js'
+export { getQuote } from './actions/getQuote.js'
+export { getRelayedTransactionStatus } from './actions/getRelayedTransactionStatus.js'
+export { getRelayerQuote } from './actions/getRelayerQuote.js'
+export { getRoutes } from './actions/getRoutes.js'
+export { getStatus } from './actions/getStatus.js'
+export { getStepTransaction } from './actions/getStepTransaction.js'
+export { getToken } from './actions/getToken.js'
+export { getTokenBalance } from './actions/getTokenBalance.js'
+export { getTokenBalances } from './actions/getTokenBalances.js'
+export { getTokenBalancesByChain } from './actions/getTokenBalancesByChain.js'
+export { getTokens } from './actions/getTokens.js'
+export { getTools } from './actions/getTools.js'
+export { getTransactionHistory } from './actions/getTransactionHistory.js'
+export { getWalletBalances } from './actions/getWalletBalances.js'
+export { actions } from './actions/index.js'
+export { patchContractCalls } from './actions/patchContractCalls.js'
+export { relayTransaction } from './actions/relayTransaction.js'
+export { createClient } from './client/createClient.js'
+export { getActionMessage, getSubstatusMessage } from './core/actionMessages.js'
+export { BaseStepExecutionTask } from './core/BaseStepExecutionTask.js'
+export { BaseStepExecutor } from './core/BaseStepExecutor.js'
+export {
+  executeRoute,
+  getActiveRoute,
+  getActiveRoutes,
+  resumeRoute,
+  stopRouteExecution,
+  updateRouteExecution,
+} from './core/execution.js'
+export { StatusManager } from './core/StatusManager.js'
+export type { SDKStorage } from './core/storage.js'
+export {
+  createDefaultStorage,
+  InMemoryStorage,
+  LocalStorageAdapter,
+} from './core/storage.js'
+export { TaskPipeline } from './core/TaskPipeline.js'
+export { CheckBalanceTask } from './core/tasks/CheckBalanceTask.js'
+export {
+  type CheckBalanceOptions,
+  checkBalance,
+} from './core/tasks/helpers/checkBalance.js'
+export { getTransactionRequestData } from './core/tasks/helpers/getTransactionRequestData.js'
+export { stepComparison } from './core/tasks/helpers/stepComparison.js'
+export { PrepareTransactionTask } from './core/tasks/PrepareTransactionTask.js'
+export { WaitForTransactionStatusTask } from './core/tasks/WaitForTransactionStatusTask.js'
+export { BaseError } from './errors/baseError.js'
+export type { ErrorCode } from './errors/constants.js'
+export { ErrorMessage, ErrorName, LiFiErrorCode } from './errors/constants.js'
+export {
+  BalanceError,
+  ExecuteStepRetryError,
+  ProviderError,
+  RPCError,
+  ServerError,
+  TransactionError,
+  UnknownError,
+  ValidationError,
+} from './errors/errors.js'
+export { HTTPError } from './errors/httpError.js'
+export { SDKError } from './errors/SDKError.js'
+export type {
+  AcceptExchangeRateUpdateHook,
+  AcceptSlippageUpdateHook,
+  AcceptSlippageUpdateHookParams,
+  ContractCallParams,
+  ContractTool,
+  ExchangeRateUpdateParams,
+  ExecuteStepRetryParams,
+  Execution,
+  ExecutionAction,
+  ExecutionActionStatus,
+  ExecutionActionType,
+  ExecutionOptions,
+  ExecutionStatus,
+  GetContractCallsHook,
+  GetContractCallsResult,
+  InteractionSettings,
+  LiFiStepExtended,
+  RequestInterceptor,
+  RouteExecutionData,
+  RouteExecutionDataDictionary,
+  RouteExecutionDictionary,
+  RouteExtended,
+  RPCUrls,
+  SDKBaseConfig,
+  SDKClient,
+  SDKConfig,
+  SDKProvider,
+  StepExecutor,
+  StepExecutorOptions,
+  StepExtended,
+  TransactionMethodType,
+  TransactionParameters,
+  TransactionRequestParameters,
+  TransactionRequestUpdateHook,
+  UpdateRouteHook,
+} from './types/core.js'
+export type {
+  StepExecutorBaseContext,
+  StepExecutorContext,
+  TaskResult,
+  TaskStatus,
+} from './types/execution.js'
+export { checkPackageUpdates } from './utils/checkPackageUpdates.js'
+export { convertQuoteToRoute } from './utils/convertQuoteToRoute.js'
+export { fetchTxErrorDetails } from './utils/fetchTxErrorDetails.js'
+export { formatUnits } from './utils/formatUnits.js'
+export { isHex } from './utils/isHex.js'
+export { parseUnits } from './utils/parseUnits.js'
+export { sleep } from './utils/sleep.js'
+export { waitForResult } from './utils/waitForResult.js'
+export { LruMap, withDedupe } from './utils/withDedupe.js'
+export { withTimeout } from './utils/withTimeout.js'

package/src/types/actions.ts

@@ -0,0 +1,16 @@
+import type {
+  GetStatusRequest,
+  QuoteRequest as QuoteRequestBase,
+} from '@lifi/types'
+
+export type GetStatusRequestExtended = GetStatusRequest & {
+  fromAddress?: string
+}
+
+export type QuoteRequestFromAmount = QuoteRequestBase
+
+export type QuoteRequestToAmount = Omit<QuoteRequestBase, 'fromAmount'> & {
+  toAmount: string
+}
+
+export type QuoteRequest = QuoteRequestFromAmount | QuoteRequestToAmount

package/src/types/core.ts

@@ -0,0 +1,264 @@
+import type {
+  ChainId,
+  ChainType,
+  CoinKey,
+  ContractCall,
+  ExtendedChain,
+  FeeCost,
+  GasCost,
+  LiFiStep,
+  Route,
+  RouteOptions,
+  Step,
+  Substatus,
+  Token,
+  TokenAmount,
+} from '@lifi/types'
+import type { SDKStorage } from '../core/storage.js'
+import type { ExtendedRequestInit } from './request.js'
+
+export type RequestInterceptor = (
+  request: ExtendedRequestInit
+) => ExtendedRequestInit | Promise<ExtendedRequestInit>
+
+export interface SDKBaseConfig {
+  apiKey?: string
+  apiUrl: string
+  integrator: string
+  userId?: string
+  routeOptions?: RouteOptions
+  executionOptions?: ExecutionOptions
+  rpcUrls: RPCUrls
+  disableVersionCheck?: boolean
+  widgetVersion?: string
+  debug: boolean
+  preloadChains?: boolean
+  chainsRefetchInterval?: number
+  requestInterceptor?: RequestInterceptor
+  storage?: SDKStorage
+}
+
+export interface SDKConfig extends Partial<Omit<SDKBaseConfig, 'integrator'>> {
+  integrator: string
+  providers?: SDKProvider[]
+}
+
+export type RPCUrls = Partial<Record<ChainId, string[]>>
+
+export interface SDKProvider {
+  readonly type: ChainType
+  isAddress(address: string): boolean
+  resolveAddress(
+    name: string,
+    client: SDKClient,
+    chainId?: ChainId,
+    token?: CoinKey
+  ): Promise<string | undefined>
+  getStepExecutor(options: StepExecutorOptions): Promise<StepExecutor>
+  getBalance(
+    client: SDKClient,
+    walletAddress: string,
+    tokens: Token[]
+  ): Promise<TokenAmount[]>
+}
+
+export interface SDKClient {
+  config: SDKBaseConfig
+  providers: SDKProvider[]
+  getProvider(type: ChainType): SDKProvider | undefined
+  setProviders(providers: SDKProvider[]): void
+  setChains(chains: ExtendedChain[]): void
+  getChains(): Promise<ExtendedChain[]>
+  getChainById(chainId: ChainId): Promise<ExtendedChain>
+  getRpcUrls(): Promise<RPCUrls>
+  getRpcUrlsByChainId(chainId: ChainId): Promise<string[]>
+}
+
+export interface StepExecutorOptions {
+  routeId: string
+  executionOptions?: ExecutionOptions
+}
+
+export interface InteractionSettings {
+  allowInteraction?: boolean
+  allowUpdates?: boolean
+  allowExecution?: boolean
+}
+
+/**
+ * Params passed when retrying executeStep after an ExecuteStepRetryError.
+ * Providers can use this to pass strategy-specific retry options (e.g. atomicityNotReady for Ethereum 7702).
+ */
+export type ExecuteStepRetryParams = Record<string, unknown>
+
+export interface StepExecutor {
+  allowUserInteraction: boolean
+  allowExecution: boolean
+  setInteraction(settings?: InteractionSettings): void
+  executeStep(
+    client: SDKClient,
+    step: LiFiStepExtended,
+    retryParams?: ExecuteStepRetryParams
+  ): Promise<LiFiStepExtended>
+}
+
+export interface RouteExecutionData {
+  route: Route
+  executors: StepExecutor[]
+  executionOptions?: ExecutionOptions
+}
+
+export type RouteExecutionDataDictionary = Partial<
+  Record<string, RouteExecutionData>
+>
+
+export interface RouteExtended extends Omit<Route, 'steps'> {
+  steps: LiFiStepExtended[]
+}
+
+export interface LiFiStepExtended extends LiFiStep {
+  execution?: Execution
+}
+
+export type StepExtended = Step & {
+  execution?: Execution
+}
+
+export type TransactionParameters = {
+  chainId?: number
+  to?: string
+  from?: string
+  nonce?: number
+  data?: string
+  value?: bigint
+  gas?: bigint
+  gasPrice?: bigint
+  maxFeePerGas?: bigint
+  maxPriorityFeePerGas?: bigint
+}
+
+export type RouteExecutionDictionary = Partial<Record<string, Promise<Route>>>
+
+export type UpdateRouteHook = (updatedRoute: RouteExtended) => void
+
+export interface TransactionRequestParameters extends TransactionParameters {
+  requestType: 'approve' | 'transaction'
+}
+
+export type TransactionRequestUpdateHook = (
+  updatedTxRequest: TransactionRequestParameters
+) => Promise<TransactionParameters>
+
+export interface AcceptSlippageUpdateHookParams {
+  toToken: Token
+  oldToAmount: string
+  newToAmount: string
+  oldSlippage: number
+  newSlippage: number
+}
+
+export type AcceptSlippageUpdateHook = (
+  params: AcceptSlippageUpdateHookParams
+) => Promise<boolean | undefined>
+
+export interface ExchangeRateUpdateParams {
+  toToken: Token
+  oldToAmount: string
+  newToAmount: string
+}
+
+export type AcceptExchangeRateUpdateHook = (
+  params: ExchangeRateUpdateParams
+) => Promise<boolean | undefined>
+
+export interface ContractCallParams {
+  fromChainId: number
+  toChainId: number
+  fromTokenAddress: string
+  toTokenAddress: string
+  fromAddress: string
+  toAddress?: string
+  fromAmount: bigint
+  toAmount: bigint
+  slippage?: number
+}
+
+export interface ContractTool {
+  name: string
+  logoURI: string
+}
+
+export interface GetContractCallsResult {
+  contractCalls: ContractCall[]
+  patcher?: boolean
+  contractTool?: ContractTool
+}
+
+export type GetContractCallsHook = (
+  params: ContractCallParams
+) => Promise<GetContractCallsResult>
+
+export interface ExecutionOptions {
+  acceptExchangeRateUpdateHook?: AcceptExchangeRateUpdateHook
+  updateRouteHook?: UpdateRouteHook
+  updateTransactionRequestHook?: TransactionRequestUpdateHook
+  getContractCalls?: GetContractCallsHook
+  adjustZeroOutputFromPreviousStep?: boolean
+  executeInBackground?: boolean
+}
+
+export type ExecutionStatus = 'ACTION_REQUIRED' | 'PENDING' | 'FAILED' | 'DONE'
+
+export type ExecutionActionStatus =
+  | 'STARTED'
+  | 'ACTION_REQUIRED'
+  | 'MESSAGE_REQUIRED'
+  | 'RESET_REQUIRED'
+  | 'PENDING'
+  | 'FAILED'
+  | 'DONE'
+  | 'CANCELLED'
+
+export type ExecutionActionType =
+  | 'PERMIT'
+  | 'CHECK_ALLOWANCE'
+  | 'NATIVE_PERMIT'
+  | 'RESET_ALLOWANCE'
+  | 'SET_ALLOWANCE'
+  | 'SWAP'
+  | 'CROSS_CHAIN'
+  | 'RECEIVING_CHAIN'
+
+export type ExecutionAction = {
+  type: ExecutionActionType
+  status: ExecutionActionStatus
+  message?: string
+  substatus?: Substatus
+  substatusMessage?: string
+  chainId?: number
+  txHash?: string
+  txLink?: string
+  taskId?: string
+  txType?: TransactionMethodType
+  txHex?: string
+  // Errors occured during the action execution (within tasks)
+  error?: { code: string | number; message: string; htmlMessage?: string }
+}
+
+export interface Execution {
+  startedAt: number
+  signedAt?: number
+  status: ExecutionStatus
+  actions: Array<ExecutionAction>
+  fromAmount?: string
+  toAmount?: string
+  toToken?: Token
+  feeCosts?: FeeCost[]
+  gasCosts?: GasCost[]
+  internalTxLink?: string
+  externalTxLink?: string
+  // Errors occured outside of actions (e.g. during context creation)
+  error?: { code: string | number; message: string; htmlMessage?: string }
+}
+
+export type TransactionMethodType = 'standard' | 'relayed' | 'batched'

package/src/types/execution.ts

@@ -0,0 +1,32 @@
+import type { ExtendedChain } from '@lifi/types'
+import type { StatusManager } from '../core/StatusManager.js'
+import type {
+  ExecuteStepRetryParams,
+  ExecutionOptions,
+  LiFiStepExtended,
+  SDKClient,
+} from './core.js'
+
+export interface StepExecutorBaseContext {
+  statusManager: StatusManager
+  executionOptions?: ExecutionOptions
+  fromChain: ExtendedChain
+  toChain: ExtendedChain
+  isBridgeExecution: boolean
+  client: SDKClient
+  step: LiFiStepExtended
+  allowUserInteraction: boolean
+  retryParams?: ExecuteStepRetryParams
+}
+
+export interface StepExecutorContext extends StepExecutorBaseContext {
+  pollingIntervalMs?: number
+}
+
+export interface TaskResult<TContext = Record<string, unknown>> {
+  status: TaskStatus
+  /** Optional: data produced for downstream tasks. Pipeline merges into the executor context. */
+  context?: TContext
+}
+
+export type TaskStatus = 'COMPLETED' | 'PAUSED'

package/src/types/request.ts

@@ -0,0 +1,3 @@
+export interface ExtendedRequestInit extends RequestInit {
+  retries?: number
+}

package/src/utils/checkPackageUpdates.ts

@@ -0,0 +1,22 @@
+import { name, version } from '../version.js'
+
+export const checkPackageUpdates = async (
+  packageName?: string,
+  packageVersion?: string
+): Promise<void> => {
+  try {
+    const pkgName = packageName ?? name
+    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(
+        `${pkgName}: new package version is available. Please update as soon as possible to enjoy the newest features. Current version: ${currentVersion}. Latest version: ${latestVersion}.`
+      )
+    }
+  } catch (_error) {
+    // Cannot verify version, might be network error etc. We don't bother showing anything in that case
+  }
+}