@lifi/sdk 3.13.5 → 4.0.0-alpha.1

package/src/actions/getRelayerQuote.unit.spec.ts

@@ -0,0 +1,220 @@
+import type {
+  LiFiStep,
+  RelayerQuoteResponse,
+  RequestOptions,
+} from '@lifi/types'
+import { ChainId } from '@lifi/types'
+import { HttpResponse, http } from 'msw'
+import { describe, expect, it } from 'vitest'
+import { BaseError } from '../errors/baseError.js'
+import { ErrorName } from '../errors/constants.js'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { QuoteRequestFromAmount } from '../types/actions.js'
+import { client, setupTestServer } from './actions.unit.handlers.js'
+import { getRelayerQuote } from './getRelayerQuote.js'
+
+describe('getRelayerQuote', () => {
+  const server = setupTestServer()
+
+  const createMockQuoteRequest = (
+    overrides: Partial<QuoteRequestFromAmount> = {}
+  ): QuoteRequestFromAmount => ({
+    fromChain: ChainId.ETH,
+    fromToken: '0xA0b86a33E6441c8C06DDD4f36e4C4C5B4c3B4c3B',
+    fromAddress: '0x1234567890123456789012345678901234567890',
+    fromAmount: '1000000',
+    toChain: ChainId.POL,
+    toToken: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
+    ...overrides,
+  })
+
+  const mockLiFiStep: LiFiStep = {
+    id: 'test-step-id',
+    type: 'lifi',
+    includedSteps: [],
+    tool: 'test-tool',
+    toolDetails: {
+      key: 'test-tool',
+      name: 'Test Tool',
+      logoURI: 'https://example.com/logo.png',
+    },
+    action: {
+      fromChainId: ChainId.ETH,
+      toChainId: ChainId.POL,
+      fromToken: {
+        address: '0xA0b86a33E6441c8C06DDD4f36e4C4C5B4c3B4c3B',
+        symbol: 'USDC',
+        decimals: 6,
+        chainId: ChainId.ETH,
+        name: 'USD Coin',
+        priceUSD: '1.00',
+      },
+      toToken: {
+        address: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
+        symbol: 'USDC',
+        decimals: 6,
+        chainId: ChainId.POL,
+        name: 'USD Coin',
+        priceUSD: '1.00',
+      },
+      fromAmount: '1000000',
+      fromAddress: '0x1234567890123456789012345678901234567890',
+      toAddress: '0x1234567890123456789012345678901234567890',
+    },
+    estimate: {
+      fromAmount: '1000000',
+      toAmount: '1000000',
+      toAmountMin: '970000',
+      approvalAddress: '0x1234567890123456789012345678901234567890',
+      tool: 'test-tool',
+      executionDuration: 30000,
+    },
+    transactionRequest: {
+      to: '0x1234567890123456789012345678901234567890',
+      data: '0x',
+      value: '0',
+      gasLimit: '100000',
+    },
+  }
+
+  const mockSuccessResponse: RelayerQuoteResponse = {
+    status: 'ok',
+    data: mockLiFiStep,
+  }
+
+  const mockErrorResponse: RelayerQuoteResponse = {
+    status: 'error',
+    data: {
+      code: 400,
+      message: 'Invalid request parameters',
+    },
+  }
+
+  describe('success scenarios', () => {
+    it('should get relayer quote successfully', async () => {
+      server.use(
+        http.get(`${client.config.apiUrl}/relayer/quote`, async () => {
+          return HttpResponse.json(mockSuccessResponse)
+        })
+      )
+
+      const request = createMockQuoteRequest()
+
+      const result = await getRelayerQuote(client, request)
+
+      expect(result).toEqual(mockLiFiStep)
+    })
+
+    it('should pass request options correctly', async () => {
+      const mockAbortController = new AbortController()
+      const options: RequestOptions = {
+        signal: mockAbortController.signal,
+      }
+
+      let capturedOptions: any
+      server.use(
+        http.get(
+          `${client.config.apiUrl}/relayer/quote`,
+          async ({ request }) => {
+            capturedOptions = request
+            return HttpResponse.json(mockSuccessResponse)
+          }
+        )
+      )
+
+      const request = createMockQuoteRequest()
+
+      await getRelayerQuote(client, request, options)
+
+      expect(capturedOptions.signal).toBeDefined()
+      expect(capturedOptions.signal).toBeInstanceOf(AbortSignal)
+    })
+  })
+
+  describe('validation scenarios', () => {
+    it('should throw SDKError when required parameters are missing', async () => {
+      const testCases = [
+        { param: 'fromChain', value: undefined },
+        { param: 'fromToken', value: undefined },
+        { param: 'fromAddress', value: undefined },
+        { param: 'fromAmount', value: undefined },
+        { param: 'toChain', value: undefined },
+        { param: 'toToken', value: undefined },
+      ]
+
+      for (const testCase of testCases) {
+        const invalidRequest = createMockQuoteRequest({
+          [testCase.param]: testCase.value,
+        })
+
+        await expect(getRelayerQuote(client, invalidRequest)).rejects.toThrow(
+          SDKError
+        )
+
+        try {
+          await getRelayerQuote(client, invalidRequest)
+        } catch (error) {
+          expect(error).toBeInstanceOf(SDKError)
+          expect((error as SDKError).cause).toBeInstanceOf(ValidationError)
+          expect((error as SDKError).cause.message).toBe(
+            `Required parameter "${testCase.param}" is missing.`
+          )
+        }
+      }
+    })
+  })
+
+  describe('error scenarios', () => {
+    it('should throw BaseError when server returns error status', async () => {
+      server.use(
+        http.get(`${client.config.apiUrl}/relayer/quote`, async () => {
+          return HttpResponse.json(mockErrorResponse)
+        })
+      )
+
+      const request = createMockQuoteRequest()
+
+      await expect(getRelayerQuote(client, request)).rejects.toThrow(BaseError)
+
+      try {
+        await getRelayerQuote(client, request)
+      } catch (error) {
+        expect(error).toBeInstanceOf(BaseError)
+        expect((error as BaseError).name).toBe(ErrorName.ServerError)
+        expect((error as BaseError).code).toBe(400)
+        expect((error as BaseError).message).toBe('Invalid request parameters')
+      }
+    })
+
+    it('should throw SDKError when network request fails', async () => {
+      server.use(
+        http.get(`${client.config.apiUrl}/relayer/quote`, async () => {
+          return HttpResponse.error()
+        })
+      )
+
+      const request = createMockQuoteRequest()
+
+      await expect(getRelayerQuote(client, request)).rejects.toThrow(SDKError)
+    })
+
+    it('should throw SDKError when request times out', async () => {
+      server.use(
+        http.get(`${client.config.apiUrl}/relayer/quote`, async () => {
+          // Simulate timeout by not responding
+          await new Promise(() => {}) // Never resolves
+        })
+      )
+
+      const request = createMockQuoteRequest()
+      const timeoutOptions: RequestOptions = {
+        signal: AbortSignal.timeout(100), // 100ms timeout
+      }
+
+      await expect(
+        getRelayerQuote(client, request, timeoutOptions)
+      ).rejects.toThrow()
+    })
+  })
+})

