@lifi/sdk 3.13.5 → 4.0.0-alpha.1

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

@@ -0,0 +1,45 @@
+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 { getToken } from './getToken.js'
+
+const mockedFetch = vi.spyOn(request, 'request')
+
+describe('getToken', () => {
+  setupTestServer()
+
+  describe('user input is invalid', () => {
+    it('throw an error', async () => {
+      await expect(
+        getToken(client, undefined as unknown as ChainId, 'DAI')
+      ).rejects.toThrowError(
+        new SDKError(
+          new ValidationError('Required parameter "chain" is missing.')
+        )
+      )
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+
+      await expect(
+        getToken(client, ChainId.ETH, undefined as unknown as string)
+      ).rejects.toThrowError(
+        new SDKError(
+          new ValidationError('Required parameter "token" is missing.')
+        )
+      )
+      expect(mockedFetch).toHaveBeenCalledTimes(0)
+    })
+  })
+
+  describe('user input is valid', () => {
+    describe('and the backend call is successful', () => {
+      it('call the server once', async () => {
+        await getToken(client, ChainId.DAI, 'DAI')
+
+        expect(mockedFetch).toHaveBeenCalledTimes(1)
+      })
+    })
+  })
+})

package/src/actions/getTokenBalance.ts

@@ -0,0 +1,21 @@
+import type { Token, TokenAmount } from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+import { getTokenBalances } from './getTokenBalances.js'
+
+/**
+ * Returns the balances of a specific token a wallet holds across all aggregated chains.
+ * @param client - The SDK client.
+ * @param walletAddress - A wallet address.
+ * @param token - A Token object.
+ * @returns An object containing the token and the amounts on different chains.
+ * @throws {ValidationError} Throws a ValidationError if validation fails.
+ * @throws {Error} Throws an Error if the SDK Provider for the wallet address is not found.
+ */
+export const getTokenBalance = async (
+  client: SDKClient,
+  walletAddress: string,
+  token: Token
+): Promise<TokenAmount | null> => {
+  const tokenAmounts = await getTokenBalances(client, walletAddress, [token])
+  return tokenAmounts.length ? tokenAmounts[0] : null
+}

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

@@ -0,0 +1,61 @@
+import { findDefaultToken } from '@lifi/data-types'
+import type { Token } from '@lifi/types'
+import { ChainId, CoinKey } from '@lifi/types'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { client } from './actions.unit.handlers.js'
+import { getTokenBalance } from './getTokenBalance.js'
+
+const mockedGetTokenBalance = vi.spyOn(
+  await import('./getTokenBalance.js'),
+  'getTokenBalance'
+)
+
+describe('getTokenBalance', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const SOME_TOKEN = {
+    ...findDefaultToken(CoinKey.USDC, ChainId.DAI),
+    priceUSD: '',
+  }
+  const SOME_WALLET_ADDRESS = 'some wallet address'
+
+  describe('user input is invalid', () => {
+    it('should throw Error because of missing walletAddress', async () => {
+      await expect(getTokenBalance(client, '', SOME_TOKEN)).rejects.toThrow(
+        'Missing walletAddress.'
+      )
+    })
+
+    it('should throw Error because of invalid token', async () => {
+      await expect(
+        getTokenBalance(client, SOME_WALLET_ADDRESS, {
+          address: 'some wrong stuff',
+          chainId: 'not a chain Id',
+        } as unknown as Token)
+      ).rejects.toThrow('Invalid tokens passed.')
+    })
+  })
+
+  describe('user input is valid', () => {
+    it('should call the balance service', async () => {
+      const balanceResponse = {
+        ...SOME_TOKEN,
+        amount: 123n,
+        blockNumber: 1n,
+      }
+
+      mockedGetTokenBalance.mockReturnValue(Promise.resolve(balanceResponse))
+
+      const result = await getTokenBalance(
+        client,
+        SOME_WALLET_ADDRESS,
+        SOME_TOKEN
+      )
+
+      expect(mockedGetTokenBalance).toHaveBeenCalledTimes(1)
+      expect(result).toEqual(balanceResponse)
+    })
+  })
+})

package/src/actions/getTokenBalances.ts