package/src/actions/getRoutes.ts

@@ -0,0 +1,43 @@
+import type { RequestOptions, RoutesRequest, RoutesResponse } from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { SDKClient } from '../types/core.js'
+import { isRoutesRequest } from '../utils/isRoutesRequest.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get a set of routes for a request that describes a transfer of tokens.
+ * @param client - The SDK client.
+ * @param params - A description of the transfer.
+ * @param options - Request options
+ * @returns The resulting routes that can be used to realize the described transfer of tokens.
+ * @throws {LiFiError} Throws a LiFiError if request fails.
+ */
+export const getRoutes = async (
+  client: SDKClient,
+  params: RoutesRequest,
+  options?: RequestOptions
+): Promise<RoutesResponse> => {
+  if (!isRoutesRequest(params)) {
+    throw new SDKError(new ValidationError('Invalid routes request.'))
+  }
+  // apply defaults
+  params.options = {
+    integrator: client.config.integrator,
+    ...client.config.routeOptions,
+    ...params.options,
+  }
+
+  return await request<RoutesResponse>(
+    client.config,
+    `${client.config.apiUrl}/advanced/routes`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(params),
+      signal: options?.signal,
+    }
+  )
+}

package/src/actions/getRoutes.unit.spec.ts

@@ -0,0 +1,112 @@
+import { findDefaultToken } from '@lifi/data-types'
+import type { RoutesRequest } from '@lifi/types'
+import { ChainId, CoinKey } from '@lifi/types'
+import { describe, expect, it, vi } from 'vitest'
+import * as request from '../utils/request.js'
+import { client, setupTestServer } from './actions.unit.handlers.js'
+import { getRoutes } from './getRoutes.js'
+
+const mockedFetch = vi.spyOn(request, 'request')
+
+describe('getRoutes', () => {
+  setupTestServer()
+
+  const getRoutesRequest = ({
+    fromChainId = ChainId.BSC,
+    fromAmount = '10000000000000',
+    fromTokenAddress = findDefaultToken(CoinKey.USDC, ChainId.BSC).address,
+    toChainId = ChainId.DAI,
+    toTokenAddress = findDefaultToken(CoinKey.USDC, ChainId.DAI).address,
+    options = { slippage: 0.03 },
+  }: {
+    fromChainId?: ChainId
+    fromAmount?: string
+    fromTokenAddress?: string
+    toChainId?: ChainId
+    toTokenAddress?: string
+    options?: { slippage: number }
+  }): RoutesRequest => ({
+    fromChainId,
+    fromAmount,
+    fromTokenAddress,
+    toChainId,
+    toTokenAddress,
+    options,
+  })
+
+  describe('user input is invalid', () => {
+    it('should throw Error because of invalid fromChainId type', async () => {
+      const request = getRoutesRequest({
+        fromChainId: 'xxx' as unknown as ChainId,
+      })
+
+      await expect(getRoutes(client, request)).rejects.toThrow(
+        'Invalid routes request.'
+      )
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+    })
+
+    it('should throw Error because of invalid fromAmount type', async () => {
+      const request = getRoutesRequest({
+        fromAmount: 10000000000000 as unknown as string,
+      })
+
+      await expect(getRoutes(client, request)).rejects.toThrow(
+        'Invalid routes request.'
+      )
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+    })
+
+    it('should throw Error because of invalid fromTokenAddress type', async () => {
+      const request = getRoutesRequest({
+        fromTokenAddress: 1234 as unknown as string,
+      })
+
+      await expect(getRoutes(client, request)).rejects.toThrow(
+        'Invalid routes request.'
+      )
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+    })
+
+    it('should throw Error because of invalid toChainId type', async () => {
+      const request = getRoutesRequest({
+        toChainId: 'xxx' as unknown as ChainId,
+      })
+
+      await expect(getRoutes(client, request)).rejects.toThrow(
+        'Invalid routes request.'
+      )
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+    })
+
+    it('should throw Error because of invalid toTokenAddress type', async () => {
+      const request = getRoutesRequest({ toTokenAddress: '' })
+
+      await expect(getRoutes(client, request)).rejects.toThrow(
+        'Invalid routes request.'
+      )
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+    })
+
+    it('should throw Error because of invalid options type', async () => {
+      const request = getRoutesRequest({
+        options: { slippage: 'not a number' as unknown as number },
+      })
+
+      await expect(getRoutes(client, request)).rejects.toThrow(
+        'Invalid routes request.'
+      )
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+    })
+  })
+
+  describe('user input is valid', () => {
+    describe('and the backend call is successful', () => {
+      it('call the server once', async () => {
+        const request = getRoutesRequest({})
+        await getRoutes(client, request)
+        expect(mockedFetch).toHaveBeenCalledTimes(1)
+      })
+    })
+  })
+})