@@ -0,0 +1,47 @@
+import type {
+  Token,
+  TokenAmount,
+  TokenAmountExtended,
+  TokenExtended,
+} from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+import { getTokenBalancesByChain } from './getTokenBalancesByChain.js'
+
+/**
+ * Returns the balances for a list tokens a wallet holds across all aggregated chains.
+ * @param client - The SDK client.
+ * @param walletAddress - A wallet address.
+ * @param tokens - A list of Token (or TokenExtended) objects.
+ * @returns A list of objects containing the tokens and the amounts on different chains.
+ * @throws {ValidationError} Throws a ValidationError if validation fails.
+ * @throws {Error} Throws an Error if the SDK Provider for the wallet address is not found.
+ */
+export async function getTokenBalances(
+  client: SDKClient,
+  walletAddress: string,
+  tokens: Token[]
+): Promise<TokenAmount[]>
+export async function getTokenBalances(
+  client: SDKClient,
+  walletAddress: string,
+  tokens: TokenExtended[]
+): Promise<TokenAmountExtended[]> {
+  // split by chain
+  const tokensByChain = tokens.reduce(
+    (tokens, token) => {
+      if (!tokens[token.chainId]) {
+        tokens[token.chainId] = []
+      }
+      tokens[token.chainId].push(token)
+      return tokens
+    },
+    {} as { [chainId: number]: Token[] | TokenExtended[] }
+  )
+
+  const tokenAmountsByChain = await getTokenBalancesByChain(
+    client,
+    walletAddress,
+    tokensByChain
+  )
+  return Object.values(tokenAmountsByChain).flat()
+}

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