package/src/actions/getStatus.ts

@@ -0,0 +1,41 @@
+import type { RequestOptions, StatusResponse } from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { GetStatusRequestExtended } from '../types/actions.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Check the status of a transfer. For cross chain transfers, the "bridge" parameter is required.
+ * @param client - The SDK client
+ * @param params - Configuration of the requested status
+ * @param options - Request options.
+ * @throws {LiFiError} - Throws a LiFiError if request fails
+ * @returns Returns status response.
+ */
+export const getStatus = async (
+  client: SDKClient,
+  params: GetStatusRequestExtended,
+  options?: RequestOptions
+): Promise<StatusResponse> => {
+  if (
+    !('taskId' in params && params.taskId) &&
+    !('txHash' in params && params.txHash)
+  ) {
+    throw new SDKError(
+      new ValidationError(
+        'Either "taskId" or "txHash" must be provided and non-empty.'
+      )
+    )
+  }
+  const queryParams = new URLSearchParams(
+    params as unknown as Record<string, string>
+  )
+  return await request<StatusResponse>(
+    client.config,
+    `${client.config.apiUrl}/status?${queryParams}`,
+    {
+      signal: options?.signal,
+    }
+  )
+}

package/src/actions/getStatus.unit.spec.ts

@@ -0,0 +1,53 @@
+import { ChainId } from '@lifi/types'
+import { describe, expect, it, vi } from 'vitest'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import * as request from '../utils/request.js'
+import { client, setupTestServer } from './actions.unit.handlers.js'
+import { getStatus } from './getStatus.js'
+
+const mockedFetch = vi.spyOn(request, 'request')
+
+describe('getStatus', () => {
+  setupTestServer()
+
+  const fromChain = ChainId.DAI
+  const toChain = ChainId.POL
+  const txHash = 'some tx hash'
+  const bridge = 'some bridge tool'
+
+  describe('user input is invalid', () => {
+    it('throw an error', async () => {
+      await expect(
+        getStatus(client, {
+          bridge,
+          fromChain,
+          toChain,
+          txHash: undefined as unknown as string,
+        })
+      ).rejects.toThrowError(
+        new SDKError(
+          new ValidationError(
+            'Either "taskId" or "txHash" must be provided and non-empty.'
+          )
+        )
+      )
+
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+    })
+  })
+
+  describe('user input is valid', () => {
+    describe('and the backend call is successful', () => {
+      it('call the server once', async () => {
+        await getStatus(client, {
+          bridge,
+          fromChain,
+          toChain,
+          txHash,
+        })
+        expect(mockedFetch).toHaveBeenCalledTimes(1)
+      })
+    })
+  })
+})

package/src/actions/getStepTransaction.ts

@@ -0,0 +1,36 @@
+import type { LiFiStep, RequestOptions, SignedLiFiStep } from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+import { isStep } from '../utils/isStep.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get the transaction data for a single step of a route
+ * @param client - The SDK client
+ * @param step - The step object.
+ * @param options - Request options
+ * @returns The step populated with the transaction data.
+ * @throws {LiFiError} Throws a LiFiError if request fails.
+ */
+export const getStepTransaction = async (
+  client: SDKClient,
+  step: LiFiStep | SignedLiFiStep,
+  options?: RequestOptions
+): Promise<LiFiStep> => {
+  if (!isStep(step)) {
+    // While the validation fails for some users we should not enforce it
+    console.warn('SDK Validation: Invalid Step', step)
+  }
+
+  return await request<LiFiStep>(
+    client.config,
+    `${client.config.apiUrl}/advanced/stepTransaction`,
+    {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(step),
+      signal: options?.signal,
+    }
+  )
+}

package/src/actions/getStepTransaction.unit.spec.ts

@@ -0,0 +1,140 @@
+import { findDefaultToken } from '@lifi/data-types'
+import type { Action, Estimate, LiFiStep, StepTool, Token } from '@lifi/types'
+import { ChainId, CoinKey } from '@lifi/types'
+import { describe, expect, it, vi } from 'vitest'
+import * as request from '../utils/request.js'
+import { client, setupTestServer } from './actions.unit.handlers.js'
+import { getStepTransaction } from './getStepTransaction.js'
+
+const mockedFetch = vi.spyOn(request, 'request')
+
+describe('getStepTransaction', () => {
+  setupTestServer()
+
+  const getAction = ({
+    fromChainId = ChainId.BSC,
+    fromAmount = '10000000000000',
+    fromToken = findDefaultToken(CoinKey.USDC, ChainId.BSC),
+    fromAddress = 'some from address', // we don't validate the format of addresses atm
+    toChainId = ChainId.DAI,
+    toToken = findDefaultToken(CoinKey.USDC, ChainId.DAI),
+    toAddress = 'some to address',
+    slippage = 0.03,
+  }): Action => ({
+    fromChainId,
+    fromAmount,
+    fromToken: fromToken as Token,
+    fromAddress,
+    toChainId,
+    toToken: toToken as Token,
+    toAddress,
+    slippage,
+  })
+
+  const getEstimate = ({
+    fromAmount = '10000000000000',
+    toAmount = '10000000000000',
+    toAmountMin = '999999999999',
+    approvalAddress = 'some approval address', // we don't validate the format of addresses atm;
+    executionDuration = 300,
+    tool = '1inch',
+  }): Estimate => ({
+    fromAmount,
+    toAmount,
+    toAmountMin,
+    approvalAddress,
+    executionDuration,
+    tool,
+  })
+
+  const getStep = ({
+    id = 'some random id',
+    type = 'lifi',
+    tool = 'some swap tool',
+    action = getAction({}),
+    estimate = getEstimate({}),
+  }: {
+    id?: string
+    type?: 'lifi'
+    tool?: StepTool
+    action?: Action
+    estimate?: Estimate
+  }): LiFiStep => ({
+    id,
+    type,
+    tool,
+    toolDetails: {
+      key: tool,
+      name: tool,
+      logoURI: '',
+    },
+    action,
+    estimate,
+    includedSteps: [],
+  })
+
+  describe('with a swap step', () => {
+    // While the validation fails for some users we should not enforce it
+    describe.skip('user input is invalid', () => {
+      it('should throw Error because of invalid id', async () => {
+        const step = getStep({ id: null as unknown as string })
+
+        await expect(getStepTransaction(client, step)).rejects.toThrow(
+          'Invalid step.'
+        )
+        expect(mockedFetch).toHaveBeenCalledTimes(0)
+      })
+
+      it('should throw Error because of invalid type', async () => {
+        const step = getStep({ type: 42 as unknown as 'lifi' })
+
+        await expect(getStepTransaction(client, step)).rejects.toThrow(
+          'Invalid Step'
+        )
+        expect(mockedFetch).toHaveBeenCalledTimes(0)
+      })
+
+      it('should throw Error because of invalid tool', async () => {
+        const step = getStep({ tool: null as unknown as StepTool })
+
+        await expect(getStepTransaction(client, step)).rejects.toThrow(
+          'Invalid step.'
+        )
+        expect(mockedFetch).toHaveBeenCalledTimes(0)
+      })
+
+      // more indepth checks for the action type should be done once we have real schema validation
+      it('should throw Error because of invalid action', async () => {
+        const step = getStep({ action: 'xxx' as unknown as Action })
+
+        await expect(getStepTransaction(client, step)).rejects.toThrow(
+          'Invalid step.'
+        )
+        expect(mockedFetch).toHaveBeenCalledTimes(0)
+      })
+
+      // more indepth checks for the estimate type should be done once we have real schema validation
+      it('should throw Error because of invalid estimate', async () => {
+        const step = getStep({
+          estimate: 'Is this really an estimate?' as unknown as Estimate,
+        })
+
+        await expect(getStepTransaction(client, step)).rejects.toThrow(
+          'Invalid step.'
+        )
+        expect(mockedFetch).toHaveBeenCalledTimes(0)
+      })
+    })
+
+    describe('user input is valid', () => {
+      describe('and the backend call is successful', () => {
+        it('call the server once', async () => {
+          const step = getStep({})
+
+          await getStepTransaction(client, step)
+          expect(mockedFetch).toHaveBeenCalledTimes(1)
+        })
+      })
+    })
+  })
+})

package/src/actions/getToken.ts

@@ -0,0 +1,47 @@
+import type {
+  ChainId,
+  ChainKey,
+  RequestOptions,
+  TokenExtended,
+} from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import { SDKError } from '../errors/SDKError.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Fetch information about a Token
+ * @param client - The SDK client
+ * @param chain - Id or key of the chain that contains the token
+ * @param token - Address or symbol of the token on the requested chain
+ * @param options - Request options
+ * @throws {LiFiError} - Throws a LiFiError if request fails
+ * @returns Token information
+ */
+export const getToken = async (
+  client: SDKClient,
+  chain: ChainKey | ChainId,
+  token: string,
+  options?: RequestOptions
+): Promise<TokenExtended> => {
+  if (!chain) {
+    throw new SDKError(
+      new ValidationError('Required parameter "chain" is missing.')
+    )
+  }
+  if (!token) {
+    throw new SDKError(
+      new ValidationError('Required parameter "token" is missing.')
+    )
+  }
+  return await request<TokenExtended>(
+    client.config,
+    `${client.config.apiUrl}/token?${new URLSearchParams({
+      chain,
+      token,
+    } as Record<string, string>)}`,
+    {
+      signal: options?.signal,
+    }
+  )
+}