@@ -0,0 +1,68 @@
+import { findDefaultToken } from '@lifi/data-types'
+import type { Token } from '@lifi/types'
+import { ChainId, CoinKey } from '@lifi/types'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { client } from './actions.unit.handlers.js'
+import { getTokenBalances } from './getTokenBalances.js'
+
+const mockedGetTokenBalances = vi.spyOn(
+  await import('./getTokenBalances.js'),
+  'getTokenBalances'
+)
+
+describe('getTokenBalances', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const SOME_TOKEN = {
+    ...findDefaultToken(CoinKey.USDC, ChainId.DAI),
+    priceUSD: '',
+  }
+  const SOME_WALLET_ADDRESS = 'some wallet address'
+
+  describe('user input is invalid', () => {
+    it('should throw Error because of missing walletAddress', async () => {
+      await expect(getTokenBalances(client, '', [SOME_TOKEN])).rejects.toThrow(
+        'Missing walletAddress.'
+      )
+    })
+
+    it('should throw Error because of an invalid token', async () => {
+      await expect(
+        getTokenBalances(client, SOME_WALLET_ADDRESS, [
+          SOME_TOKEN,
+          { not: 'a token' } as unknown as Token,
+        ])
+      ).rejects.toThrow('Invalid tokens passed.')
+    })
+
+    it('should return empty token list as it is', async () => {
+      mockedGetTokenBalances.mockReturnValue(Promise.resolve([]))
+      const result = await getTokenBalances(client, SOME_WALLET_ADDRESS, [])
+      expect(result).toEqual([])
+      expect(mockedGetTokenBalances).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('user input is valid', () => {
+    it('should call the balance service', async () => {
+      const balanceResponse = [
+        {
+          ...SOME_TOKEN,
+          amount: 123n,
+          blockNumber: 1n,
+        },
+      ]
+
+      mockedGetTokenBalances.mockReturnValue(Promise.resolve(balanceResponse))
+
+      const result = await getTokenBalances(client, SOME_WALLET_ADDRESS, [
+        SOME_TOKEN,
+      ])
+
+      expect(mockedGetTokenBalances).toHaveBeenCalledTimes(1)
+      expect(result).toEqual(balanceResponse)
+    })
+  })
+})

package/src/actions/getTokenBalancesByChain.ts

@@ -0,0 +1,76 @@
+import type {
+  Token,
+  TokenAmount,
+  TokenAmountExtended,
+  TokenExtended,
+} from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import type { SDKClient } from '../types/core.js'
+import { isToken } from '../utils/isToken.js'
+
+/**
+ * This method queries the balances of tokens for a specific list of chains for a given wallet.
+ * @param client - The SDK client.
+ * @param walletAddress - A wallet address.
+ * @param tokensByChain - A list of token objects organized by chain ids.
+ * @returns A list of objects containing the tokens and the amounts on different chains organized by the chosen chains.
+ * @throws {ValidationError} Throws a ValidationError if validation fails.
+ * @throws {Error} Throws an Error if the SDK Provider for the wallet address is not found.
+ */
+export async function getTokenBalancesByChain(
+  client: SDKClient,
+  walletAddress: string,
+  tokensByChain: { [chainId: number]: Token[] }
+): Promise<{ [chainId: number]: TokenAmount[] }>
+export async function getTokenBalancesByChain(
+  client: SDKClient,
+  walletAddress: string,
+  tokensByChain: { [chainId: number]: TokenExtended[] }
+): Promise<{ [chainId: number]: TokenAmountExtended[] }> {
+  if (!walletAddress) {
+    throw new ValidationError('Missing walletAddress.')
+  }
+
+  const tokenList = Object.values(tokensByChain).flat()
+  const invalidTokens = tokenList.filter((token) => !isToken(token))
+  if (invalidTokens.length) {
+    throw new ValidationError('Invalid tokens passed.')
+  }
+
+  const provider = client.providers.find((provider) =>
+    provider.isAddress(walletAddress)
+  )
+  if (!provider) {
+    throw new Error(`SDK Token Provider for ${walletAddress} is not found.`)
+  }
+
+  const tokenAmountsByChain: {
+    [chainId: number]: TokenAmount[] | TokenAmountExtended[]
+  } = {}
+  const tokenAmountsSettled = await Promise.allSettled(
+    Object.keys(tokensByChain).map(async (chainIdStr) => {
+      const chainId = Number.parseInt(chainIdStr, 10)
+      const chain = await client.getChainById(chainId)
+      if (provider.type === chain.chainType) {
+        const tokenAmounts = await provider.getBalance(
+          client,
+          walletAddress,
+          tokensByChain[chainId]
+        )
+        tokenAmountsByChain[chainId] = tokenAmounts
+      } else {
+        // if the provider is not the same as the chain type,
+        // return the tokens as is
+        tokenAmountsByChain[chainId] = tokensByChain[chainId]
+      }
+    })
+  )
+  if (client.config.debug) {
+    for (const result of tokenAmountsSettled) {
+      if (result.status === 'rejected') {
+        console.warn("Couldn't fetch token balance.", result.reason)
+      }
+    }
+  }
+  return tokenAmountsByChain
+}

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

@@ -0,0 +1,108 @@
+import { findDefaultToken } from '@lifi/data-types'
+import type { Token } from '@lifi/types'
+import { ChainId, CoinKey } from '@lifi/types'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { client } from './actions.unit.handlers.js'
+import { getTokenBalancesByChain } from './getTokenBalancesByChain.js'
+
+const mockedGetTokenBalancesForChains = vi.spyOn(
+  await import('./getTokenBalancesByChain.js'),
+  'getTokenBalancesByChain'
+)
+
+describe('getTokenBalancesByChain', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  const SOME_TOKEN = {
+    ...findDefaultToken(CoinKey.USDC, ChainId.DAI),
+    priceUSD: '',
+  }
+  const SOME_WALLET_ADDRESS = 'some wallet address'
+
+  describe('user input is invalid', () => {
+    it('should throw Error because of missing walletAddress', async () => {
+      await expect(
+        getTokenBalancesByChain(client, '', {
+          [ChainId.DAI]: [SOME_TOKEN],
+        })
+      ).rejects.toThrow('Missing walletAddress.')
+    })
+
+    it('should throw Error because of an invalid token', async () => {
+      await expect(
+        getTokenBalancesByChain(client, SOME_WALLET_ADDRESS, {
+          [ChainId.DAI]: [{ not: 'a token' } as unknown as Token],
+        })
+      ).rejects.toThrow('Invalid tokens passed.')
+    })
+
+    it('should return empty token list as it is', async () => {
+      mockedGetTokenBalancesForChains.mockReturnValue(Promise.resolve([]))
+
+      const result = await getTokenBalancesByChain(
+        client,
+        SOME_WALLET_ADDRESS,
+        {
+          [ChainId.DAI]: [],
+        }
+      )
+
+      expect(result).toEqual([])
+      expect(mockedGetTokenBalancesForChains).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('user input is valid', () => {
+    it('should call the balance service', async () => {
+      const balanceResponse = {
+        [ChainId.DAI]: [
+          {
+            ...SOME_TOKEN,
+            amount: 123n,
+            blockNumber: 1n,
+          },
+        ],
+      }
+
+      mockedGetTokenBalancesForChains.mockReturnValue(
+        Promise.resolve(balanceResponse)
+      )
+
+      const result = await getTokenBalancesByChain(
+        client,
+        SOME_WALLET_ADDRESS,
+        {
+          [ChainId.DAI]: [SOME_TOKEN],
+        }
+      )
+
+      expect(mockedGetTokenBalancesForChains).toHaveBeenCalledTimes(1)
+      expect(result).toEqual(balanceResponse)
+    })
+  })
+
+  describe('provider is not the same as the chain type', () => {
+    it('should return the tokens as is', async () => {
+      const balanceResponse = {
+        [ChainId.DAI]: [SOME_TOKEN],
+      }
+
+      mockedGetTokenBalancesForChains.mockReturnValue(
+        Promise.resolve(balanceResponse)
+      )
+
+      const result = await getTokenBalancesByChain(
+        client,
+        SOME_WALLET_ADDRESS,
+        {
+          [ChainId.DAI]: [SOME_TOKEN],
+        }
+      )
+
+      expect(mockedGetTokenBalancesForChains).toHaveBeenCalledTimes(1)
+      expect(result).toEqual(balanceResponse)
+    })
+  })
+})

package/src/actions/getTokens.ts

@@ -0,0 +1,54 @@
+import type {
+  RequestOptions,
+  TokensExtendedResponse,
+  TokensRequest,
+  TokensResponse,
+} from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+import { withDedupe } from '../utils/withDedupe.js'
+
+/**
+ * Get all known tokens.
+ * @param client - The SDK client
+ * @param params - The configuration of the requested tokens
+ * @param options - Request options
+ * @returns The tokens that are available on the requested chains
+ */
+export async function getTokens(
+  client: SDKClient,
+  params?: TokensRequest & { extended?: false | undefined },
+  options?: RequestOptions
+): Promise<TokensResponse>
+export async function getTokens(
+  client: SDKClient,
+  params: TokensRequest & { extended: true },
+  options?: RequestOptions
+): Promise<TokensExtendedResponse>
+export async function getTokens(
+  client: SDKClient,
+  params?: TokensRequest,
+  options?: RequestOptions
+): Promise<TokensResponse> {
+  if (params) {
+    for (const key of Object.keys(params)) {
+      if (!params[key as keyof TokensRequest]) {
+        delete params[key as keyof TokensRequest]
+      }
+    }
+  }
+  const urlSearchParams = new URLSearchParams(
+    params as Record<string, string>
+  ).toString()
+  const isExtended = params?.extended === true
+  const response = await withDedupe(
+    () =>
+      request<
+        typeof isExtended extends true ? TokensExtendedResponse : TokensResponse
+      >(client.config, `${client.config.apiUrl}/tokens?${urlSearchParams}`, {
+        signal: options?.signal,
+      }),
+    { id: `${getTokens.name}.${urlSearchParams}` }
+  )
+  return response
+}

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

@@ -0,0 +1,16 @@
+import { ChainId } from '@lifi/types'
+import { describe, expect, it } from 'vitest'
+import { client, setupTestServer } from './actions.unit.handlers.js'
+import { getTokens } from './getTokens.js'
+
+describe('getTokens', () => {
+  setupTestServer()
+
+  it('return the tokens', async () => {
+    const result = await getTokens(client, {
+      chains: [ChainId.ETH, ChainId.POL],
+    })
+    expect(result).toBeDefined()
+    expect(result.tokens[ChainId.ETH]).toBeDefined()
+  })
+})

package/src/actions/getTools.ts

@@ -0,0 +1,33 @@
+import type { RequestOptions, ToolsRequest, ToolsResponse } from '@lifi/types'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get the available tools to bridge and swap tokens.
+ * @param client - The SDK client
+ * @param params - The configuration of the requested tools
+ * @param options - Request options
+ * @returns The tools that are available on the requested chains
+ */
+export const getTools = async (
+  client: SDKClient,
+  params?: ToolsRequest,
+  options?: RequestOptions
+): Promise<ToolsResponse> => {
+  if (params) {
+    for (const key of Object.keys(params)) {
+      if (!params[key as keyof ToolsRequest]) {
+        delete params[key as keyof ToolsRequest]
+      }
+    }
+  }
+  return await request<ToolsResponse>(
+    client.config,
+    `${client.config.apiUrl}/tools?${new URLSearchParams(
+      params as Record<string, string>
+    )}`,
+    {
+      signal: options?.signal,
+    }
+  )
+}

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

@@ -0,0 +1,20 @@
+import { ChainId } from '@lifi/types'
+import { describe, expect, it } from 'vitest'
+import { client, setupTestServer } from './actions.unit.handlers.js'
+import { getTools } from './getTools.js'
+
+describe('getTools', () => {
+  setupTestServer()
+
+  describe('and the backend succeeds', () => {
+    it('returns the tools', async () => {
+      const tools = await getTools(client, {
+        chains: [ChainId.ETH, ChainId.POL],
+      })
+
+      expect(tools).toBeDefined()
+      expect(tools.bridges).toBeDefined()
+      expect(tools.exchanges).toBeDefined()
+    })
+  })
+})

package/src/actions/getTransactionHistory.ts

@@ -0,0 +1,54 @@
+import type {
+  RequestOptions,
+  TransactionAnalyticsRequest,
+  TransactionAnalyticsResponse,
+} from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Get the transaction history for a wallet
+ * @param client - The SDK client
+ * @param params - The parameters for the transaction history request
+ * @param params.wallet - The wallet address
+ * @param params.status - The status of the transactions
+ * @param params.fromTimestamp - The start timestamp for the transactions
+ * @param params.toTimestamp - The end timestamp for the transactions
+ * @param options - Request options
+ * @throws {ValidationError} - Throws a ValidationError if parameters are invalid
+ * @throws {LiFiError} - Throws a LiFiError if request fails.
+ * @returns The transaction history response
+ */
+export const getTransactionHistory = async (
+  client: SDKClient,
+  { wallet, status, fromTimestamp, toTimestamp }: TransactionAnalyticsRequest,
+  options?: RequestOptions
+): Promise<TransactionAnalyticsResponse> => {
+  if (!wallet) {
+    throw new ValidationError('Required parameter "wallet" is missing.')
+  }
+
+  const url = new URL(`${client.config.apiUrl}/analytics/transfers`)
+
+  url.searchParams.append('integrator', client.config.integrator)
+  url.searchParams.append('wallet', wallet)
+
+  if (status) {
+    url.searchParams.append('status', status)
+  }
+
+  if (fromTimestamp) {
+    url.searchParams.append('fromTimestamp', fromTimestamp.toString())
+  }
+
+  if (toTimestamp) {
+    url.searchParams.append('toTimestamp', toTimestamp.toString())
+  }
+
+  return await request<TransactionAnalyticsResponse>(
+    client.config,
+    url,
+    options
+  )
+}

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

@@ -0,0 +1,36 @@
+import type { TransactionAnalyticsRequest } from '@lifi/types'
+import { HttpResponse, http } from 'msw'
+import { describe, expect, it, vi } from 'vitest'
+import * as request from '../utils/request.js'
+import { client, setupTestServer } from './actions.unit.handlers.js'
+import { getTransactionHistory } from './getTransactionHistory.js'
+
+const mockedFetch = vi.spyOn(request, 'request')
+
+describe('getTransactionHistory', () => {
+  const server = setupTestServer()
+
+  it('returns empty array in response', async () => {
+    server.use(
+      http.get(`${client.config.apiUrl}/analytics/transfers`, async () =>
+        HttpResponse.json({})
+      )
+    )
+
+    const walletAnalyticsRequest: TransactionAnalyticsRequest = {
+      fromTimestamp: 1696326609361,
+      toTimestamp: 1696326609362,
+      wallet: '0x5520abcd',
+    }
+
+    const generatedURL =
+      'https://li.quest/v1/analytics/transfers?integrator=lifi-sdk&wallet=0x5520abcd&fromTimestamp=1696326609361&toTimestamp=1696326609362'
+
+    await expect(
+      getTransactionHistory(client, walletAnalyticsRequest)
+    ).resolves.toEqual({})
+
+    expect((mockedFetch.mock.calls[0][1] as URL).href).toEqual(generatedURL)
+    expect(mockedFetch).toHaveBeenCalledOnce()
+  })
+})

package/src/actions/getWalletBalances.ts

@@ -0,0 +1,36 @@
+import type {
+  GetWalletBalanceExtendedResponse,
+  RequestOptions,
+  WalletTokenExtended,
+} from '@lifi/types'
+import { ValidationError } from '../errors/errors.js'
+import type { SDKClient } from '../types/core.js'
+import { request } from '../utils/request.js'
+
+/**
+ * Returns the balances of tokens a wallet holds across EVM chains.
+ * @param client - The SDK client.
+ * @param walletAddress - A wallet address.
+ * @param options - Optional request options.
+ * @returns An object containing the tokens and the amounts organized by chain ids.
+ * @throws {ValidationError} Throws a ValidationError if parameters are invalid.
+ */
+export const getWalletBalances = async (
+  client: SDKClient,
+  walletAddress: string,
+  options?: RequestOptions
+): Promise<Record<number, WalletTokenExtended[]>> => {
+  if (!walletAddress) {
+    throw new ValidationError('Missing walletAddress.')
+  }
+
+  const response = await request<GetWalletBalanceExtendedResponse>(
+    client.config,
+    `${client.config.apiUrl}/wallets/${walletAddress}/balances?extended=true`,
+    {
+      signal: options?.signal,
+    }
+  )
+
+  return (response?.balances || {}) as Record<number, WalletTokenExtended[]>
+}